@su-record/vibe 2.16.4 → 3.1.0

package/skills/design-critique/SKILL.md

@@ -1,140 +0,0 @@
----
-name: design-critique
-invocation: [auto]
-tier: standard
-description: "UX design review — Nielsen heuristics scoring, 5-persona red flag analysis. Use when design-critique, ux-review, design-review."
-triggers: [design-critique, ux-review, design-review]
-priority: 50
----
-
-# Design Critique — UX Design Review
-
-Evaluate design quality through Nielsen's 10 usability heuristics and 5 persona lenses. Report only — no code modifications.
-
-## Usage
-
-```
-/design-critique <target>     # Critique specific page/flow
-/design-critique .            # Critique all changed UI files
-```
-
-## Nielsen's 10 Heuristics (0–4 Score Each)
-
-| # | Heuristic | What to Check |
-|---|-----------|---------------|
-| H1 | Visibility of system status | Loading indicators, progress bars, state feedback |
-| H2 | Match between system and real world | Natural language, familiar icons, logical groupings |
-| H3 | User control and freedom | Undo/redo, cancel actions, exit paths |
-| H4 | Consistency and standards | Same action = same pattern, platform conventions |
-| H5 | Error prevention | Confirmation dialogs, input constraints, disabled states |
-| H6 | Recognition rather than recall | Visible options, contextual help, breadcrumbs |
-| H7 | Flexibility and efficiency | Keyboard shortcuts, defaults, power user paths |
-| H8 | Aesthetic and minimalist design | Signal-to-noise ratio, essential info only |
-| H9 | Help users recognize and recover from errors | Clear error messages, suggested fixes |
-| H10 | Help and documentation | Tooltips, onboarding, contextual guidance |
-
-### Scoring
-
-| Score | Meaning |
-|-------|---------|
-| 0 | Violated — causes real user problems |
-| 1 | Weak — frequent friction points |
-| 2 | Adequate — works but not smooth |
-| 3 | Good — minor friction only |
-| 4 | Excellent — delightful experience |
-
-## 5-Persona Red Flag Analysis
-
-Test the design through these persona lenses:
-
-### 1. Power User
-- Can they complete tasks quickly?
-- Are there keyboard shortcuts or bulk actions?
-- Is information density appropriate (not too sparse)?
-
-### 2. First-Time User
-- Is the entry point obvious?
-- Can they complete the primary task without documentation?
-- Is progressive disclosure used (not overwhelming)?
-
-### 3. Accessibility-Dependent User
-- Screen reader navigation makes sense?
-- Color is not the only information channel?
-- Text is resizable without breaking layout?
-
-### 4. Stressed / Distracted User
-- Can they recover from mistakes easily?
-- Are destructive actions clearly guarded?
-- Is critical information scannable (not buried in paragraphs)?
-
-### 5. Mobile-Only User
-- Touch targets adequate?
-- Key actions reachable with one thumb?
-- Forms don't require excessive typing?
-
-## Platform Adaptation
-
-When running on mobile stacks (React Native, Flutter, iOS, Android):
-- Focus on platform-specific UX conventions (gestures, navigation patterns)
-- Evaluate against platform HIG (Human Interface Guidelines / Material Design)
-- Skip web-specific heuristic items (breadcrumbs, URL-based navigation)
-
-## Output Format
-
-```markdown
-## Design Critique: {target}
-
-### Heuristic Scores
-| # | Heuristic | Score | Key Issue |
-|---|-----------|-------|-----------|
-| H1 | Visibility of system status | 2/4 | No loading state on form submit |
-| H2 | Match real world | 4/4 | — |
-| H3 | User control | 1/4 | No undo on delete |
-| ... | ... | ... | ... |
-| **Total** | | **28/40** | **70%** |
-
-### Persona Red Flags
-
-#### Power User 🔴
-- No keyboard shortcut for primary action
-- Table lacks bulk selection
-
-#### First-Time User 🟡
-- CTA is clear but secondary options are confusing
-
-#### Accessibility-Dependent User 🔴
-- Color-only status indicators (red/green dots)
-
-#### Stressed User 🟢
-- Confirmation dialog on destructive actions ✓
-
-#### Mobile-Only User 🟡
-- Settings buried 3 levels deep
-
-### Top Recommendations
-1. {Priority-ordered design improvements}
-```
-
-## Preparation
-
-Before running the critique:
-
-1. **Read** `.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 → adjust persona priorities by `audience.primary` and `audience.expertise`
-2. **Read** brand personality to calibrate aesthetic expectations
-
-## Next Steps
-
-| If Result Shows | Recommended Next |
-|----------------|-----------------|
-| Visual complexity / clutter | `/design-distill` — remove unnecessary elements |
-| Token inconsistencies noted | `/design-normalize` — align to design system |
-| Good overall, minor polish needed | `/design-polish` — final pass |
-
-## Important
-
-- **Read-only**: Produces design critique report. No code modifications.
-- **Context-aware**: Uses `.vibe/design-context.json` for brand/audience context if available.
-- **Complementary**: Pairs with `/design-audit` (technical) — critique focuses on UX quality.

package/skills/design-distill/SKILL.md

@@ -1,131 +0,0 @@
----
-name: design-distill
-invocation: [auto]
-tier: standard
-description: "Remove unnecessary visual complexity — strip decorative clutter, apply progressive disclosure, simplify UI to essentials. Use when design-distill, simplify-ui, ui-simplify, strip-ui."
-triggers: [design-distill, simplify-ui, ui-simplify, strip-ui]
-priority: 50
----
-
-# Design Distill — Remove Visual Complexity
-
-Strip unnecessary visual elements. Every remaining element must justify its existence. Applies the principle: **if it doesn't help the user complete their task, remove it.**
-
-## Usage
-
-```
-/design-distill <target>      # Distill specific page/component
-/design-distill .              # Distill all changed UI files
-```
-
-## What Gets Distilled
-
-### 1. Decorative Clutter
-
-- Gradient backgrounds that don't convey hierarchy
-- Decorative dividers between already-spaced sections
-- Background patterns or textures without purpose
-- Ornamental icons (icons that don't aid comprehension)
-- Excessive border/shadow stacking on nested containers
-
-### 2. Redundant Information
-
-- Headings that repeat the page title or parent context
-- Labels that duplicate placeholder text
-- "Welcome to {App}" banners on authenticated pages
-- Empty state illustrations when a simple message suffices
-- Descriptions restating what the UI element obviously does
-
-### 3. Over-Wrapped Containers
-
-- Cards wrapping single elements (card containing only a button)
-- Nested cards (card inside card inside card)
-- Wrapper divs with only cosmetic purpose
-- Sections with only one child element
-
-### 4. Excessive Animation
-
-- Entry animations on every element (staggered fade-ins on list items)
-- Hover animations on non-interactive elements
-- Transitions > 300ms for feedback (feels sluggish)
-- Parallax effects on content pages
-- Decorative loading animations when a spinner suffices
-
-### 5. Progressive Disclosure Opportunities
-
-- Settings pages showing all options at once → group and collapse
-- Forms with 10+ fields visible → break into steps
-- Dashboards showing every metric → show top 3, expandable for rest
-- Navigation with 8+ top-level items → group into categories
-
-## Distillation Principles
-
-| Principle | Question to Ask |
-|-----------|----------------|
-| **Purpose** | Does this element help the user complete a task? |
-| **Duplication** | Is this information available elsewhere on screen? |
-| **Cognitive load** | Would removing this reduce decision fatigue? |
-| **Visual weight** | Does this element compete with more important content? |
-| **Progressive disclosure** | Can this be hidden until needed? |
-
-## Process
-
-1. Read target files fully
-2. Identify elements matching distillation categories
-3. For each candidate:
-   - Verify removal won't break functionality
-   - Check if element carries semantic meaning
-   - Confirm removal improves signal-to-noise ratio
-4. Apply removals and simplifications
-5. Report changes with before/after rationale
-
-## Output Format
-
-```markdown
-## Design Distill: {target}
-
-### Removed
-- ✂️ {file}:{line} — Decorative gradient background (no hierarchy purpose)
-- ✂️ {file}:{line} — Wrapper card around single button
-- ✂️ {file}:{line} — Heading repeating parent page title
-
-### Simplified
-- 🔄 {file}:{line} — Collapsed 3 nested divs into 1 flex container
-- 🔄 {file}:{line} — Replaced staggered animation with single fade-in
-
-### Progressive Disclosure Applied
-- 📦 {file}:{line} — Settings grouped into collapsible sections (was 15 flat options)
-
-### Preserved (Justified)
-- ✓ {file}:{line} — Decorative illustration on empty state (brand expression)
-
-### Summary
-- Elements reviewed: {N}
-- Removed: {N}
-- Simplified: {N}
-- Progressive disclosure: {N}
-- Net complexity reduction: {percentage}
-```
-
-## Preparation
-
-Before running distillation:
-
-1. **Read** `.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 → preserve elements that match `brand.personality` (e.g., "playful" brand may justify decorative elements)
-2. Use `aesthetic.style` to calibrate aggressiveness (minimal → more aggressive, bold → more lenient)
-
-## Next Steps
-
-| If Result Shows | Recommended Next |
-|----------------|-----------------|
-| Elements removed/simplified | `/design-normalize` — align remaining tokens |
-| Already minimal | `/design-polish` — final pre-ship pass |
-
-## Important
-
-- **Modifying**: Directly removes and simplifies identified elements.
-- **Conservative**: Only removes elements that clearly don't serve user tasks. Brand-expressive elements preserved.
-- **Reversible**: All removals listed in report for easy review and revert if needed.

