Button
import { Button } from '@rivocode/ui'Quando usar
Ação. Sai como <button> nativo, e vira <a> com render={<a href="..." />}.
Quando usar cada variante. primary para a ação principal da tela, uma só por
área. secondary para a alternativa. outline para chamada secundária de página
de marketing. ghost para ação discreta em tabela ou cabeçalho. danger
para o que apaga, e só para isso. variant="ghost" com tone="danger" é o
mesmo destrutivo na forma discreta: o "Excluir" da linha da tabela, do rodapé de um cartão ou do
cabeçalho do registro, ao lado de outros ghost, onde o vermelho cheio
gritaria mais que a ação principal da tela.
<Button size="sm" variant="ghost" tone="danger">
<Trash2 aria-hidden="true" />
Excluir
</Button>
O texto é danger-text, e sob o ponteiro e no clique o fundo vira
danger-subtle; os dois pares estão medidos a 4,5:1 nos dois temas, sobre a
página, o cartão e o cartão levantado (check:contrast). A confirmação do
excluir continua sendo variant="danger" dentro do AlertDialog ou do
Popconfirm: o fantasma é o gatilho, e não a decisão. O tone só muda o
ghost; nas outras variantes ele não pinta nada, porque o destrutivo cheio já
é danger. O IconButton aceita o mesmo par, para o ícone de lixeira da
linha.
Tamanho. sm, md e lg leem a altura do token de densidade, então encolhem
sozinhos no modo compacto. xl é de marketing: maior, com medida própria, que
não encolhe no compacto. Ele é só tamanho, como os outros três: o peso continua
o médio da casa. Para o negrito de uma chamada, some className="font-rc-bold".
Botão só com ícone é IconButton. Ele exige label, que vira o nome
acessível, tem os três tamanhos quadrados lidos do token de controle, troca o
ícone pela espera em loading sem alargar e mostra o label como dica com
tooltip. O Button não tem tamanho quadrado: o quadrado só existe no
IconButton, e é ele que cobra o nome.
O ícone ao lado do texto sai no tamanho do botão. Todo SVG de dentro vira
14px no sm, 16px no md e 18px no lg e no xl, então o ícone do lucide
entra sem size: o padrão dele, 24px, deixava o botão grosso.
<Button size="sm" variant="danger">
<Trash2 aria-hidden="true" />
Excluir
</Button>
Forma. O padrão do produto é o canto de 8px. shape="pill" é assinatura de
marketing, não de formulário.
loading desabilita e anuncia ocupado.
Desabilitado. disabled pinta o fundo de surface-raised, o rótulo de
fg-disabled e o contorno de border-disabled, em toda variante que tem
contorno ou preenchimento: primary, secondary, outline e danger.
Sem o contorno, o botão desabilitado sobre superfície branca virava rótulo
solto, porque no tema claro surface-raised e surface são o mesmo branco. O
contorno de inativo é mais fraco que o vivo (o check:contrast cobra que o
vivo pese 1,4 vez mais), então ele não parece clicável. primary e
danger já nascem com borda transparente de 1px, para o tamanho não
pular ao desabilitar. ghost continua sem contorno, nos dois tons: vivo, ele
nunca teve.
Link desabilitado. Com render={<a href="..." />} e disabled ou
loading, o link perde o href, ganha aria-disabled="true", para de receber
o ponteiro e não chama o onClick: <a> não tem disabled nativo, e sem isso
ele continuaria navegando.
Quando não usar
Para ir a outra página ou outro site, use Link: o Button age, e o Link
navega, sublinhado e no tom do texto.
Botão só com ícone é IconButton, que cobra o nome. Modo que fica apertado,
como o negrito, é Toggle, que diz aria-pressed. E ações irmãs encostadas
são ButtonGroup.
No React Native
Traduz, com o contrato controlado e o hitSlop no sm, porque 32px de alvo não se toca sem ajuda. Afunda de leve no toque, e não afunda quando o sistema pede para reduzir movimento.
O ícone entra por icon, e não como filho. No web o SVG de dentro sai no tamanho do botão sozinho; aqui a cor não desce da View para o SVG, então a forma que pinta certo é a função, que recebe a cor da variante e o tamanho (14, 16 ou 18): icon={({ color, size }) => <Plus color={color} size={size} />}. iconPosition="end" leva o ícone para depois do rótulo, a seta do "Continuar". O ícone é escondido do leitor de tela, e some durante o loading, que ocupa o lugar dele.
O filho texto é embrulhado num Text, e o resto entra como está. Texto quebrado por expressão (Enviar {n} notas) vira um Text só; classNames.label veste esse Text.
tone="danger" é o vermelho sem preenchimento: a ação destrutiva que não é a principal da tela, como "Excluir conta" no fim de um formulário. O mesmo nome e o mesmo comportamento do web: vale só com variant="ghost", e nas outras variantes o tone não muda nada; o vermelho cheio continua sendo variant="danger", e o IconButton herda o tone. O rótulo é danger-text, medido pelo gate sobre bg, surface e, sob o dedo, sobre danger-subtle.
API
| Prop | Tipo | Padrão |
|---|---|---|
loading0.4.0Desabilita e anuncia ocupado enquanto uma acao esta em andamento. | boolean | false |
ref0.4.0 | Ref<HTMLButtonElement> | sem padrão |
render0.4.0Troca o elemento renderizado mantendo a aparencia. | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
shape0.4.0 | "default""pill"null | sem padrão |
size0.4.0 | "lg""md""sm""xl"null | sem padrão |
toneO tom do `ghost`: `danger` escreve em `danger-text` e, sob o ponteiro e no clique, pinta `danger-subtle` - o destrutivo discreto da linha da tabela, ao lado de outros `ghost`. | "danger" | "neutral" | sem padrão |
variant0.4.0 | "danger""ghost""outline""primary""secondary"null | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.