get-shit-pretty 0.9.1 → 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-guidelines/SKILL.md

@@ -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,15 @@ 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.

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

@@ -89,7 +89,7 @@ Spawn the `gsp-brand-creative-director` agent. **Inline all content** — the ag
 
 Pass in the agent prompt:
 - **Content of** BRIEF.md (loaded in Step 1)
-- **Content of** strategy chunks: archetype.md, positioning.md, brand-platform.md, voice-and-tone.md (loaded in Step 1)
+- **Content of** strategy chunks: archetype.md, positioning.md, brand-platform.md, voice-and-tone.md, messaging.md (all 5 loaded in Step 1; older brands without messaging.md proceed without it). Tagline directions and core message in `messaging.md` materially shape logo concept rationale and typography voice — do not skip it.
 - **Content of** discover/mood-board-direction.md (loaded in Step 1)
 - **Content of** style base preset `.yml` + `.md` (when loaded in Step 1) — `.yml` as structural scaffold, `.md` as design philosophy and signature techniques
 - **Content of** audit/brand-inventory.md (when loaded in Step 2)
@@ -109,14 +109,15 @@ The agent writes 5 chunks + INDEX.md (creative decisions only — no technical e
 
 ## Step 3.5: Enrich with domain skills (parallel)
 
-After the creative-director finishes, invoke all 4 domain skills in parallel — they operate on separate chunks with zero dependencies:
+After the creative-director finishes, invoke all 5 domain skills in parallel — they operate on separate chunks with zero dependencies:
 
 - **`/gsp-logo --enrich`** — reads `logo-directions.md`, enriches with construction geometry, variation specs, clear space rules, minimum size calculations.
 - **`/gsp-color --enrich`** — reads `color-system.md`, generates OKLCH palettes via tints.dev, calculates WCAG contrast, writes `palettes.json`, enriches with contrast ratios and semantic mapping.
 - **`/gsp-typography --enrich`** — reads `typography.md`, generates mathematical type scale, adds fluid type formulas, enriches with font loading instructions.
-- **`/gsp-visuals --imagery --enrich`** — reads `imagery-style.md`, adds icon library specifics, CSS texture/treatment recipes, enriches with technical implementation details.
+- **`/gsp-visuals --imagery --enrich`** — reads `imagery-style.md`, enriches with photography/illustration direction, CSS texture/treatment recipes, image processing implementation. Icons are NOT covered here — `gsp-icons` owns them.
+- **`/gsp-icons --enrich`** — defines the icon system: library selection, stroke standardization, size system, container treatments, custom SVG direction.
 
-Invoke all 4 using the Skill tool simultaneously. Each skill loads its own domain references on-demand — no upfront context cost.
+Invoke all 5 using the Skill tool simultaneously. Each skill loads its own domain references on-demand — no upfront context cost.
 
 ## Step 4: Perspective check
 

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

@@ -26,7 +26,6 @@ Accept natural language feedback about brand visuals, identify which `.yml` valu
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/design-tokens.md
 </execution_context>
 
 <rules>

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

@@ -85,5 +85,5 @@ Update `{BRAND_PATH}/STATE.md`: set Phase 1 (Discover) to `complete`.
 
 ## Step 5: Phase transition
 
-Invoke `/gsp-phase-transition` with phase `discover` and output directory `{BRAND_PATH}/research/`.
+Invoke `/gsp-phase-transition` with phase `discover` and output directory `{BRAND_PATH}/discover/`.
 </process>

package/gsp/skills/gsp-brand-research/methodology/gsp-brand-researcher.md

@@ -31,6 +31,15 @@ Act as a senior design researcher. Analyze the market landscape and competitive
 - Competitor map must use real competitors from BRIEF.md
 - Mood board specs must be actionable (hex values, typeface names)
 - Recommendations must be specific to this brand's personas, not generic
+
+## Downstream expertise context (for mood-board direction)
+
+Stay opinionated but don't over-commit on technical specifics — downstream phases will refine via expertise skills:
+- Hex color picks → `gsp-color` will re-express as OKLCH and validate WCAG contrast in identity phase
+- Typeface picks → `gsp-typography` will pair, scale, and verify rhythm
+- Imagery style direction → `gsp-visuals/domains/imagery.md` owns the canonical imagery vocabulary; align mood-board language with it where possible
+
+This is forward awareness only — research output stays in research's lane.
 </methodology>
 
 <output>

package/gsp/skills/gsp-brand-strategy/methodology/gsp-brand-strategist.md

@@ -32,9 +32,9 @@ Act as Head of Strategy at a top branding agency. Define the strategic foundatio
 </methodology>
 
 <references>
-- `references/brand-archetypes.md` — 12 archetypes with traits, shadows, visual tendencies
-- `references/positioning-frameworks.md` — positioning maps, brand pyramid
-- `references/voice-tone.md` — voice attribute framework, tone spectrum, messaging matrix
+- `${CLAUDE_SKILL_DIR}/brand-archetypes.md` — 12 archetypes with traits, shadows, visual tendencies
+- `${CLAUDE_SKILL_DIR}/positioning-frameworks.md` — positioning maps, brand pyramid
+- `${CLAUDE_SKILL_DIR}/voice-tone.md` — voice attribute framework, tone spectrum, messaging matrix
 </references>
 
 <output>

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

@@ -29,7 +29,6 @@ Compare a project's shipped state against its source brand across all dimensions
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/design-tokens.md
 @${CLAUDE_SKILL_DIR}/chunk-format.md
 </execution_context>
 

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

@@ -51,10 +51,15 @@ Also read the brand `.yml` preset from `{BRAND_PATH}/patterns/`.
 
 Read:
 - `{PROJECT_PATH}/BRIEF.md` — what we're building, platforms, tech stack
-- `{PROJECT_PATH}/config.json` — get `implementation_target`, `design_scope`, `codebase_type`, `app_path`, `repo_type`
+- `{PROJECT_PATH}/config.json` — get `implementation_target`, `design_scope`, `codebase_type`, `app_path`, `repo_type`, `accessibility_level`, `style_preset`
 
 After reading config, check if `app_path` is empty. If empty AND (`repo_type` is `monorepo` OR multiple `package.json` files are found at `apps/*/package.json` or `packages/*/package.json`), set flag `NEEDS_APP_SELECTION = true`.
 
+**Expertise pointers:**
+- `accessibility_level` (AA vs AAA) carries scope implications for contrast-sensitive components — see `${CLAUDE_SKILL_DIR}/../gsp-accessibility/SKILL.md` for level interpretation when reasoning about adaptations
+- `style_preset` (when set) drives style-preset-specific component conventions — see `${CLAUDE_SKILL_DIR}/../gsp-style/styles/{preset}.md` for the preset's patterns + constraints + effects vocabulary that adaptation reasoning should respect
+- When writing token overrides in `target-adaptations.md`, consult `${CLAUDE_SKILL_DIR}/../gsp-color/domains/palette.md` for OKLCH/contrast considerations and `${CLAUDE_SKILL_DIR}/../gsp-typography/domains/scale.md` for type-scale ratios
+
 ### Codebase context
 
 Read `.design/system/STACK.md` and `.design/system/COMPONENTS.md` (if exist) — existing tech stack, components, architecture.

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

@@ -137,11 +137,10 @@ Read these reference files:
 - `${CLAUDE_SKILL_DIR}/visual-effects.md`
 - `${CLAUDE_SKILL_DIR}/../gsp-project-design/block-patterns.md`
 - `${CLAUDE_SKILL_DIR}/shadcn-composition.md`
+- `${CLAUDE_SKILL_DIR}/agent-rules.md` — common spawn guardrails (universal + per-mode)
 
 Hold their content for inlining into agent prompts in Steps 3, 4.5, 5, 7, and 8.
 
-> **Note:** Anti-patterns are distilled into the `gsp-project-builder` agent prompt. Full ref remains on disk for edge-case agent lookup.
-
 ## Step 2.7: Theme apply gate
 
 Verify brand tokens are installed in the codebase before spawning foundations. Foundations no longer pastes tokens — `/gsp-brand-apply` is the install primitive.
@@ -190,20 +189,16 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 ### Agent instructions:
 
 > execution_mode: foundations
+> Build token integration, global styles, layout primitives, theme provider/utilities ONLY.
 >
-> Build token integration, global styles, and layout primitives ONLY.
->
-> 1. **Verify** brand tokens are already installed in `globals.css`. The orchestrator gates this — by the time you run, tokens MUST be present (installed via `/gsp-brand-apply` either directly or through the brand-guidelines prompt). If you find tokens missing, abort with a clear error pointing at `/gsp-brand-apply {brand-name}`. Do NOT manually paste tokens.
-> 2. Add base styles, dark mode setup, and any font imports that `apply` did not handle. (Note: `cssVars.theme.font-sans` may set the CSS variable but not generate the `next/font/google` import in `layout.tsx`. If the import is missing, add it. If present, leave it alone.)
-> 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. 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
+> Foundation-specific actions:
+> 1. Add base styles + dark mode setup + font imports that `apply` did not handle (`cssVars.theme.font-sans` may set the CSS var without the `next/font/google` import — add it if missing)
+> 2. Create root layout with nav + footer shells (structure only)
+> 3. Create shared utilities (cn helper, theme provider)
+> 4. Apply STYLE.md bold bets + effects as CSS utilities / Tailwind extensions; validate against never/always constraints
+> 5. For shadcn targets: semantic tokens (`bg-primary`), never raw values (`bg-blue-500`); `gap-*` not `space-y-*`; `size-*` when w/h equal
 >
-> 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.
+> See `agent-rules.md` (loaded in Step 2.6) for universal + per-mode guardrails (write to codebase, leave unstaged, log to `build/logs/foundations.md`, no BUILD-LOG.md direct write).
 
 ### Checkpoint: Compile check
 
@@ -258,54 +253,13 @@ Use `AskUserQuestion`: "Foundations look good? Continue building components, or
 
 ### Brand feedback loop
 
-If the user requests adjustments during foundation review:
-
-1. Apply the changes to the project codebase first (directly or via a quick builder re-run)
-2. Ask: "Should this change also update the brand system? (Other projects using this brand would inherit it)"
-3. If yes, spawn a background `gsp-brand-engineer` agent to update brand patterns:
-   - Pass: the specific changes made (what tokens/values changed, old → new)
-   - Pass: `{BRAND_PATH}/patterns/{brand-name}.yml` and relevant identity chunks
-   - Agent updates the `.yml` preset, foundation chunks, and STYLE.md if applicable
-   - Agent writes to `{BRAND_PATH}/` — the brand source of truth
-   - Run synchronously (do NOT use `run_in_background`) — Step 4.5 reads the brand `.yml` from disk, so the updated values must be committed before components begin
-4. Wait for brand sync to complete, then continue to Step 4.5
+Read `${CLAUDE_SKILL_DIR}/brand-feedback.md` for the full procedure. Key constraint: the `gsp-brand-engineer` re-sync runs synchronously before Step 4.5 begins.
 
 ## Step 4.5: Phase 4 — COMPONENTS
 
-### Build component manifest
-
-Read ALL design chunks from `{PROJECT_PATH}/design/` — every `screen-{NN}-{name}.md`. Also read:
-- `{PROJECT_PATH}/brief/scope.md` (feature map)
-- `{PROJECT_PATH}/brief/target-adaptations.md` (component adaptations)
-- `{BRAND_PATH}/patterns/components/token-mapping.md` (if exists)
+### Build component manifest + classify + partition
 
-Extract every component referenced across all screens. Deduplicate. Build a manifest:
-
-```
-COMPONENT_MANIFEST = [
-  { name: "Button", source: "shadcn", classification: "library-default", screens: [01, 03, 05] },
-  { name: "Card", source: "shadcn", classification: "library-customize", screens: [01, 02, 04], overrides: "custom radius + shadow from STYLE.md" },
-  { name: "PricingTier", source: "custom", classification: "custom", screens: [03] },
-  ...
-]
-```
-
-### Classify each component
-
-| Category | Criteria | Action |
-|----------|----------|--------|
-| `library-default` | Exists in target library, no brand overrides needed | Install as-is |
-| `library-customize` | Exists in target library, STYLE.md or token-mapping requires overrides | Install then customize |
-| `custom` | No library match, or design requires bespoke component | Build from scratch |
-| `existing` | Already in codebase (from scaffold or prior project) | Skip — already available |
-
-### Partition into agent groups
-
-Group components to minimize conflicts:
-1. No two agents install the same library component
-2. Group related variants together (Card + CardHeader + CardContent + CardFooter → same agent)
-3. Balance work across agents (aim for 3-6 components per agent)
-4. If total components ≤ 5, use a single agent (no need to parallelize)
+Read `${CLAUDE_SKILL_DIR}/component-classification.md` for the manifest schema, classification table (`library-default` / `library-customize` / `custom` / `existing`), and partitioning rules (≤5 → single agent; group related variants; 3-6 components per agent).
 
 ### Resume check
 
@@ -348,18 +302,9 @@ Agent instructions template:
 > implementation_target: {target}
 > components: [{partition list with classifications}]
 >
-> Install, customize, or create the assigned components.
-> 1. For library-default: install via CLI, verify import works
-> 2. For library-customize: install via CLI, then apply brand overrides (STYLE.md constraints, token values)
-> 3. For custom: create from scratch following brand patterns and STYLE.md
-> 4. Read foundations from codebase (tokens, utilities already exist)
-> 5. Do NOT modify foundation files (global CSS, layout, tokens, theme provider)
-> 6. Do NOT build screens or page content
-> 7. Write code directly to the codebase
-> 8. Leave changes unstaged
+> Install, customize, or create the assigned components per their classification (library-default → install as-is; library-customize → install + STYLE.md overrides; custom → create from scratch).
 >
-> After completing components, write `{PROJECT_PATH}/build/logs/component-{partition-name}.md` — list components installed/customized/created, files written, and any issues. Do NOT write to BUILD-LOG.md directly.
-> Also write `{PROJECT_PATH}/build/status/component-{partition-name}.json` with `{"status": "complete", "components": [{list}], "timestamp": "{ISO}"}`.
+> See `agent-rules.md` (loaded in Step 2.6) for guardrails (read foundations from codebase, do not modify foundation files, log to `build/logs/component-{partition-name}.md`, write `build/status/component-{partition-name}.json` for resume support).
 
 ### Checkpoint: Compile check
 
@@ -421,19 +366,14 @@ Agent instructions per screen:
 > execution_mode: screen
 > screen: {name} ({NN})
 >
-> Build the {name} screen. Foundations and components are already in the codebase.
+> Build the {name} screen. Foundations + components are already in the codebase.
 >
-> 1. Read the existing layout, tokens, utilities, and components from the codebase
-> 2. Create the route page and screen-specific components
-> 3. Wire imports to existing foundation and component files
-> 4. Do NOT modify foundation files (global CSS, layout, tokens, theme provider)
-> 5. Do NOT modify shared component files (they were built in the components phase)
-> 6. Write code directly to the codebase, not to `.design/`
-> 7. Leave changes unstaged
-> 8. The brand's visual effects were implemented as utilities during foundations — use those utilities/classes
+> 1. Read existing layout, tokens, utilities, components from the codebase
+> 2. Create the route page + screen-specific components
+> 3. Wire imports to existing foundation + component files
+> 4. The brand's visual effects exist as utilities/classes from foundations — use them, don't redefine
 >
-> After completing this screen, write `{PROJECT_PATH}/build/logs/screen-{NN}-{name}.md` — list files written, components used, and any issues. Do NOT write to BUILD-LOG.md directly.
-> Also write `{PROJECT_PATH}/build/status/screen-{NN}-{name}.json` with `{"status": "complete", "screen": "{name}", "files": [{list}], "timestamp": "{ISO}"}`.
+> See `agent-rules.md` (loaded in Step 2.6) for guardrails (no modifying foundations or shared components, log to `build/logs/screen-{NN}-{name}.md`, write `build/status/screen-{NN}-{name}.json` for resume support).
 
 ### Checkpoint: Compile check
 
@@ -452,35 +392,7 @@ Update `{PROJECT_PATH}/STATE.md` `## Screen Build Status` table — set complete
 
 ## Step 5.5: Extraction review (lightweight)
 
-Components were built in Phase 4, so most reuse is already handled. This is a quick sanity check.
-
-### Automated scan
-
-Run these checks on the built codebase:
-
-1. **Hardcoded values** — Grep for hardcoded hex colors, rgb(), pixel values that should be tokens. Flag any that don't reference CSS variables or Tailwind tokens.
-2. **Duplicated patterns** — Use Grep to find identical `className` strings (>3 classes) appearing in 2+ screen files. These are patterns the components phase missed.
-
-### Surface findings
-
-If issues found, present to user:
-
-```
-  ◆ post-build scan
-
-    Found {N} hardcoded values and {M} duplicated patterns.
-    {list if any}
-
-  ──────────────────────────────
-```
-
-If no issues: "Post-build scan clean — no hardcoded values or duplicated patterns found."
-
-Use `AskUserQuestion` only if issues were found: "Fix these, or continue to finalize?"
-- **Fix** → apply changes inline (mechanical refactors, no agent needed)
-- **Continue** → proceed to Step 6
-
-If hardcoded values map to missing brand tokens, suggest: "These token gaps may also exist in the brand. Consider running `/gsp-brand-refine` after build completes."
+Read `${CLAUDE_SKILL_DIR}/extraction-review.md` for the full procedure. Quick post-build sanity check: hardcoded values + duplicated patterns. If issues found, AskUserQuestion (Fix inline / Continue to Step 6).
 
 ## Step 6: Finalize
 

package/gsp/skills/gsp-project-build/agent-rules.md

@@ -0,0 +1,36 @@
+# Agent Rules (foundations + components + screens)
+
+Common guardrails for `gsp-project-builder` agent spawns. Each spawn references this file once instead of repeating the rules inline. Mode-specific instructions are in the spawn block (foundations / component / screen).
+
+## Universal rules (all modes)
+
+- **Write code directly to the codebase** — not to `.design/`
+- **Leave changes unstaged** — orchestrator handles commits
+- **Do NOT write to BUILD-LOG.md directly** — orchestrator merges per-agent logs after each phase. Each agent writes to `{PROJECT_PATH}/build/logs/{phase}-{name}.md`
+- For component/screen modes, also write `{PROJECT_PATH}/build/status/{phase}-{name}.json` with `{"status": "complete", "timestamp": "{ISO}"}` for resume support
+
+## Mode-specific guardrails
+
+### foundations
+- Verify brand tokens are already installed in `globals.css` (orchestrator gates this; tokens MUST be present before agent runs)
+- If tokens missing, abort with error pointing at `/gsp-brand-apply {brand-name}`. Do NOT manually paste tokens
+- Build root layout shells, shared utilities, theme providers ONLY
+- Do NOT build individual screens or page content
+
+### component
+- Read foundations from codebase (tokens, utilities already exist)
+- Do NOT modify foundation files (global CSS, layout, tokens, theme provider)
+- Do NOT build screens or page content
+- Library-default → install via CLI as-is
+- Library-customize → install + apply STYLE.md overrides (radius, shadow, color tokens)
+- Custom → create from scratch following brand patterns
+
+### screen
+- Read foundations + components from codebase
+- Do NOT modify foundation files
+- Do NOT modify shared component files (built in Phase 4)
+- Build the screen's route page + screen-specific components only
+
+## When in doubt
+
+STYLE.md takes precedence over all defaults. If the preset explicitly defines a technique, implement it. The methodology file (`methodology/gsp-project-builder.md`) has the full domain-rule pointers (color, typography, accessibility, imagery, anti-patterns).

package/gsp/skills/gsp-project-build/brand-feedback.md

@@ -0,0 +1,12 @@
+# Brand Feedback Loop (Step 4)
+
+If the user requests adjustments during foundation review:
+
+1. **Apply to project codebase first** — directly or via a quick builder re-run
+2. **Ask:** "Should this change also update the brand system? (Other projects using this brand would inherit it.)"
+3. **If yes**, spawn a `gsp-brand-engineer` agent **synchronously** (NOT `run_in_background` — Step 4.5 reads the brand `.yml` from disk; updated values must be committed before components begin):
+   - Pass: the specific changes made (what tokens/values changed, old → new)
+   - Pass: `{BRAND_PATH}/patterns/{brand-name}.yml` and relevant identity chunks
+   - Agent updates the `.yml` preset, foundation chunks, and STYLE.md if applicable
+   - Agent writes to `{BRAND_PATH}/` — the brand source of truth
+4. **Wait for brand sync to complete**, then continue to Step 4.5

package/gsp/skills/gsp-project-build/component-classification.md

@@ -0,0 +1,36 @@
+# Component Classification (Step 4.5)
+
+## Build component manifest
+
+Read ALL design chunks from `{PROJECT_PATH}/design/` — every `screen-{NN}-{name}.md`. Also read:
+- `{PROJECT_PATH}/brief/scope.md` (feature map)
+- `{PROJECT_PATH}/brief/target-adaptations.md` (component adaptations)
+- `{BRAND_PATH}/patterns/components/token-mapping.md` (if exists)
+
+Extract every component referenced across all screens. Deduplicate. Build a manifest:
+
+```
+COMPONENT_MANIFEST = [
+  { name: "Button", source: "shadcn", classification: "library-default", screens: [01, 03, 05] },
+  { name: "Card", source: "shadcn", classification: "library-customize", screens: [01, 02, 04], overrides: "custom radius + shadow from STYLE.md" },
+  { name: "PricingTier", source: "custom", classification: "custom", screens: [03] },
+  ...
+]
+```
+
+## Classify each component
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| `library-default` | Exists in target library, no brand overrides needed | Install as-is |
+| `library-customize` | Exists in target library, STYLE.md or token-mapping requires overrides | Install then customize |
+| `custom` | No library match, or design requires bespoke component | Build from scratch |
+| `existing` | Already in codebase (from scaffold or prior project) | Skip — already available |
+
+## Partition into agent groups
+
+Group components to minimize conflicts:
+1. No two agents install the same library component
+2. Group related variants together (Card + CardHeader + CardContent + CardFooter → same agent)
+3. Balance work across agents (aim for 3-6 components per agent)
+4. If total components ≤ 5, use a single agent (no need to parallelize)

package/gsp/skills/gsp-project-build/extraction-review.md

@@ -0,0 +1,31 @@
+# Extraction Review (Step 5.5)
+
+Components were built in Phase 4, so most reuse is already handled. This is a quick sanity check.
+
+## Automated scan
+
+Run these on the built codebase:
+
+1. **Hardcoded values** — Grep for hardcoded hex colors, `rgb()`, pixel values that should be tokens. Flag any that don't reference CSS variables or Tailwind tokens.
+2. **Duplicated patterns** — Grep for identical `className` strings (>3 classes) appearing in 2+ screen files. These are patterns the components phase missed.
+
+## Surface findings
+
+If issues found:
+
+```
+  ◆ post-build scan
+
+    Found {N} hardcoded values and {M} duplicated patterns.
+    {list if any}
+
+  ──────────────────────────────
+```
+
+If no issues: "Post-build scan clean — no hardcoded values or duplicated patterns found."
+
+Use `AskUserQuestion` only if issues were found: "Fix these, or continue to finalize?"
+- **Fix** → apply changes inline (mechanical refactors, no agent needed)
+- **Continue** → proceed to Step 6
+
+If hardcoded values map to missing brand tokens, suggest: "These token gaps may also exist in the brand. Consider running `/gsp-brand-refine` after build completes."

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

@@ -93,16 +93,23 @@ When the user gives feedback during a build, classify it:
 
 Never silently apply style-level changes to code without surfacing the choice. A button radius change in one screen that doesn't flow back to the `.yml` creates drift — the next screen gets built with the old radius.
 
-## Anti-Pattern Awareness (distilled)
+## Anti-Pattern Awareness (delegated to expertise)
 
-Check code against these before marking a screen complete — **but STYLE.md takes precedence**. If the preset explicitly defines a technique listed here, implement what the preset says. These are defaults for when the style is silent.
+**STYLE.md takes precedence over all defaults.** When the preset is silent, defer to the canonical owners:
 
-- **Typography:** no Inter/Roboto defaults, `font-variant-numeric: tabular-nums` for data, `text-wrap: balance` for headings
-- **Color:** off-black not #000, tint shadows to background hue, single accent color, single light source
+- **Color** — `${CLAUDE_SKILL_DIR}/../gsp-color/domains/system.md` (off-black, accent count, shadow tinting, light source) + `${CLAUDE_SKILL_DIR}/../gsp-color/references/color-composition.md` (60-30-10 rule)
+- **Typography** — `${CLAUDE_SKILL_DIR}/../gsp-typography/domains/system.md` + `pairing.md` (no Inter/Roboto defaults, `tabular-nums`, `text-wrap: balance`, scale ratios)
+- **Motion + effects** — `${CLAUDE_SKILL_DIR}/../gsp-accessibility/motion-effects.md` (`prefers-reduced-motion`, contrast on effects, hover magnitudes, spring physics)
+- **Imagery** — `${CLAUDE_SKILL_DIR}/../gsp-visuals/domains/imagery.md` (photography, illustration, treatments)
+- **Full anti-pattern catalog** — `${CLAUDE_SKILL_DIR}/../gsp-project-critique/anti-patterns.md` (consolidated checklist; cite this for code-quality patterns beyond the domains above)
+- **STYLE.md vocabulary** — `${CLAUDE_SKILL_DIR}/../gsp-style/style-preset-schema.md` (constraint/pattern/effects/bold-bet structure)
+
+Do not re-derive these rules inline — read the canonical owner before applying.
+
+**Builder-specific defaults** (not domain knowledge — keep here):
 - **Layout:** `min-h-[100dvh]` not `h-screen`, always max-width, CSS Grid over flexbox %, bottom-align CTAs in card groups
-- **Surfaces:** vary elevation treatments, z-layer system (flat/subtle/elevated/floating/overlay)
+- **Surfaces:** z-layer system (flat/subtle/elevated/floating/overlay)
 - **Content:** real copy always, diverse names, organic numbers, sentence case, no AI clichés
-- **Motion:** spring physics (`cubic-bezier(0.16,1,0.3,1)`), `transform`+`opacity` only, 200-300ms minimum, `prefers-reduced-motion`, stagger entrances
 - **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
 
@@ -187,7 +194,7 @@ These rules are always enforced for shadcn targets. They reflect the official sh
   ```
 - Do not override `--sidebar-width` in `globals.css` — it belongs on the provider instance
 
-Full reference: `references/anti-patterns.md` (available via Read for the complete list with fixes).
+Full reference: `${CLAUDE_SKILL_DIR}/../gsp-project-critique/anti-patterns.md` (available via Read for the complete list with fixes).
 
 **Theming reference:** when building or fixing themes, read `${CLAUDE_SKILL_DIR}/../../gsp-scaffold/shadcn-theming.md` — full token table, dark mode setup, common theming bugs and fixes.
 
@@ -197,7 +204,7 @@ Every screen must pass these before marking complete. When `STYLE.md` is provide
 
 1. **Background treatment** — never plain white/dark. Subtle gradient, texture, or decorative element.
 2. **State polish** — hover/focus/active/pressed feel deliberate (shadow shifts, subtle scale, translateY) not just color swaps
-3. **Icon consistency** — one icon family, one stroke weight throughout
+3. **Icon consistency** — import from `preferences.icon_library` only (project config — defaults to `lucide`); one icon family, one stroke weight throughout. No mixing libraries within a screen
 4. **Image direction** — imagery style (photo/illustration/CSS-only) matches brand character
 5. **Responsive craft** — mobile is a designed experience, not just "it fits"
 

package/gsp/skills/gsp-project-build/visual-effects.md

@@ -457,19 +457,4 @@ Beyond basic glassmorphism — simulating realistic glass edge refraction and de
 
 ## Accessibility
 
-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;
-  }
-}
-```
-
-- Glow/shadow: ensure text contrast meets WCAG AA without effects
-- Backdrop-blur: `@supports not (backdrop-filter: blur(1px))` solid bg fallback
-- Gradient text: test contrast ratio of gradient endpoints, not just midpoint
-- Hover transforms: keep magnitude small (2-4px translate, 1.02-1.05 scale) to avoid disorientation
+Canonical motion + effects accessibility guidance lives in `${CLAUDE_SKILL_DIR}/../gsp-accessibility/motion-effects.md` — owned by `gsp-accessibility`. Builder must read it before applying any effect from this reference. Covers `prefers-reduced-motion`, contrast on glow/shadow/gradient text, backdrop-filter fallbacks, and hover-transform magnitudes.