Skip to Content
Design

Botão Button

Especificações de semântica, tamanho, forma, estado e acessibilidade para Button e IconButton.

Componente ao vivoBotão / IconButton / AIButton

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 por aria-label.
  • Ícones pouco familiares ou de significado potencialmente ambíguo devem usar também o Tooltip compartilhado; tooltip não substitui aria-label.
  • Não use o atributo DOM title como dica de produto, nem defina tooltip e 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 Button com texto vazio, texto oculto ou largura fixa para simular IconButton.
  • Não defina shape para IconButton; 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 Button com href apenas quando for necessária ênfase visual de nível de botão.

3. Hierarquia semântica variant

VarianteSignificadoCenários típicosRestrições de uso
primaryAção principal da área atualSalvar, publicar, criar, experimentar agoraGeralmente apenas uma ação principal por área de tarefa
secondaryAção clara, mas secundáriaVisualizar, cancelar, voltar, importarNão deve competir visualmente com a ação principal
ghostAção de ferramenta contextual com baixa ênfaseFechar, mais, ações de barra de ferramentas, voltar leveTransparente por padrão; não pode ser o único CTA crítico
dangerAção que exclui ou causa dano significativoExcluir item, remover conteúdo, limpar dadosExpressa 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:

  1. Identifique o próximo passo mais importante e único da tarefa atual e defina-o como primary.
  2. Ações auxiliares que ainda precisam ser claramente visíveis usam secondary.
  3. Ações de baixa ênfase em barras de ferramentas ou contextuais usam ghost.
  4. 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

TamanhoAltura/diâmetroTamanho da fonteCenários recomendados
sm40px14pxNavegação superior, barras de ferramentas compactas, áreas de trabalho densas
md44px15pxFormulários padrão, CMS, diálogos e ações comuns
lg48px16pxCTA 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 Button e o diâmetro de IconButton usam o mesmo conjunto de tokens de tamanho, permitindo alinhamento na mesma barra de ferramentas; o tamanho visível do ícone de IconButton é 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

FormaAparênciaEscopo de uso
pillBorder-radius total; oval quando há textoPadrão da plataforma, aplicável a páginas de marketing, Dashboard, Builder, CMS e Admin
roundedBorder-radius de 12pxApenas 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 usam trailingIcon.
  • 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.

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 Button sem href, renderizando finalmente como <button>.
  • Para navegar para outra rota ou recurso, use Button com href, 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 explicitamente type="submit".
  • Não use onClick para 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-hover no hover; pressionados, selecionados e expandidos usam --control-surface-active. focus-visible mantém --focus-ring em 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".
  • IconButton deve fornecer aria-label localizado.
  • Í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 danger e 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:

PropriedadeValor padrãoDescrição
variantprimaryHierarquia semântica e visual
sizemdAltura, tamanho da fonte e padding horizontal
shapepillForma de border-radius de Button
leadingIconNenhumÍcone antes do texto
trailingIconNenhumÍcone depois do texto
hrefNenhumQuando fornecido, renderiza como link
disabledfalseDesabilita interação
tooltipNenhumConteúdo complementar do Tooltip compartilhado; não substitui informações-chave visíveis ou aria-label
tooltipPlacementbottomDireção preferida; o Tooltip compartilhado pode inverter para permanecer na viewport
tooltipPortaltrueRenderiza fora do container de recorte sem adicionar camada de layout
skinNenhumFornece 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 Button ou IconButton?
  • Botões com texto e apenas ícone escolheram o componente correto?
  • A área de tarefa atual tem apenas um primary claro?
  • secondary, ghost, danger estão sendo usados por semântica e não por preferência de cor?
  • O Button da plataforma mantém o pill padrão e IconButton manté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 title nativos do navegador, bolhas de CSS data-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 type correto?
  • Os ícones ocultaram informações repetidas do leitor de tela e IconButton tem aria-label localizado?
  • 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.

Nesta página