get-shit-pretty 0.8.3 → 0.10.0

package/gsp/skills/gsp-accessibility/SKILL.md

@@ -46,6 +46,7 @@ Read `$ARGUMENTS` to determine the mode:
 |-------|------|--------|
 | `--check #FG #BG` | Quick contrast check | Display only |
 | `--tokens` | Token-only: contrast pairs, sizing, spacing | `critique/accessibility-token-audit.md` |
+| `--validate <yml-path>` | Pre-emit gate: validate a brand `.yml` for WCAG compliance | Exit 0 (pass) / exit 1 (fail) — failures to stdout, no file writes |
 | (no args) | Mode picker | Prompt user |
 
 Additional flag: `--level AAA` overrides conformance level (default: AA).
@@ -71,6 +72,10 @@ If args contain `--check`, extract the two hex color values and skip to Step 3.
 
 Skip to Step 4.
 
+### Validate mode (`--validate <yml-path>`)
+
+Skip to Step 4.5.
+
 ## Step 3: Quick check mode (`--check #FG #BG`)
 
 Calculate WCAG 2.x contrast ratio between the two hex colors.
@@ -205,6 +210,51 @@ Display result and use `AskUserQuestion`:
 - **Run code audit** — "run `/gsp-accessibility-audit --code` to check the codebase"
 - **Done** — "that's all for now"
 
+## Step 4.5: Validate mode (`--validate <yml-path>`)
+
+Pre-emit gate for `gsp-brand-guidelines` (and any caller that needs a yes/no contrast verdict on a brand `.yml` without project context).
+
+**Differs from `--tokens`:** no project resolution, no file writes, returns exit code instead of writing a chunk. Use when you need a hard PASS/FAIL gate before downstream emission.
+
+### Inputs
+
+- `<yml-path>` — absolute or relative path to a brand `.yml` preset (e.g. `.design/branding/{brand}/patterns/{brand-name}.yml`)
+- `--level AA|AAA` — optional conformance override (default: AA)
+
+### Checks (subset of `--tokens`, contrast-only)
+
+Reuse the contrast logic from Step 4 (sections 4.1, 4.2, 4.3):
+
+1. **Contrast pairs** — every semantic foreground/background pair from the `.yml`. Flag failures: normal text < 4.5:1 (AA) or < 7:1 (AAA), large text < 3:1 (AA) or < 4.5:1 (AAA), non-text < 3:1
+2. **Interactive states** — hover/active/focus/disabled pairs. Disabled states still need 3:1 non-text contrast
+3. **Focus ring** — `--ring` token vs adjacent backgrounds, ≥ 3:1
+4. **Dark mode** — if `dark_mode.color` exists, re-verify all pairs
+
+Skip the `--tokens` extras (touch targets, typography minimums) — those are not contrast gates.
+
+### Output
+
+**On pass** — print one line to stdout, exit 0:
+
+```
+✓ /gsp-accessibility --validate {yml-name} — N pairs checked, all WCAG 2.2 {level} compliant
+```
+
+**On fail** — print failing pairs + exit 1:
+
+```
+✗ /gsp-accessibility --validate {yml-name} — {M} contrast failure(s) (WCAG 2.2 {level})
+
+  Failures:
+    {token-pair}      ratio {N.N}:1   required {required}:1   ({use-case})
+    {token-pair}      ratio {N.N}:1   required {required}:1   ({use-case})
+    ...
+
+  Fix via: /gsp-brand-refine "{token-name} contrast"
+```
+
+**No file writes.** This mode is a callable gate — output goes to stdout, exit code carries the verdict. Stop here; no AskUserQuestion routing.
+
 ## Step 5: Update STATE.md
 
 If within a project and files were written:

package/gsp/skills/gsp-accessibility/motion-effects.md

