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 specsnamingforms.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 (TypePronSon/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;
  --color-link: var(--accent-strong); 
  --bg: #FAFAFA; --surface: #fff;
  --surface-sunken: #ECEEF0; 
  --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; 
  --on-surface: #F4F4F6;
  --on-surface-dim: #9A9AA0;
  --label-color: #9A9AA0;
  --outline: rgba(255, 255, 255, 0.05);
  
  --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: #3584E4;
  --accent-strong: #1C71D8;
  --accent-on: #ffffff;
  --color-link: #A4C8F3; 
}

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 mobileTVlanding.

• 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).

R4.4 — v2 token model (seed → map → alias, derived — canonical from 2026-06-23)

Verge v2 (design-RFC-007, ratified 2026-06-23) replaces the hand-transcribed flat token block as the canonical source: the token values are now *derived by algorithm from a small seed set*, not authored per-hex. The flat .preset.verge in presets.css is retained as a build-time shim (KDS_VERGE_FLAT=1) for one minor; the derived path is the default.

• Seeds (tools/design-gen/internal/tokens/seeds.go::VergeSeed): a neutral

  ramp (NeutralHue=211, NeutralChroma=4), a neutral-variant ramp (NeutralVariantHue=255, NeutralVariantChroma=11.7 — the Material/HCT higher-chroma neutral for secondary text / recessed surfaces: label, on-surface-dim), the brand accent (#3584E4), and the four state seeds (dangerwarningsuccess/info). One seed set reproduces every colour role.

• Algorithm (internal/tokens/algorithm.go::DeriveVerge): pure-Go derivation

  via the verified HCT engine (internal/hct, HCT primary; OKLCH is the no-JS fallback). Light/dark map-tone ladders are frozen constants calibrated to the Adwaita ramp; dark neutrals use a cooler hue (neutralHueDark=275). Colour space + rationale: design-RFC-007 R10.

• Structural AA (closes the v0 accent debt, R8 path-to-fix — now resolved

  by construction): the interactive accent is split into accent-fill (button fill, white-on-it ≥ AA → #1C71D8 both modes) and accent-text (links/focus, ≥ AA vs surface → darken on light, lighten on dark). deriveAccentAA walks the tone until contrast ≥ 4.5; the algorithm cannot emit a sub-threshold map. This generalizes the per-component Koder ID login fix (--color-link, R4.1).

• Emit: BuildVerge sources the colour primitives from DeriveVerge

  (parity-gated: build fails if any derived primitive drifts > ΔE2000 2.0 from its flat counterpart), preserving alias / non-colour properties (rgba tints, shadows, radii, fonts) verbatim from the flat parse until the alias / non-colour-seed tier lands (Phase 3 remainder).

• Gates (CI, design-RFC-007 Phase 2): WCAG 2 AA hard (TestVergeContrastAA),

  ΔE≤2.0 parity (TestVergeDelta + build-time gate), APCA Lc advisory (internal/tokens/apca.go, informational only — contrast-checker.kmd), and emit token-drift (tests/regression/verge_token_drift_test.go). Review artifact: design-gen verge-delta (--strict / --json).

• Parity proven: every colour role reproduces the v1 flat preset within ΔE2000

  ≤ 2.0 (light ≤ 1.63, dark ≤ 1.83) — the flip is a visual no-op; no waiver exceptions. Slices: tools/design-gen/backlog #204 (model, DONE) · #205 (flip, DONE) · #206 (gates, DONE) · #207 (consumers→generated Dart, emit `color-schemes