get-shit-pretty 0.7.4 → 0.8.2

package/bin/theme-css.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * theme-css.js — GSP deterministic token-to-CSS generator
+ *
+ * Reads a GSP style preset `.yml` file and outputs a shadcn/ui-compatible
+ * CSS variables block for `:root` and `.dark`.
+ *
+ * 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
+ *
+ * Token → CSS var mapping is 1:1. No derivation, no LLM guesswork.
+ * Hex values are converted to OKLCH. Alpha values (oklch with /) pass through.
+ * Sidebar vars are output verbatim. Extras (success/warning/info) become custom props.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// YAML parser (zero-dependency, handles the subset GSP uses)
+// ---------------------------------------------------------------------------
+
+function parseYaml(text) {
+  const lines = text.split('\n');
+  const root = {};
+  const stack = [{ indent: -1, obj: root }];
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const trimmed = raw.trimEnd();
+    if (!trimmed || trimmed.trimStart().startsWith('#')) continue;
+
+    const indent = raw.length - raw.trimStart().length;
+    const content = trimmed.trimStart();
+
+    // Handle inline arrays: key: [a, b, c]
+    const colonIdx = content.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = content.slice(0, colonIdx).trim();
+    const rest = content.slice(colonIdx + 1).trim();
+
+    // Pop stack to correct parent
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1].obj;
+
+    if (rest === '' || rest.startsWith('#')) {
+      // Nested object
+      parent[key] = {};
+      stack.push({ indent, obj: parent[key] });
+    } else if (rest.startsWith('[')) {
+      // Inline array — parse as string, not needed for color extraction
+      parent[key] = rest;
+    } else {
+      // Scalar — strip inline comments and quotes
+      let val = rest.split(' #')[0].trim();
+      if ((val.startsWith('"') && val.endsWith('"')) ||
+          (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      // Numbers
+      if (/^-?\d+(\.\d+)?$/.test(val)) {
+        parent[key] = parseFloat(val);
+      } else if (val === 'true') {
+        parent[key] = true;
+      } else if (val === 'false') {
+        parent[key] = false;
+      } else {
+        parent[key] = val;
+      }
+    }
+  }
+
+  return root;
+}
+
+// ---------------------------------------------------------------------------
+// Color conversion: hex → OKLCH
+// ---------------------------------------------------------------------------
+
+function hexToRgb(hex) {
+  const h = hex.replace('#', '');
+  const len = h.length;
+  if (len === 3) {
+    return [
+      parseInt(h[0] + h[0], 16),
+      parseInt(h[1] + h[1], 16),
+      parseInt(h[2] + h[2], 16),
+    ];
+  }
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16),
+  ];
+}
+
+// sRGB → linear
+function toLinear(c) {
+  c = c / 255;
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+// Linear RGB → XYZ (D65)
+function linearToXyz(r, g, b) {
+  return [
+    r * 0.4124564 + g * 0.3575761 + b * 0.1804375,
+    r * 0.2126729 + g * 0.7151522 + b * 0.0721750,
+    r * 0.0193339 + g * 0.1191920 + b * 0.9503041,
+  ];
+}
+
+// XYZ → OKLab
+function xyzToOklab(x, y, z) {
+  const l_ = Math.cbrt(0.8189330101 * x + 0.3618667424 * y - 0.1288597137 * z);
+  const m_ = Math.cbrt(0.0329845436 * x + 0.9293118715 * y + 0.0361456387 * z);
+  const s_ = Math.cbrt(0.0482003018 * x + 0.2643662691 * y + 0.6338517070 * z);
+  return [
+    0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_,
+    1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_,
+    0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_,
+  ];
+}
+
+// OKLab → OKLCH
+function oklabToOklch(L, a, b) {
+  const C = Math.sqrt(a * a + b * b);
+  let H = Math.atan2(b, a) * (180 / Math.PI);
+  if (H < 0) H += 360;
+  return [L, C, H];
+}
+
+function hexToOklch(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  const lr = toLinear(r);
+  const lg = toLinear(g);
+  const lb = toLinear(b);
+  const [x, y, z] = linearToXyz(lr, lg, lb);
+  const [L, a, bk] = xyzToOklab(x, y, z);
+  const [Lch, C, H] = oklabToOklch(L, a, bk);
+  // Format: oklch(L% C H)
+  const Lpct = (Lch * 100).toFixed(2);
+  const Cfmt = C.toFixed(4);
+  const Hfmt = H.toFixed(2);
+  return `oklch(${Lpct}% ${Cfmt} ${Hfmt})`;
+}
+
+// ---------------------------------------------------------------------------
+// Value formatter: hex → oklch, alpha values pass through
+// ---------------------------------------------------------------------------
+
+function formatValue(val) {
+  if (typeof val !== 'string') return String(val);
+  const v = val.trim();
+
+  // Already oklch (alpha or not) — pass through
+  if (v.startsWith('oklch(')) return v;
+
+  // Hex color
+  if (/^#[0-9a-fA-F]{3,6}$/.test(v)) {
+    return hexToOklch(v);
+  }
+
+  // Everything else (rgba, named colors, etc.) — pass through
+  return v;
+}
+
+// ---------------------------------------------------------------------------
+// CSS var name mapping (1:1 to shadcn/ui)
+// ---------------------------------------------------------------------------
+
+// Core color tokens → CSS var names
+const CORE_VARS = [
+  'background', 'foreground',
+  'card', 'card-foreground',
+  'popover', 'popover-foreground',
+  'primary', 'primary-foreground',
+  'secondary', 'secondary-foreground',
+  'accent', 'accent-foreground',
+  'muted', 'muted-foreground',
+  'destructive',
+  'border', 'input', 'ring',
+];
+
+// NOTE: 'sidebar' (not 'sidebar-background') matches shadcn's CSS var --sidebar
+const SIDEBAR_VARS = [
+  'sidebar', 'sidebar-foreground',
+  'sidebar-primary', 'sidebar-primary-foreground',
+  'sidebar-accent', 'sidebar-accent-foreground',
+  'sidebar-border', 'sidebar-ring',
+];
+
+const EXTRA_VARS = ['success', 'warning', 'info'];
+
+// Shape tokens → CSS vars
+const SHAPE_VARS = {
+  'border-radius-lg': '--radius',
+};
+
+// ---------------------------------------------------------------------------
+// CSS block generator
+// ---------------------------------------------------------------------------
+
+function generateBlock(colorObj, shapeObj, typographyObj, selector) {
+  if (!colorObj) return '';
+  const lines = [];
+
+  // Core vars
+  for (const key of CORE_VARS) {
+    if (colorObj[key] !== undefined) {
+      lines.push(`  --${key}: ${formatValue(colorObj[key])};`);
+    }
+  }
+
+  // Sidebar vars
+  for (const key of SIDEBAR_VARS) {
+    if (colorObj[key] !== undefined) {
+      lines.push(`  --${key}: ${formatValue(colorObj[key])};`);
+    }
+  }
+
+  // Chart vars — emit in both :root and .dark (dark falls back to light values if not set)
+  {
+    // For :root use light palette; for .dark use dark overrides falling back to light
+    const chartColors = [
+      colorObj['chart-1'] || colorObj.primary,
+      colorObj['chart-2'] || colorObj.secondary,
+      colorObj['chart-3'] || colorObj.accent,
+      colorObj['chart-4'] || colorObj.info || colorObj.primary,
+      colorObj['chart-5'] || colorObj.success || colorObj.secondary || colorObj.primary,
+    ];
+    chartColors.forEach((c, i) => {
+      if (c) lines.push(`  --chart-${i + 1}: ${formatValue(c)};`);
+    });
+  }
+
+  // Shape → radius (only in :root)
+  if (selector === ':root' && shapeObj) {
+    const lg = shapeObj['border-radius-lg'];
+    if (lg !== undefined) {
+      lines.push(`  --radius: ${lg};`);
+    }
+  }
+
+  // Typography → font CSS vars (only in :root)
+  if (selector === ':root' && typographyObj) {
+    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, cssVar] of fontMappings) {
+      if (typographyObj[ymlKey] !== undefined) {
+        lines.push(`  ${cssVar}: ${typographyObj[ymlKey]};`);
+      }
+    }
+  }
+
+  // Extras as custom properties
+  for (const key of EXTRA_VARS) {
+    if (colorObj[key] !== undefined) {
+      lines.push(`  --${key}: ${formatValue(colorObj[key])};`);
+    }
+  }
+
+  if (!lines.length) return '';
+  return `${selector} {\n${lines.join('\n')}\n}`;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+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`);
+    process.exit(0);
+  }
+
+  const inputPath = path.resolve(args[0]);
+  if (!fs.existsSync(inputPath)) {
+    console.error(`Error: File not found: ${inputPath}`);
+    process.exit(1);
+  }
+
+  const outputIdx = args.indexOf('--output');
+  const outputPath = outputIdx !== -1 ? path.resolve(args[outputIdx + 1]) : null;
+  const toStdout = args.includes('--stdout') || !outputPath;
+
+  const raw = fs.readFileSync(inputPath, 'utf8');
+  const preset = parseYaml(raw);
+
+  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) || null;
+
+  const rootBlock = generateBlock(colorLight, shape, typography, ':root');
+  const darkBlock = generateBlock(colorDark, null, null, '.dark');
+
+  const presetName = preset.name || path.basename(inputPath, '.yml');
+  const presetDesc = preset.description || '';
+
+  const header = [
+    `/* GSP theme: ${presetName} */`,
+    presetDesc ? `/* ${presetDesc} */` : null,
+    `/* Generated by bin/theme-css.js from ${path.basename(inputPath)} */`,
+    `/* Edit the .yml file, not this output */`,
+    '',
+  ].filter(Boolean).join('\n');
+
+  const output = [header, rootBlock, darkBlock ? '' : null, darkBlock].filter(s => s !== null).join('\n');
+
+  if (toStdout) {
+    process.stdout.write(output + '\n');
+  } else {
+    fs.writeFileSync(outputPath, output + '\n', 'utf8');
+    console.log(`Written to ${outputPath}`);
+  }
+}
+
+main();

package/gsp/agents/gsp-brand-coherence.md

@@ -0,0 +1,7 @@
+---
+name: gsp-brand-coherence
+description: Brand coherence auditor — scores intensity dials against archetype and surfaces tensions between declared values and expressed output
+tools:
+  - Read
+---
+Coherence auditor for gsp-brand-guidelines. Spawned by the skill after Pass 1 to evaluate the generated artifacts before user review.

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-brief
-description: Define your brand — who, why, and what it should feel like
+description: Define your brand — who, why, and what it should feel like — use when: create a brand, define our brand identity, who are we, what's our brand
 user-invocable: true
 allowed-tools:
   - Read
@@ -86,23 +86,35 @@ Before presenting personality options, **internally synthesize** promise (what s
     - Note: this is a high-level direction only. Brand strategy phase will deepen this into archetype + voice — don't over-refine here.
 8. What should the brand NEVER feel like? (use `AskUserQuestion` with 2-3 anti-directions inferred from their personality pick, plus open-ended option)
 9. Brands admired or styles to avoid? (open-ended `AskUserQuestion`)
+10. Visual direction — raw aesthetic feeling. Use `AskUserQuestion` (open-ended):
+    > "What should it look and feel like visually? You can share image or website links, describe a mood ('editorial and dark', 'warm brutalist', 'cinematographic with beautiful stills'), drop adjective clusters ('rounded, clean, airy'), or even describe a scene or texture. The weirder and more specific the better — this is what prevents a bland brand."
+    - Synthesize the answer into a `visual_direction` block in the brief: mood words, reference aesthetics, texture/atmosphere descriptors, any specific anti-patterns (e.g., "never stock-photo corporate"). This block directly informs color, typography, and imagery choices downstream.
 
 ## Step 4: Constraints & confirmation
 
-10. Any non-negotiables or constraints? (timeline, budget, must-haves) — open-ended `AskUserQuestion`
-11. State your understanding back: "Here's what I'm hearing: [summary]." Use `AskUserQuestion`:
+11. Any non-negotiables or constraints? (timeline, budget, must-haves) — open-ended `AskUserQuestion`
+12. State your understanding back — but lead with *feeling*, not facts. Format:
+
+    > "Here's what I'm hearing: [2-sentence factual summary].
+    > The feeling this brand should leave: **[emotional compass — one evocative sentence capturing the brand's energy, not its category]**."
+
+    The emotional compass is the hardest line to write and the most important. It should make the user feel something when they read it. Not "a fintech tool that simplifies investing" but "the brand that makes financial confidence feel earned, not given." Synthesize it from the personality direction, the persona aspiration, the brand POV, and the visual direction. It should be specific enough to be wrong — vague sentences aren't compasses.
+
+    Use `AskUserQuestion`:
     - **Looks good** — "That's accurate, let's go"
-    - **Adjust something** — "I want to change or add something"
+    - **Adjust the feeling** — "The compass is off — let me reframe it"
+    - **Adjust something else** — "Facts are right but I want to change something"
 
 If "Adjust" — ask what to change, update your understanding, re-confirm. Don't re-ask everything.
 
-## Step 5: Write artifacts
+## Step 5: Write artifacts and register brand
 
 Read templates at write time from `${CLAUDE_SKILL_DIR}/../../templates/branding/` and write:
 
 1. `.design/branding/{name}/BRIEF.md` from `brief.md` template
    - Populate all sections from conversation answers
    - Synthesize brand promise, POV, and personality (these are inferred, not asked directly)
+   - Write the confirmed emotional compass as `brand_heartbeat` in the Emotional Compass section
    - Set `brand_mode` to `new`
    - Set evolve-only sections (Existing Brand State, Evolution Scope) to "N/A — new brand"
 
@@ -117,6 +129,14 @@ Read templates at write time from `${CLAUDE_SKILL_DIR}/../../templates/branding/
 
 4. `.design/branding/{name}/ROADMAP.md` from `roadmap.md` template
 
