@su-record/vibe 2.16.4 → 3.1.0

package/skills/capability-loop/SKILL.md

@@ -5,7 +5,7 @@ invocation: [auto]
 tier: standard
 description: "When an agent fails, diagnose which capability is missing and build it into the repo. Activates after repeated agent failures, tool errors, or when a task keeps failing in the same way. Analyzes failure transcripts, identifies the missing guardrail/tool/abstraction/doc, and creates it permanently. Use this skill whenever you see 3+ similar failures, an agent hitting the same wall repeatedly, or the user asking 'why does this keep failing'."
 triggers: [capability loop, failure loop, build capability, missing capability, agent failed, why did it fail]
-priority: 75
+priority: 60
 ---
 
 # Capability Loop — Failure → Capability Building

package/skills/chub-usage/SKILL.md

@@ -4,7 +4,7 @@ invocation: [auto]
 tier: optional
 description: "Context Hub (chub) — fetch vetted, up-to-date API documentation. Write accurate code based on the latest docs instead of training data when working with external APIs/SDKs."
 triggers: [chub, context hub, API docs, latest API, deprecated API, SDK documentation, api reference, 최신 문서]
-priority: 65
+priority: 60
 ---
 
 # Context Hub (chub) Usage

package/skills/clone/SKILL.md

@@ -24,8 +24,14 @@ The rendered DOM is the source of truth for markup. Screenshots are for pixel ve
 
 ```
 1. Do NOT generate CSS values by guessing or eyeballing screenshots.
-   ✅ Use clone-extract.js computed CSS output as-is.
-   ❌ Do NOT write CSS values directly inside scoped <style> blocks.
+   ✅ clone-to-scss.js output is a DRAFT (skeleton), not a frozen artifact. You MAY
+      rewrite SCSS values/selectors — but ONLY with evidence cited from computed.json /
+      states.json / behaviors.json (value correction, dedupe, selector restructuring).
+   ✅ clone-validate.js PASS is the sole judge of value correctness — not self-report.
+   ❌ Do NOT invent values with no extraction evidence ("looks like 18px" is forbidden).
+   ❌ Do NOT write CSS values directly inside scoped <style> blocks — style LOCATION
+      rule: all values live in styles/{feature}/ SCSS (value authority and style
+      location are separate rules; both hold).
 
 2. Do NOT hotlink remote assets. All images/fonts must be downloaded and rewritten.
 
@@ -34,6 +40,9 @@ The rendered DOM is the source of truth for markup. Screenshots are for pixel ve
 4. Do NOT copy textual content verbatim from copyrighted sources for production use.
    This skill is for layout/markup learning ("클론 코딩"). Replace text with placeholders
    or user-provided copy when shipping a real product.
+   Exception: `--real-content` — the user confirms (once, explicitly) they own the site
+   or have permission. Then keep text verbatim; clone-spec.js is invoked with
+   `--real-content` so specs mark copy as verbatim.
 
 5. Do NOT build a section without confirming its interaction model. The model in
    sections.json is a static-DOM heuristic — verify scroll-driven vs click-driven vs
@@ -42,10 +51,11 @@ The rendered DOM is the source of truth for markup. Screenshots are for pixel ve
 6. Do NOT ship default-state-only. Implement every harvested state (hover/focus/active/open/
    tab-switch) from states.json / the section spec.
 
-7. Do NOT ignore behaviors.json. The ACTIVE interaction sweep (scroll-state diffs +
-   click-driven tab content-swap detection) catches JS-set state that static CSS harvesting
-   is blind to. When the spec's "Dynamic behaviors" block conflicts with the static
-   interaction heuristic, the active capture wins.
+7. Do NOT ignore behaviors.json. The ACTIVE interaction sweep (scroll-state diffs,
+   click-driven tab content-swap detection, hover diffs, in-view entrance animations,
+   time-driven mutation candidates, smooth-scroll-lib detection) catches JS-set state
+   that static CSS harvesting is blind to. When the spec's "Dynamic behaviors" block
+   conflicts with the static interaction heuristic, the active capture wins.
 ```
 
 ## Full Flow
