shawn-sandy/styles

styles

Theme generation and management for fpkit/acss projects. Routes between four flows depending on which slash command was invoked.

Token and role conventions: see references/role-catalogue.md and the CSS Token Convention below. OKLCH palette algorithm: see references/palette-algorithm.md. JSON Schema and round-tripping: see references/theme-schema.md. The JSON schema is internal to the round-trip scripts (tokens_to_css.py / css_to_tokens.py); the CSS Token Convention below is the user-facing authoring format.

---

Step 0 — Exit plan mode

Applies to every flow below (/theme-create, /theme-brand, /theme-update, /theme-extract). If the session is in plan mode, call ExitPlanMode before proceeding — the flows write theme CSS (light.css / dark.css / brand-*.css) and shell out to a per-flow subset of generate_palette.py, tokens_to_css.py, validate_theme.py, css_to_tokens.py, and verify_integration.py. Specifically: /theme-create and /theme-extract exercise the full generate → write → validate pipeline; /theme-brand with --from runs generate_palette.py then writes the brand file and validates, and without --from copies assets/brand-template.css and validates; /theme-update edits CSS in place and validates. Every flow then runs verify_integration.py per the "Integration verification (all flows)" section below. Plan mode blocks every one of those Write/Edit/Bash calls.

Stay in plan mode only when it is absolutely necessary — i.e. the user explicitly asked for a preview ("show me the palette first", "don't write the theme yet"). In that case, narrate which roles would be generated, which files would be written, and which validator would run — without invoking Write/Edit/Bash — and wait for approval before re-entering this skill.

---

CSS Token Convention

The authoring format for theme tokens is CSS custom properties — not JSON. Users edit light.css / dark.css / brand-*.css files directly; the JSON schema at ${CLAUDE_PLUGIN_ROOT}/assets/theme.schema.json is internal to the round-trip scripts and is not a user-facing contract. Existing CSS theme files remain byte-compatible with this convention.

Semantic role names

assets/theme.schema.json $defs/palette declares 18 defined --color-* properties total: 15 required roles plus 3 optional roles (--color-surface-subtle, --color-text-subtle, --color-brand-accent). Names stay byte-compatible with the bundled CSS theme files — no renames, no removals, ever. Group them by purpose, matching ROLE_GROUPS in ${CLAUDE_PLUGIN_ROOT}/scripts/_tokens.py:

Backgrounds

• --color-background (required) — page background
• --color-surface (required) — card / panel surface
• --color-surface-raised (required) — elevated surface (modals, popovers)
• --color-surface-subtle (optional) — table-stripe / hover surface

Text

• --color-text (required) — body text
• --color-text-muted (required) — secondary text
• --color-text-inverse (required) — text on primary background
• --color-text-subtle (optional) — tertiary text (timestamps, footnotes)

Borders

• --color-border (required) — default border
• --color-border-strong (required) — emphasized border (form-field focus)

Brand & semantic

• --color-primary (required) — brand primary
• --color-primary-hover (required) — primary hover state
• --color-success (required) — success / valid state
• --color-warning (required) — caution state
• --color-danger (required) — destructive / error state
• --color-info (required) — informational state
• --color-brand-accent (optional) — secondary brand color

Focus

• --color-focus-ring (required) — focus indicator color (inputs, buttons)

Full role catalog with contrast pairings is in references/role-catalogue.md.

Required Contrast Pairings (WCAG 2.2 AA)

Every theme must pass these pairings — the validator at ${CLAUDE_PLUGIN_ROOT}/scripts/validate_theme.py checks them automatically on every /theme-create, /theme-brand, /theme-update, and /theme-extract:

| Foreground | Background | Min ratio | Why | |---|---|---|---| | --color-text | --color-background | 4.5:1 | Body text on page (WCAG 1.4.3) | | --color-text-muted | --color-background | 4.5:1 | Secondary text on page (WCAG 1.4.3) | | --color-text | --color-surface | 4.5:1 | Body text on cards/panels | | --color-text-inverse | --color-primary | 4.5:1 | Label text on primary buttons | | --color-text-inverse | --color-success | 4.5:1 | Success state buttons / badges | | --color-text-inverse | --color-danger | 4.5:1 | Destructive buttons / error chips | | --color-text-inverse | --color-warning | 4.5:1 | Warning chips / banners | | --color-text-inverse | --color-info | 4.5:1 | Info chips / banners | | --color-focus-ring | --color-background | 3:1 | Focus indicator on page (WCAG 1.4.11) | | --color-border-strong | --color-surface | 3:1 | Form-field focus border (WCAG 1.4.11) |