+5. Write/update `.design/CLAUDE.md` — register the brand as started. If the file doesn't exist, read `${CLAUDE_SKILL_DIR}/../../templates/design-claude.md` first. Append under `## Brands`:
+
+```markdown
+### {brand-name} · in progress · {DATE}
+"{brand_heartbeat}"
+next: gsp-brand-research · .design/branding/{brand-name}/
+```
+
 ## Step 6: Route
 
 Use `AskUserQuestion` — always offer Continue / Stop here / What happens next:
@@ -126,4 +146,29 @@ Use `AskUserQuestion` — always offer Continue / Stop here / What happens next:
 - **What happens next?** — "Explain the research phase" → explain what brand-research does (market landscape, competitive audit, trend analysis, mood board direction) and how it uses the brief
 
 If `e2e: true`, mention that after the full branding diamond completes, it will auto-transition to project setup.
+
+## Step 7: e2e transition (only when `e2e: true` and branding diamond is complete)
+
+After all four brand phases complete (brand-research → brand-strategy → brand-identity → brand-guidelines), scaffold the project directory before invoking `/gsp-project-brief`:
+
+1. Derive `{project-slug}` from the brand name: lowercase, spaces and underscores replaced with hyphens.
+
+2. Create the project directory:
+```bash
+mkdir -p .design/projects/{project-slug}/
+```
+
+3. Read templates at write time from `${CLAUDE_SKILL_DIR}/../../templates/projects/` and write:
+   - `.design/projects/{project-slug}/config.json` from `config.json` template — set `project.name` (title-cased from project-slug) and `project.created` (ISO date)
+   - `.design/projects/{project-slug}/STATE.md` from `state.md` template — fill in project name and brand name
+
+4. Write `.design/projects/{project-slug}/brand.ref` containing the brand directory name (e.g. `{brand-name}`), so the project knows which brand it belongs to.
+
+5. Display:
+```
+  brand complete — {brand-name}
+  now let's scope your project.
+```
+
+6. Invoke `/gsp-project-brief` via Skill tool, passing `{project-slug}` so Step 0 resolves the existing directory rather than prompting for one.
 </process>

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-guidelines
-description: Operationalize your brand — assemble tokens, STYLE.md, component mapping, and guidelines (technical phase — benefits from capable models)
+description: Build design system tokens and STYLE.md (technical phase — benefits from capable models) — use when: create the design system, generate tokens, finalize brand guidelines, build the component system
 user-invocable: true
 allowed-tools:
   - Read
