get-shit-pretty 0.7.4 → 0.8.3

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
 
 ---

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

@@ -0,0 +1,167 @@
+# guidelines.html — Structure Spec
+
+The `guidelines.html` is the visual conference of the entire brand pipeline — every phase of the branding diamond distilled into one self-rendering document:
+
+- **Discover** → personas
+- **Strategy** → positioning, voice
+- **Identity** → color, typography, visual elements, logo
+- **Patterns** → components, tokens
+
+It uses the brand's own tokens, type, and primitives to render itself. One file, no build step, open in a browser. When someone opens this file, they should understand the brand completely — who it's for, what it stands for, and how it looks and speaks.
+
+**Every element in this document must be derived from the brand pipeline outputs.** There are no defaults, no fallbacks, no generic treatments. If the brand is dark and editorial, the doc is dark and editorial. If the brand is warm and rounded, the doc is warm and rounded. The guidelines file is not a template being filled in — it is a brand artifact being built from the ground up using everything the pipeline produced.
+
+## `:root` — shadcn-native token names
+
+Use these exact CSS variable names so the file maps 1:1 with the shadcn token system. All values come from the brand's `.yml` tokens — use OKLCH values from palettes.json where available.
+
+```css
+:root {
+  /* shadcn core */
+  --background: ...;         /* page background */
+  --foreground: ...;         /* primary text */
+  --primary: ...;            /* brand primary color */
+  --primary-foreground: ...; /* text on primary */
+  --secondary: ...;          /* secondary surface */
+  --secondary-foreground: ...;
+  --muted: ...;              /* muted surface */
+  --muted-foreground: ...;   /* secondary text */
+  --accent: ...;             /* accent color (the memorable one) */
+  --accent-foreground: ...;
+  --destructive: ...;        /* error state */
+  --border: ...;             /* border color */
+  --ring: ...;               /* focus ring */
+  --radius: ...;             /* base radius */
+
+  /* Brand-specific extensions */
+  --font-display: ...;       /* heading/editorial font */
+  --font-body: ...;          /* body/UI font */
+  --font-mono: ...;          /* data/code font */
+  --ease: ...;               /* brand easing curve */
+}
+```
+
+## Primitive classes
+
+Define only the primitives the brand actually uses. Their implementation is derived from the brand's identity — intensity.variance, visual_direction, effects vocabulary. Don't define a class that doesn't serve this brand.
+
+```css
+/* examples — implement only what fits the brand */
+.frosted-glass         /* glass surface — opacity/blur derived from brand intensity */
+.frosted-glass-strong  /* heavier glass — for hero overlays */
+.grain                 /* noise texture — only if brand uses texture */
+.glow                  /* ambient radial glow — only if brand uses glow */
+.atmosphere            /* full-bleed animated gradient — derived from brand palette */
+```
+
+## Layout primitives
+
+```css
+.container      /* max-width wrapper, responsive padding */
+section         /* section spacing — density derived from brand intensity */
+.section-label  /* eyebrow label */
+.section-heading /* large section heading */
+```
+
+## Sections
+
+The template defines a baseline section order. Follow it. If the brand warrants additional sections beyond this list — imagery style, motion principles, iconography, spatial system, co-branding rules, etc. — add them where they fit. Number sections sequentially. Each section gets an `id` for sidebar navigation.
+
+### Navigation — always
+Fixed left sidebar. Table of contents linking to every section. Brand-derived styling — font, color, spacing, all from the pipeline. Hidden on mobile.
+
+**Section ID convention:** every section in the doc must have an `id` attribute that the nav links to:
+
+```html
+<!-- nav -->
+<nav id="toc" style="position: fixed; left: 0; top: 0; height: 100vh; width: 180px; z-index: 50;
+                     overflow-y: auto; display: flex; flex-direction: column;
+                     justify-content: center; padding: 0 28px; gap: 8px;
+                     border-right: 1px solid var(--border); background: var(--background);">
+  <a href="#hero"         class="toc-link">Brand</a>
+  <a href="#logo"         class="toc-link">Logo</a>
+  <a href="#positioning"  class="toc-link">Positioning</a>
+  <a href="#color"        class="toc-link">Color</a>
+  <a href="#typography"   class="toc-link">Typography</a>
+  <a href="#visuals"      class="toc-link">Visual Elements</a>
+  <a href="#components"   class="toc-link">Components</a>
+  <a href="#personas"     class="toc-link">Personas</a>
+  <a href="#voice"        class="toc-link">Voice</a>
+  <!-- add entries for any brand-specific sections -->
+</nav>
+
+<!-- main content offset -->
+<main style="margin-left: 180px;">
+
+  <section id="hero">...</section>
+  <section id="logo">...</section>
+  <!-- each section id matches its toc-link href -->
+
+</main>
+```
+
+`.toc-link` styling: use the brand's body font, `--muted-foreground` at rest, `--foreground` on hover, no underline. Active state via a 10-line scroll listener that adds `.active` (accent color) to the link whose section is in view — include this JS inline at the bottom of `<body>`. Keep it small.
+
+### Hero — always
+Defined entirely by the brand. Visual direction, archetype, and identity outputs determine the background, typography scale, layout density, and supporting content. No default treatment.
+
+**The headline must be the manifesto line from `positioning.md`.** If strategy phase is not complete, fall back to `brand_heartbeat` from `BRIEF.md`. Never generate a generic headline — this line was earned through the pipeline and must appear here.
+
+The hero should feel like opening a brand book. Someone who sees it should understand the brand's energy before reading a single label.
+
+### Logo
+Logo marks (icon, wordmark, lockup) on the brand's background. Composition rules, clear space, forbidden uses. Skip if no logo was defined in identity.
+
+### Positioning
+Brand promise, point of view, manifesto line. Rendered as editorial content using the brand's type hierarchy and visual language.
+
+### Color
+Swatch grid: name, hex, OKLCH per color. Grouped by role. Contrast pairs. Layout derived from the brand.
+
+### Typography
+Show the full type scale rendered live in the actual fonts — not a table, not a screenshot. Each step is a real HTML element styled with the brand's CSS vars.
+
+For each scale step show:
+- The text rendered at its actual size
+- Label: step name + font family + weight + size + line-height
+- A sample sentence or phrase that fits the brand voice (not "The quick brown fox")
+
+Render all steps in sequence from largest to smallest so the scale relationship is visible at a glance. Show each typeface family in its own block — display font, body font, mono font — with the scale steps that use it.
+
+```html
+<!-- example step -->
+<div style="margin-bottom: 48px;">
+  <div class="scale-step" style="font-family: var(--font-display); font-size: 4rem; line-height: 1.05; letter-spacing: -0.03em;">
+    We ship what others pitch.
+  </div>
+  <div class="scale-meta">Display · Instrument Serif · 400 · 64px / 1.05</div>
+</div>
+```
+
+Include pairing notes when the brand uses multiple typefaces: which font handles which role, and what the contrast between them communicates.
+
+### Visual Elements
+The brand's signature motifs: textures, dividers, shapes, glows, atmospheric effects, SVG elements. Each shown with its composition rule — when to use it, how much, what it must never do.
+
+### Components
+Live component previews in brand tokens: buttons, inputs, cards, badges. Include only if the brand has a meaningfully distinctive component style.
+
+### Personas
+Each persona as a branded card: name, role, frustration, aspiration. Styled in the brand's own visual language.
+
+### Voice
+Never / always rules as styled components. Monospace prefix (`x` never, `>` always).
+
+### + Brand-specific sections
+Add sections as needed to fully convey the brand. Examples: Imagery, Motion, Iconography, Spatial System, Co-branding. If the pipeline produced it and it shapes how the brand is applied, it belongs here.
+
+## Mobile
+
+Single `@media (max-width: 768px)` block. Hide sidebar nav. Stack grids. Reduce section padding. Scale type with `clamp()`.
+
+## Quality bar
+
+- Open in browser → immediately recognizable as this brand, not a generic template
+- `:root` token names match shadcn — a dev can paste directly into `globals.css`
+- Every visual decision traces back to a pipeline artifact
+- No placeholder content — if a section has nothing real to show, it's omitted

