From 2b68f01ea35891baec0b42aaa381e2f619c53970 Mon Sep 17 00:00:00 2001 From: Gabi Date: Tue, 24 Mar 2026 00:01:17 +0100 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20give=20critique=20and=20audit=20act?= =?UTF-8?q?ual=20teeth=20=E2=80=94=20scoring,=20personas,=20cognitive=20lo?= =?UTF-8?q?ad?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Critique was vibes-only before. Now it scores against Nielsen's 10 heuristics (0-4 each, /40 total) so you get a number, not just feelings. Added 5 user personas that auto-select based on the interface type — a power user and a first-timer break different things, turns out. Cognitive load checklist catches the "why does this screen make my brain hurt" problems. Audit gets the same treatment: 0-4 per dimension, /20 total, P0-P3 severity instead of the vague Critical/High/Medium/Low labels nobody agrees on. Both now present recommendations inline — no plan file, no /next or /fix-all commands. Just tell the AI what to fix and it does it. Simpler. New reference files: heuristics-scoring, personas, cognitive-load. --- .agents/skills/audit/SKILL.md | 167 +++++++++---- .agents/skills/critique/SKILL.md | 123 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ .agents/skills/critique/reference/personas.md | 178 +++++++++++++ .claude/skills/audit/SKILL.md | 167 +++++++++---- .claude/skills/critique/SKILL.md | 123 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ .claude/skills/critique/reference/personas.md | 178 +++++++++++++ .codex/skills/audit/SKILL.md | 167 +++++++++---- .codex/skills/critique/SKILL.md | 123 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ .codex/skills/critique/reference/personas.md | 178 +++++++++++++ .cursor/skills/audit/SKILL.md | 167 +++++++++---- .cursor/skills/critique/SKILL.md | 123 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ .cursor/skills/critique/reference/personas.md | 178 +++++++++++++ .gemini/skills/audit/SKILL.md | 167 +++++++++---- .gemini/skills/critique/SKILL.md | 123 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ .gemini/skills/critique/reference/personas.md | 178 +++++++++++++ .kiro/skills/audit/SKILL.md | 167 +++++++++---- .kiro/skills/critique/SKILL.md | 123 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ .kiro/skills/critique/reference/personas.md | 178 +++++++++++++ .opencode/skills/audit/SKILL.md | 167 +++++++++---- .opencode/skills/critique/SKILL.md | 123 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ .../skills/critique/reference/personas.md | 178 +++++++++++++ .pi/skills/audit/SKILL.md | 167 +++++++++---- .pi/skills/critique/SKILL.md | 123 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ .pi/skills/critique/reference/personas.md | 178 +++++++++++++ source/skills/audit/SKILL.md | 166 +++++++++---- source/skills/critique/SKILL.md | 121 +++++++-- .../critique/reference/cognitive-load.md | 106 ++++++++ .../critique/reference/heuristics-scoring.md | 234 ++++++++++++++++++ source/skills/critique/reference/personas.md | 178 +++++++++++++ 45 files changed, 6631 insertions(+), 638 deletions(-) create mode 100644 .agents/skills/critique/reference/cognitive-load.md create mode 100644 .agents/skills/critique/reference/heuristics-scoring.md create mode 100644 .agents/skills/critique/reference/personas.md create mode 100644 .claude/skills/critique/reference/cognitive-load.md create mode 100644 .claude/skills/critique/reference/heuristics-scoring.md create mode 100644 .claude/skills/critique/reference/personas.md create mode 100644 .codex/skills/critique/reference/cognitive-load.md create mode 100644 .codex/skills/critique/reference/heuristics-scoring.md create mode 100644 .codex/skills/critique/reference/personas.md create mode 100644 .cursor/skills/critique/reference/cognitive-load.md create mode 100644 .cursor/skills/critique/reference/heuristics-scoring.md create mode 100644 .cursor/skills/critique/reference/personas.md create mode 100644 .gemini/skills/critique/reference/cognitive-load.md create mode 100644 .gemini/skills/critique/reference/heuristics-scoring.md create mode 100644 .gemini/skills/critique/reference/personas.md create mode 100644 .kiro/skills/critique/reference/cognitive-load.md create mode 100644 .kiro/skills/critique/reference/heuristics-scoring.md create mode 100644 .kiro/skills/critique/reference/personas.md create mode 100644 .opencode/skills/critique/reference/cognitive-load.md create mode 100644 .opencode/skills/critique/reference/heuristics-scoring.md create mode 100644 .opencode/skills/critique/reference/personas.md create mode 100644 .pi/skills/critique/reference/cognitive-load.md create mode 100644 .pi/skills/critique/reference/heuristics-scoring.md create mode 100644 .pi/skills/critique/reference/personas.md create mode 100644 source/skills/critique/reference/cognitive-load.md create mode 100644 source/skills/critique/reference/heuristics-scoring.md create mode 100644 source/skills/critique/reference/personas.md diff --git a/.agents/skills/audit/SKILL.md b/.agents/skills/audit/SKILL.md index 74cbb7475..50174e2a1 100644 --- a/.agents/skills/audit/SKILL.md +++ b/.agents/skills/audit/SKILL.md @@ -1,85 +1,133 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. user-invocable: true argument-hint: [AREA=] --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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) +- **Suggested command**: Which command to use (prefer: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -95,31 +143,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -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. +List recommended commands in priority order: -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)" +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- 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 `/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) +- 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 diff --git a/.agents/skills/critique/SKILL.md b/.agents/skills/critique/SKILL.md index f25717cab..d0bb9d463 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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. user-invocable: true argument-hint: [AREA=] --- @@ -13,7 +13,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -32,16 +32,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -79,10 +86,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -93,27 +129,82 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset) + +### 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" - 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 +- 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- 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..c91c78f74 --- /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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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 9f2d8b9d7..5dfa64dfa 100644 --- a/.claude/skills/audit/SKILL.md +++ b/.claude/skills/audit/SKILL.md @@ -1,6 +1,6 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. user-invocable: true args: - name: area @@ -8,81 +8,129 @@ args: required: false --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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) +- **Suggested command**: Which command to use (prefer: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -98,31 +146,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -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. +List recommended commands in priority order: -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)" +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- 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 `/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) +- 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 diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index bf735c842..9cf76f1d3 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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. user-invocable: true args: - name: area @@ -16,7 +16,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -35,16 +35,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -82,10 +89,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -96,27 +132,82 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset) + +### 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" - 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 +- 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- 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..67cf47d6b --- /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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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 ac09ebc59..bf54f7834 100644 --- a/.codex/skills/audit/SKILL.md +++ b/.codex/skills/audit/SKILL.md @@ -1,84 +1,132 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. argument-hint: [AREA=] --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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) +- **Suggested command**: Which command to use (prefer: $adapt, $animate, $audit, $bolder, $clarify, $colorize, $critique, $delight, $distill, $extract, $harden, $normalize, $onboard, $optimize, $polish, $quieter, $arrange, $overdrive, $typeset — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -94,31 +142,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -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. +List recommended commands in priority order: -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)" +1. **[P?] `$command-name`** — Brief description (specific context from audit findings) +2. **[P?] `$command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: $adapt, $animate, $audit, $bolder, $clarify, $colorize, $critique, $delight, $distill, $extract, $harden, $normalize, $onboard, $optimize, $polish, $quieter, $arrange, $overdrive, $typeset +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- 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 `$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) +- 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 diff --git a/.codex/skills/critique/SKILL.md b/.codex/skills/critique/SKILL.md index 615b3586b..3e19bad63 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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. argument-hint: [AREA=] --- @@ -12,7 +12,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -31,16 +31,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -78,10 +85,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -92,27 +128,82 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: $adapt, $animate, $audit, $bolder, $clarify, $colorize, $critique, $delight, $distill, $extract, $harden, $normalize, $onboard, $optimize, $polish, $quieter, $arrange, $overdrive, $typeset) + +### 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" - 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 +- 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: $adapt, $animate, $audit, $bolder, $clarify, $colorize, $critique, $delight, $distill, $extract, $harden, $normalize, $onboard, $optimize, $polish, $quieter, $arrange, $overdrive, $typeset +- 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..fdc88e20b --- /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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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 7e5205e20..f99978521 100644 --- a/.cursor/skills/audit/SKILL.md +++ b/.cursor/skills/audit/SKILL.md @@ -1,83 +1,131 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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) +- **Suggested command**: Which command to use (prefer: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -93,31 +141,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -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. +List recommended commands in priority order: -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)" +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- 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 `/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) +- 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 diff --git a/.cursor/skills/critique/SKILL.md b/.cursor/skills/critique/SKILL.md index 9e63a7468..00b2b2668 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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. --- ## MANDATORY PREPARATION @@ -11,7 +11,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -30,16 +30,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -77,10 +84,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -91,27 +127,82 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset) + +### 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" - 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 +- 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- 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..773021f95 --- /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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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 7e5205e20..f99978521 100644 --- a/.gemini/skills/audit/SKILL.md +++ b/.gemini/skills/audit/SKILL.md @@ -1,83 +1,131 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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) +- **Suggested command**: Which command to use (prefer: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -93,31 +141,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -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. +List recommended commands in priority order: -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)" +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- 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 `/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) +- 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 diff --git a/.gemini/skills/critique/SKILL.md b/.gemini/skills/critique/SKILL.md index 9e63a7468..773a9b32e 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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. --- ## MANDATORY PREPARATION @@ -11,7 +11,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -30,16 +30,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -77,10 +84,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -91,27 +127,82 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset) + +### 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" - 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 +- 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- 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..009244180 --- /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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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 7e5205e20..f99978521 100644 --- a/.kiro/skills/audit/SKILL.md +++ b/.kiro/skills/audit/SKILL.md @@ -1,83 +1,131 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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) +- **Suggested command**: Which command to use (prefer: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -93,31 +141,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -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. +List recommended commands in priority order: -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)" +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- 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 `/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) +- 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 diff --git a/.kiro/skills/critique/SKILL.md b/.kiro/skills/critique/SKILL.md index 9e63a7468..6ad561904 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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. --- ## MANDATORY PREPARATION @@ -11,7 +11,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -30,16 +30,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -77,10 +84,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -91,27 +127,82 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset) + +### 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" - 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 +- 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- 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..bf9296c16 --- /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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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 9f2d8b9d7..5dfa64dfa 100644 --- a/.opencode/skills/audit/SKILL.md +++ b/.opencode/skills/audit/SKILL.md @@ -1,6 +1,6 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. user-invocable: true args: - name: area @@ -8,81 +8,129 @@ args: required: false --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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) +- **Suggested command**: Which command to use (prefer: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -98,31 +146,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -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. +List recommended commands in priority order: -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)" +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- 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 `/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) +- 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 diff --git a/.opencode/skills/critique/SKILL.md b/.opencode/skills/critique/SKILL.md index bf735c842..258f1ca6d 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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. user-invocable: true args: - name: area @@ -16,7 +16,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -35,16 +35,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -82,10 +89,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -96,27 +132,82 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset) + +### 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" - 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 +- 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- 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..fdc88e20b --- /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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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 7e5205e20..f99978521 100644 --- a/.pi/skills/audit/SKILL.md +++ b/.pi/skills/audit/SKILL.md @@ -1,83 +1,131 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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) +- **Suggested command**: Which command to use (prefer: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -93,31 +141,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -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. +List recommended commands in priority order: -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)" +1. **[P?] `/command-name`** — Brief description (specific context from audit findings) +2. **[P?] `/command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- 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 `/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) +- 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 diff --git a/.pi/skills/critique/SKILL.md b/.pi/skills/critique/SKILL.md index 9e63a7468..3fdb409bf 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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. --- ## MANDATORY PREPARATION @@ -11,7 +11,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -30,16 +30,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -77,10 +84,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -91,27 +127,82 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset) + +### 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" - 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 +- 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: /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /arrange, /overdrive, /typeset +- 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..fdc88e20b --- /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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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/source/skills/audit/SKILL.md b/source/skills/audit/SKILL.md index 7e70200e1..3be30406a 100644 --- a/source/skills/audit/SKILL.md +++ b/source/skills/audit/SKILL.md @@ -1,6 +1,6 @@ --- name: audit -description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations. +description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates scored report with severity ratings and actionable plan. args: - name: area description: The feature or area to audit (optional) @@ -8,81 +8,129 @@ args: user-invocable: true --- -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. +Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. **First**: Use the frontend-design skill for design principles and anti-patterns. ## 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) + +### 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=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) + +**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. ## Generate Comprehensive Report -Create a detailed audit report with the following structure: +### Audit Health Score + +Present the dimension scores as a table: + +| # | 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**: +| Score | Rating | Action | +|-------|--------|--------| +| 18–20 | Excellent | Minor polish only | +| 14–17 | Good | Address weak dimensions | +| 10–13 | Acceptable | Significant work needed | +| 6–9 | Poor | Major quality overhaul | +| 0–5 | Critical | Fundamental issues across the board | ### 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. ### Executive Summary -- Total issues found (count by severity) +- Audit Health Score: **??/20** ([rating band]) +- Total issues found (count by severity: P0/P1/P2/P3) - Most critical issues (top 3-5) -- Overall quality score (if applicable) - Recommended next steps ### Detailed Findings by Severity +Tag every issue with **P0–P3 severity**: +| Priority | Name | Description | +|----------|------|-------------| +| **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 +- **[P?] Issue name** +- **Location**: Where it occurs (component, file, line) +- **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern - **Description**: What the issue is - **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: {{available_commands}} — or other installed skills you're sure exist) -#### Critical Issues -[Issues that block core functionality or violate WCAG A] +#### P0 — Blocking Issues +[Issues that prevent task completion or violate WCAG A] -#### High-Severity Issues +#### P1 — Major Issues [Significant usability/accessibility impact, WCAG AA violations] -#### Medium-Severity Issues +#### P2 — Minor Issues [Quality issues, WCAG AAA violations, performance concerns] -#### Low-Severity Issues +#### P3 — Polish Issues [Minor inconsistencies, optimization opportunities] ### Patterns & Systemic Issues @@ -98,32 +146,40 @@ Note what's working well: - Good practices to maintain - Exemplary implementations to replicate elsewhere -### 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 +Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). -### Suggested Commands for Fixes +### Action Summary -Map issues to available commands. Prefer these: {{available_commands}}. You may also suggest other installed skills you're sure exist, but never invent commands. +List recommended commands in priority order: -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)" +1. **[P?] `{{command_prefix}}command-name`** — Brief description (specific context from audit findings) +2. **[P?] `{{command_prefix}}command-name`** — Brief description (specific context) +... -**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters. +**Rules for recommendations**: +- Only recommend commands from: {{available_commands}} +- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) +- Each item's description should carry enough context that the command knows what to focus on +- Map findings to the most appropriate command +- Skip commands that would address zero issues +- End with `{{command_prefix}}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 `{{command_prefix}}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) +- 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. - diff --git a/source/skills/critique/SKILL.md b/source/skills/critique/SKILL.md index 618e69d55..38c327097 100644 --- a/source/skills/critique/SKILL.md +++ b/source/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. +description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, cognitive load, and overall design quality with quantitative scoring, persona-based testing, and actionable feedback. args: - name: area description: The feature or area to critique (optional) @@ -16,7 +16,7 @@ Use the frontend-design skill — it contains design principles, anti-patterns, 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: @@ -35,16 +35,23 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is there visual competition between elements that should have different weights? ### 3. Information Architecture +→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 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? +- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. -### 4. Emotional Resonance +### 4. Emotional Journey +→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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? - 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? @@ -82,10 +89,39 @@ 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 +### 11. Cognitive Load +→ *Consult [cognitive-load](reference/cognitive-load.md)* +- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? +- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. +- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? +- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? +- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. + +## 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. @@ -96,23 +132,30 @@ A brief gut reaction—what works, what doesn't, and the single biggest opportun 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: {{available_commands}} — or other installed skills you're sure exist) +- **Suggested command**: Which command could address this (from: {{available_commands}}) + +### 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 `{{config_file}}` 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" @@ -120,3 +163,51 @@ Provocative questions that might unlock better solutions: - 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 + +## Phase 3: Ask the User + +**After presenting findings**, use targeted questions based on what was actually found. {{ask_instruction}} 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_prefix}}command-name`** — Brief description of what to fix (specific context from critique findings) +2. **`{{command_prefix}}command-name`** — Brief description (specific context) +... + +**Rules for recommendations**: +- Only recommend commands from: {{available_commands}} +- 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 `{{command_prefix}}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 `{{command_prefix}}critique` after fixes to see your score improve. diff --git a/source/skills/critique/reference/cognitive-load.md b/source/skills/critique/reference/cognitive-load.md new file mode 100644 index 000000000..313df166b --- /dev/null +++ b/source/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/source/skills/critique/reference/heuristics-scoring.md b/source/skills/critique/reference/heuristics-scoring.md new file mode 100644 index 000000000..fd5b1b08b --- /dev/null +++ b/source/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/source/skills/critique/reference/personas.md b/source/skills/critique/reference/personas.md new file mode 100644 index 000000000..6f85892f5 --- /dev/null +++ b/source/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. Skeptical Evaluator — "Riley" + +**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Looks for pricing catches and hidden limitations +- Reads fine print and terms of service +- Tries to break things deliberately +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Is pricing and value proposition transparent? +- Are there hidden limitations or gotchas? +- How polished is error handling? +- What data is collected and why? + +**Red Flags** (report these specifically): +- Hidden pricing or "contact sales" for basic information +- Features that appear to work but produce broken results +- Poor error handling that exposes technical details +- Unclear data practices or missing privacy information +- Empty states that show nothing useful ("No results" with no guidance) + +--- + +## 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, trust, 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 `{{config_file}}` 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. From a9bf70f1ab2bb66f89c8d63bf30208c151b12629 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Tue, 24 Mar 2026 16:57:47 -0700 Subject: [PATCH 2/2] Refine critique and audit skills based on review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Collapse inline cognitive load section into reference pointer - Differentiate audit (technical, code-level) from critique (UX, holistic) - Add MANDATORY PREPARATION block to audit for context gathering - Rename Riley persona to "Deliberate Stress Tester", remove pricing focus - Restore stripped checklist items, persona examples, and emotional journey detail - Restore "Don't soften criticism" and IMPORTANT/NEVER lines in audit - Restore constraints question in Phase 3 - Fix em dash formatting (use proper — not --) - Shorten descriptions while preserving key trigger terms Co-Authored-By: Claude Opus 4.6 (1M context) --- .agents/skills/audit/SKILL.md | 101 ++++++------------ .agents/skills/critique/SKILL.md | 53 ++++----- .agents/skills/critique/reference/personas.md | 28 ++--- .claude/skills/audit/SKILL.md | 101 ++++++------------ .claude/skills/critique/SKILL.md | 53 ++++----- .claude/skills/critique/reference/personas.md | 28 ++--- .codex/skills/audit/SKILL.md | 101 ++++++------------ .codex/skills/critique/SKILL.md | 53 ++++----- .codex/skills/critique/reference/personas.md | 28 ++--- .cursor/skills/audit/SKILL.md | 101 ++++++------------ .cursor/skills/critique/SKILL.md | 53 ++++----- .cursor/skills/critique/reference/personas.md | 28 ++--- .gemini/skills/audit/SKILL.md | 101 ++++++------------ .gemini/skills/critique/SKILL.md | 53 ++++----- .gemini/skills/critique/reference/personas.md | 28 ++--- .kiro/skills/audit/SKILL.md | 101 ++++++------------ .kiro/skills/critique/SKILL.md | 53 ++++----- .kiro/skills/critique/reference/personas.md | 28 ++--- .opencode/skills/audit/SKILL.md | 101 ++++++------------ .opencode/skills/critique/SKILL.md | 53 ++++----- .../skills/critique/reference/personas.md | 28 ++--- .pi/skills/audit/SKILL.md | 101 ++++++------------ .pi/skills/critique/SKILL.md | 53 ++++----- .pi/skills/critique/reference/personas.md | 28 ++--- .trae-cn/skills/audit/SKILL.md | 101 ++++++------------ .trae-cn/skills/critique/SKILL.md | 53 ++++----- .../skills/critique/reference/personas.md | 28 ++--- .trae/skills/audit/SKILL.md | 101 ++++++------------ .trae/skills/critique/SKILL.md | 53 ++++----- .trae/skills/critique/reference/personas.md | 28 ++--- source/skills/audit/SKILL.md | 101 ++++++------------ source/skills/critique/SKILL.md | 53 ++++----- source/skills/critique/reference/personas.md | 28 ++--- 33 files changed, 759 insertions(+), 1243 deletions(-) diff --git a/.agents/skills/audit/SKILL.md b/.agents/skills/audit/SKILL.md index 74bb05abc..1debe043e 100644 --- a/.agents/skills/audit/SKILL.md +++ b/.agents/skills/audit/SKILL.md @@ -1,17 +1,23 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -23,7 +29,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -34,7 +40,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -44,7 +50,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -55,113 +61,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -173,10 +139,9 @@ After presenting the summary, tell the user: **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) +- 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 9e1322a33..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, cognitive load, and overall design 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, 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,7 +11,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +31,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -72,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"? @@ -86,27 +85,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -123,13 +114,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -138,7 +129,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -154,12 +145,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -167,9 +158,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -177,9 +168,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.agents/skills/critique/reference/personas.md b/.agents/skills/critique/reference/personas.md index c91c78f74..eb2f2b6d1 100644 --- a/.agents/skills/critique/reference/personas.md +++ b/.agents/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/audit/SKILL.md index 74bb05abc..1debe043e 100644 --- a/.claude/skills/audit/SKILL.md +++ b/.claude/skills/audit/SKILL.md @@ -1,17 +1,23 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -23,7 +29,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -34,7 +40,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -44,7 +50,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -55,113 +61,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -173,10 +139,9 @@ After presenting the summary, tell the user: **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) +- 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 7acdc2b45..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, cognitive load, and overall design 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, 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,7 +11,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +31,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -72,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"? @@ -86,27 +85,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -123,13 +114,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -138,7 +129,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -154,12 +145,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -167,9 +158,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -177,9 +168,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.claude/skills/critique/reference/personas.md b/.claude/skills/critique/reference/personas.md index 67cf47d6b..1960220aa 100644 --- a/.claude/skills/critique/reference/personas.md +++ b/.claude/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.codex/skills/audit/SKILL.md b/.codex/skills/audit/SKILL.md index 5bb698aa3..def1967dc 100644 --- a/.codex/skills/audit/SKILL.md +++ b/.codex/skills/audit/SKILL.md @@ -1,16 +1,22 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -22,7 +28,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -33,7 +39,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -43,7 +49,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -54,113 +60,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `$command-name`** — Brief description (specific context from audit findings) 2. **[P?] `$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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `$polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -172,10 +138,9 @@ After presenting the summary, tell the user: **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) +- 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 7f2ed0450..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, cognitive load, and overall design 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, 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,7 +10,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +30,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -71,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"? @@ -85,27 +84,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -122,13 +113,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -137,7 +128,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -153,12 +144,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -166,9 +157,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -176,9 +167,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.codex/skills/critique/reference/personas.md b/.codex/skills/critique/reference/personas.md index fdc88e20b..2d0f9cbf3 100644 --- a/.codex/skills/critique/reference/personas.md +++ b/.codex/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.cursor/skills/audit/SKILL.md b/.cursor/skills/audit/SKILL.md index d84428320..6dc747d60 100644 --- a/.cursor/skills/audit/SKILL.md +++ b/.cursor/skills/audit/SKILL.md @@ -1,15 +1,21 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -21,7 +27,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -32,7 +38,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -42,7 +48,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -53,113 +59,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -171,10 +137,9 @@ After presenting the summary, tell the user: **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) +- 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 7ae547bf5..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, cognitive load, and overall design 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, 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,7 +9,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +29,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -70,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"? @@ -84,27 +83,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -121,13 +112,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -136,7 +127,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -152,12 +143,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -165,9 +156,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -175,9 +166,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.cursor/skills/critique/reference/personas.md b/.cursor/skills/critique/reference/personas.md index 773021f95..84689b598 100644 --- a/.cursor/skills/critique/reference/personas.md +++ b/.cursor/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.gemini/skills/audit/SKILL.md b/.gemini/skills/audit/SKILL.md index d84428320..6dc747d60 100644 --- a/.gemini/skills/audit/SKILL.md +++ b/.gemini/skills/audit/SKILL.md @@ -1,15 +1,21 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -21,7 +27,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -32,7 +38,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -42,7 +48,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -53,113 +59,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -171,10 +137,9 @@ After presenting the summary, tell the user: **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) +- 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 359b222e8..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, cognitive load, and overall design 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, 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,7 +9,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +29,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -70,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"? @@ -84,27 +83,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -121,13 +112,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -136,7 +127,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -152,12 +143,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -165,9 +156,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -175,9 +166,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.gemini/skills/critique/reference/personas.md b/.gemini/skills/critique/reference/personas.md index 009244180..80b38a939 100644 --- a/.gemini/skills/critique/reference/personas.md +++ b/.gemini/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.kiro/skills/audit/SKILL.md b/.kiro/skills/audit/SKILL.md index d84428320..6dc747d60 100644 --- a/.kiro/skills/audit/SKILL.md +++ b/.kiro/skills/audit/SKILL.md @@ -1,15 +1,21 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -21,7 +27,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -32,7 +38,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -42,7 +48,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -53,113 +59,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -171,10 +137,9 @@ After presenting the summary, tell the user: **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) +- 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 28590d3f7..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, cognitive load, and overall design 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, 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,7 +9,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +29,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -70,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"? @@ -84,27 +83,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -121,13 +112,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -136,7 +127,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -152,12 +143,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -165,9 +156,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -175,9 +166,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.kiro/skills/critique/reference/personas.md b/.kiro/skills/critique/reference/personas.md index bf9296c16..615d30d74 100644 --- a/.kiro/skills/critique/reference/personas.md +++ b/.kiro/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.opencode/skills/audit/SKILL.md b/.opencode/skills/audit/SKILL.md index 74bb05abc..1debe043e 100644 --- a/.opencode/skills/audit/SKILL.md +++ b/.opencode/skills/audit/SKILL.md @@ -1,17 +1,23 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -23,7 +29,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -34,7 +40,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -44,7 +50,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -55,113 +61,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -173,10 +139,9 @@ After presenting the summary, tell the user: **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) +- 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 acc09f8c0..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, cognitive load, and overall design 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, 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,7 +11,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +31,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -72,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"? @@ -86,27 +85,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -123,13 +114,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -138,7 +129,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -154,12 +145,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -167,9 +158,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -177,9 +168,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.opencode/skills/critique/reference/personas.md b/.opencode/skills/critique/reference/personas.md index fdc88e20b..2d0f9cbf3 100644 --- a/.opencode/skills/critique/reference/personas.md +++ b/.opencode/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.pi/skills/audit/SKILL.md b/.pi/skills/audit/SKILL.md index d84428320..6dc747d60 100644 --- a/.pi/skills/audit/SKILL.md +++ b/.pi/skills/audit/SKILL.md @@ -1,15 +1,21 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -21,7 +27,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -32,7 +38,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -42,7 +48,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -53,113 +59,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -171,10 +137,9 @@ After presenting the summary, tell the user: **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) +- 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 f05987cbb..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, cognitive load, and overall design 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, 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,7 +9,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +29,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -70,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"? @@ -84,27 +83,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -121,13 +112,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -136,7 +127,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -152,12 +143,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -165,9 +156,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -175,9 +166,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.pi/skills/critique/reference/personas.md b/.pi/skills/critique/reference/personas.md index fdc88e20b..2d0f9cbf3 100644 --- a/.pi/skills/critique/reference/personas.md +++ b/.pi/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.trae-cn/skills/audit/SKILL.md b/.trae-cn/skills/audit/SKILL.md index 74bb05abc..1debe043e 100644 --- a/.trae-cn/skills/audit/SKILL.md +++ b/.trae-cn/skills/audit/SKILL.md @@ -1,17 +1,23 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -23,7 +29,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -34,7 +40,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -44,7 +50,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -55,113 +61,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -173,10 +139,9 @@ After presenting the summary, tell the user: **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) +- 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 1b1193ed2..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, cognitive load, and overall design 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, 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,7 +11,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +31,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -72,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"? @@ -86,27 +85,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -123,13 +114,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -138,7 +129,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -154,12 +145,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -167,9 +158,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -177,9 +168,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.trae-cn/skills/critique/reference/personas.md b/.trae-cn/skills/critique/reference/personas.md index 95daae85e..6325e2839 100644 --- a/.trae-cn/skills/critique/reference/personas.md +++ b/.trae-cn/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/.trae/skills/audit/SKILL.md b/.trae/skills/audit/SKILL.md index 74bb05abc..1debe043e 100644 --- a/.trae/skills/audit/SKILL.md +++ b/.trae/skills/audit/SKILL.md @@ -1,17 +1,23 @@ --- name: audit -description: Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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 quantitative scoring, prioritized issues, and an actionable plan. 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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -23,7 +29,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -34,7 +40,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -44,7 +50,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -55,113 +61,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `/command-name`** — Brief description (specific context from audit findings) 2. **[P?] `/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 severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `/polish` as the final step if any fixes were recommended +**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. After presenting the summary, tell the user: @@ -173,10 +139,9 @@ After presenting the summary, tell the user: **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) +- 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/skills/critique/SKILL.md b/.trae/skills/critique/SKILL.md index 1b1193ed2..8a409115a 100644 --- a/.trae/skills/critique/SKILL.md +++ b/.trae/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, cognitive load, and overall design 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, 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,7 +11,7 @@ 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. ## Phase 1: Design Critique @@ -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,20 +31,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -72,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"? @@ -86,27 +85,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -123,13 +114,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -138,7 +129,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **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)* +> *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. @@ -154,12 +145,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -167,9 +158,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -177,9 +168,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/.trae/skills/critique/reference/personas.md b/.trae/skills/critique/reference/personas.md index 95daae85e..6325e2839 100644 --- a/.trae/skills/critique/reference/personas.md +++ b/.trae/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 | diff --git a/source/skills/audit/SKILL.md b/source/skills/audit/SKILL.md index 519c29e9d..2cbf118ff 100644 --- a/source/skills/audit/SKILL.md +++ b/source/skills/audit/SKILL.md @@ -1,17 +1,23 @@ --- name: audit -description: "Perform a comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates a scored report with severity ratings and actionable plan. 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...)]" user-invocable: true --- -Run systematic quality checks and generate a comprehensive audit report with quantitative scoring, prioritized issues, and an actionable plan. Don't fix issues — document them for other commands to address. +## MANDATORY PREPARATION -**First**: Invoke {{command_prefix}}frontend-design for design principles and anti-patterns. +Invoke {{command_prefix}}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 {{command_prefix}}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 5 dimensions. Score each dimension 0–4 using the criteria below. +Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below. ### 1. Accessibility (A11y) @@ -23,7 +29,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Alt text**: Missing or poor image descriptions - **Form issues**: Inputs without labels, poor error messaging, missing required indicators -**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) +**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) ### 2. Performance @@ -34,7 +40,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization -**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) +**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) ### 3. Theming @@ -44,7 +50,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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 @@ -55,113 +61,73 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0–4 using t - **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) +**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) +**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) -**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands to fix issues after audit. - -## Generate Comprehensive Report +## Generate Report ### Audit Health Score -Present the dimension scores as a table: - | # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| -| 1 | Accessibility | ? | [most critical a11y issue or "—"] | +| 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** | -**Rating bands**: -| Score | Rating | Action | -|-------|--------|--------| -| 18–20 | Excellent | Minor polish only | -| 14–17 | Good | Address weak dimensions | -| 10–13 | Acceptable | Significant work needed | -| 6–9 | Poor | Major quality overhaul | -| 0–5 | Critical | Fundamental issues across the board | +**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 - Audit Health Score: **??/20** ([rating band]) - Total issues found (count by severity: P0/P1/P2/P3) -- Most critical issues (top 3-5) +- Top 3-5 critical issues - Recommended next steps ### Detailed Findings by Severity -Tag every issue with **P0–P3 severity**: -| Priority | Name | Description | -|----------|------|-------------| -| **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 | +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: - **[P?] Issue name** -- **Location**: Where it occurs (component, file, line) +- **Location**: Component, file, line - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern -- **Description**: What the issue is - **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: {{available_commands}} — or other installed skills you're sure exist) - -#### P0 — Blocking Issues -[Issues that prevent task completion or violate WCAG A] - -#### P1 — Major Issues -[Significant usability/accessibility impact, WCAG AA violations] - -#### P2 — Minor Issues -[Quality issues, WCAG AAA violations, performance concerns] - -#### P3 — Polish Issues -[Minor inconsistencies, optimization opportunities] +- **Suggested command**: Which command to use (prefer: {{available_commands}}) ### 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. ## Recommended Actions -Present a prioritized action summary. Order is determined by severity automatically (P0 first, then P1, then P2). - -### Action Summary - -List recommended commands in priority order: +List recommended commands in priority order (P0 first, then P1, then P2): 1. **[P?] `{{command_prefix}}command-name`** — Brief description (specific context from audit findings) 2. **[P?] `{{command_prefix}}command-name`** — Brief description (specific context) -... -**Rules for recommendations**: -- Only recommend commands from: {{available_commands}} -- Order by severity: P0 issues first, then P1, then P2 (skip P3 unless user has few issues) -- Each item's description should carry enough context that the command knows what to focus on -- Map findings to the most appropriate command -- Skip commands that would address zero issues -- End with `{{command_prefix}}polish` as the final step if any fixes were recommended +**Rules**: Only recommend commands from: {{available_commands}}. Map findings to the most appropriate command. End with `{{command_prefix}}polish` as the final step if any fixes were recommended. After presenting the summary, tell the user: @@ -173,10 +139,9 @@ After presenting the summary, tell the user: **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) +- 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. +Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. diff --git a/source/skills/critique/SKILL.md b/source/skills/critique/SKILL.md index dbcfdfda2..f8ae5c428 100644 --- a/source/skills/critique/SKILL.md +++ b/source/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, cognitive load, and overall design 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, 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...)]" user-invocable: true --- @@ -11,7 +11,7 @@ Invoke {{command_prefix}}frontend-design — it contains design principles, anti --- -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. ## Phase 1: Design Critique @@ -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,20 +31,19 @@ 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 -→ *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and checklist* +### 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? 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? -- **Cognitive load sub-check**: Run the 8-item cognitive load checklist from the reference. Report the number of failures. +- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. ### 4. Emotional Journey -→ *Consult [cognitive-load](reference/cognitive-load.md) for emotional intervention patterns* - 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) @@ -72,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"? @@ -86,27 +85,19 @@ 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? -### 11. Cognitive Load -→ *Consult [cognitive-load](reference/cognitive-load.md)* -- **Intrinsic vs. extraneous**: Is the mental effort coming from the task itself (acceptable) or from poor design choices (eliminate)? -- **Decision points**: Count visible choices at key moments. More than 4 simultaneous options = overload. -- **Working memory burden**: Does the user need to remember information from a previous screen to act on the current one? -- **Information chunking**: Is content broken into digestible groups, or presented as undifferentiated walls? -- Run the 8-item cognitive load checklist. Report failures count: 0–1 = low (good), 2–3 = moderate, 4+ = critical. - ## Phase 2: Present Findings Structure your feedback as a design director would: ### Design Health Score -→ *Consult [heuristics-scoring](reference/heuristics-scoring.md)* +> *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 | ? | | +| 2 | Match System / Real World | ? | | | 3 | User Control and Freedom | ? | | | 4 | Consistency and Standards | ? | | | 5 | Error Prevention | ? | | @@ -123,13 +114,13 @@ Be honest with scores. A 4 means genuinely excellent. Most real interfaces score **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, tag with **P0–P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): - **[P?] What**: Name the problem clearly @@ -138,7 +129,7 @@ For each issue, tag with **P0–P3 severity** (consult [heuristics-scoring](refe - **Suggested command**: Which command could address this (from: {{available_commands}}) ### Persona Red Flags -→ *Consult [personas](reference/personas.md)* +> *Consult [personas](reference/personas.md)* Auto-select 2–3 personas most relevant to this interface type (use the selection table in the reference). If `{{config_file}}` contains a `## Design Context` section from `teach-impeccable`, also generate 1–2 project-specific personas from the audience/brand info. @@ -154,12 +145,12 @@ Be specific — name the exact elements and interactions that fail each persona. Quick notes on smaller issues worth addressing. **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 +- 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 @@ -167,9 +158,9 @@ Quick notes on smaller issues worth addressing. 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. +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. +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". @@ -177,9 +168,9 @@ Ask questions along these lines (adapt to the specific findings — do NOT ask g **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 +- 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 +- If findings are straightforward (e.g., only 1–2 clear issues), skip questions and go directly to Phase 4 ## Phase 4: Recommended Actions diff --git a/source/skills/critique/reference/personas.md b/source/skills/critique/reference/personas.md index 6f85892f5..0163c265d 100644 --- a/source/skills/critique/reference/personas.md +++ b/source/skills/critique/reference/personas.md @@ -88,30 +88,30 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona --- -## 4. Skeptical Evaluator — "Riley" +## 4. Deliberate Stress Tester — "Riley" -**Profile**: Evaluating the product for their team or company. Looking for reasons to reject. Comparing against competitors. +**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) -- Looks for pricing catches and hidden limitations -- Reads fine print and terms of service -- Tries to break things deliberately +- 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)? -- Is pricing and value proposition transparent? -- Are there hidden limitations or gotchas? -- How polished is error handling? -- What data is collected and why? +- 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): -- Hidden pricing or "contact sales" for basic information -- Features that appear to work but produce broken results -- Poor error handling that exposes technical details -- Unclear data practices or missing privacy information +- 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 --- @@ -150,7 +150,7 @@ Choose personas based on the interface type: |---------------|-----------------|-----| | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | | Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, trust, clarity | +| 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 |