The validator's full pair list (10 pairs at default thresholds) is in scripts/validate_theme.py:PAIRS. Any theme that fails one of these pairings should be revised — usually by adjusting the seed color or manually tuning the OKLCH lightness on the failing role.

Authoring flow

1. Generate or edit a CSS theme file directly. /theme-create and /theme-brand write light.css / dark.css / brand-*.css using the convention above. /theme-update edits role values in place.
2. The user never authors JSON. No theme.tokens.json to write or maintain.
3. Round-trip scripts (tokens_to_css.py, css_to_tokens.py) remain internal. They use the JSON schema to translate between the OKLCH palette generator's output and CSS, but the JSON shape is not a user-facing contract.
4. Validation runs automatically at the end of every theme command (no separate step). Failures are surfaced inline.

---

CSS layer ordering

Theme files participate in the canonical @layer cascade. foundation.css declares the layer order at the top of every consumer project:

@layer foundation, components, utilities, theme;

Generated light.css / dark.css / brand-*.css must be imported after foundation.css. The cascade outcome — theme > utilities > components > foundation — means --color-* values from theme files always win over any primitive tokens declared in @layer foundation. This is by design: the foundation layer intentionally omits --color-* semantic roles (P1) so theme files hold the only source of truth for every --color-* variable.

---

/theme-create <hex-color> [--mode=light|dark|both]

Purpose: Generate light.css and/or dark.css under src/styles/theme/ from a seed color.

Workflow

1. Validate the seed is a 3- or 6-digit hex color. If invalid, halt with usage hint.
2. Run ${CLAUDE_PLUGIN_ROOT}/scripts/generate_palette.py <hex-color> --mode=<mode> (default both). Capture JSON stdout.
   • If exit code 1 ("reasons" non-empty), print the reasons and halt.
3. Determine output directory. If src/styles/theme/ exists in the project, use it. Otherwise ask the developer where to write theme files.
4. Run ${CLAUDE_PLUGIN_ROOT}/scripts/tokens_to_css.py --stdin --out-dir=<dir> piping the palette JSON. This writes light.css and/or dark.css with mandatory var(--x, <fallback>) syntax.
5. Run ${CLAUDE_PLUGIN_ROOT}/scripts/validate_theme.py <dir>. If contrast failures are found, print them as warnings and continue — generation is complete but the developer should adjust the seed or manually tune values.
6. Regenerate bridge — if ${CLAUDE_PLUGIN_ROOT}/assets/utilities/token-bridge.css exists, run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/generate_bridge.py --theme-dir=<dir> --out=<projectRoot>/<utilitiesDir>/token-bridge.css so utility aliases reflect the new palette. Skip silently when no utilitiesDir is configured (i.e. detect_target.py --what=utilities returns source: none).
7. Print a summary: files written, primary color, top contrast ratios.

References to load

• references/palette-algorithm.md — OKLCH lightness targets and state-color hue offsets.
• references/role-catalogue.md — full role list and contrast targets.

---

/theme-brand <name> [--from=<hex-color>]

Purpose: Scaffold brand-<name>.css with light and dark primary/accent overrides.

Workflow

1. Validate <name> is a lowercase slug (alphanumeric + hyphens). If not, suggest a corrected slug.
2. Determine output directory (same as /theme-create).
3. If --from is provided:
   • Run ${CLAUDE_PLUGIN_ROOT}/scripts/generate_palette.py <hex> --mode=brand. Capture brand overrides JSON.
   • Write brand-<name>.css using the :root (light) and [data-theme="dark"] overrides.
4. If --from is not provided:
   • Copy ${CLAUDE_PLUGIN_ROOT}/assets/brand-template.css to brand-<name>.css. Instruct the developer to replace the placeholder values.
5. Run ${CLAUDE_PLUGIN_ROOT}/scripts/validate_theme.py <brand-file>. Report contrast results. Failures are warnings only (the brand file's primary is validated in context of the project's existing light.css background, which may not be present here).
6. Print the file path and instruct the developer to add an import after light.css and dark.css in their entry file.

References to load

• references/palette-algorithm.md — brand mode generation.
• references/role-catalogue.md — which roles are allowed in brand files.

---

/theme-update <file> <--color-role=#hex> [...]

Purpose: Edit specific role values in an existing theme file and re-validate.

Workflow