@@ -56,9 +66,11 @@ Input: a URL (or multiple URLs for multi-page clones)
 → Phase 0: Setup (stack detection, feature naming, working dir)
 → Phase 1: Capture (Puppeteer → rendered HTML + computed CSS + screenshots + assets)
 → Phase 2: Refine (DOM → sections.json per breakpoint; + interaction model + states)
-→ Phase 3: Scaffold (spec gate → SCSS auto-gen + Claude-authored HTML/components)
+→ Phase 2.5: Foundation (fonts / favicon / OG / SVG icons — sequential, before any section)
+→ Phase 3: Scaffold (spec gate → SCSS draft + builder dispatch, parallel per section)
+→ Phase 3C: Responsive merge (clone-merge-responsive.js — mobile-first @media)
 → Phase 4: Compile gate
-→ Phase 5: Pixel verification loop
+→ Phase 5: Pixel verification loop (BOTH viewports after merge)
 
 Working directory:
   /tmp/{feature}/
@@ -67,7 +79,9 @@ Working directory:
   └── tokens.json    — extracted design tokens (colors/fonts/spacing)
 
 Code output: placed directly in the project directory per detected stack
-  components/{feature}/, components/{feature}/_specs/, styles/{feature}/, public/images/{feature}/
+  components/{feature}/, components/{feature}/_specs/{mo,pc}/,
+  styles/{feature}/{mo,pc}/ (per-BP drafts) → styles/{feature}/ (Phase 3C merged),
+  public/images/{feature}/, public/ (favicons/OG from assets/seo/)
 ```
 
 ---
@@ -124,10 +138,11 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
   ├── computed.json       — per-element computed CSS + bounding box
   ├── screenshot.png      — full-page screenshot
   ├── states.json         — non-default state rules (hover/focus/active/checked/tab/aria/data-state)
-  ├── behaviors.json      — ACTIVE sweep: scroll-triggered header/nav diffs + click-driven tab groups
+  ├── behaviors.json      — ACTIVE sweep: scroll / tab / hover / in-view / time-driven + scrollLib
   ├── assets/
   │   ├── images/         — all <img>, background-image, <picture> sources
-  │   └── fonts/          — @font-face srcs
+  │   ├── fonts/          — @font-face srcs
+  │   └── seo/            — favicons, apple-touch-icons, OG images, webmanifest
   └── asset-map.json      — remote URL → local path mapping
 ```
 
@@ -149,7 +164,15 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
    - Scroll-state diff: tag sticky/fixed/top-bar headers+nav, snapshot computed CSS at
      scroll 0, scroll past threshold, re-snapshot, diff → {prop: {from, to}, triggerScrollY}
    - Tab groups: click tab-like sibling sets, detect whether content swaps on click
+   - Hover diff: hover interactive elements (1 sample per tag+class signature, max 30),
+     diff computed styles → JS-set hover states that :hover harvesting misses
+   - In-view entrance: fresh reload, tag below-fold "waiting to animate" nodes
+     (opacity 0 / transform offset), scroll each into view, diff → fade-up/slide-in
+   - Time-driven: 3s no-input MutationObserver watch → carousel/auto-cycle candidates
+   - Scroll-lib detection: Lenis / Locomotive Scroll (native scrolling feels different —
+     the user spots it immediately; wire the lib page-level, not per-section)
    Disable with --no-interact (restores the old fully-deterministic, screenshot-stable capture).
