Verge scope expansion — align with Material's 5-layer scope (foundations + styles + components + patterns + accessibility)

draft

stackRFC004 — Verge scope expansion: align with Material's 5-layer scope

§1 — Problem

CLAUDE.md describes Verge as "linguagem visual canônica do KDS (equivalente Koder ao Material)" with v0 = Adwaita 1:1. The current implicit scope of specs/themes/verge.kmd covers *nly*visual tokens (color, typography, shape, motion, elevation) and is silent on *omponents*and *ayout patterns*

Meanwhile, layout patterns live in *iblings* topbar-placement.kmd, navigation/back-behavior.kmd, app-layout/safe-area.kmd, errors/user-facing-messages.kmd, etc. — each as an independent spec, with no umbrella authority connecting them.

This creates three concrete problems:

  1. *alse equivalence*— calling Verge "equivalente Material" while restricting scope to tokens is misleading. Material 3 spans 5 layers (foundations, styles, components, patterns, accessibility); Adwaita spans GNOME HIG (including header bar, navigation split view, primary toolbar layout patterns). Verge restricted to tokens is * fraction*of either reference.
  1. *onflict / duplication risk*— when topbar-placement.kmd §3 R2 (Kruze browser exception) prescribes sidebar layout, and a future Verge update prescribes default avatar tokens for sidebar context, there's no authority dictating which spec resolves conflict.
  1. *nomaly classification cost*— Hub's profile-as-tab pattern (discovered 20260522 audit) is *aterial 3 canonical*(sancionado as "You" tab when 45 destinations exist). Under current spec hierarchy, it's classified as anomaly requiring perproduct override. Under Verge full-scope adopting Material patterns, it's just a ratified variant — no override needed.

§2 — Goal

Expand Verge's scope to match the 5layer organization of Material 3, with sibling specs becoming *ubdomains*under Verge's umbrella authority. Concretely:

verge.kmd (canonical KDS — umbrella authority)
├── foundations/   color, typography, shape, motion, elevation, accessibility
├── styles/        design tokens (CSS vars, Flutter theme extension)
├── components/    KoderUserBadge, KoderSignInButton, AppBar, NavRail,
│                  NavigationBar, KoderSafeScaffold, KoderBackScope, …
└── patterns/
    ├── topbar-placement.kmd     ← existing spec, declared sub-domain
    ├── back-behavior.kmd        ← existing spec, declared sub-domain
    ├── safe-area.kmd            ← existing spec, declared sub-domain
    ├── user-facing-messages.kmd ← existing spec, declared sub-domain
    └── (future: adaptive-layout, navigation, communication, density, ...)

Specs *o not physically move* Each existing sibling spec declares parent: verge.kmd in frontmatter; CLAUDE.md gatilhos redirect users via Verge as the entry point.