package/gsp/skills/gsp-brand-guidelines/methodology/gsp-brand-coherence.md

@@ -0,0 +1,86 @@
+<role>
+You are a brand coherence auditor spawned by `/gsp-brand-guidelines` after the brand-engineer produces its first-pass artifacts.
+
+Your only job is to evaluate whether the output is coherent with the brand's archetype and intensity intentions — and return a structured report. You do not make changes. You do not ask questions. You return one report.
+</role>
+
+<inputs>
+You receive inlined:
+- `{brand-name}.yml` — the generated preset (intensity dials, tokens, patterns, constraints)
+- `guidelines.html` — the generated visual guide (use for component-level verification)
+- `archetype` — the brand's chosen archetype
+- `brand_heartbeat` — the emotional compass confirmed in the brief
+</inputs>
+
+<methodology>
+## Step 1: Archetype gate
+
+Each archetype has a signature tension it must express. Answer this question first — it is the primary check. Intensity dials are secondary.
+
+| Archetype | Signature question |
+|-----------|-------------------|
+| Jester | What specific rule is being broken in the visual system? If nothing is broken, it's not Jester enough. |
+| Rebel | What visual convention is explicitly rejected? |
+| Creator | What is distinctively crafted that couldn't come from a default template? |
+| Sage | Is the restraint active (every reduction intentional) or passive (just plain)? |
+| Explorer | Where is the sense of movement, discovery, or possibility? |
+| Hero | Does the visual language communicate strength and achievement? |
+| Caregiver | Does it feel warm and trustworthy without being corporate? |
+| Lover | Is there sensuality, richness, or beauty in the material choices? |
+| Ruler | Does it command authority through precision and restraint? |
+| Magician | Is there a sense of transformation or the unexpected? |
+| Innocent | Is the simplicity purposeful and delightful, not just empty? |
+| Everyman | Does it feel accessible and genuine, not dumbed-down? |
+
+If the archetype's signature tension is absent from the output, that is the primary tension to flag — regardless of what the dials say.
+
+## Step 2: Intensity dial scoring
+
+Read the declared dial values from `intensity:` in the `.yml`. Then infer what the token values actually express visually.
+
+Work primarily from the `.yml` tokens — they are the source of truth:
+- `variance` — expressed by: radius values, shadow complexity, unexpected color usage, spacing irregularity
+- `motion` — expressed by: transition durations, animation presence in effects, interaction vocabulary richness
+- `density` — expressed by: spacing scale, font size range, information layer count
+
+Cross-check against `guidelines.html` for specific component implementations (button styles, card treatments, border-radius in practice).
+
+Score each dial: **declared N/10 → expressed N/10**. A gap of ±2 or more is a coherence miss worth flagging.
+
+## Step 3: Bold bet
+
+Identify the single most distinctive choice in the output — the thing that would be hardest to achieve with a default template. One line.
+
+## Step 4: Surface tensions
+
+Rank all gaps found. Return the top 2 — specific and actionable:
+- Not "could be bolder"
+- Yes: "border-radius is 4px across all components — that reads as variance 3/10, declared dial is 8/10"
+- Yes: "button uses standard padding and default shape — no Jester rule broken in the primary interactive element"
+
+If no gaps ≥ 2 points and the archetype tension is present, there are no tensions to surface.
+</methodology>
+
+<output>
+Return exactly this format — nothing else:
+
+```
+{brand-name}  ·  {archetype}  ·  {brand_heartbeat}
+
+  intensity dials
+    variance   declared {N}/10  →  reads {N}/10  {✓ or ⚠}
+    motion     declared {N}/10  →  reads {N}/10  {✓ or ⚠}
+    density    declared {N}/10  →  reads {N}/10  {✓ or ⚠}
+
+  archetype    {✓ tension present: one-line description} or {⚠ tension absent: one-line description}
+
+  tensions
+    1. {specific gap — or "none" if coherent}
+    2. {specific gap — or omit if only one}
+
+  bold bet
+    {one-line description of most distinctive choice}
+```
+
+No preamble. No explanation. Just the report.
+</output>