+10. SEO asset harvest: favicon / apple-touch-icon / webmanifest / og:image → assets/seo/
 ```
 
 ---
@@ -240,6 +263,26 @@ Refinement applied when converting rendered.html + computed.json → sections.js
 
 ---
 
+## Phase 2.5: Foundation ← sequential, BEFORE any section build
+
+Nothing renders right until the foundation exists. Do this yourself (not delegated) — it
+touches shared files:
+
+```
+1. Fonts: verify _base.scss @font-face srcs point at downloaded assets/fonts/ files.
+   Next.js stack → wire via next/font/local in the layout instead of raw @font-face.
+2. Favicon / OG / manifest: copy assets/seo/* → public/ (project convention path),
+   wire metadata (layout.tsx metadata / <head>) to the local files.
+3. SVG icons: collect inline <svg> from rendered.html, dedupe by path data,
+   emit one stack-appropriate icon module (e.g. components/{feature}/icons.tsx).
+   Name by visual function (SearchIcon, ArrowRightIcon, LogoIcon).
+4. Global behaviors from behaviors.json: scrollLib detected → install/wire page-level
+   (Lenis etc.); global keyframes/scroll-snap → styles/{feature}/_shared.scss.
+5. Verify: compile passes before moving on.
+```
+
+---
+
 ## Phase 3: Scaffold ← stack-specific code generation
 
 **⛔ Implement MO fully first → pass verification → then PC. No responsive conversion in this phase.**
@@ -251,78 +294,105 @@ Refinement applied when converting rendered.html + computed.json → sections.js
 # Step 0: Generate per-section build-contract specs (run once per BP)
 node {{VIBE_PATH}}/hooks/scripts/clone-spec.js \
   /tmp/{feature}/{bp}/sections.json \
-  --out=/path/to/project/components/{feature}/_specs/ \
-  --feature={feature}
+  --out=/path/to/project/components/{feature}/_specs/{bp}/ \
+  --feature={feature} [--real-content]
 
-# Step A: Auto-generate SCSS skeleton (run once per BP)
+# Step A: Auto-generate SCSS draft (run once per BP — note the per-BP out dir)
 node {{VIBE_PATH}}/hooks/scripts/clone-to-scss.js \
   /tmp/{feature}/{bp}/sections.json \
-  --out=/path/to/project/styles/{feature}/ \
+  --out=/path/to/project/styles/{feature}/{bp}/ \
   --token-file=/tmp/{feature}/project-tokens.json
 
 # Step B: Per-section validation (after writing each section's component code)
 node {{VIBE_PATH}}/hooks/scripts/clone-validate.js \
-  /path/to/project/styles/{feature}/ \
+  /path/to/project/styles/{feature}/{bp}/ \
   /tmp/{feature}/{bp}/sections.json \
   --section={SectionName}
 ```
 
 ⛔ **No section is built without a completed spec.** Step 0 emits `_specs/{Section}.spec.md`
-   (interaction model + **active-capture Dynamic behaviors** + states + computed CSS + assets +
-   text + checklist). clone-spec.js auto-loads `behaviors.json` from the sections.json dir and
-   attaches matching scroll/tab behaviors per section. Before writing a
-   section's component, Claude reviews its spec and resolves every `TODO` (confirm interaction
-   model, list states to implement, choose tags, replace copyrighted text). The spec is the
-   contract AND the audit trail — it forces extraction rigor before any code is written.
-⛔ **Writing SCSS files directly without calling clone-to-scss.js invalidates Phase 3.**
+   (interaction model + **active-capture Dynamic behaviors** (scroll/tab/hover/in-view/
+   time-driven/scroll-lib) + states + computed CSS + assets + text + checklist).
+   clone-spec.js auto-loads `behaviors.json` from the sections.json dir and attaches matching
+   behaviors per section. Before dispatching a section's builder, Claude reviews its spec and
+   resolves every `TODO` (confirm interaction model, list states to implement, choose tags,
+   replace copyrighted text — skipped with --real-content). The spec is the contract AND the
+   audit trail — it forces extraction rigor before any code is written.
+⛔ **clone-to-scss.js must run first (Step A) — its output is the DRAFT every section starts
+   from.** After that, SCSS edits are allowed per Immutable Rule 1 (evidence-cited only);
+   clone-validate.js PASS is the judge.
 ⛔ **Do NOT write custom SCSS / spec generation scripts.**
-⛔ **Do NOT proceed to the next section without a clone-validate.js PASS.**
-✅ Use clone-spec.js / clone-to-scss.js output as-is. If unsatisfactory, modify the script.
+⛔ **Do NOT proceed past a section without a clone-validate.js PASS for it.**
 
 ```
-Phase 3A: MO Scaffold
+Phase 3A: MO Scaffold — parallel builder dispatch
   Input: /tmp/{feature}/mo/sections.json
-  Step 0 once: clone-spec.js → emit _specs/{Section}.spec.md for every section
-  ⛔ No parallelism. Process one section at a time:
-    1. Read the target section's spec → resolve every TODO:
-       ├─ Confirm the interaction model (spec.interaction is a heuristic guess)
-       ├─ List the states to implement (spec.states)
-       └─ Mark copyrighted text for placeholder replacement
-    2. Map component candidates against component-index.json
-       ├─ Match → import existing
-       └─ No match → create new in components/{feature}/
-    3. clone-to-scss.js → auto-generate SCSS skeleton (computed values as-is) — Step A once
-    4. Claude: HTML structure + semantic tags + framework-specific component file
-       ⛔ No CSS written directly in <style> blocks — only @import/@use allowed
-       ⛔ Build for the CONFIRMED interaction model (don't build a click UI for a
-          scroll-driven original); wire every state from the spec (hover/active/open/…)
-       Framework mapping:
-         - React/Next → .tsx with CSS Modules or styled-components per stack
-         - Vue/Nuxt   → .vue with scoped <style lang="scss"> @import only
-         - Svelte     → .svelte with <style> @import only
-         - Vanilla    → .html + linked .scss
-    5. Asset references → public/images/{feature}/ (already populated in Phase 1)
-    6. clone-validate.js → compare SCSS vs sections.json — Step B
-       ├─ PASS → next section
+  Prep (sequential, once):
+    a. Step 0: clone-spec.js → emit _specs/mo/{Section}.spec.md for every section
+    b. Step A: clone-to-scss.js → SCSS draft in styles/{feature}/mo/ (computed values)
+    c. Orchestrator resolves every spec TODO BEFORE dispatch:
+       ├─ Confirm the interaction model (spec.interaction is a heuristic guess;
+       │  the spec's active-capture "Dynamic behaviors" block overrides it on conflict)
+       ├─ List the states to implement (spec.states + Dynamic behaviors)
+       ├─ Mark copyrighted text for placeholder replacement (skip with --real-content)
+       └─ Map component candidates against component-index.json (reuse vs create)
+    d. 150-line split rule (mechanical — wc -l, don't override with "but it's related"):
+       a completed spec over 150 lines means the section is too big for one builder →
+       split into sub-component specs (one per card variant / repeated pattern) + one
+       wrapper spec that imports them.
+  Dispatch (parallel):
+    ⛔ Every builder prompt embeds the FULL spec text INLINE — never "go read the file".
+       The spec file stays on disk as the audit trail; the prompt must be self-sufficient.
+    ⛔ Builders that write files in parallel run in worktree isolation; sub-component
+       builders complete before their wrapper builder starts.
+    Builder contract (each agent):
+      1. Build HTML structure + semantic tags + framework-specific component file
+         ⛔ No CSS in <style> blocks — only @import/@use of styles/{feature}/mo/
+         ⛔ Build for the CONFIRMED interaction model in the spec; wire every state
+         Framework mapping:
+           - React/Next → .tsx with CSS Modules or styled-components per stack
+           - Vue/Nuxt   → .vue with scoped <style lang="scss"> @import only
+           - Svelte     → .svelte with <style> @import only
+           - Vanilla    → .html + linked .scss
+      2. Asset references → public/images/{feature}/ (already populated in Phase 1)
+      3. SCSS edits per Immutable Rule 1 (evidence-cited only)
+      4. Verify compile (tsc --noEmit or stack equivalent) before finishing
+  Merge (orchestrator, as builders complete):
+    5. Merge worktrees; resolve conflicts (you have full context on every spec)
+    6. clone-validate.js per section — Step B
+       ├─ PASS → section done
        └─ FAIL → fix discrepancies → re-run step 6 (loop until P1=0, no round cap)
   → Phase 4 (MO compile) → Phase 5 (MO pixel verification)
 
 Phase 3B: PC Scaffold
-  Same process as MO, input /tmp/{feature}/pc/sections.json
+  Same process as MO, input /tmp/{feature}/pc/sections.json → styles/{feature}/pc/
   → Phase 4 (PC compile) → Phase 5 (PC pixel verification)
 
-Phase 3C: Responsive Integration (after both MO+PC pass verification)
-  → Merge MO+PC styles into @media-based responsive layout (separate flow, TODO)
-
-Claude's role (restricted):
+Phase 3C: Responsive Integration (after both MO+PC pass Phase 5)
+  1. node {{VIBE_PATH}}/hooks/scripts/clone-merge-responsive.js \
+       --mo=/path/to/project/styles/{feature}/mo/ \
+       --pc=/path/to/project/styles/{feature}/pc/ \
+       --out=/path/to/project/styles/{feature}/ \
+       [--breakpoint=1024]
+     → mobile-first merge: MO declarations = base, PC diffs → @media (min-width) block
+  2. Switch component style imports from styles/{feature}/{bp}/index.scss to the merged
+     styles/{feature}/index.scss
+  3. Review pc-only/mo-only selectors in the merge report — hide/show them with the
+     media query if the original does (evidence: the two sections.json trees)
+  4. → Phase 4 (compile) → Phase 5 at BOTH viewports against each BP's screenshot.
+     ⛔ The clone is NOT complete until the MERGED build passes Phase 5 at both.
+
+Claude's role:
   ✅ Component candidates: decide which patterns become reusable components
   ✅ HTML semantics: section/h1/p/button/nav tag selection
   ✅ Text replacement: substitute copyrighted copy with placeholders or user-supplied text
   ✅ Interaction model: confirm the spec's heuristic guess, then build for the real model
   ✅ Interactions: implement every state in the spec (hover/focus/active/open), click handlers
-  ❌ Do NOT modify SCSS CSS values (use clone-to-scss.js output as-is)
+  ✅ SCSS value edits WITH cited evidence (computed.json/states.json/behaviors.json) —
+     clone-validate.js PASS is the judge
+  ❌ Do NOT invent CSS values without extraction evidence
   ❌ Do NOT write CSS directly in <style> blocks
-  ❌ Do NOT use vw/clamp/@media or create custom mixins in Phase 3A/3B
+  ❌ Do NOT hand-write vw/clamp/@media in Phase 3A/3B (responsive comes from Phase 3C merge)
   ❌ Do NOT hotlink remote URLs — all assets must use local public/images/ paths
 ```
 
@@ -382,6 +452,9 @@ Termination:
   ultrawork mode: on stuck, record TODO without prompting and complete
 
 Responsive: after MO verification → change viewport → repeat against PC screenshot
+Post-merge (Phase 3C): re-run at BOTH viewports (375×812 vs mo/screenshot.png,
+  1440×900 vs pc/screenshot.png) — either failing means the merge regressed; fix the
+  merged SCSS (evidence: the per-BP sections.json), never by re-guessing values
 Cleanup: shut down browser + dev server
 
 ⛔ "Completion summary" output only allowed after Phase 5 completes.
@@ -404,6 +477,8 @@ NOT intended for:
 
 Claude must:
   - Replace copyrighted text content with placeholders (e.g. "[Lorem ipsum]") by default
+  - --real-content: ask ONE explicit confirmation (site ownership / permission) before
+    Phase 3; on confirmation keep text verbatim (clone-spec.js --real-content)
   - Skip and warn when robots.txt disallows fetching the target path
   - Refuse if the user's stated intent is brand impersonation or deception
 ```
@@ -423,3 +498,5 @@ Claude must:
 | Interaction model guess wrong (Phase 5) | section.interaction is a static-DOM heuristic. Re-observe the live site, correct the model in the spec, rebuild the section for the confirmed model. |
 | states.json empty but site has hover/tabs | States may be set via inline JS, not CSS rules. Check behaviors.json (active sweep captures scroll/tab JS state). If still missing, note in the spec and capture manually during Phase 5. |
 | behaviors.json missing or empty | Active sweep was disabled (--no-interact), hit no sticky/tab elements, or errored (logged, non-fatal). Falls back to static states.json. Re-run without --no-interact to retry. |
+| clone-merge-responsive.js reports many mo-only/pc-only selectors | Section detection diverged between BPs (layout differs structurally). Expected for hidden-on-mobile elements; verify each against the two sections.json trees and gate with the media query manually if needed. |
+| Merged build fails Phase 5 at one viewport only | The merge dropped or mis-bucketed a declaration. Diff the failing viewport's computed CSS against its sections.json; fix in the merged SCSS with that evidence. |

package/skills/commerce-patterns/SKILL.md

@@ -3,8 +3,8 @@ name: commerce-patterns
 invocation: [auto]
 tier: core
 description: "E-commerce domain patterns — cart management, payment processing (Toss/Stripe/PG), inventory tracking, and order state machines with transaction safety. Use when implementing any shopping cart, checkout flow, payment integration, stock management, or order lifecycle. Covers idempotency keys, double-charge prevention, stock reservation, and refund flows. Must use this skill when the codebase involves e-commerce — even for seemingly simple 'add to cart' features."
-triggers: [commerce, ecommerce, cart, payment, checkout, inventory, stock, order, pg, toss, stripe]
-priority: 70
+triggers: [commerce, ecommerce, cart, payment, checkout, inventory, toss, stripe, order flow]
+priority: 60
 ---
 
 # Commerce Patterns

package/skills/commit-push-pr/SKILL.md

@@ -5,7 +5,6 @@ tier: optional
 description: "Commit, push, and create PR in one go. Auto-activates on commit, PR, push keywords."
 triggers: [commit, push, PR, pull request, merge]
 priority: 70
-chain-next: [techdebt]
 ---
 
 # Commit-Push-PR

package/skills/context7-usage/SKILL.md

@@ -3,7 +3,7 @@ name: context7-usage
 invocation: [auto]
 tier: optional
 description: "Context7 plugin for latest library documentation. Auto-activates when docs, documentation, latest version, official docs, API reference, or library help is needed."
-triggers: [docs, documentation, latest version, official docs, API reference, library help, context7]
+triggers: [latest version, official docs, API reference, library help, context7]
 priority: 60
 ---
 

package/skills/design-refine/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: design-refine
+user-invocable: true
+invocation: [command, auto]
+tier: standard
+description: "Design refinement — distill (remove visual complexity), normalize (hardcoded values → design tokens), polish (pre-ship micro-details). Modifying passes. Use when design-refine, design-polish, design-normalize, token-align, simplify-ui, ship-ready."
+triggers: [design-refine, design-polish, design-normalize, token-align, design-distill, simplify-ui, ship-ready]
+priority: 50
+---
+
+# Design Refine — Distill / Normalize / Polish
+
+Modifying design-improvement passes. Mode selected by the first argument; default runs the full pipeline in order: **distill → normalize → polish**.
+
+## Usage
+
+```
+/design-refine <target>            # Full pipeline (distill → normalize → polish)
+/design-refine distill <target>    # Remove visual complexity only
+/design-refine normalize <target>  # Token alignment only
+/design-refine polish <target>     # Pre-ship final pass only
+/design-refine .                   # Refine all changed UI files
+```
+
+---
+
+## Mode: distill — Remove Visual Complexity
+
+Every remaining element must justify its existence: **if it doesn't help the user complete their task, remove it.**
+
+### Targets
+
+1. **Decorative clutter** — purposeless gradients/patterns/textures, dividers between already-spaced sections, ornamental icons, stacked borders/shadows on nested containers
+2. **Redundant information** — headings repeating page title/parent context, labels duplicating placeholders, "Welcome to {App}" banners, descriptions restating the obvious
+3. **Over-wrapped containers** — cards wrapping a single element, nested cards, cosmetic-only wrapper divs, single-child sections
+4. **Excessive animation** — entry animations on every element, hover effects on non-interactive elements, transitions > 300ms for feedback, parallax on content pages
+5. **Progressive disclosure opportunities** — 10+ visible form fields → steps; flat settings → grouped collapsibles; 8+ nav items → categories; all-metrics dashboards → top 3 + expand
+
+### Principles
+
+| Principle | Question |
+|-----------|----------|
+| Purpose | Does this help the user complete a task? |
+| Duplication | Is this information already on screen? |
+| Cognitive load | Would removal reduce decision fatigue? |
+| Visual weight | Does this compete with more important content? |
+| Progressive disclosure | Can this be hidden until needed? |
+
+Before removing: verify functionality survives, check semantic meaning, confirm signal-to-noise improves. Preserve brand-expressive elements (per `brand.personality`); calibrate aggressiveness by `aesthetic.style` (minimal → aggressive, bold → lenient).
+
+---
+
+## Mode: normalize — Design Token Alignment
+
+Replace hardcoded design values with tokens. Naming conventions: `rubrics/token-naming.md`.
+
+### Process
+
+1. **Load token source** (priority): `.vibe/design-system/{project}/MASTER.md` → `.vibe/design-context.json` → default detection (with prompt: "Run `/design-teach` or create MASTER.md first")
+2. **Scan for hardcoded values**:
+
+   | Category | Pattern | Example |
+   |----------|---------|---------|
+   | Colors | hex, `rgb()`, `hsl()` | `#3B82F6` → `var(--color-primary)` |
+   | Typography | `font-size`, `font-weight` | `14px` → `var(--text-sm)` |
+   | Spacing | `margin`/`padding`/`gap` px | `16px` → `var(--space-4)` |
+   | Shadows | inline `box-shadow` | → `var(--shadow-sm)` |
+   | Border radius | `border-radius: 8px` | → `var(--radius-md)` |
+
+3. **Map to tokens**: exact match → replace; close match (within 2px / similar hue) → replace + note; no match → flag for manual review (may need new token)
+4. **Apply**, preserving: `/* intentional */` one-offs, animation keyframes, SVG path data, third-party overrides
+
+Use `detectedStack.styling` to pick token format (CSS vars, Tailwind, etc.). New-token suggestions go to MASTER.md, then re-run.
+
+---
+
+## Mode: polish — Pre-Ship Final Pass
+
+Last-mile pixel-level check with **direct fixes**. Detailed pass/fail criteria: `rubrics/polish-checklist.md`.
+
+### Checklist
+
+1. **Alignment & spacing** — 4/8px grid, section rhythm, baselines across columns, icons vertically centered with text, symmetric container padding
+2. **Interaction states (complete set)** — Default / Hover / Focus (visible ring) / Active / Disabled (`aria-disabled` + reduced opacity) / Loading / Error / Success
+3. **Typography & copy** — no orphaned words, consistent capitalization, no placeholder text, ellipsis truncation, line length ≤ 75ch
+4. **Visual consistency** — border radius per level, shadow matches elevation, icon sizes (16/20/24), semantic color usage
+5. **Cleanup** — no `console.log`, no commented-out JSX/HTML, no `z-index` > 100 undocumented, no inline styles that should be tokens, no dead CSS
+
+### Auto-Fix Rules
+
+| Issue | Fix |
+|-------|-----|
+| Missing hover / focus / disabled state | Add using existing tokens (`focus-visible` outline, reduced-opacity disabled) |
+| Inconsistent border radius | Normalize to nearest token |
+| Inline color values | Replace with CSS variable |
+| `console.log` / commented-out code | Remove |
+
+Only auto-fix items with clear, safe remediation — ambiguous items are flagged for manual review. Re-verify fixed files pass the checklist.
+
+---
+
+## Preparation (all modes)
+
+1. **Read** `.vibe/design-context.json`
+   - Missing → display "Run `/design-teach` first for better results" → proceed with defaults
+   - Parse error → warn → proceed with defaults → recommend `/design-teach`
+2. **Read** `.vibe/design-system/*/MASTER.md` (if exists) as authoritative token source
+
+## Output Format
+
+```markdown
+## Design Refine: {target} (mode: {distill|normalize|polish|full})
+
+### Changed
+- ✂️ {file}:{line} — removed decorative gradient (distill)
+- 🔄 {file}:{line} — #3B82F6 → var(--color-primary), confidence: exact (normalize)
+- ✅ {file}:{line} — added hover state to submit button (polish)
+
+### Manual Review Needed
+- ⚠️ {file}:{line} — no matching token / layout choice / missing loading state
+
+### Summary
+- Reviewed: {N} · Changed: {N} · New tokens suggested: {N} · Manual review: {N}
+- Ship-ready: {yes/no}
+```
+
+Report templates: `templates/polish-report.md` · `templates/token-audit.md` · `templates/design-system.md`.
+
+## Next Steps
+
+| If Result Shows | Recommended Next |
+|----------------|-----------------|
+| New tokens suggested | Add to MASTER.md → re-run `/design-refine normalize` |
+| Broad quality concerns | `/design-review` — audit + UX critique |
+| All items pass | Ship ready |
+
+## Important
+
+- **Modifying**: applies changes directly (conservative — safe items only; removals listed for easy revert).
+- **Pairs with**: `/design-review` first for findings, then `/design-refine` to fix.

package/skills/{design-polish → design-refine}/templates/polish-report.md

@@ -60,5 +60,5 @@
 
 | Condition | Recommended Skill |
 |-----------|-------------------|
-| Design system gaps found | `/design-normalize` then re-run `/design-polish` |
+| Design system gaps found | `/design-refine normalize` then re-run `/design-refine polish` |
 | All items pass | Ship ready |

package/skills/{design-normalize → design-refine}/templates/token-audit.md

@@ -84,6 +84,6 @@ These values appear 3+ times with no matching token. Candidates for addition to
 
 ## Next Steps
 
-1. {{#HAS_SUGGESTED_TOKENS}}Add suggested tokens to MASTER.md, then re-run `/design-normalize`{{/HAS_SUGGESTED_TOKENS}}
-2. {{#HAS_HARDCODED}}Run `/design-normalize` to apply replacements{{/HAS_HARDCODED}}
-3. {{#ALL_TOKENIZED}}Token coverage complete — proceed to `/design-polish`{{/ALL_TOKENIZED}}
+1. {{#HAS_SUGGESTED_TOKENS}}Add suggested tokens to MASTER.md, then re-run `/design-refine normalize`{{/HAS_SUGGESTED_TOKENS}}
+2. {{#HAS_HARDCODED}}Run `/design-refine normalize` to apply replacements{{/HAS_HARDCODED}}
+3. {{#ALL_TOKENIZED}}Token coverage complete — proceed to `/design-refine polish`{{/ALL_TOKENIZED}}