Skip to Content
Design

Botão

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

Componente em tempo realBotão / IconButton / AIButton

O AIButton reutiliza o tamanho e os significados do botão, adicionando um estado Qokit AI distintivo e perceptível.

Selecione o botão IA para pré-visualizar o seu estado de funcionamento.

Especificações do componente Button do Qokit

Este documento define as regras de utilização de botões na plataforma Qokit, no Builder, no CMS, no Dashboard, no Admin, nas páginas de marketing e nos sites gerados. O objetivo é unificar os componentes, a semântica, a forma, o tamanho, os ícones, os estados e a acessibilidade dos botões, evitando que cada rota redesenhe botões através de CSS local.

1. Modelo principal

Os botões não se classificam apenas como "oval" ou "circular"; são definidos 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
  • O tipo de componente determina se o botão tem texto visível e se deve manter uma área de clique quadrada.
  • A prioridade semântica determina a prioridade e a cor do botão na tarefa atual.
  • O tamanho determina a altura estável, o tamanho da fonte e a área de toque.
  • A forma define apenas o raio dos cantos, não expressa prioridade nem semântica de negócio.
  • A camada espacial indica apenas se o controlo se eleva do plano atual, sem alterar a semântica da ação.

Não crie novos tipos de botão combinando novas classes. Comece por escolher entre as propriedades existentes do componente partilhado.

2. Seleção de componentes

Button

Utilizado para todas as ações com texto visível, incluindo:

  • Botões apenas com texto;
  • 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 utiliza por predefinição o pill totalmente arredondado, apresentando visualmente uma forma oval. Sempre que o botão contiver texto visível, não deve ser substituído por um botão de ícone circular.

variant está desacoplado da sombra: primary utiliza por predefinição raised, enquanto secondary, danger e ghost utilizam por predefinição flat. As ações em linhas de lista, no interior de cartões, em barras de ferramentas e no interior de cápsulas compostas devem ser flat; ações principais independentes podem ser raised; apenas as ações que flutuam sobre o conteúdo utilizam floating. Cápsulas independentes ou controlos segmentados só devem ter a sombra desenhada uma vez na camada mais externa; as rotas não devem reescrever camadas partilhadas 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

Utilizado para ações de ferramentas compactas com apenas um ícone e sem texto visível, como fechar, mais, voltar, alternar menu ou eliminar.

IconButton mantém largura, altura e cantos totalmente arredondados iguais em cada tamanho, sendo visualmente um botão circular. Utiliza por predefinição ghost e exige, ao nível do tipo, aria-label.

import { IconButton } from '@qokit/components/ui';

<IconButton aria-label="关闭" tooltip="关闭" type="button">
  <CloseIcon aria-hidden="true" />
</IconButton>

Regras:

  • O próprio ícone utiliza aria-hidden="true"; o nome do botão é fornecido por aria-label.
  • Ícones pouco familiares ou de significado potencialmente ambíguo devem utilizar também o Tooltip partilhado; o tooltip não substitui aria-label.
  • Não utilize o atributo DOM title como dica de produto, nem defina simultaneamente tooltip e envolva manualmente com Tooltip.
  • O Tooltip é uma camada de informação só de leitura, não um botão oval. Utiliza o raio de canto compacto partilhado do Tooltip e não deve reutilizar pill nem os visuais hover, pressed ou focus do botão.
  • Não utilize Button com texto vazio, texto oculto ou largura fixa para simular IconButton.
  • Não defina shape em IconButton; a forma circular faz parte do contrato do componente.

Cenários em que não deve utilizar Button

  • Separadores: utilize os componentes correspondentes Tabs/PillTabs/Segmented.
  • Itens de menu: utilize os componentes correspondentes Menu/ActionMenu.
  • Estados, etiquetas e resultados de filtros: utilize Pill ou componentes de estado.
  • Navegação em texto normal: utilize links semânticos; só utilize Button com href quando for necessário ênfase visual ao nível de botão.

3. Camada semântica variant

VarianteSignificadoCenários típicosRestrições de utilização
primaryAção principal da área atualGuardar, publicar, criar, experimentar agoraNormalmente, apenas uma ação principal por área de tarefa
secondaryAção clara mas secundáriaPré-visualizar, cancelar, voltar, importarNão deve competir visualmente com a ação principal
ghostAção de ferramenta contextual com baixo ênfaseFechar, mais, ações da barra de ferramentas, voltar de forma ligeiraTransparente por predefinição; não pode ser o único CTA crítico
dangerAção que elimina ou causa danos significativosEliminar item, remover conteúdo, limpar dadosExpressa apenas semântica destrutiva; não é uma cor de ênfase genérica