@@ -113,6 +113,7 @@ Redesign the system from the ground up, informed by what exists.
 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}/guidelines-structure.md` — guidelines.html structure spec (shadcn tokens, sections, primitive classes)
 - `${CLAUDE_SKILL_DIR}/methodology/gsp-brand-engineer.md` — agent methodology
 
 Spawn the `gsp-brand-engineer` agent. **Inline all content** — the agent should not need to read input files.
@@ -120,11 +121,12 @@ Spawn the `gsp-brand-engineer` agent. **Inline all content** — the agent shoul
 Pass in the agent prompt:
 - **Content of** all identity chunks + palettes.json (loaded in Step 1)
 - **Content of** strategy chunks: voice-and-tone.md, archetype.md, positioning.md (loaded in Step 1)
-- **Content of** BRIEF.md (loaded in Step 1)
+- **Content of** BRIEF.md (loaded in Step 1) — explicitly pass the `brand_heartbeat` field as a named input so the agent uses it in the hero headline if no manifesto line exists yet
 - **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** guidelines structure spec (loaded above) — follow this exactly for `guidelines.html`
 - The `system_strategy` and `tech_stack` values
 - **Output path:** `{BRAND_PATH}/patterns/`
 
@@ -136,55 +138,64 @@ Pass in the agent prompt:
 >
 > Do NOT produce component artifacts yet (token-mapping, overrides, custom specs). Those come after the user reviews the visual output.
 
-## Step 3.5: Visual review
+## Step 3.5: Coherence check
 
-Tell the user: "Open `{BRAND_PATH}/patterns/guidelines.html` in your browser — this is your brand in one page."
+Spawn the `gsp-brand-coherence` agent with a fresh context. Load the methodology and inline all inputs — the agent should not need to read files.
 
-Present a compact summary:
+### Load
+Read these and hold for inlining:
+- `${CLAUDE_SKILL_DIR}/methodology/gsp-brand-coherence.md` — agent methodology
+- `{BRAND_PATH}/patterns/{brand-name}.yml` — generated preset
+- `{BRAND_PATH}/patterns/guidelines.html` — generated visual guide
 
-```
-  {brand-name} guidelines
-  ═══════════════════════════════════════
+Extract from Step 1 context:
+- `archetype` — from archetype.md
+- `brand_heartbeat` — from BRIEF.md
+
+### Spawn `gsp-brand-coherence`
 
