Spec — Component Semantic Groups

A camada que faltava tinha nome errado. Um Design System na Koder Stack tem duas metades de representação: (1) tokens — resolvida por DTCG + dsimport + design-gen; e (2) estilo/anatomia de componente — qual raio o botão usa, se o card tem elevação por sombra ou por borda, qual densidade, quais estados. A metade (2) não está no token primitivo e, até esta spec, não tinha lugar declarado: virava CSS lido à mão e widget Rust portado à mão. Esta spec nomeia essa camada e diz onde ela mora.

1. Posição na escada (por que NÃO é formato nem linguagem nova)

policies/language-and-format-creation.kmd manda escolher o degrau mais baixo que resolve. Aplicado aqui:

• R6 — padrão externo antes de inventar. DTCG (W3C Design Tokens) é o padrão adotado da Stack. Estilo de componente que é escalar/valor (raio, espaço, cor, sombra por-papel) cabe em DTCG como um grupo semântico. Logo, a camada é convenção sobre DTCG (degrau 1–2), não um formato (4) nem uma linguagem (5).
• R1#1 — vocabulário fechado? O vocabulário de papéis de componente (button, field, card, tag, …) é semi-aberto e ainda está se descobrindo — cada DS externo importado revela papéis novos. Vocabulário não fechado proíbe subir pra formato/linguagem dedicada; obriga ficar no degrau 2.
• R2 — dois consumidores. Um artefato de degrau ≥4 exige dois consumidores independentes já identificados. Hoje há um: gov.br. Enquanto for um, a camada é estrutura interna do import do gov.br, não formato próprio da Stack.

Conclusão normativa: estilo de componente por-DS SHALL ser expresso como grupos *.semantic no DTCG overlay do DS. Criar linguagem/formato dedicado pra isso está vetado até o gatilho de promoção da §4 disparar.

2. Onde mora e quem é a autoridade (R3 — um caminho por verdade)

tools/design-gen/design-systems/<slug>/
  tokens.upstream.dtcg.json   # snapshot externo (primitivos) — importado, read-only
  tokens.overlay.dtcg.json    # curadoria local — AQUI vivem os grupos *.semantic
  tokens.dtcg.json            # publicado = upstream ⊕ overlay (gerado, nunca à mão)

• Fonte da verdade do estilo de componente = o grupo *.semantic em tokens.overlay.dtcg.json do DS. É curadoria local (não vem do upstream primitivo), então mora no overlay por definição do modelo de proveniência (design-RFC-007/014).
• O CSS de componente do DS externo (ex.: @govbr-ds/core core.min.css) é evidência upstream, não autoridade: dele se extrai o valor (medido, nunca adivinhado), e o valor extraído é gravado no overlay. Divergência entre o CSS externo e o overlay resolve-se a favor do overlay (é a decisão de curadoria Koder), e registra-se a extração.
• A prosa em specs/components/<slug>.kmd descreve o componente para humano/IA; o valor efetivo de estilo por-DS é o *.semantic. Não duplicar o número na prosa.

3. Vocabulário emergente (estado atual — cresce com evidência)

Papéis já descobertos (extraídos MEDIDOS do gov.br v3.7 — épico #219, 2026-07-16):

pill/full é a lição de escopo: um papel de componente pode exigir um valor conceitual (pill = "totalmente arredondado") que a escala numérica de token não expressa. Novos papéis/valores conceituais entram AQUI conforme o import de cada DS os revelar — é exatamente essa descoberta incremental que a §4 está coletando antes de investir num extrator.

4. Deferral — o extrator automatizado é gated pelo 2º DS externo

Hoje a extração CSS de componente → grupo *.semantic no overlay é manual, por componente, dentro do épico do gov.br (#219 + govbr-ds-parity). Isso é correto por ora: é a instância deliberada de coleta de evidência que fecha o vocabulário da §3.

SHALL NOT construir um extrator/importador automatizado de estilo de componente enquanto gov.br for o único consumidor (R2 não satisfeito; "regra dos 3" de Meta-First). O trabalho fica especificado-não-construído no ticket tools/design-gen#249 (gated_by: evidence-soak).

Gatilho de promoção (quando construir): o 2º DS externo que exija a mesma extração (candidatos: Material 3, USWDS, Fluent) — nele, o custo de porte manual se repete, R2 passa, e o extrator (degrau 2: estender dsimport para popular grupos *.semantic a partir do CSS/tokens de componente externos) ganha justificativa. Teto: degrau 2 — mesmo então, não se inaugura linguagem.

R4 — registro: quando o extrator (ou qualquer artefato consumível novo) nascer, registrá-lo em registries/languages-and-formats.md no mesmo PR. Esta camada, por ser convenção sobre a linha "Design tokens" já inventariada, não abre linha nova enquanto for só convenção.

5. Relação com o manifesto de DS

O manifesto (specs/design-system/manifest.kmd) já tem [components].provides — os slugs de componente que um DS provê/override. Esta spec diz o que é o override no nível de estilo: os grupos *.semantic do overlay. kind = "look-only" ⇒ sem *.semantic próprios (herda Verge); kind = "full" com diferença estrutural ⇒ *.semantic próprios no overlay. gov.br (kind = full, maturity = preview) é o caso de referência.