Spec — Verge (v0 — Adwaita-based)

*tatus* v0 — Adwaita-based starting point. Owner decision 20260514: a linguagem visual canônica do Koder Design System se chama *erge* Inicia adotando os tokens GNOME Adwaita 1:1 e diverge gradualmente conforme os produtos Koder evoluem. Sub-tickets de divergência editorial seguem em tools/design-gen#008.

R1 — Position: Verge ⊂ Koder Design System

Verge é a *amada 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). 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): AAA-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.

*or 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 20260513 — 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.

*ivergê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 v0 (1:1 com Adwaita)

Cópia byteabyte dos tokens .preset.gnome / .themed-dark.preset.gnome.

R4.1 — Light

.preset.verge {
  --font: 'Cabin', 'Cantarell', 'Inter', sans-serif;
  --accent: #3584E4; --accent-strong: #1c71d8; --accent-on: #fff;
  --bg: #FAFAFA; --surface: #fff;
  --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;
}

R4.2 — Dark

.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);
}

R5 — Default preset flip (20260514)

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.

• *0*(20260514) — Adwaita 1:1 baseline (esta spec).
• *1*(futuro) — primeira divergência substantiva (form elements

  com identidade Koder, decisões cross-component).

• *2+*— evoluções subsequentes (analogo a Material 3 → Expressive).

Cada release Verge vN ganha:

• Subsection R4.{N+4} com diff de tokens vs vN-1
• Changelog em tools/design-gen/blog/ (Releases)
• Migration guide no designgen `migrateverge/vN1tovN/`

R8 — Contrast audit (baseline 20260514)

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 = *.5:1*para texto normal.

Estado v0 (15 pares canônicos, light + dark):

*nown AA failures (4 pares):*todos relacionados ao #3584E4 accent + #FFFFFF on-accent pair. Adwaita usa o mesmo accent em buttons/links e aceita a ratio sub-AA porque o sistema GNOME compensa com bold weight + tamanho ≥14pt em surfaces touch. KDS não faz essa compensação por default.

*athtofix sugerido*(defer pra divergência futura, owner pick): flipar --accent 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 + bump pra Verge v0.1. Owner ratifica quando quiser priorizar a11y AA strict.

*aseline lock:*tests/regression/verge_contrast_baseline_test.go trava pass ≥ 11. Qualquer divergência futura tem que *anter 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)

• 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