get-shit-pretty 0.7.3 → 0.7.4

package/gsp/hooks/hooks.json

@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "The gsp-project-designer agent just finished. Verify: (1) at least one design/screen-*.md chunk was written, (2) design/INDEX.md was written, (3) design/preview.html was written. Report any missing deliverables to the user."
+            "prompt": "The gsp-project-designer agent just finished. Verify: (1) at least one design/screen-*.md chunk was written, (2) design/INDEX.md was written. Report any missing deliverables to the user."
           }
         ]
       },

package/gsp/skills/gsp-project-build/SKILL.md

@@ -132,6 +132,7 @@ Read `${CLAUDE_SKILL_DIR}/methodology/gsp-project-builder.md`. Include the full
 Read these reference files:
 - `${CLAUDE_SKILL_DIR}/visual-effects.md`
 - `${CLAUDE_SKILL_DIR}/../gsp-project-design/block-patterns.md`
+- `${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/token-mapping.md`
 
 Hold their content for inlining into agent prompts in Steps 3, 4.5, 5, 7, and 8.
 
@@ -145,7 +146,7 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 
 | File | Purpose |
 |------|---------|
-| `{BRAND_PATH}/patterns/{brand-name}.yml` | Token values only — used with `gsp-brand-guidelines/token-mapping.md` to generate CSS variables. Do NOT re-read patterns/constraints/effects from here — those are in STYLE.md. |
+| `{BRAND_PATH}/patterns/{brand-name}.yml` | Token values only — used with token-mapping.md to generate CSS variables. Do NOT re-read patterns/constraints/effects from here — those are in STYLE.md. |
 | `{BRAND_PATH}/patterns/STYLE.md` | Design law — philosophy, patterns, constraints, effects, bold bets, implementation hints (if exists; fall back to `{brand-name}.md`) |
 | `{PROJECT_PATH}/brief/target-adaptations.md` | Component adaptations for target |
 | `.design/system/STACK.md` | Stack state |
@@ -153,6 +154,7 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 | `.design/system/COMPONENTS.md` | Existing components (if exists) |
 | `{PROJECT_PATH}/config.json` | Tech stack, target |
 | Build output template (from execution_context) | Build log structure |
+| Token mapping ref (loaded in Step 2.6) | Deterministic `.yml` → CSS variable mapping per target (shadcn HSL, Tailwind, vanilla). Includes all 26+ shadcn variables, hex→HSL conversion, dark mode, shape/radius derivation. |
 | Visual effects, block patterns refs (loaded in Step 2.6) | Design patterns + CSS recipes |
 | Agent methodology (loaded in Step 2.5) | Builder role, process, quality standards |
 
@@ -162,14 +164,15 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 >
 > Build token integration, global styles, and layout primitives ONLY.
 >
-> 1. Integrate design tokens into the codebase (CSS variables, Tailwind config, or theme file)
+> 1. Integrate design tokens into the codebase using the token-mapping reference: read the `.yml` token values and the token-mapping.md spec, then generate CSS variables per target (shadcn: HSL space-separated in `:root`/`.dark`, Tailwind: custom properties + config extend, vanilla: full custom property system). Map ALL variables — not just colors: background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, sidebar-*, chart-1 through chart-5, and --radius.
 > 2. Create global CSS (resets, base styles, font imports, dark mode setup)
 > 3. Create root layout with nav shell and footer shell (structure only — no page content)
 > 4. Create shared utilities (cn helper, theme provider if needed)
 > 5. Apply the STYLE.md bold bets and effects vocabulary — create CSS utilities or Tailwind extensions for the brand's signature effects. Validate against constraints (never/always rules are non-negotiable).
-> 6. Do NOT build individual screens or page content
-> 7. Write code directly to the codebase, not to `.design/`
-> 8. Leave changes unstaged
+> 6. For shadcn targets: use semantic color tokens (`bg-primary`, `text-muted-foreground`) — never raw color values like `bg-blue-500`. Use `gap-*` not `space-y-*`. Use `size-*` when width and height are equal.
+> 7. Do NOT build individual screens or page content
+> 8. Write code directly to the codebase, not to `.design/`
+> 9. Leave changes unstaged
 >
 > After completing foundations, write `{PROJECT_PATH}/build/logs/foundations.md` with what was done (foundations section). Do NOT write to BUILD-LOG.md directly — the orchestrator merges logs after each phase.
 