variant expressa camada 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 único mais importante da tarefa atual e defina-o como primary.
  2. Utilize secondary para ações secundárias que ainda devam ser claramente visíveis.
  3. Utilize ghost para ações de baixo ênfase em barras de ferramentas ou contextos.
  4. Utilize danger apenas para ações verdadeiramente destrutivas, mantendo o fluxo de confirmação existente.

Não escolha a variante com base em "qual a cor que fica melhor".

4. Tamanho size

TamanhoAltura/diâmetroTamanho da fonteCenários recomendados
sm40px14pxNavegação superior, barras de ferramentas compactas, áreas de trabalho densas
md44px15pxFormulários por predefinição, CMS, diálogos e ações regulares
lg48px16pxCTA principal em páginas de marketing, ações principais que exigem maior área de toque

O tamanho por predefinição é md.

  • Um mesmo grupo de botões deve utilizar o mesmo tamanho.
  • Os controlos compactos não devem ser inferiores a 40px; em mobile, as ações principais devem ter pelo menos 44px.
  • A altura de Button e o diâmetro de IconButton utilizam os mesmos tokens de tamanho, pelo que podem ser alinhados na mesma barra de ferramentas; o tamanho visível do ícone em IconButton é uniformizado em 18px.
  • O tamanho da fonte de Button é determinado pelo token partilhado correspondente ao tamanho, não herdando o tamanho de fonte do Header, Dialog ou de qualquer outro contentor pai.
  • O CSS da rota pode controlar o alinhamento, o espaçamento e a largura necessária dos botões, mas não pode redefinir a altura ou o tamanho da fonte dos botões partilhados.
  • Quando o texto é longo, ajuste primeiro o layout ou o contentor do botão; não resolva comprimindo altura, fonte ou espaçamento horizontal.

5. Forma shape

FormaAparênciaÂmbito de utilização
pillCantos totalmente arredondados; oval quando tem textoPredefinição da plataforma, aplicável a páginas de marketing, Dashboard, Builder, CMS e Admin
roundedCantos de 12pxApenas quando o tema do site gerado exigir explicitamente cantos mais pequenos

Button é shape="pill" por predefinição. O front-end da plataforma não deve definir explicitamente rounded, nem sobrepor os cantos 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 na escolha de negócio pill / rounded.

6. Regras de ícones

  • Ícones antes do texto utilizam leadingIcon; ícones depois do texto utilizam trailingIcon.
  • Um botão utiliza normalmente apenas um ícone auxiliar.
  • Ações conhecidas como guardar, adicionar ou voltar podem ser reforçadas com ícones, mas o ícone não substitui o texto visível de botões críticos.
  • Setas que indicam continuar, entrar ou expandir são normalmente colocadas depois do texto; ícones de voltar são normalmente colocados antes do texto.
  • Não implemente manualmente o layout de ícone e texto em children; o componente já disponibiliza slots para icon e label.
  • Utilize ícones partilhados e herde currentColor; não codifique rigidamente a cor ou o tamanho dos ícones no CSS da rota.
  • O estado de carregamento deve manter a largura e altura originais do botão e apresentar um texto curto compreensível ou o feedback de carregamento já existente; não deixe que a alteração do texto faça a barra de ferramentas saltar.

As ações e a navegação devem utilizar a semântica correta:

  • Para ações na página atual como submeter, guardar, abrir uma camada, alternar estado, utilize Button sem href, que será renderizado como <button>.
  • Para navegar para outra rota ou recurso, utilize Button com href, que será renderizado como <Link> do Next.js.
  • Botões não submetíveis dentro de formulários devem declarar explicitamente type="button"; botões de submissão devem declarar explicitamente type="submit".
  • Não utilize onClick para simular navegação normal de página.

Links desativados utilizam aria-disabled e saem da ordem de Tab; botões nativos desativados utilizam disabled. O estado desativado não pode ser expresso apenas reduzindo a opacidade; a lógica de negócio também deve impedir a ação.

8. Estados e acessibilidade

Os componentes partilhados são responsáveis de forma uniforme pelos estados hover, focus-visible, disabled e de cor. O código de negócio deve ainda cumprir:

  • O hover de botões normais não selecionados utiliza --control-surface-hover; os estados pressed, selected e expanded utilizam --control-surface-active. focus-visible mantém --focus-ring em superfícies neutras; os estilos de rota não devem fundir hover e estado persistente numa única regra azul clara.
  • O nome do botão deve ser direto, específico e indicar o que vai acontecer, como "Guardar", "Publicar site", "Eliminar item".
  • IconButton deve fornecer aria-label localizado.
  • Ícones decorativos utilizam aria-hidden="true" para evitar leitura repetida pelo leitor de ecrã.
  • O foco de teclado deve ser visível; o CSS da rota não deve remover o focus ring partilhado.
  • Não utilize o hover como única pista; a interação deve suportar simultaneamente teclado e toque.
  • Botões desativados devem ser usados apenas para ações que o utilizador 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 para a tarefa devem permanecer visíveis; o Tooltip só complementa informação, não pode ser a única forma de a descobrir.
  • Operações assíncronas devem impedir submissões duplicadas e manter um feedback compreensível de "em curso".
  • Ações perigosas utilizam danger e reutilizam o pattern de confirmação de perigo existente; não confie apenas na cor vermelha para transmitir risco.
  • O texto de botões em chinês ou noutras línguas não pode ser truncado até deixar de ser compreensível. Deve validar textos longos e a largura em mobile.

