Spec — Verge (v1 — OLED-aware dark)

Status: v1 — first substantive divergence from Adwaita baseline. Owner decision 2026-05-14: a linguagem visual canônica do Koder Design System se chama Verge. v0 (2026-05-14) iniciou com tokens GNOME Adwaita 1:1. v1 (owner ratificou 2026-05-28) promove o preset OLED-aware (palette "C" originalmente shipada em dek#123, 2026-05-25) a default canônico: a variante dark ganha surfaces near-black ramp + radii maiores + hairline outline; a variante light continua Adwaita-derived inalterada. Sub-tickets adicionais de divergência editorial seguem em tools/design-gen#008.

R1 — Position: Verge ⊂ Koder Design System

Verge é a camada visual do Koder Design System — equivalente direto ao "Material" no portfolio Google. A separação:

KDS é mais amplo que Verge: além de Verge, hospeda specs cross-stack (auth, identity, multi-tenancy, i18n, errors, voice, media, signing, naming, koder-app behaviors, iconografia de UI — Verge Symbols, specs/icons/ui-symbols.kmd). Verge é uma das peças.

R2 — Naming forms (per specs/naming/forms.kmd)

CSS selectors (dois consumidores, ambos válidos):

• tools/design-gen emite .preset.verge (+ .themed-dark.preset.verge).
• engines/sdk/koder_web_kit emite [data-style="verge"] (+ [data-theme="dark"][data-style="verge"]) — coerente com o resto dos 19 presets do SDK que já usam [data-style="…"].

Dart enum: KoderUIStyle.verge. Web JS: koderStyle.set('verge').

Pron canônica: /vɜːdʒ/ (single English syllable, universal).

Brand score (preliminar, per specs/naming/brand-score.kmd): A-A-A-A (Type/Pron/Son/Mem) com risco identificado de overlap cultural com The Verge (publicação tech). Não bloqueia adoção — namespaces diferentes (design system vs media), mas alinhar comunicação se sobreposição vier a tema.

R3 — Strategy: start from Adwaita

Verge v0 não introduz identidade visual nova: copia os tokens GNOME Adwaita 1:1.

Por quê Adwaita?

• GNOME Adwaita é uma das identidades cross-OS mais maduras e documentadas em open source (libadwaita 1.x).
• Compact density (pad-y: 8px, gap-field: 10px) cabe em surfaces pequenas sem virar Material's loose comfortable padding.
• 4/6/8px radius cobre exatamente a faixa "minimally rounded squares" que owner ratificou em 2026-05-13 — sem reinventar.
• Accent Adwaita #3584E4 é blue suficientemente neutro para um default cross-product (não é "the indigo Koder brand" — esse vive só no brand mark + landing hero).
• Dark variant Adwaita já estava shipada no #007 wave A — reuse- first: o trabalho não duplica.

Divergência futura acontece gradualmente: à medida que os produtos Koder ratifiquem decisões próprias (forma do checkbox, shape do snackbar, easing do drawer, etc.), os tokens Verge vão sendo sobrescritos com decisões Koder-specific. Eventualmente Verge deixa de parecer Adwaita — mas a base existente acelera o ramp-up.

R4 — Tokens

Verge atualmente shipa em v1. As subsections abaixo registram o estado canônico atual + o histórico v0 pra rastreabilidade.

R4.1 — Light (v0 + v1, inalterado)

Light variant fica em Adwaita-derived integralmente — tokens e radii. OLED-aware é uma decisão exclusiva de dark mode (#0F0F0F em ambiente claro é hostil; o contraste light/dark é o que dá ao Verge a personalidade dual). Owner ratificou "light intacto" em 2026-05-28 ao aprovar Verge v1.

.preset.verge {
  --font: 'Cabin', 'Cantarell', 'Inter', sans-serif;
  --accent: #3584E4; --accent-strong: #1c71d8; --accent-on: #fff;
  --bg: #FAFAFA; --surface: #fff;
  --surface-sunken: #ECEEF0; /* design-RFC-012 — recesso/well; NAO-recursivo */
  --on-surface: #2e3436; --label-color: #5e6772;
  --radius-sm: 4px; --radius-md: 6px; --radius-lg: 8px; --radius-btn: 6px;
  --pad-y: 8px; --pad-x: 12px;
  --shadow-form: 0 0 0 1px rgba(0,0,0,0.1);
  --input-border: 1px solid #c0c0c0;
  --gap-field: 10px; --gap-title: 14px;
  --pad-form: 18px;
  --btn-secondary-border: 1px solid #c0c0c0;
}

Light geometry idêntica a v0. A divergência v1 é estritamente dark.

R4.2 — Dark v0 (Adwaita 1:1, superseded by R4.3)

Mantido aqui pra histórico. Não emitir em produção a partir de 2026-05-28.

.themed-dark.preset.verge {
  --bg: #242424;
  --surface: #303030;
  --surface-2: #424242;
  --on-surface: #ffffff;
  --label-color: #cccccc;
  --input-border: 1px solid #1b1b1b;
  --btn-secondary-bg: #3a3a3a;
  --btn-secondary-fg: #ffffff;
  --btn-secondary-border: 1px solid #1b1b1b;
  --btn-secondary-hover: #4a4a4a;
  --shadow-form: 0 0 0 1px rgba(0, 0, 0, 0.5);
}

R4.3 — Dark v1 (OLED-aware, current)

Owner ratificou em 2026-05-28 (after dek#123 shipping em 2026-05-25). Surfaces pinadas em near-black ramp (NÃO #000 puro — preserva elevation cues), accent inalterado, radii maiores, hairline outline em 5% white.

.themed-dark.preset.verge {
  --bg: #0A0A0B;
  --surface: #0F0F0F;
  --card: #161618;
  --card-high: #1F1F22;
  --surface-sunken: #0A0A0B; /* design-RFC-012 — recesso/well; NAO-recursivo */
  --on-surface: #F4F4F6;
  --on-surface-dim: #9A9AA0;
  --label-color: #9A9AA0;
  --outline: rgba(255, 255, 255, 0.05);
  /* radii bumped in v1: 2/4/6/8/12 → 6/8/12/14/18 */
  --radius-xs: 6px; --radius-sm: 8px; --radius-md: 12px;
  --radius-lg: 14px; --radius-xl: 18px; --radius-btn: 12px;
  --input-border: 1px solid rgba(255, 255, 255, 0.05);
  --shadow-form: 0 0 0 1px rgba(255, 255, 255, 0.05);
  /* accent stays Verge — same as light */
  --accent: #3584E4;
  --accent-strong: #1C71D8;
  --accent-on: #ffffff;
}

Por quê OLED-aware?

• Sentimento "Koder" — distintivo vs Adwaita default GNOME que já é conhecido por usuários Linux. Verge precisa de identidade própria.
• Battery em OLED phones (#0A0A0B queima pixels off) — ganho free pra mobile/TV/landing.
• Maior contraste pra leitura code-heavy (texto #F4F4F6 em #0F0F0F ≈ 17.5:1 vs #FFFFFF em #303030 ≈ 13.2:1 do v0).
• Radii maiores casam com a estética dos chips/cards modernos sem cair em "Material 3 expressive" (que é spacious, não compact).

R5 — Default preset flip (2026-05-14)

tools/design-gen/internal/kinds/uistyle.go::canonicalPresets[0]:

{Slug: "verge", ..., Default: true, ...}

Demais especs foram atualizadas pra referenciar Verge no lugar de material3 quando descrevem o "default preset":

• specs/themes/ui-style.kmd — tabela de presets + audit rule + anti-pattern + exemplos Flutter/Web (KoderUIStyle.verge, default-state="verge").
• specs/themes/color-schemes.kmd — default agora verge + system + default.
• specs/themes/elevation.kmd — tabela default agora verge.
• specs/themes/shape.kmd — tabela default agora verge.
• specs/themes/color-resources.kmd — chrome de referência agora verge.

R6 — Versioning (Verge v0 → v1 → v2…)

Análogo a Material 1 → 2 → 3 → Expressive: Verge segue versionamento semântico ratificado por changesets quando tokens fundacionais mudam.

• v0 (2026-05-14) — Adwaita 1:1 baseline. Dark variant em #242424/#303030 ramp, radii 2/4/6/8/12, sem outline.
• v1 (2026-05-28) — OLED-aware dark. Dark variant em near-black ramp #0A0A0B/#0F0F0F/#161618/#1F1F22, on-surface #F4F4F6, hairline outline rgba(255,255,255,0.05), radii bumpadas 2/4/6/8/12 → 6/8/12/14/18. Light variant inalterada vs v0 (Adwaita-derived, radii original) — owner ratificou "light intacto". Accent inalterado em ambas brightnesses. KoderUIStyle.oled do koder_kit (display "Verge OLED") fica como alias @Deprecated apontando pra KoderUIStyle.verge. Removido em v2.
• v2+ — evoluções subsequentes (analogo a Material 3 → Expressive). Inclui: remoção do KoderUIStyle.oled alias, eventual divergência do accent (path-to-fix do §R8), tokens próprios de form elements.

Cada release Verge vN ganha:

• Subsection R4.{N+something} com diff de tokens vs vN-1 (R4.3 = v1 dark)
• Changelog em tools/design-gen/blog/ (Releases)
• Migration guide no design-gen /migrate/verge/vN-1-to-vN/

R8 — Contrast audit (baseline 2026-05-14, re-baselined 2026-05-28 for v1)

Audit automatizado em tools/design-gen/cmd/verge-contrast-audit/ (invocável via regression test tests/regression/verge_contrast_baseline_test.go). WCAG 2.1 AA threshold = 4.5:1 para texto normal.

Estado v1 (15 pares canônicos, light + dark; dark ratios bumpados pelo ramp OLED-aware):

Ratios medidos pelo verge-contrast-audit em 2026-05-28 (15 pares). Dark variant v1: texto on-surface sobe de 13.20 → 17.45 (AAA com folga). accent / surface dark sai de FAIL pra PASS AA (5.09 ≥ 4.5) pelo ramp #0F0F0F. Light variant inalterada; mantém os 2 FAILs de v0 ligados ao accent — path-to-fix abaixo persiste.

Known AA failures (2 pares em v1, ambos light-only): todos relacionados ao #3584E4 accent + #FFFFFF on-accent pair em surface clara. Adwaita usa o mesmo accent em buttons/links e aceita a ratio sub-AA porque o sistema GNOME compensa com bold weight + tamanho ≥14pt. KDS não faz essa compensação por default. Dark variant v1 não herda os FAILs (surfaces escurecidas levaram a ratio a 6.59).

Path-to-fix sugerido (defer pra Verge v2, owner pick): flipar --accent light de #3584E4 → #1c71d8 (atual --accent-strong, PASS AA 4.77) e introduzir novo --accent-strong ainda mais escuro (ex.: #155199) para o estado hover. Mudança custaria 1 commit

• atualização §R4.1 + bump pra Verge v2. Owner ratifica quando quiser priorizar a11y AA strict em light.

Baseline lock: tests/regression/verge_contrast_baseline_test.go re-baselined em 2026-05-28; trava pass ≥ 12 (era 11 em v0; v1 sobe 1 par dark — accent / surface que era 3.50 sobre #303030, agora 6.59 sobre #0F0F0F). Qualquer divergência futura tem que manter ou melhorar o score — nunca regredir. Cmd: verge-contrast-audit (report mode, sem --strict) ou verge-contrast-audit --strict (exit 1 em qualquer fail).

R7 — Sub-tickets pendentes (gradual divergence)

A divergência editorial (substituir Adwaita por decisões Verge próprias) acontece via os sub-tickets de tools/design-gen/backlog/pending/008-koder-native-style-and-form-builder.md:

• #008.2 — Form elements (button variants, input, etc.)
• #008.3-9 — Containers / nav / data / feedback / typography / layout / surface-specific
• #008.10-11 — Verge style builder (graphical tool em /tools/verge-builder/ ou /tools/koder-style-builder/)
• #008.13 — Migration de produtos existentes pra .preset.verge (alguns já podem estar em .preset.gnome — operacionalmente equivalente em v0, mas o slug canônico é verge)

Cross-link

• themes/ui-style.kmd — preset registry (Verge agora Default)
• themes/light-dark.kmd — per-preset dark contract
• themes/elevation.kmd, shape.kmd, color-schemes.kmd, color-resources.kmd — referências ao default atualizadas
• fonts/typography.kmd — Cabin/Cantarell são fallbacks; Inter é o último fallback (alinhado com a typography spec da Stack)
• icons/ui-symbols.kmd — Verge Symbols: conjunto de glyphs de UI irmão do Verge (equivalente Koder ao Material Symbols)
• naming/forms.kmd — Verge entry registrada em R2
• naming/brand-score.kmd — Verge score em R2
• registries/component-names.md — entry CI-checked
• tools/design-gen/backlog/pending/008-koder-native-style-and-form-builder.md — épico de sub-tickets pra divergir do Adwaita