Botão
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 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 poraria-label. - Ícones pouco familiares ou de significado potencialmente ambíguo devem utilizar também o
Tooltippartilhado; o tooltip não substituiaria-label. - Não utilize o atributo DOM
titlecomo dica de produto, nem defina simultaneamentetooltipe 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
pillnem os visuais hover, pressed ou focus do botão. - Não utilize
Buttoncom texto vazio, texto oculto ou largura fixa para simularIconButton. - Não defina
shapeemIconButton; 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
Buttoncomhrefquando for necessário ênfase visual ao nível de botão.
3. Camada semântica variant
| Variante | Significado | Cenários típicos | Restrições de utilização |
|---|---|---|---|
primary | Ação principal da área atual | Guardar, publicar, criar, experimentar agora | Normalmente, apenas uma ação principal por área de tarefa |
secondary | Ação clara mas secundária | Pré-visualizar, cancelar, voltar, importar | Não deve competir visualmente com a ação principal |
ghost | Ação de ferramenta contextual com baixo ênfase | Fechar, mais, ações da barra de ferramentas, voltar de forma ligeira | Transparente por predefinição; não pode ser o único CTA crítico |
danger | Ação que elimina ou causa danos significativos | Eliminar item, remover conteúdo, limpar dados | Expressa 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:
- Identifique o próximo passo único mais importante da tarefa atual e defina-o como
primary. - Utilize
secondarypara ações secundárias que ainda devam ser claramente visíveis. - Utilize
ghostpara ações de baixo ênfase em barras de ferramentas ou contextos. - Utilize
dangerapenas 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
| 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 por predefinição, CMS, diálogos e ações regulares |
lg | 48px | 16px | CTA 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
Buttone o diâmetro deIconButtonutilizam os mesmos tokens de tamanho, pelo que podem ser alinhados na mesma barra de ferramentas; o tamanho visível do ícone emIconButtoné 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
| Forma | Aparência | Âmbito de utilização |
|---|---|---|
pill | Cantos totalmente arredondados; oval quando tem texto | Predefinição da plataforma, aplicável a páginas de marketing, Dashboard, Builder, CMS e Admin |
rounded | Cantos de 12px | Apenas 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 utilizamtrailingIcon. - 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.
7. Botões e links
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
Buttonsemhref, que será renderizado como<button>. - Para navegar para outra rota ou recurso, utilize
Buttoncomhref, 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 explicitamentetype="submit". - Não utilize
onClickpara 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-visiblemantém--focus-ringem 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".
IconButtondeve forneceraria-labellocalizado.- Í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
dangere 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:
| Propriedade | Valor predefinido | Descrição |
|---|---|---|
variant | primary | Camada semântica e visual |
size | md | Altura, tamanho da fonte e padding horizontal |
shape | pill | Forma dos cantos de Button |
leadingIcon | Nenhum | Ícone antes do texto |
trailingIcon | Nenhum | Ícone depois do texto |
href | Nenhum | Quando fornecido, é renderizado como link |
disabled | false | Desativa interação |
tooltip | Nenhum | Conteúdo complementar do Tooltip partilhado; não substitui informação crítica visível nem aria-label |
tooltipPlacement | bottom | Direção preferida; o Tooltip partilhado pode inverter para permanecer no viewport |
tooltipPortal | true | Renderiza fora do contentor de recorte sem adicionar camadas de layout |
skin | Nenhum | Fornece 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
ButtonouIconButton? - Os botões com texto e apenas com ícone escolheram o componente correto?
- A área de tarefa atual tem apenas um
primaryclaro? secondary,ghost,dangersão utilizados por semântica e não por preferência de cor?- O
Buttonda plataforma mantém opillpredefinido eIconButtonmanté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
titlenativos do browser, bolhas de CSSdata-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
typecorreto? - Os ícones ocultam informação repetida do leitor de ecrã e
IconButtontemaria-labellocalizado? - 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.