get-shit-pretty 0.5.1 → 0.5.2

package/gsp/references/visual-taste.md

@@ -0,0 +1,120 @@
+# Visual Taste Evaluation Framework
+
+Companion to `nielsen-heuristics.md`. Nielsen measures usability (/50); this measures visual quality (/75). Both are evaluated independently during critique — a design can score high on one and low on the other.
+
+## What Taste Means
+
+Taste is intentionality in every decision. It's the difference between assembling parts and composing an experience.
+
+- **Signal vs noise** — knowing what deserves emphasis and what should fade
+- **Visual coherence** — all elements speaking the same design language
+- **Confidence in constraints** — doing less with more intention
+- **The gap between "it works" and "it feels right"**
+- **Not decoration** — it's the absence of things that shouldn't be there
+
+Taste cannot be added at the end. It's a quality that emerges when every decision — type, color, spacing, motion, content — serves the same story.
+
+## Sophistication Scale
+
+| Level | Name | Description | Examples |
+|-------|------|-------------|----------|
+| 1 | Default | Browser defaults, no styling intention. Looks like a homework assignment. | Unstyled HTML, Craigslist |
+| 2 | Functional | Styled but generic. Could be any product. Uses a component library without customization. | Default Bootstrap site, early-stage SaaS with Tailwind defaults |
+| 3 | Polished | Consistent, professional, follows best practices. Looks like a well-made product. | Notion, Slack, most well-funded SaaS products |
+| 4 | Refined | Intentional details, personality showing through. You notice the craft. | Raycast, Arc Browser, Lottie |
+| 5 | Distinctive | Unmistakably this brand. Memorable. You'd recognize it without the logo. | Linear, Stripe, Vercel |
+
+## Taste Evaluation Checklist
+
+Score each item 1-5. Total: X/75.
+
+### 1. Typography personality
+Does the type choice have character beyond the default? Score 1 if Inter/system font with no hierarchy. Score 5 if a distinctive pairing embodies brand personality with clear weight and size hierarchy.
+
+### 2. Color intentionality
+Is the palette considered or default? Score 1 if random, oversaturated, or too many hues. Score 5 if a cohesive system with clear semantic hierarchy and tinted neutrals.
+
+### 3. Spacing rhythm
+Does whitespace feel intentional or arbitrary? Score 1 if inconsistent padding with no scale. Score 5 if a clear vertical rhythm creates breathing room and content grouping.
+
+### 4. Shadow & depth
+Are surfaces creating meaningful hierarchy? Score 1 if flat or generic `box-shadow: 0 2px 4px rgba(0,0,0,.1)`. Score 5 if tinted shadows with consistent light direction communicate z-layers.
+
+### 5. Motion personality
+Does animation match the brand's energy? Score 1 if no motion or linear easing. Score 5 if spring physics, choreographed entrances, and exit animations match brand character.
+
+### 6. Content authenticity
+Does copy feel real or templated? Score 1 if Lorem Ipsum, "Welcome to our platform," or AI cliches. Score 5 if specific, voice-consistent, believable content throughout.
+
+### 7. Component individuality
+Are components styled to brand or default? Score 1 if stock library defaults (default Radix, unstyled shadcn). Score 5 if radius, color, shadow, and motion are customized to match brand DNA.
+
+### 8. Layout confidence
+Does the layout make bold choices or play it safe? Score 1 if generic centered single-column symmetry. Score 5 if intentional asymmetry, creative grid usage, or distinctive composition that serves the content.
+
+### 9. Visual coherence
+Do all elements speak the same design language? Score 1 if mixing incompatible styles (glassmorphism + neubrutalism + flat). Score 5 if every element reinforces one visual story.
+
+### 10. Surface texture
+Is there tactile quality or is it flat? Score 1 if pure flat vectors with no material quality. Score 5 if subtle grain, glass refraction, or tinted shadows create physical presence appropriate to brand.
+
+### 11. State completeness
+Are all interaction states designed? Score 1 if hover, active, loading, empty, and error states are missing or unstyled. Score 5 if every state feels intentional with smooth transitions between them.
+
+### 12. Responsive craft
+Is mobile a first-class experience? Score 1 if "it fits on mobile" is the only consideration. Score 5 if mobile has its own considered layout with touch-appropriate sizing and gestures.
+
+### 13. Icon consistency
+Unified family, weight, style? Score 1 if mixed icon sets, inconsistent weights, or mismatched sizing. Score 5 if one curated set with consistent stroke width and optical alignment throughout.
+
+### 14. Image direction
+Do images match brand personality? Score 1 if stock photos, broken URLs, or placeholder boxes. Score 5 if imagery style (photography, illustration, generative, CSS-only) is a deliberate brand choice.
+
+### 15. Overall impression
+Does it feel like a $150k agency build? Score 1 if it looks AI-generated or template-derived. Score 5 if someone would ask "who designed this?"
+
+## Scoring
+
+**X/75 total**, mapped to sophistication levels:
+
+- **15-25**: Level 1-2 (Default/Functional) — needs significant visual work
+- **26-40**: Level 3 (Polished) — professional but not distinctive
+- **41-55**: Level 4 (Refined) — shows craft and personality
+- **56-75**: Level 5 (Distinctive) — agency-quality, memorable
+
+## How to Improve Each Level
+
+### Level 2 → 3 (Functional → Polished)
+
+- Swap default fonts for a considered pairing
+- Establish a consistent spacing scale (4/8px or similar)
+- Add hover states and transitions to all interactive elements
+- Use one accent color consistently with tinted neutrals
+- Add loading and empty states
+
+### Level 3 → 4 (Polished → Refined)
+
+- Customize component library beyond defaults (radius, shadows, colors)
+- Add subtle texture (noise grain, tinted shadows, soft gradients)
+- Introduce spring physics for interactive motion
+- Use staggered entrances instead of instant mounting
+- Make responsive layouts feel native to each breakpoint
+
+### Level 4 → 5 (Refined → Distinctive)
+
+- Create signature visual patterns unique to this brand
+- Use advanced interactions (spotlight borders, magnetic elements, scroll choreography)
+- Ensure every surface, shadow, and animation reinforces brand personality
+- Content feels authored — specific voice, real data, believable context
+- Someone could identify the brand from a screenshot without the logo
+
+## How to Use
+
+This reference is loaded by the critique agent alongside `references/nielsen-heuristics.md`. During critique:
+
+1. Score each of the 15 taste items 1-5 with specific examples from the design
+2. Calculate total and map to sophistication level
+3. Write taste evaluation as a section in `critique.md`
+4. Include taste-specific fixes in `prioritized-fixes.md`
+
+Usability (Nielsen's, /50) and Taste (/75) are evaluated separately. A design can be highly usable but lack taste, or be visually stunning but have usability problems. Both dimensions must be addressed.

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

@@ -0,0 +1,101 @@
+---
+name: brand-sync
+description: Sync brand to match a project's shipped state — tokens, voice, visual patterns, personality
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Agent
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<context>
+Standalone brand feedback skill. After a project ships (or mid-development), the codebase and content may have diverged from the brand system — adjusted colors, shifted tone of voice, evolved visual patterns. This skill detects those divergences across all brand dimensions and updates the brand to match.
+
+This is the standalone version of the feedback loop built into `/gsp:project-build` (build-time). Use this when:
+- A project evolved beyond its original brand during development
+- Manual tweaks were made post-build
+- The voice/tone landed differently than the strategy specified
+- You want to capture a project's shipped look and feel as the new brand baseline
+</context>
+
+<objective>
+Compare a project's shipped state against its source brand across all dimensions — tokens, voice, visual patterns, and personality — surface divergences, and update the brand if confirmed.
+
+**Input:** A project with a linked brand (via project config or `.design/branding/`)
+**Output:** Updated brand tokens, strategy chunks, identity chunks, and style preset (as applicable)
+**Agent:** `gsp-brand-syncer`
+</objective>
+
+<execution_context>
+@${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
+@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
+</execution_context>
+
+<rules>
+- Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- Never update the brand without explicit user confirmation
+- Show before/after for every change — no silent updates
+- Only update dimensions that actually diverged — don't regenerate the entire brand
+</rules>
+
+<process>
+## Step 0: Resolve brand and project
+
+Scan `.design/branding/` for brand directories. One brand → use it. Multiple → use `AskUserQuestion`.
+
+Set `BRAND_PATH` = `.design/branding/{brand}`
+
+Check that the brand has at least one of: `patterns/tokens.json`, `strategy/`, `identity/`. If none exist, tell the user: "No brand system found. Run `/gsp:brand-patterns` first."
+
+Verify the project codebase has shipped output — source files with components, copy, or styles.
+
+## Step 1: Spawn syncer agent
+
+```bash
+mkdir -p {BRAND_PATH}/sync
+```
+
+Spawn the `gsp-brand-syncer` agent with:
+- `BRAND_PATH` and all available brand files (tokens.json, strategy chunks, identity chunks, foundation chunks)
+- Project codebase location (working directory)
+- **Output path:** `{BRAND_PATH}/sync/`
+
+The agent writes `SYNC-REPORT.md` with divergences across four dimensions: tokens, voice & tone, visual patterns, personality. Each divergence includes evidence (file paths, line numbers, before/after values).
+
+## Step 2: Present findings
+
+Read `{BRAND_PATH}/sync/SYNC-REPORT.md`. Present a compact summary per dimension, then use `AskUserQuestion`:
+
+- **Sync all** — update brand across all dimensions
+- **Tokens only** — just sync the quantitative token changes
+- **Pick by dimension** — choose which dimensions to sync
+- **Review each** — walk through every divergence individually
+- **Skip** — don't update the brand
+
+If "Pick by dimension", ask per dimension. If "Review each", walk through the Update Map from the report.
+
+For "Removed" tokens: ask whether to remove from brand or keep (may be used by other projects).
+
+## Step 3: Apply confirmed updates
+
+Use the Update Map from the sync report. For each confirmed change:
+
+**Tokens** — edit `tokens.json` in place (preserve W3C structure). Update corresponding foundation chunks in `{BRAND_PATH}/patterns/foundations/` and style preset `.yml` if it exists.
+
+**Voice & tone** — update `{BRAND_PATH}/strategy/voice-and-tone.md` (adjust attributes, tone positions, style rules). Update `messaging.md` if messaging shifted.
+
+**Visual patterns** — update foundation chunks in `{BRAND_PATH}/patterns/foundations/`. Update component specs and identity chunks if visual identity evolved.
+
+**Personality** — update `{BRAND_PATH}/strategy/archetype.md` and `positioning.md`. Update `brand-platform.md` if values/promise shifted.
+
+Preserve chunk format per `references/chunk-format.md`. Update INDEX.md files if chunks were added.
+
+## Step 4: Summary
+
+Show which files were updated per dimension, then use `AskUserQuestion`: "Brand synced to project. Other projects using this brand will inherit these changes on their next build."
+
+</process>

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

@@ -41,6 +41,7 @@ Skill names are left-padded with 4 spaces. Descriptions start at column 27 (4 in
     /gsp:brand-strategy    define positioning, personality, voice and messaging
     /gsp:brand-identity    create visual identity
     /gsp:brand-patterns    build design system tokens and components
+    /gsp:brand-sync        sync brand to match a project's shipped state
     /gsp:brand-audit       audit existing brand before evolving (optional)
 
   ─── Project ──────────────────────────

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

@@ -51,6 +51,7 @@ Implement designs as production-ready code in the codebase via phased pipeline w
 @${CLAUDE_SKILL_DIR}/../../templates/phases/build.md
 @${CLAUDE_SKILL_DIR}/../../references/visual-effects.md
 @${CLAUDE_SKILL_DIR}/../../references/block-patterns.md
+@${CLAUDE_SKILL_DIR}/../../references/anti-patterns.md
 </execution_context>
 
 <process>
@@ -157,9 +158,24 @@ After the foundations agent completes, run the build command:
 | TypeScript only | `npx tsc --noEmit` |
 | Generic | `npm run build` |
 
-**Pass:** Continue to Step 4.
+**Pass:** Continue to preview verification, then Step 4.
 **Fail:** Log the error. Do NOT re-spawn the agent. Surface the error to the user and ask how to proceed.
 
+### Preview verification (opt-in)
+
+After compile passes, verify the foundations actually render:
+
+1. Check if dev server is already running (`lsof -i :3000` or `:5173`)
+2. If running, use `curl -s http://localhost:{port}` to fetch the page
+3. Check the HTML response for:
+   - **Not blank** — response body has more than just the shell/boilerplate (>500 chars of content)
+   - **Tokens resolved** — grep the response for CSS variables or Tailwind classes from the token config. If `var(--` appears but no matching custom property is defined, tokens may be broken.
+   - **Font loaded** — check for the expected Google Fonts import or `@font-face` rule
+
+If dev server is not running, skip verification silently — do not start one. This keeps it zero-config.
+
+Report any issues found: "⚠️ Preview check: {issue}. This may be cosmetic — continue or investigate?"
+
 ## Step 4: Phase 3 — FOUNDATION REVIEW
 
 Present a summary of what the foundations phase produced:
@@ -180,6 +196,21 @@ Present a summary of what the foundations phase produced:
 Use `AskUserQuestion`: "Foundations look good? Continue building screens, or review first?"
 - **Continue** → proceed to Step 5
 - **Review first** → pause, let user inspect, resume when ready
+- **Adjust** → user requests changes (colors, typography, spacing, etc.)
+
+### 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-pattern-architect` agent to update brand patterns:
+   - Pass: the specific changes made (what tokens/values changed, old → new)
+   - Pass: `{BRAND_PATH}/patterns/tokens.json` and relevant identity chunks
+   - Agent updates tokens.json, foundation chunks, and style preset YAML if applicable
+   - Agent writes to `{BRAND_PATH}/` — the brand source of truth
+   - Run in background (`run_in_background: true`) so the build pipeline continues
+4. Continue to Step 5 without waiting for brand sync
 
 ## Step 5: Phase 4 — SCREENS
 
@@ -225,6 +256,53 @@ After each screen agent completes, run the build command.
 - **Skip** → mark screen as `partial` in BUILD-LOG, continue
 - **Stop** → halt pipeline, save progress
 
+## Step 5.5: Component extraction checkpoint
+
+After all screens complete, audit the codebase for duplicated patterns before review.
+
+### Automated scan
+
+Run these checks in the built codebase:
+
+1. **Duplicated Tailwind class clusters** — Use Grep to find identical `className` strings (>3 classes) appearing in 2+ files. These are extraction candidates.
+2. **Inline color/spacing values** — Grep for hardcoded hex colors, rgb(), pixel values that should be tokens. Flag any that don't reference CSS variables or Tailwind tokens.
+3. **Repeated component patterns** — Look for similar JSX structures across screen files (e.g., similar card layouts, repeated list items, identical button groups).
+
+### Surface proposals
+
+Present findings to the user as a numbered list:
+
+```
+  ◆ extraction candidates
+
+    1. Card pattern in 3 screens (landing, changelog-list, dashboard)
+       className="rounded-lg border bg-card p-6 shadow-sm"
+       → extract to <Card> component
+
+    2. Hardcoded colors in 2 files
+       text-[#FF6B35] in hero.tsx, cta.tsx
+       → use text-brand-accent token
+
+    3. Badge pattern in changelog-list, changelog-post
+       → extract to <Badge> component
+
+  ──────────────────────────────
+```
+
+Use `AskUserQuestion`: "Apply these extractions, skip, or cherry-pick?"
+- **Apply all** → make the changes inline (no agent spawn needed, these are mechanical refactors)
+- **Cherry-pick** → apply selected ones
+- **Skip** → continue to finalize
+
+This step is **not auto-applied** — the user decides what to extract.
+
+### Brand feedback on extraction
+
+If the extraction scan finds hardcoded values that should be tokens (finding type #2), and those tokens are missing from the brand system:
+
+1. After applying fixes in the project, ask: "These token gaps also exist in the brand. Update brand patterns?"
+2. If yes, spawn a background `gsp-pattern-architect` agent with the missing token definitions to add them to `{BRAND_PATH}/patterns/tokens.json` and relevant foundation chunks.
+
 ## Step 6: Finalize
 
 After all screens complete (or pipeline stops):
@@ -273,5 +351,14 @@ For `implementation_target: figma`, skip the phased pipeline. Spawn a single `gs
 
 ## Step 8: Revision mode
 
-For `needs-revision` status, spawn a single `gsp-builder` agent with execution_mode: `full` and `review/issues.md` contents. The agent fixes QA issues in the codebase and appends revision sections to BUILD-LOG.md. Then continue from Step 6 (finalize).
+For `needs-revision` status, spawn a single `gsp-builder` agent with execution_mode: `full` and `review/issues.md` contents. The agent fixes QA issues in the codebase and appends revision sections to BUILD-LOG.md.
+
+### Brand feedback on revisions
+
+After the revision agent completes, check if any QA fixes changed token-level values (colors, typography, spacing, shadows). If so:
+
+1. Ask: "These revisions changed brand-level values. Update brand patterns so future projects inherit the fix?"
+2. If yes, spawn a background `gsp-pattern-architect` agent with the changed values to update `{BRAND_PATH}/patterns/`.
+
+Then continue from Step 6 (finalize).
 </process>

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

@@ -27,6 +27,8 @@ Critique design quality and audit accessibility compliance.
 @${CLAUDE_SKILL_DIR}/../../prompts/08-accessibility-auditor.md
 @${CLAUDE_SKILL_DIR}/../../templates/phases/critique.md
 @${CLAUDE_SKILL_DIR}/../../references/nielsen-heuristics.md
+@${CLAUDE_SKILL_DIR}/../../references/visual-taste.md
+@${CLAUDE_SKILL_DIR}/../../references/anti-patterns.md
 @${CLAUDE_SKILL_DIR}/../../references/wcag-checklist.md
 @${CLAUDE_SKILL_DIR}/../../references/color-composition.md
 </execution_context>

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

@@ -30,6 +30,7 @@ Design core UI/UX screens and interaction flows.
 @${CLAUDE_SKILL_DIR}/../../references/apple-hig-patterns.md
 @${CLAUDE_SKILL_DIR}/../../references/visual-effects.md
 @${CLAUDE_SKILL_DIR}/../../references/block-patterns.md
+@${CLAUDE_SKILL_DIR}/../../references/anti-patterns.md
 </execution_context>
 
 <process>

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

@@ -35,8 +35,6 @@ Apply a named style preset to produce production-ready design tokens and foundat
 
 <rules>
 - Always use `AskUserQuestion` for user interaction — never prompt via plain text
-- Presets are the source of truth — expand tokens deterministically, don't improvise values
-- Foundation chunks follow `references/chunk-format.md` format exactly
 - `tokens.json` follows W3C Design Tokens format from `references/design-tokens.md`
 - When mixing styles, later style values override earlier ones (last-wins precedence)
 - Never mix clashing styles — check the compatibility matrix first
@@ -221,226 +219,25 @@ Stop here. Do not write any files.
 
 Transform the YAML preset tokens into the full W3C Design Tokens JSON structure.
 
-### Color tokens
-Map preset colors to the W3C structure with `$value` and `$type` fields:
-
-```json
-{
-  "color": {
-    "brand": {
-      "primary": { "$value": "{preset.color.primary}", "$type": "color" },
-      "secondary": { "$value": "{preset.color.secondary}", "$type": "color" },
-      "accent": { "$value": "{preset.color.accent}", "$type": "color" }
-    },
-    "semantic": {
-      "background": { "$value": "{preset.color.background}", "$type": "color" },
-      "surface": { "$value": "{preset.color.surface}", "$type": "color" },
-      "on-primary": { "$value": "{preset.color.on-primary}", "$type": "color" },
-      "on-background": { "$value": "{preset.color.on-background}", "$type": "color" },
-      "error": { "$value": "{preset.color.error}", "$type": "color" },
-      "success": { "$value": "{preset.color.success}", "$type": "color" },
-      "warning": { "$value": "{preset.color.warning}", "$type": "color" },
-      "info": { "$value": "{preset.color.info}", "$type": "color" }
-    }
-  }
-}
-```
-
-### Typography tokens
-```json
-{
-  "font": {
-    "family": {
-      "primary": { "$value": "{preset.typography.font-family-primary}", "$type": "fontFamily" },
-      "mono": { "$value": "{preset.typography.font-family-mono}", "$type": "fontFamily" }
-    }
-  },
-  "typography": {
-    "display": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "48px",
-        "fontWeight": "{preset.typography.font-weight-heading}",
-        "lineHeight": 1.1,
-        "letterSpacing": "-0.02em"
-      },
-      "$type": "typography"
-    },
-    "heading-1": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "36px",
-        "fontWeight": "{preset.typography.font-weight-heading}",
-        "lineHeight": 1.2,
-        "letterSpacing": "-0.01em"
-      },
-      "$type": "typography"
-    },
-    "heading-2": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "28px",
-        "fontWeight": "{preset.typography.font-weight-heading}",
-        "lineHeight": 1.3,
-        "letterSpacing": "0"
-      },
-      "$type": "typography"
-    },
-    "heading-3": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "22px",
-        "fontWeight": "{preset.typography.font-weight-heading}",
-        "lineHeight": 1.4,
-        "letterSpacing": "0"
-      },
-      "$type": "typography"
-    },
-    "body-large": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "18px",
-        "fontWeight": "{preset.typography.font-weight-body}",
-        "lineHeight": "{preset.typography.line-height-base}",
-        "letterSpacing": "0"
-      },
-      "$type": "typography"
-    },
-    "body": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "{preset.typography.font-size-base}",
-        "fontWeight": "{preset.typography.font-weight-body}",
-        "lineHeight": "{preset.typography.line-height-base}",
-        "letterSpacing": "0"
-      },
-      "$type": "typography"
-    },
-    "body-small": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "14px",
-        "fontWeight": "{preset.typography.font-weight-body}",
-        "lineHeight": "{preset.typography.line-height-base}",
-        "letterSpacing": "0"
-      },
-      "$type": "typography"
-    },
-    "caption": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "12px",
-        "fontWeight": "{preset.typography.font-weight-body}",
-        "lineHeight": 1.4,
-        "letterSpacing": "0.01em"
-      },
-      "$type": "typography"
-    },
-    "overline": {
-      "$value": {
-        "fontFamily": "{font.family.primary}",
-        "fontSize": "11px",
-        "fontWeight": 600,
-        "lineHeight": 1.5,
-        "letterSpacing": "0.08em"
-      },
-      "$type": "typography"
-    }
-  }
-}
-```
-
-### Spacing tokens
-Generate from the preset's spacing scale:
-
-```json
-{
-  "spacing": {
-    "xs": { "$value": "4px", "$type": "dimension" },
-    "sm": { "$value": "8px", "$type": "dimension" },
-    "md": { "$value": "16px", "$type": "dimension" },
-    "lg": { "$value": "24px", "$type": "dimension" },
-    "xl": { "$value": "32px", "$type": "dimension" },
-    "2xl": { "$value": "48px", "$type": "dimension" },
-    "3xl": { "$value": "64px", "$type": "dimension" },
-    "4xl": { "$value": "96px", "$type": "dimension" }
-  }
-}
-```
+### Token expansion mapping
 
-### Shadow tokens
-Map preset elevation values to W3C shadow format. Parse the CSS shadow shorthand from the preset into the structured format:
-
-```json
-{
-  "shadow": {
-    "sm": { "$value": "{parsed from preset.elevation.shadow-sm}", "$type": "shadow" },
-    "md": { "$value": "{parsed from preset.elevation.shadow-md}", "$type": "shadow" },
-    "lg": { "$value": "{parsed from preset.elevation.shadow-lg}", "$type": "shadow" },
-    "xl": { "$value": "{parsed from preset.elevation.shadow-xl}", "$type": "shadow" }
-  }
-}
-```
+Transform each YAML preset section into W3C Design Tokens JSON with `$value` and `$type` fields:
 
-### Border radius tokens
-```json
-{
-  "radius": {
-    "none": { "$value": "0px", "$type": "dimension" },
-    "sm": { "$value": "{preset.shape.border-radius-sm}", "$type": "dimension" },
-    "md": { "$value": "{preset.shape.border-radius-md}", "$type": "dimension" },
-    "lg": { "$value": "{preset.shape.border-radius-lg}", "$type": "dimension" },
-    "full": { "$value": "9999px", "$type": "dimension" }
-  }
-}
-```
+| Preset section | Token path | $type | Notes |
+|---------------|------------|-------|-------|
+| `color.*` | `color.brand.{key}`, `color.semantic.{key}` | `color` | Split into brand (primary, secondary, accent) and semantic (background, surface, on-primary, on-background, error, success, warning, info) |
+| `typography.*` | `font.family.{primary,mono}` | `fontFamily` | — |
+| `typography.*` | `typography.{level}` | `typography` | Composite: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing. 9 levels: display, heading-1 through heading-3, body-large, body, body-small, caption, overline |
+| `spacing.*` | `spacing.{xs,sm,md,lg,xl,2xl,3xl,4xl}` | `dimension` | — |
+| `elevation.*` | `shadow.{sm,md,lg,xl}` | `shadow` | Parse CSS shadow shorthand into structured format |
+| `shape.*` | `radius.{none,sm,md,lg,full}` | `dimension` | `full` = 9999px |
+| `motion.*` | `motion.duration.{fast,normal}`, `motion.easing.default` | `duration`, `cubicBezier` | — |
 
-### Style-specific token groups
-If the preset has extra token groups (e.g., `glass` for glassmorphism, `glow` for cyberpunk, `gradient` for vaporwave, `syntax` for terminal), include them under an `$extensions` key:
-
-```json
-{
-  "$extensions": {
-    "gsp-style": "{preset-name}",
-    "gsp-style-specific": {
-      // style-specific tokens preserved as-is from the preset
-    }
-  }
-}
-```
+**Style-specific tokens:** If preset has extra groups (e.g., `glass`, `glow`, `gradient`, `syntax`), include under `$extensions.gsp-style-specific`.
 
-### Dark mode
-If the preset has a `dark_mode` section, include it under `$extensions.dark`:
-
-```json
-{
-  "$extensions": {
-    "dark": {
-      "color": {
-        "semantic": {
-          "background": { "$value": "{preset.dark_mode.color.background}" },
-          "surface": { "$value": "{preset.dark_mode.color.surface}" }
-        }
-      }
-    }
-  }
-}
-```
+**Dark mode:** If preset has `dark_mode` section, include under `$extensions.dark` with semantic color overrides.
 
-### Motion tokens
-```json
-{
-  "motion": {
-    "duration": {
-      "fast": { "$value": "{preset.motion.duration-fast}", "$type": "duration" },
-      "normal": { "$value": "{preset.motion.duration-normal}", "$type": "duration" }
-    },
-    "easing": {
-      "default": { "$value": "{preset.motion.easing}", "$type": "cubicBezier" }
-    }
-  }
-}
-```
+**Extensions metadata:** Always include `$extensions.gsp-style` with the preset name.
 
 ## Step 7: Write tokens.json