1. Confirm <file> exists and its name matches light.css, dark.css, or brand-*.css. Halt if not.
2. Parse the developer's role=value arguments. Each must be of the form --color-<role>=#<hex>.
3. For each update: a. Use Edit to replace the existing hex value for that role in-place, preserving comments and file structure. b. After each edit, run ${CLAUDE_PLUGIN_ROOT}/scripts/validate_theme.py <file>. c. If any contrast pair fails: print the failure, revert the edit for that role (restore original value), and continue with remaining roles.
4. Regenerate bridge — after all accepted edits, run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/generate_bridge.py --theme-dir=<dir> --out=<projectRoot>/<utilitiesDir>/token-bridge.css so utility aliases stay in sync. Skip silently when no utilitiesDir is configured.
5. Print a final table: role / old value / new value / accepted|reverted.

References to load

• references/role-catalogue.md — contrast thresholds per pair.

---

/theme-extract <image-path|figma-url>

Purpose: Extract brand colors from an image or Figma design and generate theme CSS.

Workflow

1. Detect input type:
   • figma.com URL → delegate to user-level figma-design-tokens skill.
   • File path (png/jpg/webp/gif) → delegate to user-level design-token-extractor skill.
   • Neither → halt with usage hint.
2. Both extractors return at minimum a primary hex color (and optionally secondary, accent, background). Map the primary value to the seed color.
3. Run ${CLAUDE_PLUGIN_ROOT}/scripts/generate_palette.py <primary-hex> --mode=both. Capture JSON.
4. If the extractor also returned secondary or accent colors, AskUserQuestion: "Should I also scaffold a brand preset using the secondary color?" If yes, run the brand flow inline.
5. Write theme CSS via ${CLAUDE_PLUGIN_ROOT}/scripts/tokens_to_css.py. Validate with ${CLAUDE_PLUGIN_ROOT}/scripts/validate_theme.py.
6. Optionally write theme.tokens.json alongside the CSS files:
   • Run ${CLAUDE_PLUGIN_ROOT}/scripts/css_to_tokens.py on the written files and save the result.
7. Print files written and a note about round-tripping via scripts/css_to_tokens.py.

References to load

• references/palette-algorithm.md
• references/theme-schema.md — JSON output format and round-trip contract.
• references/role-catalogue.md

---

/color-scale <color> [--name=<name>] [--format=css|json|both]

Purpose: Generate a 10-step OKLCH color scale (steps 50–900) from any seed color — a hex value, a CSS named color, or a theme role from the project's existing theme.

Input resolution

Resolve <color> to a 6-digit hex string before calling the script:

