@su-record/vibe 2.9.18 → 2.9.20

package/skills/design-critique/SKILL.md

@@ -1,139 +1,139 @@
----
-name: design-critique
-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** `.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.
+---
+name: design-critique
+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** `.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-critique/rubrics/ux-heuristics.md

@@ -1,143 +1,143 @@
-# Nielsen's 10 Usability Heuristics — Code Review Adaptation
-
-Scoring per heuristic: 0 (violated) → 4 (excellent). Focus on what is observable in the code.
-
----
-
-## H1 — Visibility of System Status
-
-**What to look for in code**: Loading states on async actions, progress indicators, state-driven class/attribute changes, `aria-live` regions for dynamic content.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Every async action has a loading state; progress shown for multi-step ops; dynamic regions use `aria-live` |
-| **3** | Most async actions covered; 1 operation missing feedback |
-| **2** | Loading states on primary actions only; secondary actions have no feedback |
-| **1** | Only a spinner on page load; form submissions and mutations give no feedback |
-| **0** | No loading states anywhere; UI freezes silently on async calls |
-
----
-
-## H2 — Match Between System and Real World
-
-**What to look for**: Label copy, icon choices, terminology in component props and display text, logical grouping of related items.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | All labels use user-facing language (not internal field names); icons are universally understood; groupings match mental models |
-| **3** | Mostly natural language; 1–2 developer-facing terms exposed in UI |
-| **2** | Mixed: some labels match user expectations, others use internal/technical terminology |
-| **1** | Predominantly technical labels (`user_id`, `ts`, `ref_code`) in visible UI |
-| **0** | Raw API field names or database column names exposed directly to users |
-
----
-
-## H3 — User Control and Freedom
-
-**What to look for**: Cancel buttons on dialogs and forms, undo functionality, ability to navigate back, escape-to-close on modals.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Undo available for destructive actions; all modals closeable via Escape; cancel on all multi-step flows |
-| **3** | Most paths have exits; one flow lacks a clear back/cancel |
-| **2** | Cancel exists on modals but destructive actions (delete, submit) have no undo |
-| **1** | No undo; several flows trap the user until completion |
-| **0** | Irreversible destructive actions with no confirmation or recovery path |
-
----
-
-## H4 — Consistency and Standards
-
-**What to look for**: Reuse of shared components, consistent prop naming, same action always produces same UI response, platform conventions followed.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Shared component library used throughout; same action triggers same visual pattern; follows platform HIG |
-| **3** | 1–2 inconsistencies (e.g., one custom button not using Button component) |
-| **2** | Some shared components but several one-off implementations for identical patterns |
-| **1** | Each page re-implements its own UI patterns; no shared components |
-| **0** | Same action produces visually different results on different screens |
-
----
-
-## H5 — Error Prevention
-
-**What to look for**: Input validation (inline, not just on submit), confirmation dialogs on destructive actions, disabled states on invalid forms, input constraints (maxLength, type, pattern).
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Inline validation; destructive actions confirmed; submit disabled until valid; input types constrain input |
-| **3** | Confirmation dialogs present; validation on submit but not inline |
-| **2** | Some validation; destructive actions have confirmation but forms don't validate until submit |
-| **1** | No inline validation; destructive actions unconstrained |
-| **0** | No validation or confirmation; data loss possible without warning |
-
----
-
-## H6 — Recognition Rather Than Recall
-
-**What to look for**: Breadcrumbs, visible current state in navigation, contextual help text, search suggestions, recently used items.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Current location always visible; options surfaced in context; search includes suggestions |
-| **3** | Navigation shows current state; options visible on primary flows |
-| **2** | Some affordances; secondary flows require user to remember where they are |
-| **1** | No breadcrumbs; navigation doesn't indicate current section; users must recall paths |
-| **0** | Deep nested flows with no orientation cues |
-
----
-
-## H7 — Flexibility and Efficiency
-
-**What to look for**: Keyboard shortcuts, bulk actions, saved defaults, power-user paths that bypass multi-step flows.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Keyboard shortcuts for primary actions; bulk selection; smart defaults pre-populated |
-| **3** | Good defaults; 1–2 keyboard shortcuts on critical actions |
-| **2** | No shortcuts; forms have some defaults but key fields are always blank |
-| **1** | Every task requires the same number of steps regardless of user expertise |
-| **0** | Power users actively slowed down (e.g., forced onboarding on repeat visits) |
-
----
-
-## H8 — Aesthetic and Minimalist Design
-
-**What to look for**: Signal-to-noise ratio in rendered output; unnecessary decorative elements; information density relative to task complexity.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Every visible element serves a task or provides necessary context; no decorative noise |
-| **3** | Mostly clean; 1–2 decorative elements that could be removed without loss |
-| **2** | Several decorative elements that compete with primary content |
-| **1** | UI is visually busy; primary actions compete with decoration |
-| **0** | Information overload; users cannot identify primary action without significant scanning |
-
----
-
-## H9 — Help Users Recognize and Recover from Errors
-
-**What to look for**: Error message copy (specific, human-readable, with next steps), error placement (near the problem), error state styling.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Errors are specific, placed next to the problem, and suggest a fix; styled distinctly |
-| **3** | Clear error messages; placed correctly; fix suggestion sometimes missing |
-| **2** | Error messages exist but are generic ("Something went wrong") or placed in a toast far from the issue |
-| **1** | Raw error codes or API messages exposed to users |
-| **0** | No error states; failures silently ignored or produce white screens |
-
----
-
-## H10 — Help and Documentation
-
-**What to look for**: Tooltips on complex fields, onboarding flows for new users, empty states with guidance, contextual help links.
-
-| Score | Code Evidence |
-|-------|---------------|
-| **4** | Tooltips on non-obvious fields; empty states guide next action; onboarding present for new users |
-| **3** | Empty states with calls-to-action; tooltips on some complex fields |
-| **2** | Generic empty states ("No data found") without guidance |
-| **1** | No tooltips, empty state guidance, or onboarding |
-| **0** | Confusing UI with no help and no path to documentation |
+# Nielsen's 10 Usability Heuristics — Code Review Adaptation
+
+Scoring per heuristic: 0 (violated) → 4 (excellent). Focus on what is observable in the code.
+
+---
+
+## H1 — Visibility of System Status
+
+**What to look for in code**: Loading states on async actions, progress indicators, state-driven class/attribute changes, `aria-live` regions for dynamic content.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Every async action has a loading state; progress shown for multi-step ops; dynamic regions use `aria-live` |
+| **3** | Most async actions covered; 1 operation missing feedback |
+| **2** | Loading states on primary actions only; secondary actions have no feedback |
+| **1** | Only a spinner on page load; form submissions and mutations give no feedback |
+| **0** | No loading states anywhere; UI freezes silently on async calls |
+
+---
+
+## H2 — Match Between System and Real World
+
+**What to look for**: Label copy, icon choices, terminology in component props and display text, logical grouping of related items.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | All labels use user-facing language (not internal field names); icons are universally understood; groupings match mental models |
+| **3** | Mostly natural language; 1–2 developer-facing terms exposed in UI |
+| **2** | Mixed: some labels match user expectations, others use internal/technical terminology |
+| **1** | Predominantly technical labels (`user_id`, `ts`, `ref_code`) in visible UI |
+| **0** | Raw API field names or database column names exposed directly to users |
+
+---
+
+## H3 — User Control and Freedom
+
+**What to look for**: Cancel buttons on dialogs and forms, undo functionality, ability to navigate back, escape-to-close on modals.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Undo available for destructive actions; all modals closeable via Escape; cancel on all multi-step flows |
+| **3** | Most paths have exits; one flow lacks a clear back/cancel |
+| **2** | Cancel exists on modals but destructive actions (delete, submit) have no undo |
+| **1** | No undo; several flows trap the user until completion |
+| **0** | Irreversible destructive actions with no confirmation or recovery path |
+
+---
+
+## H4 — Consistency and Standards
+
+**What to look for**: Reuse of shared components, consistent prop naming, same action always produces same UI response, platform conventions followed.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Shared component library used throughout; same action triggers same visual pattern; follows platform HIG |
+| **3** | 1–2 inconsistencies (e.g., one custom button not using Button component) |
+| **2** | Some shared components but several one-off implementations for identical patterns |
+| **1** | Each page re-implements its own UI patterns; no shared components |
+| **0** | Same action produces visually different results on different screens |
+
+---
+
+## H5 — Error Prevention
+
+**What to look for**: Input validation (inline, not just on submit), confirmation dialogs on destructive actions, disabled states on invalid forms, input constraints (maxLength, type, pattern).
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Inline validation; destructive actions confirmed; submit disabled until valid; input types constrain input |
+| **3** | Confirmation dialogs present; validation on submit but not inline |
+| **2** | Some validation; destructive actions have confirmation but forms don't validate until submit |
+| **1** | No inline validation; destructive actions unconstrained |
+| **0** | No validation or confirmation; data loss possible without warning |
+
+---
+
+## H6 — Recognition Rather Than Recall
+
+**What to look for**: Breadcrumbs, visible current state in navigation, contextual help text, search suggestions, recently used items.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Current location always visible; options surfaced in context; search includes suggestions |
+| **3** | Navigation shows current state; options visible on primary flows |
+| **2** | Some affordances; secondary flows require user to remember where they are |
+| **1** | No breadcrumbs; navigation doesn't indicate current section; users must recall paths |
+| **0** | Deep nested flows with no orientation cues |
+
+---
+
+## H7 — Flexibility and Efficiency
+
+**What to look for**: Keyboard shortcuts, bulk actions, saved defaults, power-user paths that bypass multi-step flows.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Keyboard shortcuts for primary actions; bulk selection; smart defaults pre-populated |
+| **3** | Good defaults; 1–2 keyboard shortcuts on critical actions |
+| **2** | No shortcuts; forms have some defaults but key fields are always blank |
+| **1** | Every task requires the same number of steps regardless of user expertise |
+| **0** | Power users actively slowed down (e.g., forced onboarding on repeat visits) |
+
+---
+
+## H8 — Aesthetic and Minimalist Design
+
+**What to look for**: Signal-to-noise ratio in rendered output; unnecessary decorative elements; information density relative to task complexity.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Every visible element serves a task or provides necessary context; no decorative noise |
+| **3** | Mostly clean; 1–2 decorative elements that could be removed without loss |
+| **2** | Several decorative elements that compete with primary content |
+| **1** | UI is visually busy; primary actions compete with decoration |
+| **0** | Information overload; users cannot identify primary action without significant scanning |
+
+---
+
+## H9 — Help Users Recognize and Recover from Errors
+
+**What to look for**: Error message copy (specific, human-readable, with next steps), error placement (near the problem), error state styling.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Errors are specific, placed next to the problem, and suggest a fix; styled distinctly |
+| **3** | Clear error messages; placed correctly; fix suggestion sometimes missing |
+| **2** | Error messages exist but are generic ("Something went wrong") or placed in a toast far from the issue |
+| **1** | Raw error codes or API messages exposed to users |
+| **0** | No error states; failures silently ignored or produce white screens |
+
+---
+
+## H10 — Help and Documentation
+
+**What to look for**: Tooltips on complex fields, onboarding flows for new users, empty states with guidance, contextual help links.
+
+| Score | Code Evidence |
+|-------|---------------|
+| **4** | Tooltips on non-obvious fields; empty states guide next action; onboarding present for new users |
+| **3** | Empty states with calls-to-action; tooltips on some complex fields |
+| **2** | Generic empty states ("No data found") without guidance |
+| **1** | No tooltips, empty state guidance, or onboarding |
+| **0** | Confusing UI with no help and no path to documentation |