package/gsp/skills/gsp-project-build/methodology/gsp-project-builder.md

@@ -17,7 +17,7 @@ You are spawned with an `execution_mode` parameter. Follow the mode strictly:
 
 ### `foundations`
 Build token integration, global styles, and layout primitives ONLY. Stop after foundations.
-- Design tokens → CSS variables / Tailwind config. Write only **global tokens**: brand colors, font families, spacing scale, base radius, base shadows. Do NOT write screen-specific tokens yet.
+- Design tokens → CSS variables / Tailwind config. Use the **token-mapping.md** reference to map `.yml` values to the correct format per target. For shadcn: convert hex to HSL space-separated channels (e.g., `#1E40AF` → `221 72% 40%`), write ALL variables in `:root` and `.dark` scopes (background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, sidebar-*, chart-1 through chart-5, --radius). Write only **global tokens**: brand colors, font families, spacing scale, base radius, base shadows. Do NOT write screen-specific tokens yet.
 - Global CSS (resets, base styles, dark mode)
 - Layout components (root layout, nav shell, footer shell)
 - Shared utilities (cn helper, theme provider)
@@ -106,6 +106,36 @@ Check code against these before marking a screen complete — **but STYLE.md tak
 - **Components:** customize shadcn radii/colors/shadows, skeleton loaders not spinners, semantic HTML
 - **Code:** no inline styles mixed with utilities, relative units, clean z-index scale, alt text, verify imports exist
 
+## shadcn/ui Rules (when target is shadcn)
+
+These rules are always enforced for shadcn targets. They reflect the official shadcn/ui composition patterns:
+
+**Styling:**
+- Use semantic color tokens (`bg-primary`, `text-muted-foreground`) — never raw values like `bg-blue-500`
+- No manual `dark:` color overrides — use semantic tokens that auto-adapt
+- Use `gap-*` with flex/grid — never `space-x-*` or `space-y-*`
+- Use `size-*` when width and height are equal — `size-10` not `w-10 h-10`
+- Use `cn()` for conditional classes — never manual template literal ternaries
+- No manual `z-index` on overlay components (Dialog, Sheet, Popover handle their own stacking)
+- Use built-in variants before custom styles (`variant="outline"`, `size="sm"`)
+
+**Composition:**
+- Items always inside their Group (`SelectItem` → `SelectGroup`, `DropdownMenuItem` → `DropdownMenuGroup`)
+- Dialog, Sheet, and Drawer always need a Title (use `className="sr-only"` if visually hidden)
+- Use full Card composition (`CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`)
+- `TabsTrigger` must be inside `TabsList`
+- `Avatar` always needs `AvatarFallback`
+- Use `Alert` for callouts, `Badge` for status, `Skeleton` for loading, `Separator` for dividers, `sonner` for toast
+
+**Icons:**
+- Icons in `Button` use `data-icon` attribute (`data-icon="inline-start"` or `data-icon="inline-end"`)
+- No sizing classes on icons inside components — components handle icon sizing via CSS
+
+**CLI awareness:**
+- Install components via `npx shadcn@latest add {name}` — never copy/paste from GitHub
+- Use `npx shadcn@latest search` to find components before building custom ones
+- After installing components from registries, verify imports match the project's alias config
+
 Full reference: `references/anti-patterns.md` (available via Read for the complete list with fixes).
 
 ## Visual Quality Checklist

package/gsp/skills/gsp-project-design/SKILL.md

@@ -146,7 +146,6 @@ Pass in the agent prompt:
 The agent writes chunks directly:
 - `design/screen-{NN}-{name}.md` (one per screen)
 - `design/shared/` (personas, IA, navigation, micro-interactions, responsive, component-plan)
