@su-record/vibe 2.9.25 → 2.9.32

package/skills/design-normalize/rubrics/token-naming.md

@@ -1,117 +1,117 @@
-# Design Token Naming Conventions
-
-Reference for evaluating and creating design tokens. Consistent naming prevents duplication and aids discovery.
-
----
-
-## Naming Structure
-
-```
---{category}-{scale-or-variant}[-{modifier}]
-```
-
-Examples: `--color-primary`, `--space-4`, `--radius-md`, `--shadow-lg-hover`
-
----
-
-## Color Tokens
-
-### Semantic over descriptive
-
-| Preferred | Avoid | Reason |
-|-----------|-------|--------|
-| `--color-primary` | `--color-blue` | Blue may change; "primary" is stable |
-| `--color-surface` | `--color-white` | White fails in dark mode |
-| `--color-border` | `--color-gray-200` | Ties to a specific shade, not intent |
-| `--color-error` | `--color-red` | Semantic meaning is the point |
-| `--color-text-muted` | `--color-gray-500` | Describes role, not value |
-
-### Required color token set
-
-| Token | Purpose |
-|-------|---------|
-| `--color-primary` | Primary brand action color |
-| `--color-primary-hover` | Hover state of primary |
-| `--color-secondary` | Secondary action color |
-| `--color-surface` | Default background surface |
-| `--color-surface-raised` | Cards, elevated surfaces |
-| `--color-surface-overlay` | Modals, popovers |
-| `--color-border` | Default border |
-| `--color-border-focus` | Focus ring color |
-| `--color-text` | Primary body text |
-| `--color-text-muted` | Secondary/subdued text |
-| `--color-error` | Error states |
-| `--color-success` | Success states |
-| `--color-warning` | Warning states |
-
----
-
-## Spacing Tokens
-
-Use a numeric scale tied to a base unit (4px or 8px).
-
-| Token | 4px base | 8px base | Use |
-|-------|----------|----------|-----|
-| `--space-1` | 4px | 8px | Tight gaps |
-| `--space-2` | 8px | 16px | Icon-text gap |
-| `--space-3` | 12px | 24px | Input padding |
-| `--space-4` | 16px | 32px | Card padding |
-| `--space-6` | 24px | 48px | Section gap |
-| `--space-8` | 32px | 64px | Large section |
-| `--space-12` | 48px | 96px | Hero spacing |
-
----
-
-## Typography Tokens
-
-| Token | Purpose |
-|-------|---------|
-| `--text-xs` | Caption, footnote |
-| `--text-sm` | Secondary labels |
-| `--text-base` | Body text (≥16px on mobile) |
-| `--text-lg` | Emphasized body |
-| `--text-xl` | Subheading |
-| `--text-2xl` | Section heading |
-| `--text-3xl` | Page heading |
-| `--text-4xl` | Hero heading |
-| `--font-normal` | 400 weight |
-| `--font-medium` | 500 weight |
-| `--font-semibold` | 600 weight |
-| `--font-bold` | 700 weight |
-| `--leading-tight` | 1.2 (headings) |
-| `--leading-normal` | 1.5 (body) |
-| `--leading-relaxed` | 1.75 (long-form) |
-
----
-
-## Border Radius Tokens
-
-| Token | Value | Use |
-|-------|-------|-----|
-| `--radius-sm` | 4px | Tags, badges |
-| `--radius-md` | 6–8px | Inputs, buttons |
-| `--radius-lg` | 12px | Cards |
-| `--radius-xl` | 16px | Large panels |
-| `--radius-full` | 9999px | Pills, avatars |
-
----
-
-## Shadow Tokens
-
-| Token | Use |
-|-------|-----|
-| `--shadow-sm` | Subtle card lift |
-| `--shadow-md` | Default card shadow |
-| `--shadow-lg` | Popovers, dropdowns |
-| `--shadow-xl` | Modals, floating panels |
-
----
-
-## Anti-Patterns
-
-| Pattern | Problem | Fix |
-|---------|---------|-----|
-| `--blue-500` | Descriptive, breaks dark mode | Use `--color-primary` |
-| `--margin-top-16` | Property-specific; use spacing scale | Use `--space-4` |
-| `--button-text-color` | Component-scoped; can't be shared | Use `--color-text` or `--color-primary` |
-| `--size-large` | Ambiguous category | Specify: `--text-lg`, `--radius-lg`, `--space-lg` |
+# Design Token Naming Conventions
+
+Reference for evaluating and creating design tokens. Consistent naming prevents duplication and aids discovery.
+
+---
+
+## Naming Structure
+
+```
+--{category}-{scale-or-variant}[-{modifier}]
+```
+
+Examples: `--color-primary`, `--space-4`, `--radius-md`, `--shadow-lg-hover`
+
+---
+
+## Color Tokens
+
+### Semantic over descriptive
+
+| Preferred | Avoid | Reason |
+|-----------|-------|--------|
+| `--color-primary` | `--color-blue` | Blue may change; "primary" is stable |
+| `--color-surface` | `--color-white` | White fails in dark mode |
+| `--color-border` | `--color-gray-200` | Ties to a specific shade, not intent |
+| `--color-error` | `--color-red` | Semantic meaning is the point |
+| `--color-text-muted` | `--color-gray-500` | Describes role, not value |
+
+### Required color token set
+
+| Token | Purpose |
+|-------|---------|
+| `--color-primary` | Primary brand action color |
+| `--color-primary-hover` | Hover state of primary |
+| `--color-secondary` | Secondary action color |
+| `--color-surface` | Default background surface |
+| `--color-surface-raised` | Cards, elevated surfaces |
+| `--color-surface-overlay` | Modals, popovers |
+| `--color-border` | Default border |
+| `--color-border-focus` | Focus ring color |
+| `--color-text` | Primary body text |
+| `--color-text-muted` | Secondary/subdued text |
+| `--color-error` | Error states |
+| `--color-success` | Success states |
+| `--color-warning` | Warning states |
+
+---
+
+## Spacing Tokens
+
+Use a numeric scale tied to a base unit (4px or 8px).
+
+| Token | 4px base | 8px base | Use |
+|-------|----------|----------|-----|
+| `--space-1` | 4px | 8px | Tight gaps |
+| `--space-2` | 8px | 16px | Icon-text gap |
+| `--space-3` | 12px | 24px | Input padding |
+| `--space-4` | 16px | 32px | Card padding |
+| `--space-6` | 24px | 48px | Section gap |
+| `--space-8` | 32px | 64px | Large section |
+| `--space-12` | 48px | 96px | Hero spacing |
+
+---
+
+## Typography Tokens
+
+| Token | Purpose |
+|-------|---------|
+| `--text-xs` | Caption, footnote |
+| `--text-sm` | Secondary labels |
+| `--text-base` | Body text (≥16px on mobile) |
+| `--text-lg` | Emphasized body |
+| `--text-xl` | Subheading |
+| `--text-2xl` | Section heading |
+| `--text-3xl` | Page heading |
+| `--text-4xl` | Hero heading |
+| `--font-normal` | 400 weight |
+| `--font-medium` | 500 weight |
+| `--font-semibold` | 600 weight |
+| `--font-bold` | 700 weight |
+| `--leading-tight` | 1.2 (headings) |
+| `--leading-normal` | 1.5 (body) |
+| `--leading-relaxed` | 1.75 (long-form) |
+
+---
+
+## Border Radius Tokens
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--radius-sm` | 4px | Tags, badges |
+| `--radius-md` | 6–8px | Inputs, buttons |
+| `--radius-lg` | 12px | Cards |
+| `--radius-xl` | 16px | Large panels |
+| `--radius-full` | 9999px | Pills, avatars |
+
+---
+
+## Shadow Tokens
+
+| Token | Use |
+|-------|-----|
+| `--shadow-sm` | Subtle card lift |
+| `--shadow-md` | Default card shadow |
+| `--shadow-lg` | Popovers, dropdowns |
+| `--shadow-xl` | Modals, floating panels |
+
+---
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| `--blue-500` | Descriptive, breaks dark mode | Use `--color-primary` |
+| `--margin-top-16` | Property-specific; use spacing scale | Use `--space-4` |
+| `--button-text-color` | Component-scoped; can't be shared | Use `--color-text` or `--color-primary` |
+| `--size-large` | Ambiguous category | Specify: `--text-lg`, `--radius-lg`, `--space-lg` |

package/skills/design-normalize/templates/token-audit.md

@@ -1,89 +1,89 @@
-# Design Token Consistency Audit: {{TARGET}}
-
-**Date**: {{DATE}}
-**Token Source**: {{TOKEN_SOURCE}} (MASTER.md / design-context.json / auto-detected)
-**Scope**: {{SCOPE_DESCRIPTION}}
-
----
-
-## Token Coverage Summary
-
-| Category | Total Found | Tokenized | Hardcoded | Coverage % |
-|----------|-------------|-----------|-----------|------------|
-| Colors | {{COLOR_TOTAL}} | {{COLOR_TOKEN}} | {{COLOR_HARD}} | {{COLOR_PCT}}% |
-| Typography sizes | {{TYPO_TOTAL}} | {{TYPO_TOKEN}} | {{TYPO_HARD}} | {{TYPO_PCT}}% |
-| Spacing | {{SPACE_TOTAL}} | {{SPACE_TOKEN}} | {{SPACE_HARD}} | {{SPACE_PCT}}% |
-| Border radius | {{RADIUS_TOTAL}} | {{RADIUS_TOKEN}} | {{RADIUS_HARD}} | {{RADIUS_PCT}}% |
-| Shadows | {{SHADOW_TOTAL}} | {{SHADOW_TOKEN}} | {{SHADOW_HARD}} | {{SHADOW_PCT}}% |
-| **Overall** | **{{GRAND_TOTAL}}** | **{{GRAND_TOKEN}}** | **{{GRAND_HARD}}** | **{{GRAND_PCT}}%** |
-
----
-
-## Hardcoded Values Found
-
-### Colors
-
-| File | Line | Value | Nearest Token | Action |
-|------|------|-------|---------------|--------|
-{{#COLOR_FINDINGS}}
-| `{{FILE}}` | {{LINE}} | `{{VALUE}}` | `{{TOKEN}}` | {{ACTION}} |
-{{/COLOR_FINDINGS}}
-{{#NO_COLOR_FINDINGS}}
-| — | — | None found | — | — |
-{{/NO_COLOR_FINDINGS}}
-
-### Typography
-
-| File | Line | Value | Nearest Token | Action |
-|------|------|-------|---------------|--------|
-{{#TYPO_FINDINGS}}
-| `{{FILE}}` | {{LINE}} | `{{VALUE}}` | `{{TOKEN}}` | {{ACTION}} |
-{{/TYPO_FINDINGS}}
-{{#NO_TYPO_FINDINGS}}
-| — | — | None found | — | — |
-{{/NO_TYPO_FINDINGS}}
-
-### Spacing
-
-| File | Line | Value | Nearest Token | Action |
-|------|------|-------|---------------|--------|
-{{#SPACE_FINDINGS}}
-| `{{FILE}}` | {{LINE}} | `{{VALUE}}` | `{{TOKEN}}` | {{ACTION}} |
-{{/SPACE_FINDINGS}}
-{{#NO_SPACE_FINDINGS}}
-| — | — | None found | — | — |
-{{/NO_SPACE_FINDINGS}}
-
----
-
-## New Tokens Suggested
-
-These values appear 3+ times with no matching token. Candidates for addition to MASTER.md.
-
-| Suggested Token Name | Value | Usage Count | Category |
-|----------------------|-------|-------------|----------|
-{{#SUGGESTED_TOKENS}}
-| `{{NAME}}` | `{{VALUE}}` | {{COUNT}} | {{CATEGORY}} |
-{{/SUGGESTED_TOKENS}}
-{{#NO_SUGGESTED_TOKENS}}
-| — | — | — | — |
-{{/NO_SUGGESTED_TOKENS}}
-
----
-
-## Skipped (Intentional / Not Replaceable)
-
-{{#SKIPPED}}
-- `{{FILE}}:{{LINE}}` — `{{VALUE}}` — {{REASON}}
-{{/SKIPPED}}
-{{#NO_SKIPPED}}
-- None
-{{/NO_SKIPPED}}
-
----
-
-## 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}}
+# Design Token Consistency Audit: {{TARGET}}
+
+**Date**: {{DATE}}
+**Token Source**: {{TOKEN_SOURCE}} (MASTER.md / design-context.json / auto-detected)
+**Scope**: {{SCOPE_DESCRIPTION}}
+
+---
+
+## Token Coverage Summary
+
+| Category | Total Found | Tokenized | Hardcoded | Coverage % |
+|----------|-------------|-----------|-----------|------------|
+| Colors | {{COLOR_TOTAL}} | {{COLOR_TOKEN}} | {{COLOR_HARD}} | {{COLOR_PCT}}% |
+| Typography sizes | {{TYPO_TOTAL}} | {{TYPO_TOKEN}} | {{TYPO_HARD}} | {{TYPO_PCT}}% |
+| Spacing | {{SPACE_TOTAL}} | {{SPACE_TOKEN}} | {{SPACE_HARD}} | {{SPACE_PCT}}% |
+| Border radius | {{RADIUS_TOTAL}} | {{RADIUS_TOKEN}} | {{RADIUS_HARD}} | {{RADIUS_PCT}}% |
+| Shadows | {{SHADOW_TOTAL}} | {{SHADOW_TOKEN}} | {{SHADOW_HARD}} | {{SHADOW_PCT}}% |
+| **Overall** | **{{GRAND_TOTAL}}** | **{{GRAND_TOKEN}}** | **{{GRAND_HARD}}** | **{{GRAND_PCT}}%** |
+
+---
+
+## Hardcoded Values Found
+
+### Colors
+
+| File | Line | Value | Nearest Token | Action |
+|------|------|-------|---------------|--------|
+{{#COLOR_FINDINGS}}
+| `{{FILE}}` | {{LINE}} | `{{VALUE}}` | `{{TOKEN}}` | {{ACTION}} |
+{{/COLOR_FINDINGS}}
+{{#NO_COLOR_FINDINGS}}
+| — | — | None found | — | — |
+{{/NO_COLOR_FINDINGS}}
+
+### Typography
+
+| File | Line | Value | Nearest Token | Action |
+|------|------|-------|---------------|--------|
+{{#TYPO_FINDINGS}}
+| `{{FILE}}` | {{LINE}} | `{{VALUE}}` | `{{TOKEN}}` | {{ACTION}} |
+{{/TYPO_FINDINGS}}
+{{#NO_TYPO_FINDINGS}}
+| — | — | None found | — | — |
+{{/NO_TYPO_FINDINGS}}
+
+### Spacing
+
+| File | Line | Value | Nearest Token | Action |
+|------|------|-------|---------------|--------|
+{{#SPACE_FINDINGS}}
+| `{{FILE}}` | {{LINE}} | `{{VALUE}}` | `{{TOKEN}}` | {{ACTION}} |
+{{/SPACE_FINDINGS}}
+{{#NO_SPACE_FINDINGS}}
+| — | — | None found | — | — |
+{{/NO_SPACE_FINDINGS}}
+
+---
+
+## New Tokens Suggested
+
+These values appear 3+ times with no matching token. Candidates for addition to MASTER.md.
+
+| Suggested Token Name | Value | Usage Count | Category |
+|----------------------|-------|-------------|----------|
+{{#SUGGESTED_TOKENS}}
+| `{{NAME}}` | `{{VALUE}}` | {{COUNT}} | {{CATEGORY}} |
+{{/SUGGESTED_TOKENS}}
+{{#NO_SUGGESTED_TOKENS}}
+| — | — | — | — |
+{{/NO_SUGGESTED_TOKENS}}
+
+---
+
+## Skipped (Intentional / Not Replaceable)
+
+{{#SKIPPED}}
+- `{{FILE}}:{{LINE}}` — `{{VALUE}}` — {{REASON}}
+{{/SKIPPED}}
+{{#NO_SKIPPED}}
+- None
+{{/NO_SKIPPED}}
+
+---
+
+## 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}}

package/skills/design-polish/SKILL.md

@@ -1,131 +1,131 @@
----
-name: design-polish
-tier: standard
-description: "Pre-ship final polish pass — pixel alignment, interaction states, micro-details check and auto-fix. Use when design-polish, ui-polish, final-pass, ship-ready."
-triggers: [design-polish, ui-polish, final-pass, ship-ready]
-priority: 50
----
-
-# Design Polish — Pre-Ship Final Pass
-
-Last-mile quality pass before shipping. Checks pixel-level details and **directly fixes** issues found.
-
-## Usage
-
-```
-/design-polish <target>       # Polish specific component/page
-/design-polish .              # Polish all changed UI files
-```
-
-## Checklist
-
-### 1. Alignment & Spacing
-
-- [ ] Elements align to consistent grid (4px or 8px base)
-- [ ] Spacing between sections follows rhythm (not arbitrary gaps)
-- [ ] Text baselines align across columns
-- [ ] Icons vertically centered with adjacent text
-- [ ] Padding inside containers is symmetric unless intentional
-
-### 2. Interaction States (Complete Set)
-
-Every interactive element must have ALL applicable states:
-
-| State | Check |
-|-------|-------|
-| Default | Base appearance defined |
-| Hover | Visual feedback on mouse enter |
-| Focus | Visible focus ring (a11y requirement) |
-| Active / Pressed | Visual response on click/tap |
-| Disabled | Reduced opacity + `pointer-events: none` + `aria-disabled` |
-| Loading | Spinner or skeleton replacing content |
-| Error | Red/danger styling + error message |
-| Success | Confirmation feedback (toast, checkmark, color change) |
-
-### 3. Typography & Copy
-
-- [ ] No orphaned words (single word on last line of heading)
-- [ ] Consistent capitalization (Title Case vs sentence case)
-- [ ] No placeholder text ("Lorem ipsum", "TODO", "test")
-- [ ] Truncation with ellipsis where text can overflow
-- [ ] Line length ≤ 75 characters for readability
-
-### 4. Visual Consistency
-
-- [ ] Border radius consistent across same-level elements
-- [ ] Shadow depth matches elevation hierarchy
-- [ ] Icon sizes consistent (16/20/24px common set)
-- [ ] Color usage matches semantic meaning (red=error, green=success)
-
-### 5. Cleanup
-
-- [ ] No `console.log` statements
-- [ ] No commented-out JSX/HTML
-- [ ] No `z-index` values > 100 without documented reason
-- [ ] No inline styles that should be classes/tokens
-- [ ] No dead CSS classes
-
-## Auto-Fix Rules
-
-| Issue | Fix Action |
-|-------|-----------|
-| Missing hover state on button | Add hover style using existing token |
-| Missing focus ring | Add `focus-visible` outline |
-| Missing disabled state | Add disabled variant with reduced opacity |
-| Inconsistent border radius | Normalize to nearest design token |
-| Inline color values | Replace with CSS variable |
-| `console.log` in UI files | Remove |
-| Commented-out code | Remove |
-
-## Process
-
-1. Read target files fully
-2. Run checklist against each file
-3. Collect findings with file:line references
-4. Apply auto-fixes for safe items
-5. Report items requiring manual review
-6. Re-verify fixed files pass checklist
-
-## Output Format
-
-```markdown
-## Design Polish: {target}
-
-### Auto-Fixed
-- ✅ {file}:{line} — Added hover state to submit button
-- ✅ {file}:{line} — Replaced #3B82F6 with var(--color-primary)
-- ✅ {file}:{line} — Removed console.log
-
-### Manual Review Needed
-- ⚠️ {file}:{line} — Orphaned word in heading (layout choice)
-- ⚠️ {file}:{line} — Missing loading state on async action
-
-### Summary
-- Items checked: {N}
-- Auto-fixed: {N}
-- Manual review: {N}
-- Ship-ready: {yes/no}
-```
-
-## Preparation
-
-Before running polish:
-
-1. **Read** `.claude/vibe/design-context.json`
-   - If missing → display: "Run `/design-teach` first for better results" → proceed with defaults
-   - If parse error → display warning → proceed with defaults → recommend `/design-teach`
-   - If present → apply brand-appropriate micro-interaction styles from `aesthetic.style`
-2. **Read** `.claude/vibe/design-system/*/MASTER.md` (if exists) for token references
-
-## Next Steps
-
-| If Result Shows | Recommended Next |
-|----------------|-----------------|
-| All items pass | Ship ready — no further action needed |
-| Design system gaps found | `/design-normalize` first, then re-run `/design-polish` |
-
-## Important
-
-- **Modifying**: This skill directly applies safe fixes.
-- **Conservative**: Only auto-fixes items with clear, safe remediation. Ambiguous items flagged for manual review.
-- **Pairs with**: Run `/design-audit` first for broad issues, then `/design-polish` for final touches.
+---
+name: design-polish
+tier: standard
+description: "Pre-ship final polish pass — pixel alignment, interaction states, micro-details check and auto-fix. Use when design-polish, ui-polish, final-pass, ship-ready."
+triggers: [design-polish, ui-polish, final-pass, ship-ready]
+priority: 50
+---
+
+# Design Polish — Pre-Ship Final Pass
+
+Last-mile quality pass before shipping. Checks pixel-level details and **directly fixes** issues found.
+
+## Usage
+
+```
+/design-polish <target>       # Polish specific component/page
+/design-polish .              # Polish all changed UI files
+```
+
+## Checklist
+
+### 1. Alignment & Spacing
+
+- [ ] Elements align to consistent grid (4px or 8px base)
+- [ ] Spacing between sections follows rhythm (not arbitrary gaps)
+- [ ] Text baselines align across columns
+- [ ] Icons vertically centered with adjacent text
+- [ ] Padding inside containers is symmetric unless intentional
+
+### 2. Interaction States (Complete Set)
+
+Every interactive element must have ALL applicable states:
+
+| State | Check |
+|-------|-------|
+| Default | Base appearance defined |
+| Hover | Visual feedback on mouse enter |
+| Focus | Visible focus ring (a11y requirement) |
+| Active / Pressed | Visual response on click/tap |
+| Disabled | Reduced opacity + `pointer-events: none` + `aria-disabled` |
+| Loading | Spinner or skeleton replacing content |
+| Error | Red/danger styling + error message |
+| Success | Confirmation feedback (toast, checkmark, color change) |
+
+### 3. Typography & Copy
+
+- [ ] No orphaned words (single word on last line of heading)
+- [ ] Consistent capitalization (Title Case vs sentence case)
+- [ ] No placeholder text ("Lorem ipsum", "TODO", "test")
+- [ ] Truncation with ellipsis where text can overflow
+- [ ] Line length ≤ 75 characters for readability
+
+### 4. Visual Consistency
+
+- [ ] Border radius consistent across same-level elements
+- [ ] Shadow depth matches elevation hierarchy
+- [ ] Icon sizes consistent (16/20/24px common set)
+- [ ] Color usage matches semantic meaning (red=error, green=success)
+
+### 5. Cleanup
+
+- [ ] No `console.log` statements
+- [ ] No commented-out JSX/HTML
+- [ ] No `z-index` values > 100 without documented reason
+- [ ] No inline styles that should be classes/tokens
+- [ ] No dead CSS classes
+
+## Auto-Fix Rules
+
+| Issue | Fix Action |
+|-------|-----------|
+| Missing hover state on button | Add hover style using existing token |
+| Missing focus ring | Add `focus-visible` outline |
+| Missing disabled state | Add disabled variant with reduced opacity |
+| Inconsistent border radius | Normalize to nearest design token |
+| Inline color values | Replace with CSS variable |
+| `console.log` in UI files | Remove |
+| Commented-out code | Remove |
+
+## Process
+
+1. Read target files fully
+2. Run checklist against each file
+3. Collect findings with file:line references
+4. Apply auto-fixes for safe items
+5. Report items requiring manual review
+6. Re-verify fixed files pass checklist
+
+## Output Format
+
+```markdown
+## Design Polish: {target}
+
+### Auto-Fixed
+- ✅ {file}:{line} — Added hover state to submit button
+- ✅ {file}:{line} — Replaced #3B82F6 with var(--color-primary)
+- ✅ {file}:{line} — Removed console.log
+
+### Manual Review Needed
+- ⚠️ {file}:{line} — Orphaned word in heading (layout choice)
+- ⚠️ {file}:{line} — Missing loading state on async action
+
+### Summary
+- Items checked: {N}
+- Auto-fixed: {N}
+- Manual review: {N}
+- Ship-ready: {yes/no}
+```
+
+## Preparation
+
+Before running polish:
+
+1. **Read** `.claude/vibe/design-context.json`
+   - If missing → display: "Run `/design-teach` first for better results" → proceed with defaults
+   - If parse error → display warning → proceed with defaults → recommend `/design-teach`
+   - If present → apply brand-appropriate micro-interaction styles from `aesthetic.style`
+2. **Read** `.claude/vibe/design-system/*/MASTER.md` (if exists) for token references
+
+## Next Steps
+
+| If Result Shows | Recommended Next |
+|----------------|-----------------|
+| All items pass | Ship ready — no further action needed |
+| Design system gaps found | `/design-normalize` first, then re-run `/design-polish` |
+
+## Important
+
+- **Modifying**: This skill directly applies safe fixes.
+- **Conservative**: Only auto-fixes items with clear, safe remediation. Ambiguous items flagged for manual review.
+- **Pairs with**: Run `/design-audit` first for broad issues, then `/design-polish` for final touches.