9. Limites de responsabilidade de estilos

A estrutura, semântica e estados dos botões partilhados são da responsabilidade de Button / IconButton; os tokens visuais e o CSS partilhado são da responsabilidade do pacote de componentes; a rota é responsável apenas pelo layout.

Responsabilidades da camada partilhada

  • DOM, semântica de link/botão, comportamento disabled;
  • Slots icon/label e restrições de tipo de acessibilidade;
  • Classes variant, size, shape;
  • Altura, cantos, padding, tamanho da fonte, peso da fonte;
  • Fundo, cor do texto, sombra, estados hover, focus-visible e disabled.

Responsabilidades da camada de rota

  • Direção, espaçamento, alinhamento e quebra de grupos de botões;
  • Disposição responsiva;
  • width: 100% ou largura de contentor necessária para fluxos específicos;
  • Classes de posicionamento que não alteram a visual base.

A camada de rota não deve

  • Reescrever altura, tamanho da fonte, cantos, fundo, cor do texto, sombra ou focus ring do botão;
  • Reimplementar botões partilhados com cores codificadas rigidamente ou border-radius: 999px;
  • Adicionar variantes visuais locais como primary-alt, outline-blue, icon-round;
  • Competir com o contrato do botão partilhado usando !important;
  • Copiar diretamente os estilos base de .qk-ui-button.

Se surgir efetivamente uma nova variante semântica necessária em várias páginas, deve primeiro estabelecer um contrato unificado no ButtonVariant partilhado, nos tokens e no primitives.css, 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 predefinidoDescrição
variantprimaryCamada semântica e visual
sizemdAltura, tamanho da fonte e padding horizontal
shapepillForma dos cantos de Button
leadingIconNenhumÍcone antes do texto
trailingIconNenhumÍcone depois do texto
hrefNenhumQuando fornecido, é renderizado como link
disabledfalseDesativa interação
tooltipNenhumConteúdo complementar do Tooltip partilhado; não substitui informação crítica visível nem aria-label
tooltipPlacementbottomDireção preferida; o Tooltip partilhado pode inverter para permanecer no viewport
tooltipPortaltrueRenderiza fora do contentor de recorte sem adicionar camadas de layout
skinNenhumFornece slots de classe e adaptação de variáveis conforme o contrato skeleton/skin

IconButton herda as propriedades aplicáveis de Button, mas não fornece shape, leadingIcon nem trailingIcon; exige aria-label, com valor predefinido 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 fique clara 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 submeter UI relacionada com botões, confirme:

  • Foi dada prioridade à reutilização de Button ou IconButton?
  • Os botões com texto e apenas com ícone escolheram o componente correto?
  • A área de tarefa atual tem apenas um primary claro?
  • secondary, ghost, danger são utilizados por semântica e não por preferência de cor?
  • O Button da plataforma mantém o pill predefinido e IconButton mantém a forma circular?
  • Cada Tooltip continua a ser uma camada de informação com cantos compactos, e não um botão oval clicável?
  • Foram eliminados title nativos do browser, bolhas de CSS data-tooltip, dicas duplicadas e Tooltips sinónimos de botões de texto?
  • Os tamanhos utilizam apenas sm, md, lg, com altura e tamanho da fonte consistentes no mesmo grupo?
  • Os botões nativos definem explicitamente o type correto?
  • Os ícones ocultam informação repetida do leitor de ecrã e IconButton tem aria-label localizado?
  • Os estados focus-visible, disabled, assíncrono e de confirmação de perigo estão completos?
  • O CSS da rota trata apenas do layout, sem sobrepor a visual base do botão?
  • Foram validados textos longos, tamanhos de toque e disposição de grupos de botões em larguras de 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 partilhados de botões: packages/components/src/styles/primitives.css
  • Contrato público de integração de componentes: docs/public/design/component-integration.md

Quando houver divergências entre a documentação e a implementação, o componente, os tokens, os estilos e este documento devem ser sincronizados na mesma alteração.

Nesta página