-- `design/preview.html` (self-contained wireframe preview)
 - `design/INDEX.md`
 - Updates `{PROJECT_PATH}/exports/INDEX.md` (design section)
 

package/gsp/skills/gsp-project-design/methodology/gsp-project-designer.md

@@ -13,21 +13,40 @@ When an **Existing Components** inventory is provided (for `shadcn`, `rn-reusabl
 <methodology>
 ## Design Process
 
+### Step 0: Internalize brand DNA (BEFORE designing anything)
+
+When `STYLE.md` is provided, read it first and extract a working checklist before designing any screen. STYLE.md is your design law — not a reference to consult later, but the lens through which every decision is made.
+
+Extract and hold in working memory:
+- **Constraints** → hard boundaries (never/always lists). Violating these is a Critical error.
+- **Patterns** → component composition rules (how to build cards, buttons, inputs, etc.)
+- **Effects vocabulary** → the ONLY interaction techniques you may use. Anything not listed is off-limits.
+- **Bold bets** → brand-specific techniques you MUST actively implement. These are what prevent generic output. If the brand has "purple atmospheric glow" as a bold bet, every relevant screen must show it.
+- **Intensity dials** → calibrate your creativity (variance drives layout, motion drives animation, density drives spacing)
+
+Every screen you design must reference specific techniques by name (e.g., "lift-shadow on feature cards", "press-down on CTA", "purple glow behind glass hero") — never generic terms like "use brand styling."
+
+### Steps 1-8: Design with brand DNA active
+
 1. **Define personas** — From BRIEF.md audience, create primary persona with goals and pain points
 2. **Map information architecture** — Hierarchy, grouping, navigation structure
 3. **Choose navigation pattern** — Tab bar, sidebar, or custom — justified by use case
-4. **Design 8 core screens** — Each with wireframe description, component usage, interactions, and all states
+4. **Design core screens** — Each with wireframe description, component usage, interactions, and all states. Apply brand patterns and effects in every screen — not as a separate pass, but as the default visual language.
 5. **Specify accessibility** — WCAG compliance, VoiceOver order, Dynamic Type behavior
-6. **Define micro-interactions** — Meaningful animations that communicate state changes
+6. **Define micro-interactions** — Only use techniques from the effects vocabulary. Reference them by name.
 7. **Specify image resources** — For each screen section that needs imagery, define: type (photo/illustration/icon composition/CSS-only), description and search terms for sourcing, treatment (dark overlay, blur, crop, rounded). Match the brand's imagery style from `imagery-style.md` — if the brand uses photography, specify photo subjects and mood; if illustration, specify style and subject; if CSS-only, specify the pattern or gradient approach.
 8. **Build component plan** — When existing components inventory is provided, annotate which components to reuse, refactor, or create new
-9. **Apply brand visual DNA** — When `STYLE.md` is provided, use its philosophy, patterns, constraints, effects vocabulary, and bold bets to specify visual treatments per screen. STYLE.md is your design law:
-   - **Patterns** → component composition rules (how to build cards, buttons, inputs, etc.)
-   - **Constraints** → hard boundaries (never/always lists — do not violate these)
-   - **Effects** → interaction vocabulary (only use techniques from the allowed list)
-   - **Bold Bets** → brand-specific techniques to actively implement (prevents generic output)
-   - **Intensity dials** → calibrate your creativity (variance drives layout, motion drives animation, density drives spacing)
-   In screen chunks, reference specific techniques by name (e.g., "lift-shadow on feature cards", "press-down on CTA") — not generic terms like "use brand styling"
+
+### Step 9: Brand fidelity self-check
+
+Before writing INDEX.md, verify your output against STYLE.md:
+- [ ] Every constraint respected (check the never/always lists)
+- [ ] Every bold bet appears in at least one screen (list which screen for each)
+- [ ] Effects vocabulary is the only source of interaction techniques used
+- [ ] Intensity dials match — variance, motion, density are calibrated correctly
+- [ ] No generic visual treatments — every surface, shadow, glow, gradient references a named brand technique
+
+If any bold bet is missing from all screens, go back and add it. Bold bets are the brand's differentiation — skipping them produces generic output.
 
 ## Style Feedback Detection
 
@@ -111,18 +130,6 @@ Write to `design/shared/` (~50-100 lines each):
 
 Shared chunks link to related shared chunks and relevant screen chunks.
 
-### `design/preview.html`
-
-After writing all screen chunks, generate a self-contained HTML preview file:
-- Single HTML file with embedded CSS (no external dependencies)
-- One section per screen showing a wireframe-level layout visualization
-- Use simple boxes, text labels, and semantic structure to represent each screen's layout
-- Include navigation between screens
-- Use the brand's color tokens (from the brand `.yml`) for accents if available, otherwise use neutral grays
-- Responsive — preview itself adapts to viewport width
-- Add a table of contents sidebar listing all screens
-- Keep it minimal — this is a wireframe preview, not a polished mockup
-
 ### `INDEX.md`
 
 After writing all chunks, write `INDEX.md` in the design directory:

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

@@ -184,6 +184,21 @@ Clear any build cache first (`rm -rf .next` for Next.js), then run the build com
   - After fix attempt, clear cache and re-run build once
 - **Second failure:** Log the error and stop. Do not loop.
 
+## Step 5.5: Capture project context (shadcn targets)
+
+If `implementation_target` is `shadcn`, run `npx shadcn@latest info --json` and capture the output. This provides:
+- `aliases` — the actual alias prefix for imports (`@/`, `~/`)
+- `tailwindVersion` — `"v4"` (uses `@theme inline`) vs `"v3"` (uses `tailwind.config.js`)
+- `tailwindCssFile` — the global CSS file where custom properties go
+- `style` — component visual treatment (nova, vega, etc.)
+- `base` — primitive library (radix or base)
+- `iconLibrary` — determines icon imports (lucide-react, @tabler/icons-react, etc.)
+- `resolvedPaths` — exact file-system destinations for components, utils, hooks
+- `framework` — routing and file conventions (Next.js App Router, Vite SPA, etc.)
+- `isRSC` — whether "use client" directives are needed
+
+Include this JSON in the scaffold log under a `## Project Context` section so the foundations agent can reference it.
+
 ## Step 6: Write scaffold log
 
 Write `{PROJECT_PATH}/build/SCAFFOLD-LOG.md`:
@@ -225,6 +240,10 @@ Write `{PROJECT_PATH}/build/SCAFFOLD-LOG.md`:
 - **Result:** {pass / fail}
 - **Output:** {first/last lines if relevant}
 
+## Project Context
+
+{If shadcn target: JSON output from `npx shadcn@latest info --json`. Otherwise: "N/A — non-shadcn target"}
+
 ## Issues
 
 {Any problems encountered and how they were resolved, or "None"}

package/gsp/templates/branding/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.7.3",
+  "version": "0.7.4",
   "project_type": "brand",
   "brand": {
     "name": "",

package/gsp/templates/phases/design.md

@@ -28,14 +28,6 @@ Naming: `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`, `screen-0
 | `shared/responsive.md` | Mobile, tablet, desktop breakpoint adaptations |
 | `shared/component-plan.md` | Reuse / Refactor / New (shared) / New (local) — omit when target is `figma` |
 
-### Wireframe Preview (`design/preview.html`)
-
-Self-contained HTML wireframe preview:
-- One section per screen with box-model layout visualization
-- Navigation between screens via sidebar table of contents
-- Brand color accents from the brand `.yml` preset (or neutral grays)
-- Responsive, no external dependencies
-
 ## Content Reference
 
 Each chunk follows the standard chunk format. Below is the structural reference for what each chunk should contain:

package/gsp/templates/projects/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.7.3",
+  "version": "0.7.4",
   "project_type": "design",
   "project": {
     "name": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-pretty",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Design engineering system for AI coding agents. Brand identity + design projects, from strategy to code.",
   "bin": {
     "get-shit-pretty": "bin/install.js"