package/skills/design-normalize/SKILL.md

@@ -1,135 +0,0 @@
----
-name: design-normalize
-user-invocable: true
-invocation: [command, auto]
-tier: standard
-description: "Normalize hardcoded values to design system tokens — colors, typography, spacing, shadows aligned to MASTER.md. Use when design-normalize, design-system, token-align."
-triggers: [design-normalize, design-system, token-align]
-priority: 50
----
-
-# Design Normalize — Design System Token Alignment
-
-Replace hardcoded design values with design system tokens from MASTER.md. Ensures visual consistency across the project.
-
-## Usage
-
-```
-/design-normalize              # Normalize all changed UI files
-/design-normalize <target>     # Normalize specific component/page
-```
-
-## Process
-
-### Step 1: Load Design System
-
-Load token source in priority order:
-
-1. `.vibe/design-system/{project}/MASTER.md` (project-specific)
-2. `.vibe/design-context.json` (from `/design-teach`)
-3. If neither exists → prompt: "Run `/design-teach` or create MASTER.md first. Proceeding with default token detection."
-
-### Step 2: Scan for Hardcoded Values
-
-Detect these categories:
-
-| Category | Pattern | Example |
-|----------|---------|---------|
-| Colors | Hex `#xxx`, `#xxxxxx`, `rgb()`, `hsl()` | `#3B82F6` → `var(--color-primary)` |
-| Typography | `font-size: 14px`, `font-weight: 600` | `14px` → `var(--text-sm)` |
-| Spacing | `margin: 16px`, `padding: 24px`, `gap: 12px` | `16px` → `var(--space-4)` |
-| Shadows | `box-shadow: 0 2px 4px ...` | Inline → `var(--shadow-sm)` |
-| Border Radius | `border-radius: 8px` | `8px` → `var(--radius-md)` |
-
-### Step 3: Map to Tokens
-
-For each hardcoded value:
-
-1. Find closest matching token in MASTER.md
-2. If exact match → replace directly
-3. If close match (within 2px/similar hue) → replace + note the mapping
-4. If no match → flag for manual review (may need new token)
-
-### Step 4: Apply Replacements
-
-Replace values in source files, preserving:
-- Intentional one-off values (commented with `/* intentional */`)
-- Animation keyframe values
-- SVG path data
-- Third-party library overrides
-
-## Token Mapping Example
-
-```css
-/* Before */
-.card {
-  background: #ffffff;
-  border: 1px solid #e5e7eb;
-  border-radius: 8px;
-  padding: 24px;
-  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
-}
-
-/* After */
-.card {
-  background: var(--color-surface);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-lg);
-  padding: var(--space-6);
-  box-shadow: var(--shadow-sm);
-}
-```
-
-## Output Format
-
-```markdown
-## Design Normalize: {target}
-
-### Token Source
-- Using: MASTER.md / design-context.json / default detection
-
-### Replacements Applied
-| File | Line | Before | After | Confidence |
-|------|------|--------|-------|------------|
-| Card.tsx | 12 | #3B82F6 | var(--color-primary) | exact |
-| Card.tsx | 15 | 16px | var(--space-4) | exact |
-| Card.tsx | 18 | 7px | var(--radius-md) (8px) | close |
-
-### New Tokens Suggested
-- `--color-accent-light: #DBEAFE` — used 4 times, no matching token
-
-### Skipped (Manual Review)
-- {file}:{line} — animation keyframe value
-- {file}:{line} — no matching token found
-
-### Summary
-- Scanned: {N} files
-- Replaced: {N} values
-- New tokens suggested: {N}
-- Skipped: {N}
-```
-
-## Preparation
-
-Before running normalization:
-
-1. **Read** `.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 → use `detectedStack.styling` to determine token format (CSS vars, Tailwind, etc.)
-2. **Read** `.vibe/design-system/*/MASTER.md`
-   - If missing → display: "Run `/design-teach` or create MASTER.md first. Proceeding with default token detection."
-   - If present → use as authoritative token source for replacements
-
-## Next Steps
-
-| If Result Shows | Recommended Next |
-|----------------|-----------------|
-| Tokens aligned successfully | `/design-polish` — final pre-ship pass |
-| New tokens suggested | Add to MASTER.md, then re-run `/design-normalize` |
-
-## Important
-
-- **Modifying**: Directly replaces hardcoded values with token references.
-- **MASTER.md required**: Works best with a defined design system. Falls back to auto-detection if missing.
-- **Safe**: Preserves intentional overrides and third-party styles.

package/skills/design-polish/SKILL.md

@@ -1,132 +0,0 @@
----
-name: design-polish
-invocation: [auto]
-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** `.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** `.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.