@@ -0,0 +1,43 @@
+# Motion + Effects Accessibility
+
+Canonical accessibility guidance for visual effects. Read by `gsp-project-build`'s builder methodology and `gsp-project-build/visual-effects.md`. Owned by `gsp-accessibility` per the two-layer architecture (CLAUDE.md): expertise skills own domain knowledge.
+
+## prefers-reduced-motion
+
+All visual effects must degrade gracefully:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+This rule applies everywhere — entrance animations, hover transforms, scroll-driven reveals, parallax. No effect should fight the user's stated preference.
+
+## Contrast on effects
+
+Effects must not compromise text/UI contrast:
+
+- **Glow / shadow on text** — ensure text contrast meets WCAG AA *without* the effect (effects can fail in high-contrast mode or for users with backdrop-filter disabled)
+- **Backdrop-blur** — pair with `@supports not (backdrop-filter: blur(1px))` solid-background fallback. The fallback must independently meet AA contrast against the foreground content
+- **Gradient text** — test contrast ratio of *both endpoints*, not just the midpoint. A gradient from light-blue to dark-blue passes at one end and fails at the other
+- **Translucent surfaces** — verify the layer behind (worst case: pure white or pure black if backdrop-filter is dropped) meets AA against the foreground
+
+## Hover / interaction magnitudes
+
+Keep transforms small to avoid disorientation:
+
+- Translate: 2-4px maximum
+- Scale: 1.02-1.05 maximum (5% growth ceiling)
+- Rotation: avoid except for explicit affordances (loading spinners, expand chevrons)
+- Layout-property animation (width/height/padding) — don't; use transform instead
+
+## Cross-references
+
+- `gsp-project-build/visual-effects.md` — CSS recipes for the effects this guidance constrains
+- `gsp-accessibility-audit/wcag-checklist.md` — broader WCAG 2.2 AA criteria
+- `gsp-accessibility/SKILL.md` — `--check`, `--tokens` modes for contrast validation

