Spec — Color resources

Catálogo de tokens exportáveis. Sibling: color-roles.kmd (semântica), color-schemes.kmd (per-preset color values), color-customization.kmd (override mechanism). Esta spec foca em export format por surface.

Princípios

1. Source-of-truth ÚNICA — tokens vivem em themes/color-schemes.kmd per preset; este spec define como RENDERIZAR em formatos consumíveis.
2. 5 formatos canônicos — CSS / Dart / Compose / SwiftUI / Figma Variables.
3. Per-preset per-theme — light + dark + ~31 presets disponíveis na Stack.
4. Versioning estrito — qualquer mudança em token bump em releases.toml.
5. AAA contrast preserved — exports retêm contrast guarantees per color-roles.kmd R4.

R1 — Catálogo dos 18 color roles (per surface)

Tabela canônica de naming per surface, derivada de color-roles.kmd:

Note: Material ColorScheme doesn't natively have warning/success — Koder extends via custom extension property OR derives from tertiary/primary. Per surface implementation, document fallback.

R2 — Per-preset export

For each of ~31 presets (material3, material_expressive, material2, cyberpunk_neon, glassmorphism, brutalist, ...; per ui-style.kmd):

design-gen renders 5 code blocks per preset, light + dark themes:

R2.1 — CSS

/* Koder Design System — material3 preset, light theme */
:root {
  --kds-color-primary: #6750A4;
  --kds-color-on-primary: #FFFFFF;
  --kds-color-primary-container: #EADDFF;
  --kds-color-on-primary-container: #21005D;
  /* ... 14 more roles ... */
}

[data-theme="dark"] {
  --kds-color-primary: #D0BCFF;
  --kds-color-on-primary: #381E72;
  /* ... */
}

R2.2 — Dart (Flutter)

// Koder Design System — material3 preset
const KoderColorScheme material3Light = KoderColorScheme(
  primary: Color(0xFF6750A4),
  onPrimary: Color(0xFFFFFFFF),
  primaryContainer: Color(0xFFEADDFF),
  // ... 15 more roles ...
);

const KoderColorScheme material3Dark = KoderColorScheme(
  primary: Color(0xFFD0BCFF),
  // ...
);

R2.3 — Compose (Kotlin)

// Koder Design System — material3 preset
val material3LightColorScheme = lightColorScheme(
    primary = Color(0xFF6750A4),
    onPrimary = Color(0xFFFFFFFF),
    primaryContainer = Color(0xFFEADDFF),
    // ... 15 more roles ...
)

val material3DarkColorScheme = darkColorScheme(
    primary = Color(0xFFD0BCFF),
    // ...
)

R2.4 — SwiftUI (Swift)

// Koder Design System — material3 preset
extension Color {
    static let koderMaterial3LightPrimary = Color(hex: 0x6750A4)
    static let koderMaterial3LightOnPrimary = Color(hex: 0xFFFFFF)
    static let koderMaterial3LightPrimaryContainer = Color(hex: 0xEADDFF)
    // ... 15 more roles ...

    static let koderMaterial3DarkPrimary = Color(hex: 0xD0BCFF)
    // ...
}

R2.5 — Figma Variables (JSON)

{
  "$schema": "https://www.figma.com/plugin-docs/variables",
  "modes": ["Light", "Dark"],
  "variables": {
    "Koder/Primary": {
      "type": "COLOR",
      "valuesByMode": {
        "Light": { "r": 0.404, "g": 0.314, "b": 0.643 },
        "Dark":  { "r": 0.816, "g": 0.737, "b": 1.000 }
      }
    },
    "Koder/OnPrimary": {
      "type": "COLOR",
      "valuesByMode": {
        "Light": { "r": 1.0, "g": 1.0, "b": 1.0 },
        "Dark":  { "r": 0.220, "g": 0.118, "b": 0.447 }
      }
    }
    /* ... 16 more variables ... */
  }
}

R3 — Light + Dark side-by-side

Renderização exibe ambos os themes simultâneos:

┌──────────────────────┬──────────────────────┐
│  Light Theme         │  Dark Theme          │
├──────────────────────┼──────────────────────┤
│  [color swatch]      │  [color swatch]      │
│  primary             │  primary             │
│  #6750A4             │  #D0BCFF             │
│  [Copy CSS] [Copy   │  [Copy CSS] [Copy   │
│   Dart] [Compose]    │   Dart] [Compose]    │
│   ...                │   ...                │
└──────────────────────┴──────────────────────┘

Cada role mostrado lado-a-lado com swatch + code blocks copy-paste.

R4 — Versionamento

Mudança em qualquer token registra entry em releases.toml:

[[release]]
version = "0.X.Y"
date = "2026-MM-DD"
type = "color-tokens"
changes = [
  "preset material_expressive: primary updated from #6750A4 to #6644A0 (Expressive ratification)",
  "preset cyberpunk_neon: dark theme on-primary contrast lifted to AAA",
]

CI gate: any color token change MUST have corresponding releases.toml entry OR be flagged as drift.

R5 — Cross-link bidirecional

Each role row links bidirecional:

• Semantic role → click → opens color-roles.kmd anchor for that role.
• Customization mechanism → link in footer → color-customization.kmd for override patterns.
• Per-preset values → link in preset header → color-schemes.kmd for full preset definition.

R6 — Copy buttons

Each code block has 1 Copy button:

• Tap → writes full block (NOT truncated) to clipboard.
• Toast "Copied" feedback ~1.5s per code-block.kmd R4.
• Per-block (não per-format-batch) — user copies what they need.

Bulk copy: top-of-page "Download all formats as .zip" button (renders full set).

R7 — Accessibility

• Color swatches: aria-label includes hex value + role name.
• AAA contrast verified per role per preset per theme (CI gate in design-gen render pipeline).
• Color-blindness simulation: optional toggle (cross-link color-customization.kmd color-blindness packs).
• Reduced-motion: no animations in this page (static reference).

R8 — i18n

R9 — Per-preset variation (in renderization)

The data (color values per preset) varies; the rendering structure is identical per preset. Page layout NOT per-preset-styled (it's a reference page — uses default verge chrome regardless of which preset's tokens are being shown; flipado de material3 2026-05-14 per verge.kmd R5).

R10 — Rendering ticket

Renderização gerenciada por design-gen (extends themes kind ou novo kind color-resources). Acompanha sidebar update: Color section gains 5th item (system / roles / schemes / advanced / resources).

Tracking: ticket pendente para design-gen impl deste novo kind.

T-suite

• T1 All 18 roles listed in R1 per surface.
• T2 Per-preset rendering: each of ~31 presets has 5 code blocks (CSS/Dart/Compose/SwiftUI/Figma) × 2 themes (light/dark).
• T3 Copy button: tap → clipboard equals full block text.
• T4 Bulk download: .zip contains all 5 formats × all presets × both themes.
• T5 AAA contrast: CI gate verifies all role × preset × theme combinations.
• T6 Cross-link: tap role → opens color-roles.kmd anchor.
• T7 Versioning: token change WITHOUT releases.toml entry → CI fail.
• T8 A11y: aria-label correto per swatch.
• N1 Material ColorScheme missing warning/success: Compose code block uses Koder extension property OR derives.

Cross-link

• Semantic source: color-roles.kmd
• Per-preset values: color-schemes.kmd
• Override mechanism: color-customization.kmd
• Light/dark contract: light-dark.kmd
• Preset registry: ui-style.kmd
• Code-block widget: code-block hosts the per-format blocks
• Rendering: design-gen themes kind extension
• Refs: M3 Color resources https://m3.material.io/styles/color/resources