Bootstrap a Design System

You are helping me generate a complete color scheme for my design system — semantic color role tokens, as CSS custom properties ready to ship. **Step 1 — Read the living brief:** Read `LIVING_BRIEF.md`. Note the theme setting (light-only / dark-only / both), any existing color decisions, and the product's density and brand stance. If the living brief includes a visual direction from `establish-visual-language`, note the OKLCH commitment level — this drives how much chromatic presence the surface and neutral tokens should have. **Step 2 — Read the references:** Read the following from the Sistema knowledge base: - Color architecture synthesis: `/raw/principles/color/architecture` - Primitive ramp scalability: `/raw/principles/color/primitive-ramp-scalability` - Token architecture synthesis: `/raw/principles/tokens/architecture` - Visual quality signals: `/raw/principles/quality/visual-quality-signals` The color architecture synthesis explains the four major architectural models, the non-negotiable floor (contrast requirements, foreground pairings, never-hardcode), and dark mode tonal shift logic. Use it to select the appropriate model for this product and to structure the output. The primitive ramp scalability document explains the default preference for full 19-stop primitive ramps before semantic mapping and how they feed the semantic layer. The visual quality signals document defines the OKLCH commitment levels (§4) and absolute color bans (§3.2) — apply both when selecting values. **Step 3 — Clarify scope:** Theme mode: {{color_mode}} - **Light only:** generate `:root { }` with light mode values only - **Dark only:** generate `:root { }` with dark mode values only - **Both:** generate `:root { }` with light mode values, then `[data-theme="dark"] { }` with dark mode values **Step 3.5 — Resolve seed colors and generate primitive ramps:** The default approach is to generate a full 19-stop OKLCH primitive ramp for each key hue before mapping semantic roles. This makes semantic role mapping deterministic and keeps the primitive layer extensible as the system grows. **Determine seed colors from the color direction:** My color direction: {{color_direction}} Read the color direction above and determine the seed hex(es) to use: - If a specific hex is given, use it directly. - If a color name or description is given (e.g. "royal blue", "warm amber"), select an appropriate seed hex that matches the intent. Prefer hues that are not the AI-default medium blue (220–240°) unless explicitly requested — run the first-order reflex check from the quality signals document. - If no color direction is given at all, check the LIVING_BRIEF for a primary seed hex from `establish-visual-language`. If none exists, ask the user for a primary brand color before proceeding. Generate ramps for at minimum: - **Primary hue** — the brand or action color seed - **Neutral/gray** — pick a seed with slight chroma that matches the product's temperature (warm: slight yellow/red shift; cool: slight blue/cyan shift). Do not use a pure achromatic gray. - **Feedback hues** — use the pre-built ramps from the Sistema palette library for error, success, and warning unless the brief specifies custom feedback colors. **API call — generate custom ramps:** POST `/api/palette` with the body: ```json { "colors": { "primary": "#[seed]", "neutral": "#[seed]" } } ``` The response is `{ "palettes": { "[name]": { "seed": "...", "stops": { "50": { "hex": "...", "contrast_white": ..., "contrast_black": ... }, ... "950": {...} } } } }`. Call this endpoint with your determined seed hex(es). Use the returned stop values for all semantic role assignments in Step 4. **Pre-built ramps for feedback and neutral hues:** If the brief does not specify custom feedback colors, fetch the pre-built library at `/palettes/library.json`. Available named ramps: slate, gray, zinc, neutral, stone (neutral grays); red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose (chromatic). Select the neutral ramp that best matches the product temperature and use red/amber/green for error/warning/success feedback roles. **Step 4 — Map semantic roles:** Using the generated ramp stops from Step 3.5, assign the following semantic roles as DTCG JSON. For each role, note which ramp name and stop number you selected. For each `on-*` role, include a `$description` with the contrast ratio against its paired surface. ```json { "color": { "primary": { "$type": "color", "$value": "#...", "$description": "" }, "on-primary": { "$type": "color", "$value": "#...", "$description": "X.X:1 against primary" } } } ``` **Required roles:** - `color.primary` and `color.on-primary` — primary action and its text - `color.primary-container` and `color.on-primary-container` — contained variant and its text - `color.secondary` and `color.on-secondary` — secondary action and its text - `color.secondary-container` and `color.on-secondary-container` - `color.surface` — default background - `color.surface-raised` — elevated surface (cards, sheets) - `color.surface-overlay` — modal / dialog overlay surface - `color.on-surface` — primary text on surface - `color.on-surface-muted` — secondary / muted text on surface - `color.border` — default border - `color.border-focus` — focus ring color (must meet 3:1 against surface) - `color.error` and `color.on-error` — error states - `color.success` and `color.on-success` — success / confirmation states - `color.warning` and `color.on-warning` — warning states **For dark mode (if theme is "both"):** Do not invert light mode values. Use tonal shift logic: surface values draw from the dark end of the neutral palette; primary/secondary role colors draw from the lighter portion of each hue to maintain contrast against dark surfaces. Every `on-*` role must meet WCAG 4.5:1 against its paired surface. Write overrides as a separate `color.dark.json` containing only the roles that change. **Contrast verification:** Before finalizing any role assignment, verify each `on-*` pairing using the Sistema contrast API: ``` POST /api/contrast { "foreground": "#hex-of-on-role", "background": "#hex-of-surface-role" } ``` The response returns the exact WCAG ratio and pass/fail for each criterion. All normal text `on-*` roles must return `aa_text: true` (≥ 4.5:1). `color.border-focus` must return `aa_ui: true` (≥ 3:1). Adjust stop selection for any pair that fails — do not proceed to the file write with a failing pair. Before finalizing, run these checks from the visual quality signals document: - **First-order reflex check:** Is the primary color medium-blue without explicit justification? Are surfaces generic near-white? If so, reconsider or justify. - **Commitment level check:** Do surface and neutral token chroma values match the OKLCH commitment level from the visual direction? (Restrained: C < 15; Committed: C 8–20; Full palette: C 15–30; Drenched: C 25+.) - **Absolute bans check:** No opacity-derived container colors; primary and secondary must have distinct hues; no pure `#000000` or `#FFFFFF` surfaces; neutral ramp must have hue temperature. Write to `tokens/src/color.json` (and `tokens/src/color.dark.json` if dark mode is required). These JSON files are the authoritative source — CSS is compiled from them by Style Dictionary, not authored separately. **Step 5 — Update the living brief:** Update the Color entry in Key Decisions and append to the decision log: ``` [date] — Color scheme generated — [architecture model, theme scope, commitment level, primary color] ``` ---