-    .yml preset
-      colors:     {primary}, {secondary}, {accent}
-      typography: {primary font}, {secondary font}
-      intensity:  variance {N}/10, motion {N}/10, density {N}/10
+Pass inline:
+- **Agent methodology** (loaded above)
+- **Content of** `{brand-name}.yml`
+- **Content of** `guidelines.html`
+- `archetype` and `brand_heartbeat`
 
-    STYLE.md
-      patterns:   {N} components defined
-      constraints: {N} never, {N} always rules
-      effects:    {interaction vocabulary list}
-      bold bets:  {1-line summary of boldest bet}
+The agent returns a structured coherence report. No back-and-forth — one response.
 
-    → open guidelines.html in your browser to preview
+### Present the report
 
+Display the agent's report, then add:
+
+```
+  → open guidelines.html in your browser
   ─────────────────────────────────────
 ```
 
 Use `AskUserQuestion`:
-- **Looks good** — "The brand looks right, build components"
-- **Adjust tokens** — "I want to tweak colors, typography, or spacing"
-- **Adjust patterns** — "I want to change component rules or constraints"
-- **Adjust intensity** — "More/less creative, more/less motion, more/less density"
+- **Looks right** — "Coherent — build components"
+- **Push [tension 1]** — pre-fill with the specific gap from the report
+- **Push [tension 2]** — same
+- **Adjust something else** — "I want to change colors / type / patterns"
 
