@su-record/vibe 2.7.22 → 2.8.0

package/skills/create-prd/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: create-prd
+description: "Create a Product Requirements Document using a comprehensive 8-section template covering problem, objectives, segments, value propositions, solution, and release planning."
+triggers: [prd, product requirements, feature spec, requirements document]
+priority: 60
+chain-next: [user-personas, prioritization-frameworks]
+---
+
+# Create a Product Requirements Document
+
+> Based on the PRD template from [Product Compass](https://www.productcompass.pm/p/prd-template) by Pawel Huryn (MIT License).
+
+## Purpose
+
+You are an experienced product manager responsible for creating a comprehensive Product Requirements Document (PRD) for $ARGUMENTS. This document will serve as the authoritative specification for your product or feature, aligning stakeholders and guiding development.
+
+## Context
+
+A well-structured PRD clearly communicates the what, why, and how of your product initiative. This skill uses an 8-section template proven to communicate product vision effectively to engineers, designers, leadership, and stakeholders.
+
+## Instructions
+
+1. **Gather Information**: If the user provides files, read them carefully. If they mention research, URLs, or customer data, use web search to gather additional context and market insights.
+
+2. **Think Step by Step**: Before writing, analyze:
+   - What problem are we solving?
+   - Who are we solving it for?
+   - How will we measure success?
+   - What are our constraints and assumptions?
+
+3. **Apply the PRD Template**: Create a document with these 8 sections:
+
+   **1. Summary** (2-3 sentences)
+   - What is this document about?
+
+   **2. Contacts**
+   - Name, role, and comment for key stakeholders
+
+   **3. Background**
+   - Context: What is this initiative about?
+   - Why now? Has something changed?
+   - Is this something that just recently became possible?
+
+   **4. Objective**
+   - What's the objective? Why does it matter?
+   - How will it benefit the company and customers?
+   - How does it align with vision and strategy?
+   - Key Results: How will you measure success? (Use SMART OKR format)
+
+   **5. Market Segment(s)**
+   - For whom are we building this?
+   - What constraints exist?
+   - Note: Markets are defined by people's problems/jobs, not demographics
+
+   **6. Value Proposition(s)**
+   - What customer jobs/needs are we addressing?
+   - What will customers gain?
+   - Which pains will they avoid?
+   - Which problems do we solve better than competitors?
+   - Consider the Value Curve framework
+
+   **7. Solution**
+   - 7.1 UX/Prototypes (wireframes, user flows)
+   - 7.2 Key Features (detailed feature descriptions)
+   - 7.3 Technology (optional, only if relevant)
+   - 7.4 Assumptions (what we believe but haven't proven)
+
+   **8. Release**
+   - How long could it take?
+   - What goes in the first version vs. future versions?
+   - Avoid exact dates; use relative timeframes
+
+4. **Use Accessible Language**: Write for a primary school graduate. Avoid jargon. Use clear, short sentences.
+
+5. **Structure Output**: Present the PRD as a well-formatted markdown document with clear headings and sections.
+
+6. **Save the Output**: Save the PRD as `PRD-[product-name].md` in the project root or docs directory.
+
+## Notes
+
+- Be specific and data-driven where possible
+- Link each section back to the overall strategy
+- Flag assumptions clearly so the team can validate them
+- Keep the document concise but complete
+
+## Further Reading
+
+- [How to Write a Product Requirements Document? The Best PRD Template.](https://www.productcompass.pm/p/prd-template)
+- [A Proven AI PRD Template by Miqdad Jaffer (Product Lead @ OpenAI)](https://www.productcompass.pm/p/ai-prd-template)

package/skills/design-audit/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: design-audit
+description: "Design technical quality audit — a11y, performance, responsive, theming, AI slop detection with 5-dimension scoring. Use when design-audit, ui-audit, a11y-check, design-check."
+triggers: [design-audit, ui-audit, a11y-check, design-check]
+priority: 50
+---
+
+# Design Audit — Technical Quality Inspection
+
+Perform a read-only technical quality audit across 5 dimensions. No code modifications — report only.
+
+## Usage
+
+```
+/design-audit <target>        # Audit specific component/page
+/design-audit .               # Audit all changed UI files
+```
+
+## 5-Dimension Scoring
+
+Each dimension scored 0–4:
+
+| Score | Meaning |
+|-------|---------|
+| 0 | Critical failures — unusable |
+| 1 | Major issues — degraded experience |
+| 2 | Moderate issues — functional but rough |
+| 3 | Minor issues — good with polish needed |
+| 4 | Excellent — production ready |
+
+### 1. Accessibility (a11y)
+
+- [ ] All interactive elements keyboard-reachable (`tabIndex`, focus order)
+- [ ] ARIA roles and labels on custom widgets
+- [ ] Color contrast ≥ 4.5:1 (text), ≥ 3:1 (large text, UI components)
+- [ ] Images have meaningful `alt` text (not "image" or filename)
+- [ ] Form inputs linked to `<label>` or `aria-label`
+- [ ] Focus indicator visible on all interactive elements
+- [ ] Screen reader announcements for dynamic content (`aria-live`)
+- [ ] Skip-to-content link present on pages with navigation
+
+### 2. Performance
+
+- [ ] Images: `loading="lazy"` on below-fold, `srcset` for responsive, WebP/AVIF formats
+- [ ] Fonts: `font-display: swap`, subset if possible, ≤3 font files
+- [ ] CSS: No unused large frameworks, critical CSS inlined or above-fold prioritized
+- [ ] JS: Code-split at route level, no blocking scripts in `<head>`
+- [ ] Layout shifts: Explicit `width`/`height` on media, skeleton placeholders
+- [ ] Bundle: No duplicate dependencies, tree-shaking enabled
+
+### 3. Responsive
+
+- [ ] Breakpoints use `min-width` (mobile-first) or consistent direction
+- [ ] Touch targets ≥ 44×44px on mobile
+- [ ] No horizontal scroll at any breakpoint
+- [ ] Typography scales appropriately (clamp or breakpoint-based)
+- [ ] `@container` queries where component-level responsiveness needed
+- [ ] Navigation adapts (hamburger, drawer, or tab bar on mobile)
+
+### 4. Theming
+
+- [ ] Colors use CSS custom properties (not hardcoded hex/rgb)
+- [ ] Dark mode support or explicit opt-out documented
+- [ ] Spacing uses design tokens (not arbitrary pixel values)
+- [ ] Border radius, shadows consistent via tokens
+- [ ] Component variants use data attributes or CSS classes, not inline styles
+
+### 5. AI Slop Detection
+
+- [ ] No cyan-on-dark or neon accent color schemes without brand justification
+- [ ] No purple-to-blue gradient backgrounds as default aesthetic
+- [ ] No hero metric template (oversized number + tiny label) without data purpose
+- [ ] No identical card grids (3-up with icon + title + description)
+- [ ] No glassmorphism applied as default surface treatment
+- [ ] No bounce/elastic easing on functional animations
+- [ ] No Inter/Roboto as lazy font choice (match brand personality instead)
+- [ ] No gradient text on metrics or statistics
+
+## Severity Tagging
+
+| Severity | Meaning | Example |
+|----------|---------|---------|
+| P0 | Blocker — breaks functionality | Missing focus trap on modal |
+| P1 | Critical — significant UX impact | No keyboard navigation |
+| P2 | Important — noticeable quality gap | Touch targets too small |
+| P3 | Minor — polish opportunity | Inconsistent border radius |
+
+## Platform Adaptation
+
+When running on mobile stacks (React Native, Flutter, iOS, Android):
+- Skip web-specific items: CSS variables, `@container`, `srcset`, `font-display`
+- Focus on: visual hierarchy, cognitive load, accessibility, AI slop detection
+- Adapt responsive checks to platform conventions (safe areas, orientation)
+
+## Output Format
+
+```markdown
+## Design Audit Report: {target}
+
+### Scores
+| Dimension | Score | Grade |
+|-----------|-------|-------|
+| Accessibility | 3/4 | Good |
+| Performance | 2/4 | Moderate |
+| Responsive | 4/4 | Excellent |
+| Theming | 1/4 | Major Issues |
+| AI Slop | 3/4 | Good |
+| **Overall** | **13/20** | **65%** |
+
+### Findings
+
+#### P0 (Blocker)
+- None
+
+#### P1 (Critical)
+- [A11Y] Modal missing focus trap — {file}:{line}
+- [THEME] 12 hardcoded color values — should use CSS variables
+
+#### P2 (Important)
+- [PERF] Images without lazy loading — {file}:{line}
+
+#### P3 (Minor)
+- [SLOP] Purple-to-blue gradient matches AI template aesthetic
+
+### Recommendations
+1. {Priority-ordered actionable items}
+```
+
+## Preparation
+
+Before running the audit:
+
+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 → weight findings by `audience.context`, `constraints.accessibility`, `brand.personality`
+2. **Read** `.claude/vibe/design-system/*/MASTER.md` (if exists) for token reference
+
+## Next Steps
+
+| If Result Shows | Recommended Next |
+|----------------|-----------------|
+| Design system inconsistencies | `/design-normalize` — align tokens |
+| UX/usability concerns | `/design-critique` — deeper UX review |
+| Ship-ready (score ≥ 16/20) | `/design-polish` — final micro-details |
+
+## Important
+
+- **Read-only**: This skill produces a report. It does NOT modify code.
+- **Context-aware**: If `.claude/vibe/design-context.json` exists, findings are weighted by project brand and audience.
+- **Incremental**: When run on `.` (changed files), only audits files in current diff.

package/skills/design-critique/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: design-critique
+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** `.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 → 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 `.claude/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

@@ -0,0 +1,129 @@
+---
+name: design-distill
+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** `.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 → 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

@@ -0,0 +1,132 @@
+---
+name: design-normalize
+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. `.claude/vibe/design-system/{project}/MASTER.md` (project-specific)
+2. `.claude/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** `.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 → use `detectedStack.styling` to determine token format (CSS vars, Tailwind, etc.)
+2. **Read** `.claude/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.