package/gsp/skills/gsp-brand-apply/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: gsp-brand-apply
+description: Install a brand theme into a shadcn codebase — use when: apply the brand to the code, install the theme, switch to brand X, refresh the theme
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<context>
+The universal theme-install primitive. Reads a `{brand}.theme.json` (registry:theme) artifact and installs it into a shadcn codebase via `shadcn apply --only theme`. Surgical — only cssVars (and optionally fonts) change; components are untouched.
+
+Spawns an ephemeral localhost HTTP server (`serve-preset.js`, colocated in this skill's `bin/`) because shadcn CLI's `--preset` flag accepts HTTP URLs only (`file://` and bare paths are rejected).
+
+Called explicitly by the user, or invoked by `/gsp-brand-guidelines` (after generation, with consent) and `/gsp-brand-refine` (after token regen).
+</context>
+
+<objective>
+Install a brand's `{brand}.theme.json` into a target shadcn project's `globals.css`.
+
+**Input:** brand name (positional arg) + optional `--target <path>`
+**Output:** Updated CSS file (path declared in `{target}/components.json` → `tailwind.css`) — cssVars only — plus log entry in `{BRAND_PATH}/STATE.md`
+**Agent:** None — inline Bash
+</objective>
+
+<rules>
+- Always use `AskUserQuestion` for user-facing questions — never raw text prompts
+- One decision per question — never batch multiple questions in a single message
+</rules>
+
+<process>
+## Step 0: Resolve brand
+
+Parse the user's argument:
+- If a brand name was passed (e.g. `/gsp-brand-apply lyra`) → `BRAND={arg}`.
+- If no name was given → scan `.design/branding/` for brand directories.
+  - If exactly one → use it.
+  - If multiple → use `AskUserQuestion`: "Which brand should I apply?" — list names as options.
+  - If zero → error: "No brand found. Run `/gsp-brand-guidelines` first." Stop.
+
+Set `BRAND_PATH=.design/branding/{BRAND}`.
+Set `THEME_JSON={BRAND_PATH}/patterns/{BRAND}.theme.json`.
+
+If `THEME_JSON` does not exist → error: "Brand '{BRAND}' has no theme.json. Run `/gsp-brand-guidelines {BRAND}` to generate it." Stop.
+
+## Step 0.5: Pre-flight — preserve user work
+
+`shadcn apply --only theme` is not strictly cssVars-only. Its preflight may also bump dependency versions in `package.json` (notably `shadcn` itself and `@base-ui/react`), regenerate `package-lock.json`, and rewrite `components.json`. We don't suppress this — there's no upstream flag (see issue tracker) — but we refuse to run when those files have uncommitted work, so the user can review the dep changes via `git diff` afterward.
+
+If `{TARGET}` is inside a git repository, run:
+
+```bash
+git -C {TARGET} diff --quiet -- package.json package-lock.json components.json 2>/dev/null
+```
+
+If the exit code is non-zero (uncommitted changes exist in any of those three files), use `AskUserQuestion`:
+
+- Question: "`{TARGET}` has uncommitted changes in `package.json`, `package-lock.json`, or `components.json`. `shadcn apply` may modify these (preflight bumps versions). Continue anyway?"
+- Options:
+  - A: "Cancel — I'll commit/stash first"
+  - B: "Proceed anyway — I accept potential conflicts with my pending work"
+
+If A → exit cleanly. If B → continue.
+
+If `{TARGET}` is not a git repo, skip this check silently — there's nothing to compare against.
+
+## Step 1: Resolve target
+
+Parse `--target` flag if present.
+
+If no flag:
+- Read project config at `.design/projects/*/config.json` and find `app_path`.
+  - If exactly one project config → use that `app_path`.
+  - If multiple → use `AskUserQuestion`: "Which project's codebase?" — list project names + paths.
+  - If zero project configs → error: "No project found. Pass `--target <path>` explicitly." Stop.
+
+Set `TARGET={app_path}` (default `.` if empty).
+
+Verify `{TARGET}/components.json` exists. If not → error: "{TARGET} is not a shadcn project (no components.json). Run `/gsp-scaffold` first." Stop.
+
+## Step 2: Detect currently-installed brand (informational)
+
+Resolve the CSS path: read `{TARGET}/components.json` and extract the value at `.tailwind.css` (a relative path from `{TARGET}`). Open `{TARGET}/{cssPath}`. Look for OKLCH cssVars in `:root`. Compare the `--background` light value against `.design/branding/*/patterns/*.theme.json` files in the workspace.
+
+- If a match is found → `CURRENT={matched-brand-name}`.
+- If file exists but no match → `CURRENT="custom or shadcn defaults"`.
+- If file missing → `CURRENT="(none — fresh project)"`.
+
+This is informational only — surfaced in the confirmation message in Step 3.
+
+## Step 2.5: Detect custom token indirection
+
+Scan the cssVars sections of `{TARGET}/{cssPath}` (`:root` and `.dark` blocks) for declarations of the form `--<name>: var(--<other>);` — these are custom indirection layers (e.g. `--background: var(--brand-bg);`).
+
+`shadcn apply --only theme` will REPLACE those `var()` references with literal OKLCH values from the theme.json. The custom indirection is lost — the upstream tokens (e.g. `--brand-bg`) remain defined elsewhere in the file, but the shadcn cssVars no longer reference them.
+
+If any `var(--*)` declarations are found in the cssVars blocks, use `AskUserQuestion`:
+- Question: "`{cssPath}` has **{N} cssVar(s) using `var(--*)` indirection** (e.g. `{first-example}`). `shadcn apply` will replace these with literal OKLCH values, breaking the indirection layer. Continue?"
+- Options:
+  - A: "Yes, replace with literal values"
+  - B: "No, cancel — preserve the indirection"
+
+If B → append `- {ISO-8601 timestamp}: apply cancelled — would have broken indirection in {cssPath}` to `{BRAND_PATH}/STATE.md` under `## Apply log`. Output "Apply cancelled — preserve your indirection layer manually if needed." Exit cleanly.
+If A → continue.
+
+If no `var(--*)` indirection is found, skip this confirmation silently.
+
+## Step 3: Confirm (when overwriting a different installed brand)
+
+If `CURRENT` is a recognized brand name AND it differs from `BRAND`:
+
+Use `AskUserQuestion`:
+- Question: "Currently installed: **{CURRENT}**. Replace with **{BRAND}**?"
+- Options:
+  - A: "Yes, replace"
+  - B: "No, cancel"
+
+If B → append `- {ISO-8601 timestamp}: apply cancelled by user (target: {TARGET})` to `{BRAND_PATH}/STATE.md` under `## Apply log`. Output "Apply cancelled" and exit cleanly.
+If A → continue.
+
+If `CURRENT` is unrecognized or fresh, skip this confirmation and proceed silently.
+
+## Steps 4–6: Spawn preset server, run apply, kill server
+
+**Run Steps 4 through 6 as a single Bash call.** `SERVER_PID`, `PRESET_URL`, and `APPLY_EXIT` are shell variables — they do not survive across separate Bash tool invocations.
+
+```bash
+# Step 4: spawn preset server, capture URL
+node ${CLAUDE_SKILL_DIR}/bin/serve-preset.js {THEME_JSON} > /tmp/preset-server-url-$$.txt 2>/dev/null &
+SERVER_PID=$!
+# Wait up to 2s for the URL to be written
+for i in 1 2 3 4 5 6 7 8 9 10; do sleep 0.2; [ -s /tmp/preset-server-url-$$.txt ] && break; done
+PRESET_URL=$(head -1 /tmp/preset-server-url-$$.txt 2>/dev/null)
+rm -f /tmp/preset-server-url-$$.txt
+
+# Bail if the server didn't print a URL
+if [[ -z "$PRESET_URL" || "$PRESET_URL" != http* ]]; then
+  kill "$SERVER_PID" 2>/dev/null
+  wait "$SERVER_PID" 2>/dev/null
+  echo "ERROR: preset server failed to start — serve-preset.js executable? Node available?"
+  exit 1
+fi
+
+# Step 5: run apply (quote {TARGET} — paths may contain spaces)
+cd "{TARGET}" && npx shadcn@latest apply --only theme --preset "$PRESET_URL" --yes 2>&1
+APPLY_EXIT=$?
+
+# Step 6: kill preset server unconditionally
+kill "$SERVER_PID" 2>/dev/null
+wait "$SERVER_PID" 2>/dev/null
+
+# Surface APPLY_EXIT for the verification step
+echo "APPLY_EXIT=$APPLY_EXIT"
+```
+
+Capture the bash output (especially the `APPLY_EXIT=N` line and any shadcn stderr) to use in Step 7.
+
+## Step 7: Verify or report failure
+
+If `APPLY_EXIT != 0`:
+- Surface the captured shadcn output to the user (concise — full stderr, plus a single-line summary).
+- Append to `{BRAND_PATH}/STATE.md` under `## Apply log`: `- {ISO-timestamp}: apply FAILED — exit {code} on {TARGET}`.
+- Stop. Do NOT auto-retry. Do NOT manually paste tokens as a fallback.
+
+If `APPLY_EXIT == 0`:
+- Resolve the CSS path: read `{TARGET}/components.json` and extract the value at `.tailwind.css` (a relative path from `{TARGET}`).
+- Read `{BRAND_PATH}/patterns/{BRAND}.theme.json` and extract `cssVars.light.background` (the brand's signature OKLCH value).
+- Open `{TARGET}/{cssPath}`. Verify:
+  - Contains `oklch(`
+  - Has both `:root {` and `.dark {` blocks
+  - Declares `--background`, `--foreground`, `--primary`, `--radius`
+  - **Contains the exact `cssVars.light.background` value from the theme.json** (this distinguishes a successful brand apply from shadcn's own nova defaults, which also satisfy the structural checks above)
+- If any check fails → warn (do not error): "Apply reported success but expected tokens not found in `{cssPath}` — the apply may have fallen back to defaults. Inspect manually." Continue to Step 8.
+- If all checks pass → continue to Step 8.
+
+## Step 8: Log success
+
+Append to `{BRAND_PATH}/STATE.md` under a `## Apply log` section. If the file or section doesn't exist, create it.
+
+```
+## Apply log
+
+- {ISO-8601 timestamp}: applied to `{TARGET}` (replaced: {CURRENT})
+```
+
+## Step 9: Output
+
+After apply, check whether `package.json`, `package-lock.json`, or `components.json` were modified by shadcn's preflight:
+
+```bash
+cd {TARGET} && git diff --name-only -- package.json package-lock.json components.json 2>/dev/null
+```
+
+If the output is non-empty, list those files in the success block under a "Review" line so the user knows to inspect them. If empty (or the target is not a git repo), omit the Review line.
+
+```
+  ◆ brand applied — {BRAND} → {TARGET}
+
+    {cssPath} updated
+    Re-apply: /gsp-brand-apply {BRAND}
+    Refine:   /gsp-brand-refine
+
+    [if dep files changed]
+    Review:   git diff {file1} {file2} ...
+              (shadcn preflight may have bumped dep versions —
+               commit or revert as you prefer)
+
+  ──────────────────────────────
+```
+</process>

package/gsp/skills/gsp-brand-apply/bin/serve-preset.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * serve-preset.js — ephemeral HTTP server for shadcn --preset URL fetch.
+ *
+ * Usage (from repo root):
+ *   node gsp/skills/gsp-brand-apply/bin/serve-preset.js <path-to-registry-item.json>
+ *
+ * Behavior:
+ *   - Listens on a random free port on 127.0.0.1.
+ *   - Prints the URL ("http://127.0.0.1:<port>/<basename>") to stdout.
+ *   - Serves the file as application/json on any request path.
+ *   - Exits cleanly on SIGTERM/SIGINT.
+ *   - Self-exits after 60s as a safety net.
+ */
+
+'use strict';
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const TIMEOUT_MS = 60_000;
+
+function main() {
+  const filePath = process.argv[2];
+  if (!filePath) {
+    console.error('Usage: node gsp/skills/gsp-brand-apply/bin/serve-preset.js <path-to-json>');
+    process.exit(1);
+  }
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) {
+    console.error(`File not found: ${abs}`);
+    process.exit(1);
+  }
+  const body = fs.readFileSync(abs, 'utf8');
+  const basename = path.basename(abs);
+
+  const server = http.createServer((req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(body);
+  });
+
+  server.on('error', (err) => {
+    console.error(`Server error: ${err.message}`);
+    process.exit(1);
+  });
+
+  server.listen(0, '127.0.0.1', () => {
+    const { port } = server.address();
+    const url = `http://127.0.0.1:${port}/${basename}`;
+    process.stdout.write(url + '\n');
+  });
+
+  let shuttingDown = false;
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 1000).unref();
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  setTimeout(() => {
+    console.error('serve-preset: 60s safety timeout reached, exiting');
+    shutdown();
+  }, TIMEOUT_MS).unref();
+}
+
+main();

package/gsp/skills/gsp-brand-guidelines/SKILL.md

@@ -20,7 +20,7 @@ Identity made the creative decisions. This phase makes them work in code.
 Operationalize brand identity into project-ready artifacts and complete the branding diamond.
 
 **Input:** Brand identity (enriched by domain skills) + strategy + BRIEF.md
-**Output:** `{brand}/patterns/` ({brand-name}.yml, STYLE.md, guidelines.html, components/, INDEX.md)
+**Output:** `{brand}/patterns/` ({brand-name}.yml, {brand-name}.theme.json, STYLE.md, guidelines.html, components/, INDEX.md)
 **Agent:** `gsp-brand-engineer`
 </objective>
 
@@ -112,7 +112,7 @@ Redesign the system from the ground up, informed by what exists.
 ### Load references and agent methodology
 Read these files and hold their content for inlining into the agent prompt:
 - `${CLAUDE_SKILL_DIR}/../../templates/phases/patterns.md` — patterns output template
-- `${CLAUDE_SKILL_DIR}/design-tokens.md` — design tokens reference
+- `${CLAUDE_SKILL_DIR}/../gsp-style/style-preset-schema.md` — canonical `.yml` schema (shadcn-flat, 1:1 CSS var mapping)
 - `${CLAUDE_SKILL_DIR}/guidelines-structure.md` — guidelines.html structure spec (shadcn tokens, sections, primitive classes)
 - `${CLAUDE_SKILL_DIR}/methodology/gsp-brand-engineer.md` — agent methodology
 
@@ -125,7 +125,7 @@ Pass in the agent prompt:
 - **Content of** style base preset `.yml` + `.md` (loaded in Step 1) — `.yml` as structural scaffold, `.md` as philosophy + implementation content for STYLE.md
 - **Agent methodology** (loaded above)
 - **Content of** patterns output template (loaded above)
-- **Content of** design tokens reference (loaded above)
+- **Content of** style preset schema (loaded above) — the engineer assembles `{brand-name}.yml` matching this exact shape
 - **Content of** guidelines structure spec (loaded above) — follow this exactly for `guidelines.html`
 - The `system_strategy` and `tech_stack` values
 - **Output path:** `{BRAND_PATH}/patterns/`
@@ -216,6 +216,66 @@ Spawn the `gsp-brand-engineer` agent with (reuse **Agent methodology** loaded in
 >
 > The `.yml` and `STYLE.md` are confirmed — do not modify them. Focus on mapping tokens to the detected component library and specifying overrides.
 
+## Step 4.7: WCAG validation gate
+
+Before emitting `theme.json` (the artifact that installs into real codebases), validate the assembled `.yml` against WCAG 2.2 AA contrast requirements. Inaccessible token pairs must not ship to production.
+
+Invoke `/gsp-accessibility --validate {BRAND_PATH}/patterns/{brand-name}.yml` (use `--level AAA` if `accessibility_level` in the project config is set to AAA).
+
+- **Pass (exit 0):** continue to Step 4.75
+- **Fail (exit 1):** STOP. The skill prints failing token pairs + the recommended fix path. Surface the failures to the user with: `Theme emission blocked — {N} contrast failure(s). Run /gsp-brand-refine to fix the failing pairs, then re-run /gsp-brand-guidelines.` Do NOT emit theme.json. The pipeline is incomplete until validation passes
+
+## Step 4.75: Emit shadcn theme registry artifact
+
+Generate `{brand-name}.theme.json` (registry:theme) alongside the existing patterns. This is the artifact `/gsp-brand-apply` installs into shadcn codebases.
+
+```bash
+node ${CLAUDE_SKILL_DIR}/bin/theme-css.js \
+  {BRAND_PATH}/patterns/{brand-name}.yml \
+  --registry \
+  --output {BRAND_PATH}/patterns/{brand-name}.theme.json
+```
+
+Verify the file was written and contains valid JSON:
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('{BRAND_PATH}/patterns/{brand-name}.theme.json', 'utf8'))" \
+  && echo "✓ theme.json emitted"
+```
+
+If either command fails, surface the error and stop — the brand pipeline is incomplete without this artifact.
+
+## Step 4.8: Offer to apply theme to codebase
+
+Detect installable target. Read project config (`.design/projects/*/config.json`) and look for `preferences.app_path`:
+
+- If no project config exists, or `app_path` is empty/missing → skip this step. Output a one-line note: `Apply later with /gsp-brand-apply {brand-name}`. Continue to Step 4.5.
+- If `app_path` exists, check `{app_path}/components.json`:
+  - If missing → skip (no shadcn project to install into). Same one-line note.
+  - If present → continue.
+
+Detect currently-installed brand (informational):
+- Resolve the CSS path from `{app_path}/components.json` → `.tailwind.css` (a relative path).
+- Read `{app_path}/{cssPath}` if it exists.
+- Look for OKLCH `:root` declarations.
+- Compare `--background` light value against other `.design/branding/*/patterns/*.theme.json` files in the workspace.
+- Set `CURRENT={matched-brand-name}` or `CURRENT="shadcn defaults"` or `CURRENT="(none)"`.
+
+Use `AskUserQuestion`:
+- Question: "Apply **{brand-name}** to `{app_path}`? Currently installed: **{CURRENT}**. This replaces cssVars in the CSS file; components stay as-is."
+- Options:
+  - A: "Apply now"
+  - B: "Skip — I'll apply later"
+  - C: "Apply to a different project"
+
+On A: output `Run /gsp-brand-apply {brand-name}` as the next step the user should take.
+
+On B: output `Skipped. Apply later with /gsp-brand-apply {brand-name}.`
+
+On C: use `AskUserQuestion` to ask for the target path. Then output `Run /gsp-brand-apply {brand-name} --target {chosen-path}` as the next step.
+
+Continue to Step 4.5 regardless of choice.
+
 ## Step 4.5: Update state
 
 Update `{BRAND_PATH}/STATE.md`:
@@ -228,7 +288,7 @@ Update `.design/CLAUDE.md` — replace the existing `### {brand-name}` entry (wr
 ```markdown
 ### {brand-name} · complete · {DATE}
 "{brand_heartbeat}"
-.design/branding/{brand-name}/patterns/ — guidelines.html · STYLE.md · {brand-name}.yml
+.design/branding/{brand-name}/patterns/ — guidelines.html · STYLE.md · {brand-name}.yml · {brand-name}.theme.json
 ```
 
 ## Step 5: Phase transition output

package/{bin → gsp/skills/gsp-brand-guidelines/bin}/theme-css.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 /**
- * theme-css.js — GSP deterministic token-to-CSS generator
+ * theme-css.js — GSP deterministic token generator
  *
- * Reads a GSP style preset `.yml` file and outputs a shadcn/ui-compatible
- * CSS variables block for `:root` and `.dark`.
+ * Reads a GSP style preset `.yml` file and emits either a shadcn-compatible
+ * CSS variables block (`:root` and `.dark`) or a `registry:theme`
+ * registry-item.json artifact for use with `shadcn apply --only theme`.
  *
- * Usage:
- *   node bin/theme-css.js <path-to-preset.yml>
- *   node bin/theme-css.js <path-to-preset.yml> --output globals.css
- *   node bin/theme-css.js <path-to-preset.yml> --stdout
+ * Usage (from repo root):
+ *   node gsp/skills/gsp-brand-guidelines/bin/theme-css.js <preset.yml>                                # CSS to stdout
+ *   node gsp/skills/gsp-brand-guidelines/bin/theme-css.js <preset.yml> --output globals.css           # CSS to file
+ *   node gsp/skills/gsp-brand-guidelines/bin/theme-css.js <preset.yml> --stdout                       # CSS to stdout (explicit)
+ *   node gsp/skills/gsp-brand-guidelines/bin/theme-css.js <preset.yml> --registry --output theme.json # registry-item.json
  *
  * Token → CSS var mapping is 1:1. No derivation, no LLM guesswork.
  * Hex values are converted to OKLCH. Alpha values (oklch with /) pass through.
@@ -274,6 +276,103 @@ function generateBlock(colorObj, shapeObj, typographyObj, selector) {
   return `${selector} {\n${lines.join('\n')}\n}`;
 }
 
+// ---------------------------------------------------------------------------
+// Registry-item.json builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk a flat color object (e.g. preset.tokens.color) and convert every value
+ * through formatValue, returning a flat key→value map for cssVars.
+ * Keys are the same as in the YAML (background, primary, etc.) — NOT prefixed
+ * with "--" because shadcn's registry-item.json schema uses bare names.
+ */
+// Note: unlike generateBlock (CSS path), this does NOT synthesize chart-1..5
+// from primary/secondary/etc. when not explicitly defined in the YAML. All
+// current GSP presets define all five chart vars explicitly, so the paths
+// stay symmetric in practice; if a future preset omits chart vars, add the
+// fallback logic here too.
+function colorObjToCssVars(colorObj) {
+  if (!colorObj) return {};
+  const out = {};
+  // Walk all known CSS var groups: core, sidebar, chart, extras
+  const allKeys = [...CORE_VARS, ...SIDEBAR_VARS, ...EXTRA_VARS];
+  for (const key of allKeys) {
+    if (colorObj[key] !== undefined) {
+      out[key] = formatValue(colorObj[key]);
+    }
+  }
+  // Chart vars
+  const chartSources = [
+    colorObj['chart-1'],
+    colorObj['chart-2'],
+    colorObj['chart-3'],
+    colorObj['chart-4'],
+    colorObj['chart-5'],
+  ];
+  chartSources.forEach((c, i) => {
+    if (c !== undefined) {
+      out[`chart-${i + 1}`] = formatValue(c);
+    }
+  });
+  return out;
+}
+
+/**
+ * Build a shadcn registry-item.json object from a parsed preset.
+ */
+function buildRegistryItem(preset, inputPath) {
+  const name = preset.name || path.basename(inputPath, '.yml');
+  const title = preset.title || name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+  const description = preset.description || '';
+
+  const colorLight = (preset.tokens && preset.tokens.color) || {};
+  const colorDark = (preset.dark_mode && preset.dark_mode.color) || {};
+  const shape = (preset.tokens && preset.tokens.shape) || {};
+  const typography = (preset.tokens && preset.tokens.typography) || {};
+
+  // Build cssVars.theme from typography font mappings
+  const theme = {};
+  const fontMappings = [
+    ['font-family-primary', 'font-sans'],
+    ['font-family-mono', 'font-mono'],
+    ['font-family-display', 'font-display'],
+    ['font-family-secondary', 'font-secondary'],
+  ];
+  for (const [ymlKey, cssKey] of fontMappings) {
+    if (typography[ymlKey] !== undefined) {
+      theme[cssKey] = typography[ymlKey];
+    }
+  }
+
+  // Build cssVars.light — colors + radius
+  const light = colorObjToCssVars(colorLight);
+  const lg = shape['border-radius-lg'];
+  if (lg !== undefined) {
+    light['radius'] = String(lg);
+  }
+
+  // Build cssVars.dark — dark_mode color overrides
+  const dark = colorObjToCssVars(colorDark);
+
+  const registryItem = {
+    $schema: 'https://ui.shadcn.com/schema/registry-item.json',
+    name,
+    type: 'registry:theme',
+    title,
+    cssVars: {
+      ...(Object.keys(theme).length ? { theme } : {}),
+      light,
+      dark,
+    },
+  };
+
+  if (description) {
+    registryItem.description = description;
+  }
+
+  return registryItem;
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -281,8 +380,10 @@ function generateBlock(colorObj, shapeObj, typographyObj, selector) {
 function main() {
   const args = process.argv.slice(2);
   if (!args.length || args.includes('--help') || args.includes('-h')) {
-    console.log(`Usage: node bin/theme-css.js <preset.yml> [--output <file>] [--stdout]`);
-    console.log(`       node bin/theme-css.js gsp/skills/gsp-style/styles/saas.yml`);
+    const cmd = 'node gsp/skills/gsp-brand-guidelines/bin/theme-css.js';
+    console.log(`Usage: ${cmd} <preset.yml> [--output <file>] [--stdout] [--registry]`);
+    console.log(`       ${cmd} gsp/skills/gsp-style/styles/saas.yml`);
+    console.log(`       ${cmd} gsp/skills/gsp-style/styles/saas.yml --registry --output saas.theme.json`);
     process.exit(0);
   }
 
@@ -295,10 +396,23 @@ function main() {
   const outputIdx = args.indexOf('--output');
   const outputPath = outputIdx !== -1 ? path.resolve(args[outputIdx + 1]) : null;
   const toStdout = args.includes('--stdout') || !outputPath;
+  const asRegistry = args.includes('--registry');
 
   const raw = fs.readFileSync(inputPath, 'utf8');
   const preset = parseYaml(raw);
 
+  if (asRegistry) {
+    const registryItem = buildRegistryItem(preset, inputPath);
+    const output = JSON.stringify(registryItem, null, 2);
+    if (toStdout) {
+      process.stdout.write(output + '\n');
+    } else {
+      fs.writeFileSync(outputPath, output + '\n', 'utf8');
+      console.log(`Written to ${outputPath}`);
+    }
+    return;
+  }
+
   const colorLight = (preset.tokens && preset.tokens.color) || {};
   const colorDark = (preset.dark_mode && preset.dark_mode.color) || {};
   const shape = (preset.tokens && preset.tokens.shape) || {};
@@ -313,7 +427,7 @@ function main() {
   const header = [
     `/* GSP theme: ${presetName} */`,
     presetDesc ? `/* ${presetDesc} */` : null,
-    `/* Generated by bin/theme-css.js from ${path.basename(inputPath)} */`,
+    `/* Generated by theme-css.js from ${path.basename(inputPath)} */`,
     `/* Edit the .yml file, not this output */`,
     '',
   ].filter(Boolean).join('\n');