-If adjustments needed, use `/gsp-brand-refine` with the feedback to surgically update the `.yml`, regenerate `STYLE.md`, and regenerate `guidelines.html`. Then re-present.
+If refinement needed → invoke `/gsp-brand-refine` with the specific tension. After it completes, re-spawn `gsp-brand-coherence` with the updated `.yml` and `guidelines.html`. Only proceed to Step 3.75 when the archetype tension is present and dials are coherent.
 
 ## Step 3.75: Perspective check
 
-Load persona profiles from `{BRAND_PATH}/BRIEF.md` and present stakeholder reactions:
+Load persona profiles and the `brand_heartbeat` from `{BRAND_PATH}/BRIEF.md`. Present stakeholder reactions framed around the compass:
 
-"Stress-testing the brand visuals:
+```
+  stress-testing against: "{brand_heartbeat}"
 
- {primary persona name}: {would this visual language feel trustworthy and appropriate?}
- Skeptic: {are the constraints too restrictive or too loose? Is the intensity calibrated right?}
- {top competitor}: {is the brand visually differentiated?}"
+  {primary persona name}: {does this visual language make them feel that sentence?}
+  Skeptic: {does the intensity feel calibrated — or is it playing it safe?}
+  {top competitor}: {is the brand visually distinct enough to own this feeling?}
+```
 
 Use `AskUserQuestion`:
