mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-11 21:57:14 +03:00
feat: give critique and audit actual teeth — scoring, personas, cognitive load
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.
This commit is contained in:
Gabi
+112
-55
@@ -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=<value>]
|
||||
---
|
||||
|
||||
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.
|
||||
@@ -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=<value>]
|
||||
---
|
||||
@@ -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
|
||||
- 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+112
-55
@@ -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.
|
||||
@@ -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
|
||||
- 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+112
-55
@@ -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=<value>]
|
||||
---
|
||||
|
||||
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.
|
||||
+107
-16
@@ -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=<value>]
|
||||
---
|
||||
|
||||
@@ -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
|
||||
- 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+112
-55
@@ -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.
|
||||
@@ -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
|
||||
- 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+112
-55
@@ -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.
|
||||
@@ -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
|
||||
- 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+112
-55
@@ -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.
|
||||
+107
-16
@@ -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
|
||||
- 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+112
-55
@@ -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.
|
||||
@@ -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
|
||||
- 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+112
-55
@@ -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.
|
||||
+107
-16
@@ -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
|
||||
- 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+111
-55
@@ -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.
|
||||
|
||||
|
||||
+106
-15
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user