1. Hex value (#rrggbb or #rgb) — use directly, no lookup needed.
2. Theme role name (background, primary, surface, text, border, etc.) — find the project's light.css (or dark.css if specified), grep for --color-<role>:, and extract the hex fallback from the var(--color-<role>, <hex>) value. If both files exist, default to light.css. If neither exists, halt with: "No theme file found. Run /theme-create first or pass a hex value directly."
3. CSS named color (red, cornflowerblue, tomato, etc.) — resolve to hex using the W3C CSS Color 4 named-color table (Claude knows these). Example: red → #ff0000, cornflowerblue → #6495ed.
4. Anything else — halt with the usage hint.

Default --name:

• Theme role input → use the role name (e.g. primary → --color-primary-50)
• Named color input → use the color name (e.g. red → --color-red-50)
• Hex input → use scale unless --name is provided

Workflow

1. Resolve <color> to hex per the rules above.

2. Run ${CLAUDE_PLUGIN_ROOT}/scripts/generate_color_scale.py <hex> --name=<name> --format=both. Capture stdout.

   • If exit code non-zero, print the stderr message and halt.
   • The script emits two sections separated by a blank line: JSON first, then the CSS block. Split on the first blank line to isolate each section.

3. Parse the JSON section (everything before the first blank line) to extract the 10 steps entries.

4. Display results in this order: a. CSS block — the :root { … } output from the script (ready to paste or write to a file). b. Scale table — a compact Markdown table:

   | Step | Hex | OKLCH | |------|-----|-------| | 50 | #f3f5fc | oklch(0.971 0.010 273.4) | | … | … | … | | 900 | #050128 | oklch(0.137 0.080 276.5) |

5. If the user asked to write the scale to a file, write to the path they specified. Otherwise display only — no files written unless explicitly requested.

References to load

• references/palette-algorithm.md — OKLCH color space and gamut clamping behaviour.

Error handling

| Situation | Action | |---|---| | Resolved hex is invalid | Halt: "<value>" is not a valid hex color. Use #rrggbb or #rgb. | | Theme role not found in CSS file | Halt: "--color-<role> not found in <file>. Check the role name or pass a hex directly." | | generate_color_scale.py exits 2 | Print stderr message and halt. |

---

Style-Tune Mode — Theme-Layer Adjustment

Invoked by /style-tune when the subject resolves to a theme role. See style-tune/SKILL.md Step A for intent parsing and dispatch.

ST-B. Locate theme files

Locate src/styles/theme/light.css and src/styles/theme/dark.css.

• Both exist → edit both with the same OKLCH delta (auto-mirror — same perceptual shift, mode-appropriate hex per file).
• Only one exists → edit that one.
• brand-*.css files are NOT edited unless the user names the brand explicitly. When brand files are present and unnamed, surface a hint in Step F: "Brand <name> is present and unchanged. To tune it, say 'tune the <name> brand'."
• No theme files found → halt: "No theme files at src/styles/theme/. Run /theme-create #seedhex first."

ST-C. Compute theme deltas

For each (role, delta) resolved in style-tune/SKILL.md Step A:

1. Read the current hex from each in-scope file via python3 ${CLAUDE_PLUGIN_ROOT}/scripts/css_to_tokens.py <theme-file>.
2. Compute the new hex via python3 ${CLAUDE_PLUGIN_ROOT}/scripts/oklch_shift.py <currentHex> --hue=±deg --chroma=×float --lightness=±float.
   • Exit 0 (always when a hex is produced): use the returned hex. If clamped: true, surface reasons in Step F as informational warnings and still apply.
   • Exit 2: usage / IO error — surface stderr and skip that role.
3. Paired-role rule: when shifting --color-primary, always shift --color-primary-hover by the same delta. Treat both as a single atomic batch entry.
4. Dark-mirror rule: when both files are in scope, run the same delta against each file's starting hex — the two files yield mode-appropriate hex values.
5. Build the full plan as (file, role, oldHex, newHex) tuples. Do not invoke /theme-update yet — pre-validate first.

ST-D0. Pre-validate the theme batch

1. Create a tmp directory via mktemp -d.
2. Copy each in-scope theme file into the tmp dir and apply the proposed edits (preserve comments and whitespace).
3. Run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_theme.py <staged-file> on each staged copy.
4. If any contrast pair fails on any file, halt the entire batch — write nothing. Print the failures and hint: "Re-run with a smaller delta, or pick an explicit hex via /theme-update."

ST-D1. Apply theme edits

With the batch pre-validated, invoke /theme-update <file> --color-<role>=#<hex> [...] once per theme file. /theme-update runs validate_theme.py internally; given D0, this should always pass.

ST-E. Post-apply checks

If /theme-update's post-write validation fires unexpectedly (rounding mismatch between oklch_shift.py and validate_theme.py), surface the discrepancy as a bug and suggest git revert.

After applying any colour shift, inspect the post-edit OKLCH of the tuned role. If chroma < 0.05 OR |hue − palette-derived hue| > 30°, append a drift hint to Step F: "Note: --color-<role> has drifted from its palette-derived value. Consecutive tunes accumulate hex round-trip noise — run /theme-create #seedhex to reset."

---

Integration verification (all flows)

After any flow writes theme CSS to disk and validate_theme.py succeeds, run ${CLAUDE_PLUGIN_ROOT}/scripts/verify_integration.py <project_root> to confirm the entrypoint actually imports the generated theme. The verifier reads stack.entrypointFile from .acss-target.json (populated by detect_stack.py during /kit-add first-run, or after /setup).

• Exit 0 → theme is wired up. Done.
• Exit 1 → print the reasons array as a numbered fix-up list. Do not auto-edit the entrypoint — the developer adds the import themselves.
• If .acss-target.json lacks a stack block, the verifier exits 1 with a hint to run detect_stack.py first. Surface that hint and continue (theme generation itself succeeded).

---

Error handling (all flows)

| Situation | Action | |---|---| | Seed hex invalid | Halt with: "<value>" is not a valid hex color. Use #rrggbb or #rgb. | | generate_palette.py exits 1 | Print each reason from "reasons" array. Halt. | | Output file already exists | Halt with list of conflicts. Proceed only with --force. | | Contrast failure during update | Revert that specific role. Continue with remaining roles. | | Extractor skill unavailable | Halt with: "/theme-extract requires the design-token-extractor or figma-design-tokens skill. Run: /find-skills design-token" |