-- **Lock it in** — "The brand is solid, build components"
-- **Adjust** — "One of these concerns resonates — I want to change something"
+- **Lock it in** — "The brand earns that feeling — build components"
+- **Adjust** — "One of these concerns resonates"
 
-If adjust → use `/gsp-brand-refine` with the concern, then re-present. If confirmed → proceed to components.
+If adjust → invoke `/gsp-brand-refine` with the concern, re-present. If confirmed → proceed to components.
 
 ## Step 4: Spawn brand engineer — Pass 2: Components
 
@@ -212,6 +223,14 @@ Update `{BRAND_PATH}/STATE.md`:
 - Record completion date
 - Set Prettiness Level to 100%
 
+Update `.design/CLAUDE.md` — replace the existing `### {brand-name}` entry (written by gsp-brand-brief when started) with the completed entry:
+
+```markdown
+### {brand-name} · complete · {DATE}
+"{brand_heartbeat}"
+.design/branding/{brand-name}/patterns/ — guidelines.html · STYLE.md · {brand-name}.yml
+```
+
 ## Step 5: Phase transition output
 
 Invoke `/gsp-phase-transition` with phase `guidelines` and output directory `{BRAND_PATH}/patterns/`.
@@ -224,6 +243,7 @@ Also display a brand summary after the standard transition — this is the final
 
 ```
   brand complete — {brand-name}
+  "{brand_heartbeat}"
 
     discover       {key finding}
     strategy       {archetype}, {positioning}, {top voice attributes}

package/gsp/skills/gsp-brand-guidelines/design-tokens.md

@@ -1,5 +1,7 @@
 # Design Token Standards
 
+> **GSP approach (v0.8.0+):** GSP presets use **shadcn/ui-native token names** directly — keys in `.yml` files map 1:1 to shadcn CSS variables (`background`, `foreground`, `primary`, `accent`, etc.). The W3C format below is background context on token standards in general; it does not reflect GSP's flat, shadcn-native schema. See `bin/theme-css.js` for how GSP converts `.yml` tokens to CSS.
+
 **Format:** W3C Design Tokens Community Group specification
 
 ---