Button

Overview

Button é o click target mais elementar do KDS. Toda interação que dispara uma ação — submit de formulário, abrir um Dialog, confirmar um item da lista — passa por ele. Internamente é um <button> estilizado por class-variance-authority, com seis variantes visuais (default, destructive, outline, secondary, ghost, link) e oito presets de tamanho — quatro textuais (xs a lg) e quatro icon-only para botões quadrados em toolbars e linhas de tabela.

A escolha da variante é uma escolha de hierarquia visual antes de ser estética. Cada superfície carrega no máximo uma ação primária — o default. Tudo mais é secundário (outline, secondary, ghost) ou intencionalmente cauteloso (destructive).

Anatomy

<Button variant="default" size="default">
  ├─ [data-slot="button"]
  ├─ [data-variant="default"]
  ├─ [data-size="default"]
  └─ children (texto + ícones lucide opcionais)
</Button>

Atributos de dado (data-variant, data-size) estão expostos para CSS custom downstream sem hack de classes. asChild permite renderizar como um <a>, <Link> do Next, ou qualquer outro elemento — útil para que um link se comporte visualmente como botão sem perder semântica de navegação.

Usage

import { Button } from "@kalvner/kds/forms/button";

export function Example() {
  return <Button onClick={() => save()}>Salvar</Button>;
}

Props

Variants

States

Composition

Para ações de alto impacto — Excluir conta, Apagar workspace — não basta um destructive: peça que o usuário digite o nome do recurso em um Dialog antes de habilitar o botão. O Dialog ainda não está no KDS, mas o padrão de stakes (low / high) ditará o gating.

When to use

• Disparar uma ação imediata (submit, salvar, abrir, navegar via JS).
• Apresentar uma escolha primária + alternativas (form footer, dialog).
• Comandos em toolbars — use size="icon" com aria-label claro.

When not to use

• Para navegação pura entre páginas, prefira <a> ou <Link> — só troque para <Button asChild> se precisar do estilo de botão na navegação.
• Para alternar uma configuração de efeito imediato (notificações on/off), use Switch.
• Para selecionar entre múltiplos valores, use RadioGroup ou Select.

Best practices

• Uma ação primária por superfície. Se você está com dois botões default no mesmo card, um deles deveria ser outline ou ghost.
• Ordem ocidental nos rodapés. Cancelar à esquerda, confirmar à direita. O olho percorre da esquerda para a direita até o commit.
• Destrutivo nunca é a escolha mais fácil. Posicione longe da ação primária, sempre confirme em um Dialog para itens críticos.
• Loading desabilita. Trocar texto por spinner sem desabilitar abre brecha para duplo envio.
• Não use cores fora do token. Botões coloridos out-of-token quebram a hierarquia. Cite [[ui/colors/pure-white-black-avoid]] — nunca um bg-white puro mesmo em contraste.

Accessibility

Related

• Form — wrappers de react-hook-form que combinam Button no rodapé.
• Input — frequente companheiro nos formulários.
• Switch — para efeito imediato em vez de submit.