package/gsp/skills/gsp-brand-guidelines/methodology/gsp-brand-engineer.md

@@ -9,8 +9,8 @@ The identity phase produced: logo directions, color system (with OKLCH palettes)
 <inputs>
 - Identity chunks: color-system.md, typography.md, logo-directions.md, imagery-style.md (all enriched by domain skills)
 - Identity palettes.json (OKLCH scales)
-- BRIEF.md
-- Strategy chunks: voice-and-tone.md, archetype.md, positioning.md
+- BRIEF.md — including `brand_heartbeat` (the emotional compass sentence confirmed in the brief phase)
+- Strategy chunks: voice-and-tone.md, archetype.md, positioning.md — `manifesto_line` from positioning.md is the hero headline; fall back to `brand_heartbeat` if not present
 - system_strategy and tech_stack from config.json
 - `.design/system/STACK.md`, `COMPONENTS.md`, `TOKENS.md` (if exist)
 - style_base from config.json + preset `.yml` (if set) — the starting scaffold
@@ -42,7 +42,15 @@ The identity phase produced: logo directions, color system (with OKLCH palettes)
 
 4. **Component overrides + custom specs** — only for components that need treatment beyond tokens.
 
-5. **`guidelines.html`** — self-contained visual brand guide. This is the primary artifact users see. Single HTML file with embedded CSS, no external dependencies. Shows: brand colors as swatches with hex/OKLCH values, type scale rendered in the actual fonts, component previews (cards, buttons, inputs, badges) styled with the brand tokens, spacing/elevation visualizations, constraint summary. Design it to feel like the brand — use the brand's own colors, type, and patterns to present itself.
+5. **`guidelines.html`** — the visual conference of the entire brand pipeline. Every phase distilled into one self-rendering document: personas (discover), positioning + voice (strategy), color + type + visual elements + logo (identity), components (patterns). Follow the structure spec passed in the prompt exactly. The file IS the brand — it renders itself using the brand's own tokens, type, and primitives. Key requirements:
+   - `:root` uses shadcn-native CSS variable names (from spec) — a dev can paste these directly into `globals.css`
+   - Define only the primitive classes the brand actually uses — don't add `.frosted-glass` to a brand that has no glass aesthetic
+   - Hero is always required; all other sections are conditional — include only what the brand actually has. Sections in order when present: Hero (metric strip) → Logo → Positioning → Color → Typography → Visual Elements → Components → Personas → Voice → Custom Components
+   - Hero must feel alive: use a CSS animated gradient atmosphere (or embed a video link if one was referenced in the brief), frosted glass nav, large typographic headline in brand voice, 3-4 KPIs from the brief in the metric strip
+   - Voice section renders brand rules as `.never-list` / `.always-list` components
+   - Mobile responsive via a single `@media (max-width: 768px)` block
+   - No external dependencies except Google Fonts `@import`
+   - The brand's aesthetic sets the tone: dark brand → dark doc; light brand → light doc; match intensity.variance
 
 ## Inheritance from style_base
 
