# Contrato de shape — Baluarte v1.5

## Princípio

Shape combina três decisões: **raio**, **curva** e **papel semântico**. Componentes não escolhem cantos isoladamente.

## Categorias oficiais

| Categoria | Curva | Uso |
|---|---|---|
| Rounded rectangle | `round` | inputs, textareas e superfícies neutras |
| Squircle | `squircle` | superfícies interativas de alta confiança |
| Pill | `round` + raio máximo | chips, tags e filtros |
| Circle | `round` + 50% | avatares, radio, indicadores e Icon Buttons em composições radiais governadas |

## Aplicações squircle promovidas

### Controles e navegação

- menu lateral do portal, `.b-nav__item` e `.b-entity-item` usam `--b-shape-navigation-radius` 16px com Squircle nativo e fallback rounded; o radius 8px do source é referência histórica, não substitui a assinatura de shape da família;
- `.b-nav-section__trigger` usa Squircle compacto 8px para foco/hover sem alterar a métrica do título;
- Button em todos os tamanhos e variantes;
- Icon Button usa Squircle por padrão; Circle exige `.b-composer__action.b-icon-btn--circle` dentro de `.b-composer` ou filho direto de `.b-icon-btn-context--radial`; 
- `.b-menu__item` usa `--b-shape-menu-item-radius`, mapeado ao próximo raio oficial `--b-radius-3xl` 24px para uma curva mais pronunciada; a altura par de 36px é compartilhada com a navegação lateral e produz curva efetiva aproximada de 18px; 24px continua sendo o raio semântico declarado sem migrar para pill; account e entity item permanecem no papel de navegação 16px, enquanto radio row mantém seu contrato de controle;
- picker cell/upload, paginação e ação do toast;
- controles icon-only do shell, busca, copiar e limpar.

### Superfícies interativas

- Card explicitamente interativo;
- destination card e preview do catálogo;
- swatches copiáveis;
- file tile, file card e source/link item;
- ferramenta de edição independente;
- composer conversacional como container; suas ações internas são Circle.

## Escala e tokens

A escala primitiva é curta: **4, 8, 12, 16 e 24px**, além de **pill** e **circle**. Valores 6, 10, 14, 18, 20 e 32px não pertencem mais ao fallback. Papéis semânticos podem compartilhar o mesmo raio; a curva e o contexto mantêm a distinção.

```css
--b-radius-xs: 4px;
--b-radius-md: 8px;
--b-radius-xl: 12px;
--b-radius-2xl: 16px;
--b-radius-3xl: 24px;
--b-radius-pill: 999px;
--b-radius-circle: 50%;

--b-corner-rounded: round;
--b-corner-squircle: squircle;
--b-shape-control-compact-radius: 8px;
--b-shape-navigation-radius: var(--b-radius-2xl);
--b-shape-menu-item-radius: var(--b-radius-3xl);
--b-shape-control-radius: 12px;
--b-shape-control-large-radius: 16px;
--b-shape-interactive-radius: 16px;
--b-shape-composer-radius: 24px;
```

## Migração de valores intermediários

A categoria semântica vem antes da proximidade numérica. Depois de confirmar o papel, converta 0–5→4px, 6–9→8px, 10–13→12px, 14–19→16px e 20–31→24px. Cápsulas migram para pill; círculos com lados iguais migram para circle somente quando o papel circular é permitido.

`--b-radius-sm` (6px) converge para `--b-radius-md` (8px) e `--b-radius-lg` (10px) converge para `--b-radius-xl` (12px). Não recrie aliases na escala oficial. A matriz processável está em `assets/tokens/migration-v1.5.json`; referências remanescentes bloqueiam a retirada do legado.

## Relação com o perímetro

Shape não corrige posicionamento. Quando um controle ou tile é adjacente ao canto de outra superfície, aplique também `ALIGNMENT-CHECKLIST.md`: os insets relevantes devem ter delta geométrico zero; 0,1px CSS é apenas tolerância numérica. Ajuste padding, tamanho ou layout; nunca mova a curva com offsets.

## Estados

A curva é estável em default, hover, focus, active, selected, loading e disabled. Estados podem alterar superfície, borda, cor ou conteúdo; nunca a categoria de shape.

O item lateral ativo e o hover compartilham a mesma geometria. O container do composer mantém Squircle quando a borda muda para azul em `focus-within`; o reforço é interno, não glow, e não altera a caixa. Suas ações mantêm Circle e inset 9px nas laterais/base em todos os estados.

## Fallback

```css
.component {
  border-radius: var(--b-shape-control-radius);
  corner-shape: var(--b-corner-squircle);
}
```

Navegadores sem suporte a `corner-shape` ignoram a propriedade e preservam o `border-radius`. Não use máscara SVG ou `clip-path` como fallback: eles podem comprometer borda, outline, sombra e hit area.

## Exceções

- chips, tags e filtros permanecem pill;
- avatares, radio, indicadores e `.b-icon-btn--circle` permanecem circulares;
- campos comuns e linhas `summary` dentro de containers rounded permanecem rounded rectangle;
- marcas oficiais preservam a forma do asset;
- Circle em Icon Button exige `.b-composer` ou o wrapper radial público; a classe isolada e `data-shape-role` são inválidos.

## Regras

1. Não anime `corner-shape` ou `border-radius` em hover.
2. Não aplique squircle indiscriminadamente a tabelas, inputs ou conteúdo editorial.
3. Não substitua pill e circle por aproximações squircle.
4. Mantenha foco visível, bordas e sombras acompanhando a geometria nativa.
5. Valide claro, escuro, mobile, desktop, zoom e forced colors.
6. Registre navegador, versão, `CSS.supports` e estilo computado.
7. Novas aplicações exigem specimen em Foundations antes de promoção ao core.

## Evidência computada

A consulta reproduzível vive em `scripts/audit_squircle.py`. A entrega só é aprovada quando:

- o Chromium de referência confirma `CSS.supports("corner-shape", "squircle")`;
- todos os 28 seletores promovidos visíveis computam curva e raio positivos;
- todos os interativos são classificados antes de qualquer filtro por raio;
- fallback simulado não perde raio;
- forced colors preserva shape, exclusões, classificação e indicadores de foco representativos (não substitui auditoria integral de contraste);
- pill, circle e rounded têm invariantes computados próprios; campos, mídia e superfícies neutras permanecem protegidos;
- doze capturas before/after registram navegador, viewport e tema, incluindo file tiles e file cards.

Os **28 contratos** são seletores normativos. Os **32 casos de render** são outra dimensão: oito páginas × desktop/mobile × claro/escuro.

## Specimens no portal

A taxonomia usa palcos de altura uniforme e rodapé técnico para curva/raio. Aplicações promovidas mantêm specimens reais; navegação, Button e Composer não são substituídos por ilustrações. Estados do rail são agrupados por frame expandido, colapsado e fallback, sem alterar a geometria ou o comportamento público.