Spec — UI Style preset families

Facet Styles of Koder Design. Cross-link: policies/reuse-first.kmd.

Source ticket: meta/docs/stack#030. This spec defines the taxonomy; each family expansion is tracked in its own sub-ticket (#050-#054).

Why families

19 presets in flat list is hard to browse, and the picker page becomes unscannable past ~25 entries. Material 3 itself groups its design examples by "type of brand" tacitly; Koder makes the grouping explicit:

Taxonomy — 5 families

R1 — Preset slug grammar

Backwards compatibility: existing presets keep their flat slugs; no rename. New presets in ambiguous categories prefix the family explicitly. Future migration to all-tagged slugs requires owner ratification.

R2 — Family membership declaration

Each preset's CSS file (assets/css/presets/<slug>.css) carries a frontmatter comment block:

/*!
 * preset: ios_cupertino
 * family: brand
 * era: 2020s (current)  # optional sub-tag
 * description: Apple's modern iOS / macOS visual style
 * ratified: 2026-02-15
 */

design-gen reads the comment header to populate the picker page groups.

R3 — Preset picker layout

/style/ page (root of styles):

┌─────────────────────────────────────────────┐
│  Pick a UI Style                             │
│ ─────────────────────────────────────────── │
│                                              │
│  Filter:  [All] [Era] [Brand] [Mood] [Cult.] │
│           [Domain] [Light] [Dark]             │
│                                              │
│  Era (5 / planned 10)                         │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐    │
│  │win95│ │aqua │ │frut │ │synth│ │cyber│    │
│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘    │
│                                              │
│  Brand (9 / planned 13)                       │
│  ┌─────┐ ┌─────┐ ┌─────┐ ...                 │
│  │mat3 │ │mat2 │ │ios  │                     │
│  └─────┘ └─────┘ └─────┘                     │
│                                              │
│  Mood / Aesthetic (8 / planned 14)            │
│  ...                                          │
└─────────────────────────────────────────────┘

• Filter chips (per components/chips.kmd filter variant) at top
• Section per family with count badge (current / planned)
• Tiles arranged in 4-5 column grid (responsive)
• Hover / focus shows preset name + ratification date

R4 — Expansion roadmap

Target ~35-45 total presets across families. Owner-directed allocation (approximate, not rigid):

Wave order recommended:

1. Era + Brand first (lower design risk, high recognition factor)
2. Mood / Aesthetic next (creative; needs designer sweeps)
3. Cultural and Domain last (require research / consultation)

R5 — Quality gates per preset

Each new preset MUST satisfy before merging:

• All 18 color roles (color-roles.kmd) defined for Light + Dark
• Contrast pairs pass WCAG 2.2 AA per tools/contrast-checker.kmd § R6
• Typography stack defined (4 roles per themes/typography.kmd)
• Shape scale defined (6 levels per themes/shape.kmd)
• Elevation tokens (6 levels per themes/elevation.kmd)
• Motion tokens (duration + easing per themes/motion.kmd)
• Renders correctly for ALL canonical components in tools/theme-builder.kmd § R3 preview gallery
• Mobile-responsive per develop/docs-mobile-responsiveness.kmd

R6 — Naming + brand-score

Preset slug follows specs/naming/forms.kmd — [a-z][a-z0-9_]*, unique across all families. Brand-score (per specs/naming/brand-score.kmd) applies only to presets named after real brands (Material 3, iOS, etc.); fictional / generic preset names need not score.

R7 — Per-locale display name

Display names localized:

# tools/design-gen/i18n/en-US.json
"style.ios_cupertino.display": "iOS Cupertino"

# tools/design-gen/i18n/pt-BR.json
"style.ios_cupertino.display": "iOS Cupertino"  # often kept English

Localization optional — many preset names work as-is in en-US (e.g., brand names).

R8 — Color-blindness packs

Per themes/color-customization.kmd § color-blindness packs, every preset must support the 4 simulation modes (Protanopia, Deuteranopia, Tritanopia, Achromatopsia). Validation runs as part of preset PR review.

R9 — Forbidden patterns

• ❌ Preset that fails WCAG 2.2 AA on any role pair
• ❌ Preset with > 30 character display name (picker tile truncates)
• ❌ Preset that exists only in Light or only in Dark
• ❌ Preset that doesn't render for canonical wave-1 components
• ❌ Preset registered without family classification
• ❌ Preset slug clashing with an existing one (case-insensitive)
• ❌ Preset that references images / illustrations not in assets/illustrations/ (atomic CSS, no orphan dependencies)

Cross-link

• themes/color-roles.kmd — required role coverage
• themes/color-dynamic.kmd — palette generation
• tools/theme-builder.kmd — preview gallery test
• tools/contrast-checker.kmd — WCAG gate
• tools/design-kit-export.kmd — preset packs export
• develop/docs-mobile-responsiveness.kmd — mobile render check
• foundations/customization.kmd — preset is a key customization axis

Implementation tracking

Programme tickets (already opened):

• meta/docs/stack#050 — Era family expansion
• meta/docs/stack#051 — Brand family expansion
• meta/docs/stack#052 — Mood / Aesthetic expansion
• meta/docs/stack#053 — Cultural family expansion
• meta/docs/stack#054 — Domain family expansion
• meta/docs/stack#030 — umbrella (remains pending until all 5 sub-tickets close)