@@ -66,7 +74,7 @@ Read `system_strategy` from brand config:
 
 Leverage existing UI libraries — don't rewrite from scratch.
 
-**Tier 1: Token mapping** (always) — `components/token-mapping.md`. Maps brand tokens to library's theming API. Copy-paste-ready. See `references/token-mapping.md` for the CSS generation spec.
+**Tier 1: Token mapping** (always) — `components/token-mapping.md`. Maps brand tokens to library's theming API. Copy-paste-ready. Generate the CSS variables block by running `node bin/theme-css.js {brand-name}.yml` — it outputs a ready-to-paste `:root`/`.dark` block with OKLCH values. Token names in `.yml` are 1:1 with shadcn/ui CSS var names — no translation needed.
 
 **Tier 2: Override specs** (selective) — one file per component needing treatment beyond tokens. Why it's overridden, code hints.
 
@@ -88,7 +96,7 @@ Write operational artifacts to the brand's guidelines directory (path provided b
 
 - **`{brand-name}.yml`** — Single source of truth. Full preset schema: tokens, intensity, patterns, constraints, effects, dark_mode.
 - **`STYLE.md`** — Agent-readable contract rendered from `.yml` + philosophy + bold bets. Follows `templates/phases/style.md`.
-- **`guidelines.html`** — Self-contained visual brand guide. Single HTML file with embedded CSS — no external deps. Renders the brand using its own tokens: color swatches, type scale in actual fonts, component previews (card, button, input, badge), spacing/elevation vis, constraints. This is what the user sees.
+- **`guidelines.html`** — Self-rendering visual brand guide. Single HTML file with embedded CSS — no external deps except Google Fonts. `:root` uses shadcn-native CSS var names. Section order: Navigation (sidebar) → Hero (manifesto line as headline) → Logo → Positioning → Color → Typography → Visual Elements → Components → Personas → Voice → any brand-specific additions. Define only the primitive classes the brand actually uses. This is what the user sees — make it feel like the brand.
 
 ### Components