Spec — Koder Style: Design Decisions

Status: v0 — cobrindo décisions #008.1–#008.11. Atualizar a cada nova divergência editorial sobre o baseline Adwaita.

§1 — Position

Esta spec é o log editorial das decisões de design Koder. A spec normativa de tokens é specs/themes/verge.kmd; o CSS canônico vive em tools/design-gen/assets/css/presets.css (.preset.verge).

A relação:

KDS (Koder Design System)
 └── Verge (design language — specs/themes/verge.kmd)
       └── v0: Adwaita 1:1 baseline  ← ponto de partida
       └── v1: primeiro wave de divergência ← governado por ESTA SPEC
       └── v2+: evolução subsequente

"Koder style" não é um preset separado de verge: é o caminho de divergência que Verge percorre à medida que se afasta do baseline Adwaita e adopta decisões específicas da identidade Koder. Quando uma decisão está ratificada, ela entra em verge.kmd §R4.{N} como diff de tokens + bump de versão menor.

§2 — Decisões ratificadas

D1 — Forma dos botões em formulários

Decisão (owner, 2026-05-13): Botões em formulários e ações primárias usam "formato quadrado, porém com cantos minimamente abaulados". Tradução em token:

Rationale: 5px cai entre "square 0" e Material's "rounded 8". Aparência profissional sem a redondeza genérica do Material 3. Pill (999px) é reservado exclusivamente para toggles e segmented controls, onde a forma circular tem significado funcional.

Implementação: tokens adicionados ao .preset.verge em presets.css (v0 ainda usa 6px de Adwaita para --radius-btn; flip para 5px é o primeiro commit de divergência v0→v0.1).

Pending (D1.flip): Owner precisa confirmar que o flip --radius-btn: 5px pode ir pro CSS. Quando confirmar, editar a linha em presets.css e bump Verge para v0.1.

D2 — Paleta de cores da identidade Koder

Decisão (2026-05-14): A paleta de identidade Koder (usada no brand mark e em hero/marketing surfaces) é índigo, derivada do gradiente visual da logomarca:

#c7d2fe (índigo 200) → #6366f1 (índigo 500) → #4338ca (índigo 700) → #1e1b4b (índigo 950) → #818cf8 (dark-mode accent)

Esta paleta NÃO é o default de Verge v0. O default de Verge v0 é Adwaita blue (#3584E4), escolhido por:

• Neutralidade cross-product (não "força" a marca Koder em apps sem relação com a brand)
• Paridade com GNOME para apps desktop nativos
• a11y: #3584E4 em --accent-strong (#1c71d8) passa AA 4.77

A paleta índigo ENTRA no preset quando um produto explicitamente se identifica como produto Koder (landing pages, produtos horizontais da Stack — Kode, Koder Hub, Koder ID, etc.). O mecanismo de aplicação é via CSS var override no nível do produto:

/* No CSS do produto, sobre .preset.verge */
:root {
  --accent: #6366f1;
  --accent-strong: #4338ca;
  --accent-on: #ffffff;
  --focus: 2px solid #818cf8;
}

Pending (D2.when): Definir quais produtos adoptam índigo vs ficam em Adwaita blue. Sugestão: produtos da Koder Stack core (Kode, Hub, ID, Pass, Drive) usam índigo; produtos sectoriais (Crescer, Vivver) usam sua própria paleta.

D3 — Tipografia

Decisão (per specs/fonts/typography.kmd, ratificada no #008):

O fallback de Verge v0 ('Cabin', 'Cantarell', 'Inter', sans-serif) mantém compatibilidade com GNOME desktop. Em web apps Koder puros, Inter é servido como self-hosted .woff2 per specs/fonts/ typography.kmd.

Pending (D3.display): Koder Display custom (tracking em projects/koder-stack#128). Em v0, Inter cobre display roles.

D4 — Espaçamento

Decisão (#008.1): Escala 4-base em doubling: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 px

Equivale ao sistema Tailwind / Material default — muscle memory preservado. Tokens CSS:

D5 — Sombras

Decisão (#008.1): Sombras Koder são índigo-tinted (em vez de pure-black de Adwaita) para amarrar com a palette da identidade:

--shadow-form:     0 0 0 1px rgba(30,27,75,0.06);
--shadow-card:     0 1px 3px rgba(30,27,75,0.12), 0 1px 2px rgba(30,27,75,0.08);
--shadow-elevated: 0 4px 12px rgba(30,27,75,0.14), 0 2px 6px rgba(30,27,75,0.08);

Em dark mode, sombras voltam ao neutro preto (rgba(0,0,0,...)) porque o contraste índigo-on-dark é imperceptível.

Status: tokens ratificados mas não aplicados ao preset Verge v0 ainda (Adwaita usa black-channel shadows). Entram na divergência v0.1.

§3 — Component decisions (#008.2–#008.8)

§3.1 — Form elements (#008.2)

Implementados em .preset.verge (+ dark overrides):

Motion: todos os elementos usam transition: var(--motion, 150ms ease).

§3.2 — Containers (#008.3)

§3.3 — Navegação (#008.4)

§3.4 — Data (#008.5)

§3.5 — Feedback (#008.6)

§3.6 — Tipografia aplicada (#008.7)

Escala T1–T7 alinhada com --kdr-font-size-* tokens implícitos:

Tokens adicionados: --font-mono, --code-bg, --code-color.

§3.7 — Layout primitives (#008.8)

§3.8 — Surface-specific (#008.9)

Tabs Mobile / Desktop / Web / TV na detail page de cada preset. Density overrides por surface (via .preset.surface-<X>):

TV: focus ring explícito 4px solid var(--accent) (D-pad nav). Web: progressive enhancement — sem hover states como requirement.

§4 — Form builder (#008.10-11)

O Preset builder em kds.koder.dev/<locale>/tools/style-builder/ implementa edição visual dos tokens Verge:

• Aba Colors: 11 tokens de cor (accent, bg, surface, on-surface, label, error, success, warning)
• Aba Shape: 4 sliders de radius (sm/md/lg/btn)
• Aba Spacing: 4 sliders (pad-y/x, gap-field, pad-form)
• Aba Type: dropdown de font-family
• Preview: form de cadastro + strip de componentes ao vivo
• Export: CSS preset block + JSON + URL compartilhável (hash base64)
• Import: JSON ou CSS vars
• Undo/Redo: stack de 50 passos (Ctrl+Z / Ctrl+Y)
• Diff: painel <details> com alterações vs defaults Verge

§5 — Decisões pendentes

§6 — Ferramentas e testes

§7 — Cross-links

• specs/themes/verge.kmd — spec normativa de tokens + versioning
• specs/themes/ui-style.kmd — registry de 43 presets + audit
• specs/themes/light-dark.kmd — esquema light/dark cross-surface
• specs/fonts/typography.kmd — roles de tipografia + self-hosted .woff2
• specs/themes/motion/ — easing + durations + transitions
• tools/design-gen/assets/css/presets.css — CSS canônico (.preset.verge)
• tools/design-gen/backlog/pending/008-koder-native-style-and-form-builder.md — épico de sub-tickets