Escala regular de 4 valores (sm/md/lg/xl) para superfícies e containers, 2 tokens exclusivos da família de botões (secondary e tertiary) e 6 raios dedicados à família da tecla — componentes da mesma família compartilham o mesmo raio.
Princípio
A escala regular tem 4 valores: --radius-sm (8px), --radius-md (16px), --radius-lg (24px) e --radius-xl (32px). Esses tokens governam cards, containers e inputs — nunca mais de 3 aparecem ao mesmo tempo no produto. Os botões secondary e tertiary têm raios próprios (--radius-button-md 12px e --radius-button-lg 20px) que não se generalizam para outros componentes. A tecla é família à parte: seus 6 raios dedicados existem para sustentar o volume físico de três camadas e também não se generalizam.
Escala regular
Os 4 valores cobrem todas as superfícies de produto fora da família da tecla.
sm — 8px
Chips de estado funcional, badges, code inline e ajustes internos de componente. Um input dentro de um card também pode usar --radius-sm quando o card-pai estiver em --radius-md — o filho desce um degrau na escala, nunca sobe.
--radius-smToken: --radius-sm · Valor: 8px
md — 16px
Inputs (Search Field, campos de formulário), callouts e containers menores dentro de seções. É o raio de entrada padrão: quando um componente vive dentro de outro, --radius-md é o ponto de partida antes de descer para --radius-sm.
--radius-mdToken: --radius-md · Valor: 16px
lg — 24px
Commitment Card, cards secundários do dashboard, wrappers de tabela e containers de contraste. É o raio dos cards-filhos quando o card-pai usa --radius-xl — um degrau abaixo, hierarquia visível sem precisar de cor ou peso extra.
--radius-lgToken: --radius-lg · Valor: 24px
xl — 32px
Balance Card, Quick Actions Card e cards dominantes da área principal do dashboard. É o raio de maior abertura da escala regular — reservado para as superfícies que ocupam o topo da hierarquia visual da tela.
--radius-xlToken: --radius-xl · Valor: 32px
Raios dos botões (secondary e tertiary)
Os botões de camada plana (secondary e tertiary) têm dois tokens de raio exclusivos que não se aplicam a cards, containers ou inputs. Os valores são mais generosos que a escala regular equivalente — 12px em vez de 8px no tamanho md e 20px em vez de 24px no tamanho lg — para calibração visual adequada ao touch target e ao perfil de arredondamento de botão.
Button md — 12px
Aplicado nos botões secondary e tertiary de altura 40px. Valor entre --radius-sm (8px) e --radius-md (16px) — não pertence à escala regular, é token de família.
Token: --radius-button-md · Valor: 12px
Button lg — 20px
Aplicado nos botões secondary e tertiary de altura 64px. Valor entre --radius-md (16px) e --radius-lg (24px) — calibrado para a superfície maior sem chegar ao arredondamento de card.
Token: --radius-button-lg · Valor: 20px
Raios da tecla (V-B)
A tecla é família própria: 6 raios dedicados (large e compacta) que não se generalizam para nenhum outro componente. Os valores 18px e 14px dos sockets são exceções aceitas à regra de múltiplos de 4 — origem documentada na Story B.5 (Figma, 2026-04-21) e registrada no callout abaixo.
O raio decresce em passos de 2 e 4 pixels entre camadas (socket → rim → cap): na large, 18px → 16px → 12px; na compacta, 14px → 12px → 8px. A progressão não é uniforme por design — o passo de 2px entre socket e rim é sutil (o rim precisa parecer encaixado, não separado), e o passo de 4px entre rim e cap acentua o recuo do cap para dentro da cena, sustentando a ilusão de volume físico em três camadas.
Tecla large
Socket em --radius-tecla-socket (18px, oddball documentado), rim em --radius-tecla-rim (16px), cap em --radius-tecla-cap (12px). Passos: socket→rim = 2px; rim→cap = 4px.
- Socket
- —
--radius-tecla-socket·18px - Rim
- —
--radius-tecla-rim·16px - Cap
- —
--radius-tecla-cap·12px
Tecla compacta (md)
Socket em --radius-tecla-md-socket (14px, oddball documentado — par proporcional do 18px da large), rim em --radius-tecla-md-rim (12px), cap em --radius-tecla-md-cap (8px = --radius-sm). Passos: socket→rim = 2px; rim→cap = 4px. O cap coincide com --radius-sm, o que permite alinhar a tecla compacta com .btn na mesma linha de UI sem criar token extra.
- Socket
- —
--radius-tecla-md-socket·14px - Rim
- —
--radius-tecla-md-rim·12px - Cap
- —
--radius-tecla-md-cap·8px
Tokens
12 tokens: 4 da escala regular, 2 da família de botões, 6 da família da tecla. Valores completos em design-system/tokens/tokens.css.
| Token | Valor | Família | Papel |
|---|---|---|---|
--radius-sm | 8px | Regular | Chips, badges, code inline, componentes internos de card |
--radius-md | 16px | Regular | Inputs, Search Field, callouts, containers menores de seção |
--radius-lg | 24px | Regular | Commitment Card, cards secundários, wrappers de tabela, containers de contraste |
--radius-xl | 32px | Regular | Balance Card, Quick Actions Card, cards dominantes do dashboard |
--radius-button-md | 12px | Botão | Secondary e tertiary tamanho md (40px) |
--radius-button-lg | 20px | Botão | Secondary e tertiary tamanho lg (64px) |
--radius-tecla-socket | 18px (oddball) | Tecla large | Camada exterior (socket) da tecla large |
--radius-tecla-rim | 16px | Tecla large | Camada rim (borgonha) da tecla large |
--radius-tecla-cap | 12px | Tecla large | Camada cap (âmbar) da tecla large |
--radius-tecla-md-socket | 14px (oddball) | Tecla compacta | Camada exterior (socket) da tecla compacta |
--radius-tecla-md-rim | 12px | Tecla compacta | Camada rim (borgonha) da tecla compacta |
--radius-tecla-md-cap | 8px (= --radius-sm) | Tecla compacta | Camada cap (âmbar) da tecla compacta; coincide com --radius-sm |
Regras de uso
- Escala regular de 4 valores: sm (8px) / md (16px) / lg (24px) / xl (32px). Todo componente fora da família da tecla usa um desses 4 valores. Sem intermediários, sem valores ad hoc.
- Máximo 3 valores em uso simultâneo no produto. Se uma tela já usa sm, md e xl, lg não entra — a hierarquia fica nos 3 valores presentes. Mais de 3 fragmenta a leitura e sinaliza decisão aleatória, não escala.
- Componentes da mesma família usam o mesmo raio. Todos os Commitment Cards de uma listagem ficam em
--radius-lg. Todos os Balance Cards ficam em--radius-xl. Raio diferente dentro de uma família é violação — não decisão de ênfase. - Card e input dentro do mesmo card compartilham a escala — input pode ser 1 degrau abaixo. Um input dentro de um card
--radius-xlusa--radius-lg, não--radius-sm. Saltar mais de um degrau quebra a coerência do container. - Raio 100% (círculo) só em avatar ou indicador de status. Círculo tem papel funcional específico — sinaliza identidade ou estado pontual. Aplicado em card ou botão, vira ornamento e perde o papel funcional.
- Raios da tecla são exceção documentada — não generalizar para outros componentes. Os 6 tokens da família da tecla (incluindo os oddballs 18px e 14px) existem para sustentar o volume físico de três camadas. Usar
--radius-tecla-socketem um card comum é violação — o nome do token é o contrato.
Anti-padrões referenciados
Anti-padrões com relação direta a decisões de raio. O arquivo-fonte está em .claude/ui-design/anti-patterns.md. Links permanentes serão atualizados quando a seção de anti-padrões visuais for publicada.
- #11 — Raio inconsistente entre componentesUsar valores de raio diferentes em componentes da mesma família ou dentro de um mesmo container — card com
--radius-xlcontendo input com--radius-smcontendo ícone com--radius-md. Três raios sem escala coerente produzem ritmo quebrado; o olho registra que os cantos não rimam. Solução: escala disciplinada de 2–3 valores por tela, com filho sempre 1 degrau abaixo do pai. - #12 — Espaçamento fora da escala estrutural (exceção óptica aceita)Usar valores de raio fora da escala estrutural (múltiplos de 4) sem justificativa documentada — 13px, 18px, 22px por ajuste visual informal. O problema não é o valor em si: é a ausência de origem. Os oddballs 18px e 14px da tecla são aceitos exatamente porque têm origem documentada (Figma, Story B.5, 2026-04-21) e ficam contidos na família da tecla. Um 18px aparecendo em card genérico sem documentação é violação do mesmo anti-padrão.
Consultar .claude/ui-design/anti-patterns.md na íntegra para demais anti-padrões visuais.