Botão Button
Especificações de semântica, tamanho, forma, estado e acessibilidade para Button e IconButton.
O AIButton reutiliza o tamanho e os significados do botão, adicionando um estado distintivo e perceptível do Qokit AI.
Selecione o botão IA para visualizar seu estado de trabalho.
Especificações do componente Button do Qokit
Este documento define as regras de uso de botões na plataforma Qokit, Builder, CMS, Dashboard, Admin, páginas de marketing e sites gerados. O objetivo é unificar componentes, semântica, forma, tamanho, ícones, estados e acessibilidade dos botões, evitando que cada rota redesenhe botões com CSS local.
1. Modelo central
Os botões não são classificados apenas como "oval" ou "circular", mas sim compostos por cinco dimensões independentes:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Tipo de componente determina se o botão tem texto visível e se deve manter uma área de clique quadrada.
- Prioridade semântica determina a prioridade e a cor do botão na tarefa atual.
- Tamanho determina a altura estável, o tamanho da fonte e a área de toque.
- Forma determina apenas o border-radius, não expressa prioridade nem semântica de negócio.
- Camada espacial indica apenas se o controle se eleva do plano atual, sem alterar a semântica da ação.
Não crie novos tipos de botão combinando novas classes. Primeiro escolha entre as propriedades existentes do componente compartilhado.
2. Seleção de componente
Button
Usado para todas as ações com texto visível, incluindo:
- Botões de texto puro;
- Botões com ícone antes do texto;
- Botões com ícone depois do texto;
- Links de página com aparência de botão.
O Button na plataforma usa por padrão pill totalmente arredondado, resultando visualmente em um botão oval. Sempre que o botão contiver texto visível, não deve ser substituído por um botão de ícone circular.
variant é desacoplado da sombra: primary usa raised por padrão; secondary, danger e ghost usam flat por padrão. Ações em linhas de lista, dentro de cards, barras de ferramentas e dentro de cápsulas compostas devem ser flat; ações primárias independentes podem usar raised; apenas ações flutuantes sobre o conteúdo usam floating. Cápsulas independentes ou controles segmentados devem ter sombra desenhada apenas uma vez pelo container mais externo; rotas não devem sobrescrever camadas compartilhadas com CSS local.
import { Button } from '@qokit/components/ui';
<Button type="button" variant="primary">
保存
</Button>
<Button
leadingIcon={<SaveIcon aria-hidden="true" />}
type="button"
variant="primary"
>
保存
</Button>
<Button
href="/projects"
trailingIcon={<ArrowRightIcon aria-hidden="true" />}
variant="secondary"
>
查看项目
</Button>IconButton
Usado para ações compactas de ferramenta com apenas um ícone e sem texto visível, como fechar, mais, voltar, alternar menu ou excluir.
IconButton mantém largura, altura e border-radius total iguais em todos os tamanhos, sendo visualmente um botão circular. Usa ghost por padrão e exige aria-label no nível de tipo.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Regras:
- O ícone em si usa
aria-hidden="true"; o nome do botão é fornecido poraria-label. - Ícones pouco familiares ou de significado potencialmente ambíguo devem usar também o
Tooltipcompartilhado; tooltip não substituiaria-label. - Não use o atributo DOM
titlecomo dica de produto, nem definatooltipe envolva manualmente com Tooltip ao mesmo tempo. - Tooltip é uma camada de informação somente leitura, não um botão oval. Usa o border-radius compacto compartilhado de Tooltip e não deve reutilizar
pill, nem visuais de hover, pressed ou focus de botão. - Não use
Buttoncom texto vazio, texto oculto ou largura fixa para simularIconButton. - Não defina
shapeparaIconButton; a forma circular é o contrato do componente.
Cenários em que Button não deve ser usado
- Abas: use os componentes correspondentes Tabs/PillTabs/Segmented.
- Itens de menu: use os componentes correspondentes Menu/ActionMenu.
- Estados, tags e resultados de filtro: use Pill ou componentes de estado.
- Navegação de texto comum: use links semânticos; use
Buttoncomhrefapenas quando for necessária ênfase visual de nível de botão.
3. Hierarquia semântica variant
| Variante | Significado | Cenários típicos | Restrições de uso |
|---|---|---|---|
primary | Ação principal da área atual | Salvar, publicar, criar, experimentar agora | Geralmente apenas uma ação principal por área de tarefa |
secondary | Ação clara, mas secundária | Visualizar, cancelar, voltar, importar | Não deve competir visualmente com a ação principal |
ghost | Ação de ferramenta contextual com baixa ênfase | Fechar, mais, ações de barra de ferramentas, voltar leve | Transparente por padrão; não pode ser o único CTA crítico |
danger | Ação que exclui ou causa dano significativo | Excluir item, remover conteúdo, limpar dados | Expressa apenas semântica destrutiva; não usar como cor de ênfase comum |
variant expressa hierarquia semântica e visual, não forma. Por exemplo, ghost pode ser um botão oval com texto ou um IconButton circular.
Ordem de seleção:
- Identifique o próximo passo mais importante e único da tarefa atual e defina-o como
primary. - Ações auxiliares que ainda precisam ser claramente visíveis usam
secondary. - Ações de baixa ênfase em barras de ferramentas ou contextuais usam
ghost. - Apenas ações realmente destrutivas usam
danger, mantendo o fluxo de confirmação existente.
Não escolha a variante com base em "qual cor fica mais bonita".
4. Tamanho size
| Tamanho | Altura/diâmetro | Tamanho da fonte | Cenários recomendados |
|---|---|---|---|
sm | 40px | 14px | Navegação superior, barras de ferramentas compactas, áreas de trabalho densas |
md | 44px | 15px | Formulários padrão, CMS, diálogos e ações comuns |
lg | 48px | 16px | CTA principal de páginas de marketing, ações primárias que exigem maior área de toque |
O tamanho padrão é md.
- Um mesmo grupo de botões deve usar o mesmo tamanho.
- Controles compactos não devem ter menos de 40px; ações primárias em mobile devem priorizar pelo menos 44px.
- A altura de
Buttone o diâmetro deIconButtonusam o mesmo conjunto de tokens de tamanho, permitindo alinhamento na mesma barra de ferramentas; o tamanho visível do ícone deIconButtoné uniformemente 18px. - O tamanho da fonte de
Buttoné determinado pelo token compartilhado correspondente ao size, não herdando o tamanho de fonte de Header, Dialog ou outro container pai. - O CSS da rota pode controlar o alinhamento, espaçamento e largura necessária dos botões, mas não pode redefinir a altura ou o tamanho da fonte dos botões compartilhados.
- Quando o texto for longo, priorize ajustar o layout ou o container do botão; não resolva comprimindo altura, fonte ou espaçamento lateral.
5. Forma shape
| Forma | Aparência | Escopo de uso |
|---|---|---|
pill | Border-radius total; oval quando há texto | Padrão da plataforma, aplicável a páginas de marketing, Dashboard, Builder, CMS e Admin |
rounded | Border-radius de 12px | Apenas quando o tema do site gerado exigir explicitamente border-radius menor |
Button usa shape="pill" por padrão. O frontend da plataforma não deve definir explicitamente rounded nem sobrescrever o border-radius em CSS local.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton é sempre circular e não participa da escolha de negócio pill / rounded.
6. Regras de ícones
- Ícones antes do texto usam
leadingIcon; ícones depois do texto usamtrailingIcon. - Um botão geralmente usa apenas um ícone auxiliar.
- Ações familiares como salvar, adicionar e voltar podem usar ícones para reforçar o reconhecimento, mas o ícone não pode substituir o texto visível de botões críticos.
- Setas que indicam continuar, entrar ou expandir geralmente ficam depois do texto; ícones de voltar geralmente ficam antes do texto.
- Não escreva manualmente o layout de ícone e texto em
children; o componente já fornece slots de icon e label. - Use ícones compartilhados e herde
currentColor; não codifique cores ou tamanhos de ícones no CSS da rota. - O estado de carregamento deve manter a largura e altura originais do botão e fornecer um texto curto compreensível ou feedback de carregamento existente; não permita que a troca de texto cause saltos na barra de ferramentas.
7. Botões e links
Ações e navegação devem usar a semântica correta:
- Para ações na página atual como enviar, salvar, abrir modal, alternar estado, use
Buttonsemhref, renderizando finalmente como<button>. - Para navegar para outra rota ou recurso, use
Buttoncomhref, renderizando finalmente como Next.js<Link>. - Botões não-submit dentro de formulários devem declarar explicitamente
type="button"; botões de submit devem declarar explicitamentetype="submit". - Não use
onClickpara simular navegação normal de página.
Links desabilitados usam aria-disabled e saem da ordem de Tab; botões nativos desabilitados usam disabled. O estado desabilitado não pode ser expresso apenas reduzindo a opacidade; a lógica de negócio também deve bloquear a ação.
8. Estados e acessibilidade
Os componentes compartilhados são responsáveis por hover, focus-visible, disabled e estados de cor. O código de negócio ainda deve atender a:
- Botões comuns não selecionados usam
--control-surface-hoverno hover; pressionados, selecionados e expandidos usam--control-surface-active.focus-visiblemantém--focus-ringem superfícies neutras; estilos de rota não devem combinar hover e estado persistente na mesma regra azul clara. - Os nomes dos botões devem ser diretos, específicos e descrever o que acontecerá, como "Salvar", "Publicar site", "Excluir item".
IconButtondeve forneceraria-labellocalizado.- Ícones decorativos usam
aria-hidden="true"para evitar leitura repetida pelo leitor de tela. - O foco do teclado deve ser visível; o CSS da rota não deve remover o focus ring compartilhado.
- Não use hover como única dica; a interação deve suportar teclado e toque simultaneamente.
- Botões desabilitados devem ser usados apenas para ações que o usuário não pode executar temporariamente; se for necessário explicar o motivo, forneça uma explicação próxima ou um tooltip.
- Erros, requisitos de permissão, riscos, custos e outras informações críticas da tarefa devem permanecer visíveis; Tooltip só complementa informações, não pode ser a única forma de descobri-las.
- Operações assíncronas devem evitar envio duplicado e manter um feedback compreensível de andamento.
- Ações perigosas usam
dangere reutilizam o pattern de confirmação de perigo existente; não dependa apenas da cor vermelha para comunicar risco. - Textos de botões em chinês ou outros idiomas não devem ser truncados a ponto de se tornarem incompreensíveis. É obrigatório validar textos longos e larguras em mobile.
9. Limites de responsabilidade de estilo
A estrutura, semântica e estados dos botões compartilhados são responsabilidade de Button / IconButton; tokens visuais e CSS compartilhado são responsabilidade do pacote de componentes; a rota é responsável apenas pelo layout.
Camada compartilhada é responsável por
- DOM, semântica de link/botão, comportamento disabled;
- Slots icon/label e restrições de tipo de acessibilidade;
- Classes variant, size, shape;
- Altura, border-radius, padding, tamanho da fonte, peso da fonte;
- Background, cor do texto, sombra, estados hover, focus-visible e disabled.
Camada de rota pode ser responsável por
- Direção, espaçamento, alinhamento e quebra de grupo de botões;
- Disposição responsiva;
width: 100%ou largura de container necessários para fluxos específicos;- Classes de posicionamento que não alteram a visual base.
Camada de rota não deve ser responsável por
- Sobrescrever altura, tamanho da fonte, border-radius, background, cor do texto, sombra ou focus ring do botão;
- Reimplementar botões compartilhados com cores codificadas ou
border-radius: 999px; - Adicionar variantes visuais locais como
primary-alt,outline-blue,icon-round; - Competir com o contrato de botão compartilhado usando
!important; - Copiar diretamente os estilos base de
.qk-ui-button.
Se realmente surgirem novas variantes semânticas necessárias em múltiplas páginas, primeiro estabeleça um contrato unificado no ButtonVariant, tokens e primitives.css compartilhados, em vez de adicionar estilos na rota.
10. Referência rápida da API
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Principais propriedades de Button:
| Propriedade | Valor padrão | Descrição |
|---|---|---|
variant | primary | Hierarquia semântica e visual |
size | md | Altura, tamanho da fonte e padding horizontal |
shape | pill | Forma de border-radius de Button |
leadingIcon | Nenhum | Ícone antes do texto |
trailingIcon | Nenhum | Ícone depois do texto |
href | Nenhum | Quando fornecido, renderiza como link |
disabled | false | Desabilita interação |
tooltip | Nenhum | Conteúdo complementar do Tooltip compartilhado; não substitui informações-chave visíveis ou aria-label |
tooltipPlacement | bottom | Direção preferida; o Tooltip compartilhado pode inverter para permanecer na viewport |
tooltipPortal | true | Renderiza fora do container de recorte sem adicionar camada de layout |
skin | Nenhum | Fornece slots de class e adaptação de variáveis conforme contrato skeleton/skin |
IconButton herda as propriedades aplicáveis de Button, mas não fornece shape, leadingIcon ou trailingIcon; exige aria-label, com padrão variant="ghost".
Recomenda-se escrever explicitamente variant e o type nativo do botão no código de negócio, para que a semântica da ação seja claramente visível na revisão de código.
11. Combinações comuns
// 主要操作:椭圆形文字按钮
<Button type="submit" variant="primary">
保存
</Button>
// 次要操作
<Button type="button" variant="secondary" onClick={onPreview}>
预览
</Button>
// 低强调文字操作
<Button type="button" variant="ghost" onClick={onCancel}>
取消
</Button>
// 图标 + 文字,仍然使用 Button
<Button
leadingIcon={<PlusIcon aria-hidden="true" />}
type="button"
variant="primary"
>
新建内容
</Button>
// 纯图标:圆形按钮
<IconButton aria-label="更多操作" tooltip="更多操作" type="button">
<MoreIcon aria-hidden="true" />
</IconButton>
// 危险操作
<Button type="button" variant="danger" onClick={openDeleteConfirm}>
删除项目
</Button>12. Checklist de revisão
Antes de enviar UI relacionada a botões, confirme:
- Foi priorizada a reutilização de
ButtonouIconButton? - Botões com texto e apenas ícone escolheram o componente correto?
- A área de tarefa atual tem apenas um
primaryclaro? secondary,ghost,dangerestão sendo usados por semântica e não por preferência de cor?- O
Buttonda plataforma mantém opillpadrão eIconButtonmantém a forma circular? - Cada Tooltip continua sendo uma camada de informação com border-radius compacto, e não parece um botão oval clicável?
- Foram eliminados
titlenativos do navegador, bolhas de CSSdata-tooltip, dicas duplicadas e Tooltips sinônimos de botões de texto? - Os tamanhos usam apenas
sm,md,lg, com altura e tamanho de fonte consistentes no mesmo grupo? - Os botões nativos definiram explicitamente o
typecorreto? - Os ícones ocultaram informações repetidas do leitor de tela e
IconButtontemaria-labellocalizado? - Os estados focus-visible, disabled, assíncrono e confirmação de perigo estão completos?
- O CSS da rota trata apenas do layout, sem sobrescrever a visual base do botão?
- Textos longos, tamanhos de toque e disposição de grupos de botões foram validados em larguras desktop e mobile?
13. Origem da implementação
- API do componente:
packages/components/src/ui/Button/Button.tsx - Exportações do componente:
packages/components/src/ui/Button/index.ts - Tokens de tamanho e cor:
packages/components/src/styles/foundations.css - Estilos compartilhados de botão:
packages/components/src/styles/primitives.css - Contrato de integração de componente público:
docs/public/design/component-integration.md
Quando houver divergência entre a documentação e a implementação, o componente, tokens, estilos e este documento devem ser sincronizados na mesma alteração.