§3 — Non-goals

  • *ot*a re-implementation of every spec from scratch. Each spec content stays; only umbrella declaration changes.
  • *ot*Verge replacing componentlevel specs (e.g., `koderapp/behaviors.kmd` stays as product behavior contract, separate authority).
  • *ot*mandatory Adwaita 1:1 forever — Verge inherits Adwaita v0; divergence is owner-driven per existing policy.
  • *ot*Material 3 1:1. Verge selects which Material patterns to adopt; some may diverge (e.g., dense Linux desktop layouts may need patterns Material doesn't have).

§4 — Proposal

R1 — Verge scope = Material 5-layer equivalent

Update verge.kmd §1 (or add §0 Scope) to declare:

Verge cobre 5 camadas (equivalente Material 3): foundations (colortyposhapemotionelevationaccessibility), styles (design tokens), components (widgets canonical), patterns (layoutnavigationcommunicationadaptive), accessibility (crosscutting). v0 = Adwaita 1:1; divergence incremental ownerdriven.

R2 — Sub-domain spec declaration

Each spec that is a Verge pattern declares in frontmatter:

parent: specs/themes/verge.kmd
verge-domain: patterns/<sub-domain-name>

Initial migration (this RFC ratification):

  • topbar-placement.kmd — verge-domain: patterns/topbar-placement
  • navigation/back-behavior.kmd — verge-domain: patterns/back-behavior
  • app-layout/safe-area.kmd — verge-domain: patterns/safe-area
  • errors/user-facing-messages.kmd — verge-domain: patterns/communication

Other specs (componentlevel: `koderappbehaviors.kmd, authoauthflow.kmd, identity/loginresolution.kmd`) *tay independent*— they are product/service behavior contracts, not Verge patterns.

R3 — CLAUDE.md gatilho consolidation

CLAUDE.md gatilho "Tokens visuais em qualquer UI Koder" → specs/themes/verge.kmd already points to Verge. Add new gatilhos directing to sub-domain specs through Verge umbrella when ratified.

R4 — Adopted Material patterns (initial seed)

Verge full-scope adopts these Material 3 patterns immediately on ratification:

  • *profileastab** (Material 3 "You" tab) — when nav has 4–5 destinations, avatar may be tab in NavigationRail/NavigationBar. Hub profileastab` becomes conforming variant (resolves topbar-placement.kmd Q6 as path (a)).
  • *topbar-right avatar`*(Material 3 top app bar trailing) — default for apps without dedicated profile tab.
  • *drawer-header avatar`*(Material 3 navigation drawer) — when ham menu is primary nav.
  • *sidebarlefttop avatar`*(Adwaita header bar variant) — Kruze browser/IDE exception retains explicit per-product override since browsers don't fit Material 3 navigation patterns 1:1.

R5 — Adopted Adwaita patterns (initial seed)

From Adwaita v0 baseline:

  • *eader bar*as default desktop topbar (already implicit)
  • *avigation split view*for list-detail (already used in some products via Flutter equivalent)
  • *rimary toolbar*placement at bottom for compact windows (currently unused; available)

§5 — Migration plan

Phase 1 — RFC ratification (this doc)

Owner ratifies §7 questions. No code/spec changes yet.

Phase 2 — Verge scope declaration

Update verge.kmd adding §0 Scope per R1. Single PR, no behavioral changes.

Phase 3 — Sub-domain frontmatter migration

Update 4 sibling spec frontmatters (R2). Single PR, mechanical change.

Phase 4 — topbar-placement.kmd Q6 resolution

With Verge scope ratified, Q6 resolves as path (a) — profile-as-tab is variant ratificada in §2. Update spec, close Q6, Hub registry entry moves from "Pending owner ratification" to "Conforming (variant: profileastab)".

Phase 5 — CLAUDE.md gatilho update

Add/redirect gatilhos pointing to Verge umbrella for sub-domain queries.

Phase 6 — Future patterns

New patterns (adaptivelayout, navigation, communication, density, …) added as Verge subdomain specs under same convention. No need to revisit RFC unless scope changes.

§6 — Tradeoffs

*ros:*

  • Single authority for visual language (no spec conflicts)
  • Coherence with Material referência (devs onboard faster)
  • Hub profile-as-tab ratifies naturally without per-product exception
  • Future patterns have a clear home

*ons:*

  • Larger scope = larger surface area to maintain (Material team is huge; Verge team is owner)
  • Risk of Verge becoming "god spec" if not disciplined about sub-domain boundaries
  • Specs that ARE sub-domains lose some independent identity (mitigated by physical location staying intact)

§7 — Open questions (owner ratify)

  1. *dopt full 5layer scope?*Or restrict Verge to 3 layers (foundations + styles + components) and keep patterns as independent siblings? RFC default = full 5layer (resolves Hub anomaly + matches Material referência).
  1. *aterial 3 selection vs Adwaita 1:1 priority*— when Material 3 pattern conflicts with Adwaita pattern (e.g., bottom nav vs header bar primary toolbar), which wins? RFC default = surfacedependent (desktop → Adwaita; mobile → Material 3; web/TV → caseby-case).
  1. *ubdomain spec naming*— keep current paths (`specs/applayouttopbar-placement.kmd) or move under specsthemesvergepatterns/name.kmd`? RFC default = keep current paths, declare parent via frontmatter only (zero file moves).
  1. *profileastab ratification trigger** — accept ratification implicitly when this RFC merges, OR require separate owner ack in topbar-placement.kmd §7 Q6`? RFC default = implicit (this RFC's R4 is explicit enough).
  1. *erge versioning*— when Verge scope expands (5 layers ratified), bump Verge version v0 → v1? Or stay v0 since tokens didn't change? RFC default = bump to v0.2 (scope clarification, not breaking change).

§8 — Histórico

  • *0260522*— draft v0.1 criada. Motivada pela auditoria de topbar-placement.kmd Q6 (Hub profile-as-tab); ao tentar resolver Q6, identificado que escopo de Verge não estava formalizado e que a analogia Verge=Material implicava escopo maior que o atual. Owner ratificou direção ("sim, Verge deve ter os mesmos escopos que o Material") via diálogo na sessão de 20260522; RFC formaliza a direção pra ratificação assíncrona com tradeoffs explícitos.

§9 — Spec/policy alignment

  • specs/themes/verge.kmd — target spec a ser expandido
  • specs/app-layout/topbar-placement.kmd — sub-domínio candidato (Phase 3)
  • specs/navigation/back-behavior.kmd — sub-domínio candidato (Phase 3)
  • specs/app-layout/safe-area.kmd — sub-domínio candidato (Phase 3)
  • specs/errors/user-facing-messages.kmd — sub-domínio candidato (Phase 3)
  • stack-RFC-003 — Koder Icons — sibling RFC sobre ícones; quando ratificada, kodericons vira subdomínio Verge (components/icons)
  • policies/reuse-first.kmd — Verge full-scope reforça reuse via authority única
  • meta/brand/koder-design/ — KDS source of truth; Verge scope expansion documenta o que KDS cobre

Source: ../home/koder/dev/koder/meta/docs/stack/rfcs/stack-RFC-004-verge-scope-expansion.kmd