Spec — Dynamic color

Facet *isual*do Koder Design. Material parity: https://m3.material.io/styles/color/dynamic/user-generated-source.

Marked mandatory: false — dynamic color is an OPTIONAL surface feature; apps may ship with only the canonical presets and expose no seed-color picker.

What it does

Input: 1 seed color (hex, e.g. #3B5BFD). Output: a full token bundle compatible with color-roles.kmd — bg, surface, surface-variant, text, text-muted, accent, accent-strong, accent-on, error, error-bg, etc. — for both light and dark variants.

The token bundle plugs into the same renderer as the 12 canonical presets (color-schemes.kmd Catalog), so widgets see no difference between a dynamic scheme and a canonical one.

R1 — Tonal palette generation

From the seed:

1. *onvert*seed RGB → HCT (HueChromaTone) color space
2. *xtract*Hue from seed
3. *enerate*13 tones (0, 10, 20, …, 95, 99, 100) at consistent

   chroma per role

4. *ind*roles to tones per the role-tone map (see R2)

Algorithm: based on Material Color Utilities (@material/material-color-utilities) or equivalent HCT library. Koder ships a Dart port in koder_kit + JS port in koder_web_kit (planned).

R2 — Roletotone bindings

Status colors (errorsuccesswarning/info) keep fixed hues regardless of seed — preserves semantic meaning across themes (red error reads as error even with green-seeded brand).

R3 — Extraction from image

When the seed is an image (wallpaper, hero):

1. Resize to 128×128 to bound compute
2. K-means quantize to 32 colors
3. Score each color: chroma × population × saturation
4. Pick top-scoring color as seed
5. Run R1 algorithm with that seed

Honors prefers-reduced-motion (no extraction animation) and runs off main thread (Worker on web; isolate in Flutter).

R4 — Quality gates

Dynamic color must pass the same AAA contrast gates as canonical presets (color-schemes.kmd). If the seed produces a palette that fails any required pair:

• Auto-adjust: shift the failing role's tone toward higher contrast
• Or: reject the seed and prompt the user with the offending failure
• Never silently produce inaccessible output

R5 — Persistence

Dynamic scheme persists per-user (synced via Koder ID) when the seed source is the user's deliberate choice. Per-surface (local) when the seed comes from device wallpaper (which itself is local).

Storage key: koder.color_scheme.dynamic = {seed: "#...", source: "manual"|"wallpaper", generated_at: ISO8601}. The generated tokens are reproducible from seed alone, so we don't store the full token bundle.

R6 — Switching between dynamic and canonical

The color scheme picker in Settings shows:

• 12 canonical presets (cards with name + preview swatch)
• "Custom" option that opens a seed-color picker
• "Match device wallpaper" toggle (when supported by the platform)

Switching is instant; the new tokens replace via CSS custom property update (no full reload).

R7 — Supported platforms

Cross-link

• color-schemes.kmd — canonical presets dynamic schemes drop into
• color-roles.kmd — role taxonomy dynamic schemes must satisfy
• customization.kmd — Settings binding location