---
fonte: 02-tokens/seed-tokens.md
versao_da_fonte: v1.23
secao: 03
titulo: "Camada 2 — Semânticos (light + dark)"
sequencia: 4 de 17
bytes_do_corpo: 16814
md5_do_corpo: ba0667bc941da53e618fdc9918534b9f
gerado_por: 06-validacao/geradores/gen-camada-ia.py
nota: fatia GERADA — o corpo abaixo é byte a byte o trecho do canônico; edite o canônico, nunca esta fatia. Canônico inteiro em https://ds.seed.eng.br/02-tokens/seed-tokens.md
---
## 3. Camada 2 — Semânticos (light + dark)

Grupos entregues (valores completos no JSON/CSS): `surface` (page, subtle, raised, sunken, overlay, brand, brand-deep, inverse) · `text` (primary, secondary, muted, disabled, brand, inverse, on-brand, link) · `border` (subtle, default, strong, focus, interactive — v1.12) · `action` (primary±hover/active, secondary, ghost, destructive) · `feedback` (success/warning/danger/info × bg/text/border/solid) · `chart` (cat-1…6, positive, negative, grid, axis).

Decisões dignas de registro:

- **`action-primary` light = turquesa-600 (verde institucional).** Dark = turquesa-300 com texto turquesa-900 (7.39:1) — padrão moderno de "fill claro + texto escuro" no dark, em vez de escurecer o botão.
- **`text-primary` = **#0B3330** *(v1.9 — SUPERSEDE de `cinza-900 #242E34`)*.
  A v1.0 superseava o `#2a3942` ad-hoc do HTML v1; a **v1.9 tinge a tinta na família da marca**.

