diff --git a/.agents/skills/audit/SKILL.md b/.agents/skills/audit/SKILL.md index b0cee9eaa..1debe043e 100644 --- a/.agents/skills/audit/SKILL.md +++ b/.agents/skills/audit/SKILL.md @@ -1,125 +1,147 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. user-invocable: true argument-hint: "[area (feature, page, component...)]" --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke /frontend-design for design principles and anti-patterns. +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. -Examples: -- "Use `/normalize` to align with design system (addresses N theming issues)" -- "Use `/optimize` to improve performance (addresses N performance issues)" -- "Use `/harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.agents/skills/critique/SKILL.md b/.agents/skills/critique/SKILL.md index 29806cd81..70ac82f1d 100644 --- a/.agents/skills/critique/SKILL.md +++ b/.agents/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. user-invocable: true argument-hint: "[area (feature, page, component...)]" --- @@ -11,9 +11,9 @@ Invoke /frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -21,7 +21,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -31,17 +31,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -65,7 +71,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -79,41 +85,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `.github/copilot-instructions.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.agents/skills/critique/reference/cognitive-load.md b/.agents/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.agents/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.agents/skills/critique/reference/heuristics-scoring.md b/.agents/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.agents/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.agents/skills/critique/reference/personas.md b/.agents/skills/critique/reference/personas.md new file mode 100644 index 000000000..eb2f2b6d1 --- /dev/null +++ b/.agents/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `.github/copilot-instructions.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/audit/SKILL.md index b0cee9eaa..1debe043e 100644 --- a/.claude/skills/audit/SKILL.md +++ b/.claude/skills/audit/SKILL.md @@ -1,125 +1,147 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. user-invocable: true argument-hint: "[area (feature, page, component...)]" --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke /frontend-design for design principles and anti-patterns. +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. -Examples: -- "Use `/normalize` to align with design system (addresses N theming issues)" -- "Use `/optimize` to improve performance (addresses N performance issues)" -- "Use `/harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index 29806cd81..2c8e073ed 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. user-invocable: true argument-hint: "[area (feature, page, component...)]" --- @@ -11,9 +11,9 @@ Invoke /frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -21,7 +21,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -31,17 +31,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -65,7 +71,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -79,41 +85,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `CLAUDE.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. STOP and call the AskUserQuestion tool to clarify. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.claude/skills/critique/reference/cognitive-load.md b/.claude/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.claude/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.claude/skills/critique/reference/heuristics-scoring.md b/.claude/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.claude/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.claude/skills/critique/reference/personas.md b/.claude/skills/critique/reference/personas.md new file mode 100644 index 000000000..1960220aa --- /dev/null +++ b/.claude/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `CLAUDE.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.codex/skills/audit/SKILL.md b/.codex/skills/audit/SKILL.md index 700e98f63..def1967dc 100644 --- a/.codex/skills/audit/SKILL.md +++ b/.codex/skills/audit/SKILL.md @@ -1,124 +1,146 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. argument-hint: "[area (feature, page, component...)]" --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke $frontend-design for design principles and anti-patterns. +Invoke $frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run $teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: $animate, $quieter, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: $animate, $quieter, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `$command-name`** — Brief description (specific context from audit findings) +2. **[P?] `$command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: $animate, $quieter, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: $animate, $quieter, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive. Map findings to the most appropriate command. End with `$polish` as the final step if any fixes were recommended. -Examples: -- "Use `$normalize` to align with design system (addresses N theming issues)" -- "Use `$optimize` to improve performance (addresses N performance issues)" -- "Use `$harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `$audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.codex/skills/critique/SKILL.md b/.codex/skills/critique/SKILL.md index 27e5d98bc..5cb4af114 100644 --- a/.codex/skills/critique/SKILL.md +++ b/.codex/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. argument-hint: "[area (feature, page, component...)]" --- @@ -10,9 +10,9 @@ Invoke $frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -20,7 +20,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -30,17 +30,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -64,7 +70,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -78,41 +84,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: $animate, $quieter, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: $animate, $quieter, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer$bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`$command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`$command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: $animate, $quieter, $optimize, $adapt, $clarify, $distill, $delight, $onboard, $normalize, $audit, $harden, $polish, $extract, $bolder, $arrange, $typeset, $critique, $colorize, $overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `$polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `$critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.codex/skills/critique/reference/cognitive-load.md b/.codex/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.codex/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.codex/skills/critique/reference/heuristics-scoring.md b/.codex/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.codex/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.codex/skills/critique/reference/personas.md b/.codex/skills/critique/reference/personas.md new file mode 100644 index 000000000..2d0f9cbf3 --- /dev/null +++ b/.codex/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `AGENTS.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.cursor/skills/audit/SKILL.md b/.cursor/skills/audit/SKILL.md index 6490cb9aa..6dc747d60 100644 --- a/.cursor/skills/audit/SKILL.md +++ b/.cursor/skills/audit/SKILL.md @@ -1,123 +1,145 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke /frontend-design for design principles and anti-patterns. +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. -Examples: -- "Use `/normalize` to align with design system (addresses N theming issues)" -- "Use `/optimize` to improve performance (addresses N performance issues)" -- "Use `/harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.cursor/skills/critique/SKILL.md b/.cursor/skills/critique/SKILL.md index f964b3eee..3d2746f69 100644 --- a/.cursor/skills/critique/SKILL.md +++ b/.cursor/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. --- ## MANDATORY PREPARATION @@ -9,9 +9,9 @@ Invoke /frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -19,7 +19,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -29,17 +29,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -63,7 +69,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -77,41 +83,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `.cursorrules` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.cursor/skills/critique/reference/cognitive-load.md b/.cursor/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.cursor/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.cursor/skills/critique/reference/heuristics-scoring.md b/.cursor/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.cursor/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.cursor/skills/critique/reference/personas.md b/.cursor/skills/critique/reference/personas.md new file mode 100644 index 000000000..84689b598 --- /dev/null +++ b/.cursor/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `.cursorrules` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.gemini/skills/audit/SKILL.md b/.gemini/skills/audit/SKILL.md index 6490cb9aa..6dc747d60 100644 --- a/.gemini/skills/audit/SKILL.md +++ b/.gemini/skills/audit/SKILL.md @@ -1,123 +1,145 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke /frontend-design for design principles and anti-patterns. +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. -Examples: -- "Use `/normalize` to align with design system (addresses N theming issues)" -- "Use `/optimize` to improve performance (addresses N performance issues)" -- "Use `/harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.gemini/skills/critique/SKILL.md b/.gemini/skills/critique/SKILL.md index f964b3eee..12180ce73 100644 --- a/.gemini/skills/critique/SKILL.md +++ b/.gemini/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. --- ## MANDATORY PREPARATION @@ -9,9 +9,9 @@ Invoke /frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -19,7 +19,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -29,17 +29,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -63,7 +69,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -77,41 +83,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `GEMINI.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.gemini/skills/critique/reference/cognitive-load.md b/.gemini/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.gemini/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.gemini/skills/critique/reference/heuristics-scoring.md b/.gemini/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.gemini/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.gemini/skills/critique/reference/personas.md b/.gemini/skills/critique/reference/personas.md new file mode 100644 index 000000000..80b38a939 --- /dev/null +++ b/.gemini/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `GEMINI.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.kiro/skills/audit/SKILL.md b/.kiro/skills/audit/SKILL.md index 6490cb9aa..6dc747d60 100644 --- a/.kiro/skills/audit/SKILL.md +++ b/.kiro/skills/audit/SKILL.md @@ -1,123 +1,145 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke /frontend-design for design principles and anti-patterns. +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. -Examples: -- "Use `/normalize` to align with design system (addresses N theming issues)" -- "Use `/optimize` to improve performance (addresses N performance issues)" -- "Use `/harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.kiro/skills/critique/SKILL.md b/.kiro/skills/critique/SKILL.md index f964b3eee..5d9660aae 100644 --- a/.kiro/skills/critique/SKILL.md +++ b/.kiro/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. --- ## MANDATORY PREPARATION @@ -9,9 +9,9 @@ Invoke /frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -19,7 +19,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -29,17 +29,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -63,7 +69,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -77,41 +83,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `.kiro/settings.json` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.kiro/skills/critique/reference/cognitive-load.md b/.kiro/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.kiro/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.kiro/skills/critique/reference/heuristics-scoring.md b/.kiro/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.kiro/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.kiro/skills/critique/reference/personas.md b/.kiro/skills/critique/reference/personas.md new file mode 100644 index 000000000..615d30d74 --- /dev/null +++ b/.kiro/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `.kiro/settings.json` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.opencode/skills/audit/SKILL.md b/.opencode/skills/audit/SKILL.md index b0cee9eaa..1debe043e 100644 --- a/.opencode/skills/audit/SKILL.md +++ b/.opencode/skills/audit/SKILL.md @@ -1,125 +1,147 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. user-invocable: true argument-hint: "[area (feature, page, component...)]" --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke /frontend-design for design principles and anti-patterns. +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. -Examples: -- "Use `/normalize` to align with design system (addresses N theming issues)" -- "Use `/optimize` to improve performance (addresses N performance issues)" -- "Use `/harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.opencode/skills/critique/SKILL.md b/.opencode/skills/critique/SKILL.md index 29806cd81..74f39ab4e 100644 --- a/.opencode/skills/critique/SKILL.md +++ b/.opencode/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. user-invocable: true argument-hint: "[area (feature, page, component...)]" --- @@ -11,9 +11,9 @@ Invoke /frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -21,7 +21,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -31,17 +31,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -65,7 +71,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -79,41 +85,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. STOP and call the `question` tool to clarify. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.opencode/skills/critique/reference/cognitive-load.md b/.opencode/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.opencode/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.opencode/skills/critique/reference/heuristics-scoring.md b/.opencode/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.opencode/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.opencode/skills/critique/reference/personas.md b/.opencode/skills/critique/reference/personas.md new file mode 100644 index 000000000..2d0f9cbf3 --- /dev/null +++ b/.opencode/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `AGENTS.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.pi/skills/audit/SKILL.md b/.pi/skills/audit/SKILL.md index 6490cb9aa..6dc747d60 100644 --- a/.pi/skills/audit/SKILL.md +++ b/.pi/skills/audit/SKILL.md @@ -1,123 +1,145 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke /frontend-design for design principles and anti-patterns. +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. -Examples: -- "Use `/normalize` to align with design system (addresses N theming issues)" -- "Use `/optimize` to improve performance (addresses N performance issues)" -- "Use `/harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.pi/skills/critique/SKILL.md b/.pi/skills/critique/SKILL.md index f964b3eee..dba9b20aa 100644 --- a/.pi/skills/critique/SKILL.md +++ b/.pi/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. --- ## MANDATORY PREPARATION @@ -9,9 +9,9 @@ Invoke /frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -19,7 +19,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -29,17 +29,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -63,7 +69,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -77,41 +83,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.pi/skills/critique/reference/cognitive-load.md b/.pi/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.pi/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.pi/skills/critique/reference/heuristics-scoring.md b/.pi/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.pi/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.pi/skills/critique/reference/personas.md b/.pi/skills/critique/reference/personas.md new file mode 100644 index 000000000..2d0f9cbf3 --- /dev/null +++ b/.pi/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `AGENTS.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.trae-cn/skills/audit/SKILL.md b/.trae-cn/skills/audit/SKILL.md index b0cee9eaa..1debe043e 100644 --- a/.trae-cn/skills/audit/SKILL.md +++ b/.trae-cn/skills/audit/SKILL.md @@ -1,125 +1,147 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a prioritized report with severity ratings. Use when the user wants a design review, accessibility check, quality audit, or a full list of UI issues to fix. +description: Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review. user-invocable: true argument-hint: "[area (feature, page, component...)]" --- -Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke /frontend-design for design principles and anti-patterns. +Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. + +--- + +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. + +This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. ## Diagnostic Scan -Run comprehensive checks across multiple dimensions: +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. -1. **Accessibility (A11y)** - Check for: - - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) - - **Missing ARIA**: Interactive elements without proper roles, labels, or states - - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps - - **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons - - **Alt text**: Missing or poor image descriptions - - **Form issues**: Inputs without labels, poor error messaging, missing required indicators +### 1. Accessibility (A11y) -2. **Performance** - Check for: - - **Layout thrashing**: Reading/writing layout properties in loops - - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity - - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change - - **Bundle size**: Unnecessary imports, unused dependencies - - **Render performance**: Unnecessary re-renders, missing memoization +**Check for**: +- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) +- **Missing ARIA**: Interactive elements without proper roles, labels, or states +- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps +- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons +- **Alt text**: Missing or poor image descriptions +- **Form issues**: Inputs without labels, poor error messaging, missing required indicators -3. **Theming** - Check for: - - **Hard-coded colors**: Colors not using design tokens - - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme - - **Inconsistent tokens**: Using wrong tokens, mixing token types - - **Theme switching issues**: Values that don't update on theme change +**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA) -4. **Responsive Design** - Check for: - - **Fixed widths**: Hard-coded widths that break on mobile - - **Touch targets**: Interactive elements < 44x44px - - **Horizontal scroll**: Content overflow on narrow viewports - - **Text scaling**: Layouts that break when text size increases - - **Missing breakpoints**: No mobile/tablet variants +### 2. Performance -5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). +**Check for**: +- **Layout thrashing**: Reading/writing layout properties in loops +- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity +- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Bundle size**: Unnecessary imports, unused dependencies +- **Render performance**: Unnecessary re-renders, missing memoization -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit. +**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized) -## Generate Comprehensive Report +### 3. Theming -Create a detailed audit report with the following structure: +**Check for**: +- **Hard-coded colors**: Colors not using design tokens +- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme +- **Inconsistent tokens**: Using wrong tokens, mixing token types +- **Theme switching issues**: Values that don't update on theme change + +**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly) + +### 4. Responsive Design + +**Check for**: +- **Fixed widths**: Hard-coded widths that break on mobile +- **Touch targets**: Interactive elements < 44x44px +- **Horizontal scroll**: Content overflow on narrow viewports +- **Text scaling**: Layouts that break when text size increases +- **Missing breakpoints**: No mobile/tablet variants + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets) + +### 5. Anti-Patterns (CRITICAL) + +Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy). + +**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design) + +## Generate Report + +### Audit Health Score + +| # | Dimension | Score | Key Finding | +|---|-----------|-------|-------------| +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | +| 2 | Performance | ? | | +| 3 | Responsive Design | ? | | +| 4 | Theming | ? | | +| 5 | Anti-Patterns | ? | | +| **Total** | | **??/20** | **[Rating band]** | + +**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. +**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. ### Executive Summary -- Total issues found (count by severity) -- Most critical issues (top 3-5) -- Overall quality score (if applicable) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0-P3 severity**: +- **P0 Blocking**: Prevents task completion — fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release +- **P2 Minor**: Annoyance, workaround exists — fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits + For each issue, document: -- **Location**: Where the issue occurs (component, file, line) -- **Severity**: Critical / High / Medium / Low -- **Category**: Accessibility / Performance / Theming / Responsive -- **Description**: What the issue is +- **[P?] Issue name** +- **Location**: Component, file, line +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) - -#### Critical Issues -[Issues that block core functionality or violate WCAG A] - -#### High-Severity Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### Medium-Severity Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### Low-Severity Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) ### Patterns & Systemic Issues -Identify recurring problems: +Identify recurring problems that indicate systemic gaps rather than one-off mistakes: - "Hard-coded colors appear in 15+ components, should use design tokens" - "Touch targets consistently too small (<44px) throughout mobile experience" -- "Missing focus indicators on all custom interactive components" ### Positive Findings -Note what's working well: -- Good practices to maintain -- Exemplary implementations to replicate elsewhere +Note what's working well — good practices to maintain and replicate. -### Recommendations by Priority +## Recommended Actions -Create actionable plan: -1. **Immediate**: Critical blockers to fix first -2. **Short-term**: High-severity issues (this sprint) -3. **Medium-term**: Quality improvements (next sprint) -4. **Long-term**: Nice-to-haves and optimizations +List recommended commands in priority order (P0 first, then P1, then P2): -### Suggested Commands for Fixes +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. You may also suggest other installed skills you're sure exist, but never invent commands. +**Rules**: Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive. Map findings to the most appropriate command. End with `/polish` as the final step if any fixes were recommended. -Examples: -- "Use `/normalize` to align with design system (addresses N theming issues)" -- "Use `/optimize` to improve performance (addresses N performance issues)" -- "Use `/harden` to improve resilience (addresses N edge cases)" +After presenting the summary, tell the user: -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/audit` after fixes to see your score improve. + +**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. **NEVER**: - Report issues without explaining impact (why does this matter?) -- Mix severity levels inconsistently -- Skip positive findings (celebrate what works) - Provide generic recommendations (be specific and actionable) -- Forget to prioritize (everything can't be critical) +- Skip positive findings (celebrate what works) +- Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy. \ No newline at end of file +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. \ No newline at end of file diff --git a/.trae-cn/skills/critique/SKILL.md b/.trae-cn/skills/critique/SKILL.md index 29806cd81..8a409115a 100644 --- a/.trae-cn/skills/critique/SKILL.md +++ b/.trae-cn/skills/critique/SKILL.md @@ -1,6 +1,6 @@ --- name: critique -description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback. Use when the user asks to review, critique, evaluate, audit, or give feedback on a design, UI, or component. +description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component. user-invocable: true argument-hint: "[area (feature, page, component...)]" --- @@ -11,9 +11,9 @@ Invoke /frontend-design — it contains design principles, anti-patterns, and th --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback. -## Design Critique +## Phase 1: Design Critique Evaluate the interface across these dimensions: @@ -21,7 +21,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill — they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -31,17 +31,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Do size, color, and position communicate importance correctly? - Is there visual competition between elements that should have different weights? -### 3. Information Architecture +### 3. Information Architecture & Cognitive Load +> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist* - Is the structure intuitive? Would a new user understand the organization? - Is related content grouped logically? -- Are there too many choices at once? (cognitive overload) +- Are there too many choices at once? Count visible options at each decision point — if >4, flag it - Is the navigation clear and predictable? +- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront? +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. -### 4. Emotional Resonance +### 4. Emotional Journey - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful — whatever it should feel? - Would the target user feel "this is for me"? +- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)? +- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit) +- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof) ### 5. Discoverability & Affordance - Are interactive elements obviously interactive? @@ -65,7 +71,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically — does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -79,41 +85,117 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Are labels and buttons unambiguous? - Does error copy help users fix the problem? -## Generate Critique Report +## Phase 2: Present Findings Structure your feedback as a design director would: +### Design Health Score +> *Consult [heuristics-scoring](reference/heuristics-scoring.md)* + +Score each of Nielsen's 10 heuristics 0–4. Present as a table: + +| # | Heuristic | Score | Key Issue | +|---|-----------|-------|-----------| +| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] | +| 2 | Match System / Real World | ? | | +| 3 | User Control and Freedom | ? | | +| 4 | Consistency and Standards | ? | | +| 5 | Error Prevention | ? | | +| 6 | Recognition Rather Than Recall | ? | | +| 7 | Flexibility and Efficiency | ? | | +| 8 | Aesthetic and Minimalist Design | ? | | +| 9 | Error Recovery | ? | | +| 10 | Help and Documentation | ? | | +| **Total** | | **??/40** | **[Rating band]** | + +Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20–32. + ### Anti-Patterns Verdict **Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +A brief gut reaction — what works, what doesn't, and the single biggest opportunity. ### What's Working -Highlight 2-3 things done well. Be specific about why they work. +Highlight 2–3 things done well. Be specific about why they work. ### Priority Issues -The 3-5 most impactful design problems, ordered by importance: +The 3–5 most impactful design problems, ordered by importance. -For each issue: -- **What**: Name the problem clearly +For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): +- **[P?] What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive) + +### Persona Red Flags +> *Consult [personas](reference/personas.md)* + +Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. + +For each selected persona, walk through the primary user action and list specific red flags found: + +**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. ⚠️ High abandonment risk. + +**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. ⚠️ Will abandon at step 2. + +Be specific — name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. ### Minor Observations Quick notes on smaller issues worth addressing. -### Questions to Consider -Provocative questions that might unlock better solutions: -- "What if the primary action were more prominent?" -- "Does this need to feel this complex?" -- "What would a confident version of this look like?" - **Remember**: -- Be direct—vague feedback wastes everyone's time -- Be specific—"the submit button" not "some elements" +- Be direct — vague feedback wastes everyone's time +- Be specific — "the submit button" not "some elements" - Say what's wrong AND why it matters to users - Give concrete suggestions, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly — if everything is important, nothing is +- Don't soften criticism — developers need honest feedback to ship great design + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. + +Ask questions along these lines (adapt to the specific findings — do NOT ask generic questions): + +1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2–3 issue categories as options. + +2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2–3 tonal directions as options based on what would fix the issues found. + +3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only". + +4. **Constraints** (optional — only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. + +**Rules for questions**: +- Every question must reference specific findings from Phase 2 — never ask generic "who is your audience?" questions +- Keep it to 2–4 questions maximum — respect the user's time +- Offer concrete options, not open-ended prompts +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 + +## Phase 4: Recommended Actions + +**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Phase 3. + +### Action Summary + +List recommended commands in priority order, based on the user's answers: + +1. **`/command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`/command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive +- Order by the user's stated priorities first, then by impact +- Each item's description should carry enough context that the command knows what to focus on +- Map each Priority Issue to the appropriate command +- Skip commands that would address zero issues +- If the user chose a limited scope, only include items within that scope +- If the user marked areas as off-limits, exclude commands that would touch those areas +- End with `/polish` as the final step if any fixes were recommended + +After presenting the summary, tell the user: + +> You can ask me to run these one at a time, all at once, or in any order you prefer. +> +> Re-run `/critique` after fixes to see your score improve. \ No newline at end of file diff --git a/.trae-cn/skills/critique/reference/cognitive-load.md b/.trae-cn/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/.trae-cn/skills/critique/reference/cognitive-load.md @@ -0,0 +1,106 @@ +# Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +## Three Types of Cognitive Load + +### Intrinsic Load — The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure — show what's needed now, hide the rest +- Grouping related decisions together + +### Extraneous Load — Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +### Germane Load — Learning Effort +Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +## Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +## The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits — manageable +- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure +- **8+ items**: Overloaded — users will skip, misclick, or abandon + +**Practical applications**: +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Form sections: ≤4 fields visible per group before a visual break +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Dashboard widgets: ≤4 key metrics visible without scrolling +- Pricing tiers: ≤3 options (more causes analysis paralysis) + +--- + +## Common Cognitive Load Violations + +### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight — nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. diff --git a/.trae-cn/skills/critique/reference/heuristics-scoring.md b/.trae-cn/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/.trae-cn/skills/critique/reference/heuristics-scoring.md @@ -0,0 +1,234 @@ +# Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." + +## Nielsen's 10 Heuristics + +### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback — user is guessing what happened | +| 1 | Rare feedback — most actions produce no visible response | +| 2 | Partial — some states communicated, major gaps remain | +| 3 | Good — most operations give clear feedback, minor gaps | +| 4 | Excellent — every action confirms, progress is always visible | + +### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing — requires domain expertise to navigate | +| 2 | Mixed — some plain language, some jargon leaks through | +| 3 | Mostly natural — occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped — no way out without refreshing | +| 1 | Difficult exits — must find obscure paths to escape | +| 2 | Some exits — main flows have escape, edge cases don't | +| 3 | Good control — users can exit and undo most actions | +| 4 | Full control — undo, cancel, back, and escape everywhere | + +### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere — feels like different products stitched together | +| 1 | Many inconsistencies — similar things look/behave differently | +| 2 | Partially consistent — main flows match, details diverge | +| 3 | Mostly consistent — occasional deviation, nothing confusing | +| 4 | Fully consistent — cohesive system, predictable behavior | + +### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make — no guardrails anywhere | +| 1 | Few safeguards — some inputs validated, most aren't | +| 2 | Partial prevention — common errors caught, edge cases slip | +| 3 | Good prevention — most error paths blocked proactively | +| 4 | Excellent — errors nearly impossible through smart constraints | + +### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization — users must remember paths and commands | +| 1 | Mostly recall — many hidden features, few visible cues | +| 2 | Some aids — main actions visible, secondary features hidden | +| 3 | Good recognition — most things discoverable, few memory demands | +| 4 | Everything discoverable — users never need to memorize | + +### 7. Flexibility and Efficiency of Use + +Accelerators — invisible to novices — speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path — no shortcuts or alternatives | +| 1 | Limited flexibility — few alternatives to the main path | +| 2 | Some shortcuts — basic keyboard support, limited bulk actions | +| 3 | Good accelerators — keyboard nav, some customization | +| 4 | Highly flexible — multiple paths, power features, customizable | + +### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming — everything competes for attention equally | +| 1 | Cluttered — too much noise, hard to find what matters | +| 2 | Some clutter — main content clear, periphery noisy | +| 3 | Mostly clean — focused design, minor visual noise | +| 4 | Perfectly minimal — every element earns its pixel | + +### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors — codes, jargon, or no message at all | +| 1 | Vague errors — "Something went wrong" with no guidance | +| 2 | Clear but unhelpful — names the problem but not the fix | +| 3 | Clear with suggestions — identifies problem and offers next steps | +| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | + +### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help — FAQ or docs exist, not contextual | +| 3 | Good documentation — searchable, mostly task-focused | +| 4 | Excellent contextual help — right info at the right moment | + +--- + +## Score Summary + +**Total possible**: 40 points (10 heuristics × 4 max) + +| Score Range | Rating | What It Means | +|-------------|--------|---------------| +| 36–40 | Excellent | Minor polish only — ship it | +| 28–35 | Good | Address weak areas, solid foundation | +| 20–27 | Acceptable | Significant improvements needed before users are happy | +| 12–19 | Poor | Major UX overhaul required — core experience broken | +| 0–11 | Critical | Redesign needed — unusable in current state | + +--- + +## Issue Severity (P0–P3) + +Tag each individual issue found during scoring with a priority level: + +| Priority | Name | Description | Action | +|----------|------|-------------|--------| +| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P1** | Major | Causes significant difficulty or confusion | Fix before release | +| **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | +| **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | + +**Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. diff --git a/.trae-cn/skills/critique/reference/personas.md b/.trae-cn/skills/critique/reference/personas.md new file mode 100644 index 000000000..6325e2839 --- /dev/null +++ b/.trae-cn/skills/critique/reference/personas.md @@ -0,0 +1,178 @@ +# Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns. + +--- + +## 1. Impatient Power User — "Alex" + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +## 2. Confused First-Timer — "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +## 3. Accessibility-Dependent User — "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +## 4. Deliberate Stress Tester — "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +## 5. Distracted Mobile User — "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only — prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms leverage autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence — progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +## Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +## Project-Specific Personas + +If `RULES.md` contains a `## Design Context` section (generated by `teach-impeccable`), derive 1–2 additional personas from the audience and brand information: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +### [Role] — "[Name]" + +**Profile**: [2-3 key characteristics derived from Design Context] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists. diff --git a/.trae-cn/skills/frontend-design/reference/interaction-design.md b/.trae-cn/skills/frontend-design/reference/interaction-design.md index 10a77564b..19d6809a8 100644 --- a/.trae-cn/skills/frontend-design/reference/interaction-design.md +++ b/.trae-cn/skills/frontend-design/reference/interaction-design.md @@ -84,6 +84,78 @@ For tooltips, dropdowns, and non-modal overlays, use native popovers: **Benefits**: Light-dismiss (click outside closes), proper stacking, no z-index wars, accessible by default. +## Dropdown & Overlay Positioning + +Dropdowns rendered with `position: absolute` inside a container that has `overflow: hidden` or `overflow: auto` will be clipped. This is the single most common dropdown bug in generated code. + +### CSS Anchor Positioning + +The modern solution uses the CSS Anchor Positioning API to tether an overlay to its trigger without JavaScript: + +```css +.trigger { + anchor-name: --menu-trigger; +} + +.dropdown { + position: fixed; + position-anchor: --menu-trigger; + position-area: block-end span-inline-end; + margin-top: 4px; +} + +/* Flip above if no room below */ +@position-try --flip-above { + position-area: block-start span-inline-end; + margin-bottom: 4px; +} +``` + +Because the dropdown uses `position: fixed`, it escapes any `overflow` clipping on ancestor elements. The `@position-try` block handles viewport edges automatically. **Browser support**: Chrome 125+, Edge 125+. Not yet in Firefox or Safari - use a fallback for those browsers. + +### Popover + Anchor Combo + +Combining the Popover API with anchor positioning gives you stacking, light-dismiss, accessibility, and correct positioning in one pattern: + +```html + +
+``` + +The `popover` attribute places the element in the **top layer**, which sits above all other content regardless of z-index or overflow. No portal needed. + +### Portal / Teleport Pattern + +In component frameworks, render the dropdown at the document root and position it with JavaScript: + +- **React**: `createPortal(dropdown, document.body)` +- **Vue**: `