> ### NORMALIZAÇÃO DO `focus-ring` — v1.10 (2026-08-14)
>
> **O que muda:** nada de valor. O `--seed-focus-ring` do tema **claro** deixa de consumir o
> primitivo `--seed-branco` e passa a consumir o semântico `--seed-surface-page`, que é o que o
> bloco **escuro** já fazia. `surface-page` claro **é** `#FFFFFF`, então a cor renderizada é
> idêntica — o que muda é a EXPRESSÃO.
>
> **Por que importa, e o achado veio de fora:** os previews `componentes` e `tokens` já usavam
> `surface-page` nos DOIS temas, e a guarda `paridade-previews.py` os acusou de divergir do gêmeo.
> Ao apurar, **eles estavam mais corretos que o canônico**: um token semântico composto não deve
> depender de primitivo, e ter expressão diferente por tema para o mesmo papel é a porta por onde
> um tema envelhece sem o outro. Quem se ajustou foi o gêmeo.
>
> **Efeito colateral bom:** o `--seed-branco` deixa de ser exigido por qualquer preview que embuta
> o `focus-ring`. A pendência de `--seed-branco` sem definição em `formfield` **fecha por
> consequência**, sem precisar acrescentar token.
>
> ### COMPOSIÇÃO E CHROME — v1.11 (2026-08-14 · CP-P3, executa o SUP-6 em escopo mínimo)
>
> **Contexto para leitor novo:** o gate visual da Fase 2 da composição (2026-08-14, vereditos
> G1–G5 registrados no `seed-composicao.md` §11) adotou o **gradiente do rail** (CP20, G2),
> aprovou a **paleta de entidade** (CP23, G3) e o **marcador de "agora"** (CP24, G4). A adoção do
> gradiente disparou o gatilho do SUP-6 (hover/pressed em cinza sólido falham sobre superfície
> gradiente), resolvido aqui em **escopo mínimo**: dois tokens de overlay, não a rampa alpha
> completa do C27 (custo declarado dela: valores a olho, reauditados a cada superfície — e o CP20
> proíbe gradiente fora do chrome, então só existe UMA superfície gradiente no sistema).
>
> **Os quatro grupos são INVARIANTES DE TEMA — nenhum se redeclara no bloco dark dos gêmeos**, e
> cada um declara aqui o seu par light/dark (que é o mesmo valor) com o porquê:
>
> | Token | Valor (light = dark) | Por quê invariante | Medido |
> |---|---|---|---|
> | `--seed-rail-background` | `linear-gradient(180deg, #006C62 0%, #005048 100%)` (`turquesa-700 → turquesa-800`) | **Por DECISÃO** — SH15: chrome não segue o tema; CP20 exige semântico próprio, senão o tema escuro vira regra manual (o ClickUp escreveu 22 regras à mão) | Branco sobre os **dois extremos**, não na média: **6,32** e **9,37** (≥4,5) |
> | `--seed-chrome-overlay-hover` | `rgba(255, 255, 255, 0.12)` | **Por CONSTRUÇÃO** — compõe sobre superfície invariante (o rail) | Rótulo branco sobre a **COMPOSIÇÃO** (overlay composto sobre cada extremo): **4,88** e **6,82** (≥4,5) |
> | `--seed-chrome-overlay-active` | `rgba(255, 255, 255, 0.14)` | Idem. É o estado **pressionado**; o item ATIVO (`aria-current`) segue sendo a pílula clara do SH15-b | Branco sobre a composição: **4,68** e **6,50** (≥4,5) |
> | `--seed-entity-1…6` + `--seed-entity-N-ink` | E1 `#11B0A0`+`#242E34` · E2 `#D49400`+`#242E34` · E3 `#01B3E0`+`#242E34` · E4 `#005048`+`#FFFFFF` · E5 `#006783`+`#FFFFFF` · E6 `#7B5500`+`#FFFFFF` | **Por CONSTRUÇÃO** — o par medido é interno ao chip (fundo × tinta) e não inverte com o tema; o CP23 define **um hex por posição** | Admissão CP22 (≥4,5 com a tinta declarada): **5,11 · 5,30 · 5,63 · 9,37 · 6,43 · 6,68** |
> | `--seed-marker-now` | `#098475` (`turquesa-600`) | **Por DECISÃO** — CP24: terceiro membro nomeado da classe invariante de tema (SH15 · DG12 · CP24) | ≥3,0 (non-text) contra as cinco superfícies canônicas: **4,60 · 4,23 · 4,05 · 3,72 · 3,31** |
>
> **Decisões de forma, com as alternativas descartadas:**
> **(a) Tinta POR POSIÇÃO** (`entity-N-ink`), não só o par `ink-dark`/`ink-light` com mapa em
> prosa: consumidor que precisa saber um mapeamento de cor é exatamente a classe de defeito que
> produziu a E-CP-01 (artefato consumindo a escala errada). Custo: 6 tokens a mais; ganho: o
> consumo vira `background: var(--seed-entity-3); color: var(--seed-entity-3-ink)` sem decisão local.
> **(b) NÃO redeclarar os invariantes no bloco dark** (nem no espelho `prefers-color-scheme`):
> redeclarar valor idêntico é duplicação, e duplicação é o vetor de deriva que os gêmeos existem
> para matar — quem editar um bloco e esquecer o outro criaria divergência silenciosa. No JSON,
> os quatro grupos ficam **sem `seed.mode` de propósito** (a ausência declara a invariância; a
> guarda `paridade-tokens.py` G2 pula a exigência de bloco dark exatamente nesse caso).
> **(c) Overlays em vez da rampa alpha do C27**: veredito do gate registrado no MANIFESTO v6.7 —
> a rampa completa segue adiada porque só o chrome admite gradiente.
> **(d) Os alphas .12/.14 não foram inventados**: são os dois valores que os artefatos aprovados
> já praticavam (o shell no hover; o preview da composição no ativo do gate), fixados **depois**
> da medição em composição — a quinta camada existe porque par isolado verde já escondeu 1,48.
>
> **Fronteira (mesma do CP23/PN7):** o DS declara o MECANISMO de identidade; **qual entidade usa
> qual posição** vem do PRODUTO, via `data-ident="1..6"`. Acima de 6 entidades repete-se a cor e
> distingue-se pelo **glifo** (nunca letra — decisão do MANIFESTO v6.4, mantida); nunca nasce uma
> sétima cor.
>
> ### `border-interactive` — v1.12 (2026-08-14 · FECHA A PENDÊNCIA SH-P1/PN-P5)
>
> **Contexto para leitor novo:** a SH-P1 nasceu no bloco 6A (2026-08-11), achada pelo
> `contraste-shell.py`: **nenhum token semântico de borda passava 3:1 contra `surface-raised`
> no tema claro** — `border-default` mede 1,49 e `border-strong` 2,53 — e o campo de busca do
> shell consumia o **primitivo `cinza-500`** por *empréstimo declarado*, violando a lei
> "componente consome semântico". O CP17 já havia fechado a metade "separação de peça" da
> pendência (separação virou tarefa do par sombra+anel); restava a metade menor: **fronteira de
> componente interativo** (SC 1.4.11, piso 3:1). A regra GI2 mandava fechá-la "quando a camada 2
> fosse editada por outro motivo" — o motivo foi a CP-P3 (v1.11), e o Rafael decidiu fechar na
> mesma janela (2026-08-14: *"vamos resolver logo"*).
>
> **O token:** `--seed-border-interactive` = `cinza-500` `#788F9D`, **nos dois temas**, medido
> contra as seis superfícies onde borda de componente aparece: raised/page/subtle claro
> **3,38 / 3,38 / 3,11** · raised/page/subtle escuro **4,50 / 5,51 / 5,05** — todos ≥3,0.
> **Não é invariante de tema:** o slot dark fica declarado (o valor idêntico hoje é
> *coincidência medida*, não lei — o dark pode divergir no futuro sem mudar a expressão),
> diferente dos quatro grupos da v1.11, invariantes por decisão ou construção.
>
> **Alternativa descartada, com o número:** `cinza-600` `#617683` também passa as seis
> (3,21–4,74) — mas mudaria a cor **renderizada** que o gate visual do shell já aprovou, sem
> nenhum motivo além da troca: a pendência pedia promoção de **expressão** (primitivo →
> semântico), não de valor. Mesma lógica da normalização do `focus-ring` na v1.10.
>
> ### `row-selected-*` — v1.13 (2026-08-15 · F7.2 · fecha uma lacuna que o sistema já vivia)
>
> **Contexto para leitor novo:** ao produzir o gabarito A2 (`tela-lista.html`), a linha
> selecionada foi pintada com o primitivo `turquesa-100`. O `contraste-f72.py` reprovou:
> **1,57** no tema escuro. A causa é estrutural, não de escolha — **um primitivo é fixo, e
> realce de seleção precisa virar por tema**, senão reprova sempre em um dos dois lados.
>
> Ao procurar o semântico certo, o achado: **a bancada `banco-dados.html` já consumia
> `--seed-row-selected-bg`, `-text` e `-border` desde a Fase 3 — com definição LOCAL, dentro
> do próprio arquivo, ausente deste gêmeo.** O nome existia no sistema sem dono no canônico.
> Não era drift de valor, era drift de PROPRIEDADE: enquanto o token não é do gêmeo, cada
> artefato que precisar dele reinventa o valor, e ninguém mede o par.
>
> **Os tokens** (adição pura — nenhum valor anterior muda; os hex são exatamente os que a
> bancada já usava, para que a promoção não altere um pixel do que o gate já aprovou):
>
> | Token | Claro | Escuro | Papel |
> |---|---|---|---|
> | `--seed-row-selected-bg` | `#E8FBF7` (turquesa-50) | `#00352F` (turquesa-900) | fundo da linha selecionada |
> | `--seed-row-selected-text` | `#242E34` (cinza-900) | `#E3EBF0` (cinza-100) | tinta sobre o realce |
> | `--seed-row-selected-border` | `#098475` (turquesa-600) | `#66D1C2` (turquesa-300) | marcador de 3px na borda da linha |
>
> **Medido:** `bg × text` = **12,53** claro / **11,12** escuro (piso 4,5) · `border × bg` =
> **3,42** / **4,64** (piso 3,0 — o marcador é elemento de interface, SC 1.4.11).
>
> **Alternativa descartada:** manter o realce como primitivo e escrever a exceção do tema à
> mão em cada artefato — que é literalmente o que o CP20 alerta e o que a `tela-lista.html`
> fazia antes desta edição. **Guarda:** `paridade-tokens.py` ganhou quatro verificações,
> incluindo uma que exige que o `bg` **mude entre os temas** — realce fixo é o defeito, não a
> ausência do token. A guarda foi provada real: rodada contra o CSS v1.12, reprova em 7.
>
> ### SUPERSEDE DA TINTA DE TEXTO — v1.9 (2026-08-13)
>
> **O que muda:** os três tokens de tinta de CONTEÚDO passam da família cinza para a família
> turquesa da marca, nos dois temas. **Bordas, superfícies e a régua de ação NÃO mudam.**
>
> | Token | Antes (claro/escuro) | Agora (claro/escuro) | Croma | Pior contraste |
> |---|---|---|---:|---|
> | `text-primary` | `#242E34` / `#E3EBF0` | **#0B3330** / **#DDECE8** | 0,063 → **0,157** | 11,49 → **11.37** |
> | `text-secondary` | `#4D606C` / `#ACBECA` | **#2F5A54** / **#A3C4BE** | 0,122 → **0,169** | 5,43 → **6.42** |
> | `text-muted` | `#788F9D` / `#90A6B3` | **#40706A** / **#8FB5AD** | 0,145 → **0,188** | **2,80 (reprovava)** → **4.65** |
>
> **POR QUÊ.** O `estudo-viver-de-ia.md` §2.1 mede a tinta de texto da plataforma em
> **#0A1F3B — croma 0,192**, declarada como *"navy-tinta, não preto puro, MESMA FAMÍLIA do escuro
> estrutural"*. Como texto e borda ocupam a maior parte da área de qualquer tela, tinta neutra faz
> a tela inteira ler cinza mesmo com a âncora colorida — foi o achado do gate do Rafael em
> 2026-08-13. Os valores adotados ficam em **82% e 88% do croma da referência**: mesma família, na
> mesma intensidade, sem exagero.
>
> **O QUE FOI DESCARTADO, com o número que descartou.**
> **(a) Usar primitivos existentes da escala** (`turquesa-900` + `turquesa-700`): o secundário
> daria croma **0,424 — 2,2× o da referência**. Deixaria de ser tinta discreta e viraria verde
> forte; serve a título, não a corpo de texto.
> **(b) Esverdear BORDAS e SUPERFÍCIES**, como a 1ª redação da proposta previa: **a plataforma não
> faz isso** — as bordas dela medem croma 0,027/0,031 e a página é **branco puro**; o próprio
> estudo diz que *"a sensação de cinza claro vem só das bordas e sombras"*. E há razão nossa,
> medida: a âncora do painel é **cromática**, e o mecanismo **P4** (ritmo neutro↔cromático) depende
> de a página ser neutra. Contra `surface-sunken` esverdeada a âncora cairia de **2,71 para 2,21**,
> e a série `chart-cat-1` cairia junto — perderíamos contraste de saturação exatamente no único
> elemento que precisa dele.
>
> **SUPERSEDE FORMAL DA RESTRIÇÃO "NENHUM HEX NOVO".** Os quatro valores de tinta não existem na
> escala de primitivos. Eles entram como **valores SEMÂNTICOS — nunca como primitivos** —, e os
> **8 hex canônicos da paleta 2018 seguem intocados**, que é a lei do `marca-seed.md`. Precedente
> exato: a **escala categórica estendida** fez este mesmo supersede na v1.6 destes gêmeos.
>
> **ERRATA FECHADA NA MESMA EDIÇÃO (regra GI2): o `text-muted` REPROVAVA no canônico vigente.**
> `#788F9D` (cinza-500) é declarado para *"metadados, placeholders, captions"* — texto pequeno,
> piso 4,5 — e media **3,38** contra page/raised, **3,11** contra subtle e **2,80** contra sunken:
> reprovava nas quatro superfícies do tema claro. O defeito é **anterior a esta rodada** e não foi
> introduzido por ela; foi encontrado na medição que precedeu esta edição. `cinza-600 #617683`
> também reprovaria (3,93). O valor adotado é o único candidato medido que fecha os dois
> requisitos ao mesmo tempo — família e piso nas quatro superfícies.
>
> **A RÉGUA DE AÇÃO NÃO MUDA, E ISSO É O REGISTRO MAIS IMPORTANTE DESTA EDIÇÃO.** Conferido nos
> gêmeos: `action-primary` já era **`#098475` (turquesa-600)** no claro e **`#66D1C2`
> (turquesa-300)** no escuro. **A camada de tokens nunca saiu do §3.5 do `marca-seed.md`** — só o
> preview do painel havia desviado, com o azul, e o desvio foi retirado. Nenhuma linha de token de
> ação precisou mudar.
- **`surface-brand-subtle` = `#E8FBF7` no claro / `#1A3833` no escuro (NOVO em 2026-08-17).** É a superfície de marca **sutil**: balão de mensagem própria, faixa de destaque leve — coisas que precisam de tinta de marca sem virar `surface-brand`. **Nasceu de um defeito, e o defeito era DESTA camada, não do artefato.** A `tela-chat.html` pintava o balão da mensagem própria com a **primitiva** `--seed-turquesa-50` porque **não existia semântico para isso** — e primitiva não inverte com o tema, enquanto o texto (`--seed-text-primary`) inverte: no tema escuro o par media **1,14** contra o piso 3,00, ou seja, **mensagem branca sobre branca** (defeito BT-P6, achado pela `validacao/guarda-gi2.mjs` na primeira varredura da pasta inteira). *O artefato alcançou a primitiva porque era a única coisa disponível — culpar o artefato aqui seria culpar o sintoma.* **Alternativas descartadas:** (a) reusar `--seed-row-selected-bg` ou `--seed-action-secondary-bg`, que já carregam `#E8FBF7` no claro — recusado porque o semântico estaria mentindo: balão de mensagem não é linha selecionada nem fundo de botão secundário; (b) usar `--seed-surface-subtle` como o balão **alheio** já usa — recusado porque apagaria a distinção de tinta entre mensagem própria e alheia, que é desenho aprovado. O valor escuro `#1A3833` **não é valor novo**: é o que esta camada já escolheu para superfície de marca que assenta na página (`--seed-action-secondary-bg` no escuro), então a coerência é com decisão existente. **Medido** contra `--seed-text-primary`: **12,79** no claro e **10,40** no escuro, piso de texto **4,50**. E era o **único** consumo de `--seed-turquesa-50` no acervo inteiro — medido por comando em 29 artefatos.
- **`surface-brand-deep` = turquesa-700/800.** Supersede formalmente a "variante não-oficial tolerada #0d8f82" registrada no `marca-seed.md` v4 — a necessidade (fundo de capa profundo) agora tem resposta oficial dentro da rampa.
- **`feedback-success` usa a família turquesa/verde institucional.** Alternativa descartada: criar rampa verde-folha nova (adicionaria cor fora da marca para resolver ambiguidade que ícone+contexto já resolvem; na SEED, êxito É verde da marca).
- **`chart`: sequência categórica de ordem fixa** — ~~cat-1 turquesa-400, cat-2 dourado-300, cat-3 azul-500, cat-4 turquesa-800, cat-5 cinza-400, cat-6 dourado-700~~ **SUPERSEDIDA na v1.5 pela categórica ESTENDIDA da §3c** (2 matizes exclusivos de dado; sequência turquesa → dourado → magenta → azul → violeta → azul-800; o cinza sai da categórica e fica exclusivo de "sem dado"). Positivo/negativo = turquesa-500/vermelho-500 (inalterado). Regra de acompanhamento inalterada: diferenciar séries também por forma e espessura (acessibilidade).