maestro-flow 0.5.36 → 0.5.37

package/.claude/skills/team-ux-improve/roles/tester/role.md

@@ -1,84 +1,84 @@
----
-role: tester
-prefix: TEST
-inner_loop: false
-message_types: [state_update]
----
-
-# Test Engineer
-
-Generate and run tests to verify fixes (loading states, error handling, state updates).
-
-## Phase 2: Environment Detection
-
-1. Detect test framework from project files:
-
-| Signal | Framework |
-|--------|-----------|
-| package.json has "jest" | Jest |
-| package.json has "vitest" | Vitest |
-| package.json has "@testing-library/react" | React Testing Library |
-| package.json has "@vue/test-utils" | Vue Test Utils |
-
-2. Get changed files from implementer state:
-   ```
-   team_msg(operation="get_state", session_id=<session-id>, role="implementer")
-   ```
-
-3. Load test strategy from design guide
-
-### Wisdom Input
-
-1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common issues to test
-2. Read `<session>/wisdom/patterns/ui-feedback.md` for expected feedback behaviors to verify
-3. Use wisdom to design comprehensive test cases covering known edge cases
-
-## Phase 3: Test Generation & Execution
-
-### Test Generation
-
-For each modified file, generate test cases covering loading states, error handling, state updates, and accessibility.
-
-### Test Execution
-
-Iterative test-fix cycle (max 5 iterations):
-
-1. Run tests: `npm test` or `npm run test:unit`
-2. Parse results -> calculate pass rate
-3. If pass rate >= 95% -> exit (success)
-4. If pass rate < 95% and iterations < 5:
-   - Analyze failures
-   - Use CLI to generate fixes:
-     ```
-     Bash(`maestro delegate "PURPOSE: Fix test failures
-     CONTEXT: @<test-file> @<source-file>
-     EXPECTED: Fixed code that passes tests
-     CONSTRAINTS: Maintain existing functionality" --tool gemini --mode write`)
-     ```
-   - Increment iteration counter
-   - Loop to step 1
-5. If iterations >= 5 -> send fix_required message
-
-## Phase 4: Test Report
-
-### Wisdom Contribution
-
-If new edge cases or test patterns discovered:
-1. Write test findings to `<session>/wisdom/contributions/tester-edge-cases-<timestamp>.md`
-2. Format: Edge case description, test scenario, expected behavior, actual behavior
-
-Write report to `<session>/artifacts/test-report.md`.
-
-Share state via team_msg:
-```
-team_msg(operation="log", session_id=<session-id>, from="tester",
-         type="state_update", data={
-           total_tests: <count>,
-           passed: <count>,
-           failed: <count>,
-           pass_rate: <percentage>,
-           fix_iterations: <count>
-         })
-```
-
-If pass rate < 95%, send fix_required message to coordinator.
+---
+role: tester
+prefix: TEST
+inner_loop: false
+message_types: [state_update]
+---
+
+# Test Engineer
+
+Generate and run tests to verify fixes (loading states, error handling, state updates).
+
+## Phase 2: Environment Detection
+
+1. Detect test framework from project files:
+
+| Signal | Framework |
+|--------|-----------|
+| package.json has "jest" | Jest |
+| package.json has "vitest" | Vitest |
+| package.json has "@testing-library/react" | React Testing Library |
+| package.json has "@vue/test-utils" | Vue Test Utils |
+
+2. Get changed files from implementer state:
+   ```
+   team_msg(operation="get_state", session_id=<session-id>, role="implementer")
+   ```
+
+3. Load test strategy from design guide
+
+### Wisdom Input
+
+1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common issues to test
+2. Read `<session>/wisdom/patterns/ui-feedback.md` for expected feedback behaviors to verify
+3. Use wisdom to design comprehensive test cases covering known edge cases
+
+## Phase 3: Test Generation & Execution
+
+### Test Generation
+
+For each modified file, generate test cases covering loading states, error handling, state updates, and accessibility.
+
+### Test Execution
+
+Iterative test-fix cycle (max 5 iterations):
+
+1. Run tests: `npm test` or `npm run test:unit`
+2. Parse results -> calculate pass rate
+3. If pass rate >= 95% -> exit (success)
+4. If pass rate < 95% and iterations < 5:
+   - Analyze failures
+   - Use CLI to generate fixes:
+     ```
+     Bash(`maestro delegate "PURPOSE: Fix test failures
+     CONTEXT: @<test-file> @<source-file>
+     EXPECTED: Fixed code that passes tests
+     CONSTRAINTS: Maintain existing functionality" --tool agy --mode write`)
+     ```
+   - Increment iteration counter
+   - Loop to step 1
+5. If iterations >= 5 -> send fix_required message
+
+## Phase 4: Test Report
+
+### Wisdom Contribution
+
+If new edge cases or test patterns discovered:
+1. Write test findings to `<session>/wisdom/contributions/tester-edge-cases-<timestamp>.md`
+2. Format: Edge case description, test scenario, expected behavior, actual behavior
+
+Write report to `<session>/artifacts/test-report.md`.
+
+Share state via team_msg:
+```
+team_msg(operation="log", session_id=<session-id>, from="tester",
+         type="state_update", data={
+           total_tests: <count>,
+           passed: <count>,
+           failed: <count>,
+           pass_rate: <percentage>,
+           fix_iterations: <count>
+         })
+```
+
+If pass rate < 95%, send fix_required message to coordinator.

package/.claude/skills/team-ux-improve/specs/anti-patterns.md

@@ -1,103 +1,103 @@
-# AI Slop Detection Catalog
-
-20 visual anti-patterns commonly produced by AI code generation. Use during scanning to flag design quality issues.
-
-### 1. AI Color Palette
-- **Pattern**: Cyan (#00d4ff, #06b6d4), purple-blue gradients on dark backgrounds as default aesthetic
-- **Detection**: Search for cyan/teal hex values, linear-gradient with blue-purple stops on dark bg
-- **Severity**: P1
-
-### 2. Gradient Text
-- **Pattern**: `background-clip: text` + `-webkit-text-fill-color: transparent` on headings or metric values
-- **Detection**: Grep for `background-clip:\s*text` or `-webkit-background-clip:\s*text`
-- **Severity**: P1
-
-### 3. Default Dark Mode + Glow
-- **Pattern**: Dark background (#0a0a0a, #111) with neon accent colors and box-shadow glow effects
-- **Detection**: Dark bg colors + box-shadow with colored spread on interactive elements
-- **Severity**: P2
-
-### 4. Glassmorphism Everywhere
-- **Pattern**: `backdrop-filter: blur()` applied to more than 2 components
-- **Detection**: Count occurrences of `backdrop-filter:\s*blur` across components
-- **Severity**: P1
-
-### 5. Hero Metric Layout
-- **Pattern**: Large number + small label arranged in card grid, dashboard-style metrics as default layout
-- **Detection**: Pattern of large font-size number + small text label repeated 3+ times in grid
-- **Severity**: P2
-
-### 6. Identical Card Grids
-- **Pattern**: 3+ cards with identical size, structure, and visual weight
-- **Detection**: Repeated card components with same dimensions and no visual differentiation
-- **Severity**: P2
-
-### 7. Nested Cards
-- **Pattern**: Border/shadow container inside another border/shadow container
-- **Detection**: Card component rendered inside another card component, nested border-radius + box-shadow
-- **Severity**: P2
-
-### 8. Generic Fonts
-- **Pattern**: Inter, Roboto, Open Sans, Lato, Montserrat, Arial as primary font-family
-- **Detection**: Grep font-family declarations for generic font names
-- **Severity**: P2
-
-### 9. Rounded Rect + Generic Shadow
-- **Pattern**: `border-radius: 8-16px` + `box-shadow: 0 1-4px ...` on more than 5 elements
-- **Detection**: Count elements with both border-radius and box-shadow, flag if >5
-- **Severity**: P3
-
-### 10. Large Icons Above Every Heading
-- **Pattern**: Decorative icon/emoji placed above section headings, repeated 3+ times
-- **Detection**: Icon component or SVG immediately preceding heading elements, 3+ occurrences
-- **Severity**: P2
-
-### 11. One-Side Border Accent
-- **Pattern**: `border-left: 3-4px solid <accent>` as visual accent on cards/sections
-- **Detection**: Grep for `border-left:\s*\d+px\s+solid` repeated across components
-- **Severity**: P3
-
-### 12. Decorative Sparklines
-- **Pattern**: Tiny inline charts without axis labels, data values, or interactive tooltips
-- **Detection**: Small chart components (<100px height) without label/tooltip props
-- **Severity**: P2
-
-### 13. Bounce/Elastic Easing
-- **Pattern**: `cubic-bezier` with negative control point values, spring/bounce animation keywords
-- **Detection**: Grep for `cubic-bezier\([^)]*-` or animation names containing bounce/spring/elastic
-- **Severity**: P2
-
-### 14. Redundant Copy
-- **Pattern**: Heading text restated in immediately following body paragraph with >50% word overlap
-- **Detection**: Compare heading text with first paragraph text for word overlap
-- **Severity**: P3
-
-### 15. All Buttons Primary
-- **Pattern**: Every button uses same filled/accent treatment, no visual hierarchy
-- **Detection**: All button variants resolve to same background-color, no secondary/tertiary variants
-- **Severity**: P1
-
-### 16. Everything Centered
-- **Pattern**: Body text centered (`text-align: center`), more than 60% of sections centered
-- **Detection**: Count `text-align: center` on non-heading, non-hero elements
-- **Severity**: P2
-
-### 17. Same Spacing Everywhere
-- **Pattern**: >70% of padding/margin values are identical (e.g., all `p-4` or `p-6`)
-- **Detection**: Extract padding/margin values, check distribution uniformity
-- **Severity**: P2
-
-### 18. Monospace as Tech Aesthetic
-- **Pattern**: Monospace font applied to non-code elements (headings, labels, navigation)
-- **Detection**: `font-family: monospace` or code font on non-`<code>`/`<pre>` elements
-- **Severity**: P3
-
-### 19. Modal Overuse
-- **Pattern**: More than 3 modal dialogs for non-critical interactions (settings, confirmations, info)
-- **Detection**: Count modal/dialog component usages, check trigger context
-- **Severity**: P3
-
-### 20. Pure Black/White
-- **Pattern**: #000, #fff, rgb(0,0,0), rgb(255,255,255) as primary background or text colors
-- **Detection**: Grep for exact #000, #fff, rgb(0,0,0), rgb(255,255,255) in color/background properties
-- **Severity**: P1
+# AI Slop Detection Catalog
+
+20 visual anti-patterns commonly produced by AI code generation. Use during scanning to flag design quality issues.
+
+### 1. AI Color Palette
+- **Pattern**: Cyan (#00d4ff, #06b6d4), purple-blue gradients on dark backgrounds as default aesthetic
+- **Detection**: Search for cyan/teal hex values, linear-gradient with blue-purple stops on dark bg
+- **Severity**: P1
+
+### 2. Gradient Text
+- **Pattern**: `background-clip: text` + `-webkit-text-fill-color: transparent` on headings or metric values
+- **Detection**: Grep for `background-clip:\s*text` or `-webkit-background-clip:\s*text`
+- **Severity**: P1
+
+### 3. Default Dark Mode + Glow
+- **Pattern**: Dark background (#0a0a0a, #111) with neon accent colors and box-shadow glow effects
+- **Detection**: Dark bg colors + box-shadow with colored spread on interactive elements
+- **Severity**: P2
+
+### 4. Glassmorphism Everywhere
+- **Pattern**: `backdrop-filter: blur()` applied to more than 2 components
+- **Detection**: Count occurrences of `backdrop-filter:\s*blur` across components
+- **Severity**: P1
+
+### 5. Hero Metric Layout
+- **Pattern**: Large number + small label arranged in card grid, dashboard-style metrics as default layout
+- **Detection**: Pattern of large font-size number + small text label repeated 3+ times in grid
+- **Severity**: P2
+
+### 6. Identical Card Grids
+- **Pattern**: 3+ cards with identical size, structure, and visual weight
+- **Detection**: Repeated card components with same dimensions and no visual differentiation
+- **Severity**: P2
+
+### 7. Nested Cards
+- **Pattern**: Border/shadow container inside another border/shadow container
+- **Detection**: Card component rendered inside another card component, nested border-radius + box-shadow
+- **Severity**: P2
+
+### 8. Generic Fonts
+- **Pattern**: Inter, Roboto, Open Sans, Lato, Montserrat, Arial as primary font-family
+- **Detection**: Grep font-family declarations for generic font names
+- **Severity**: P2
+
+### 9. Rounded Rect + Generic Shadow
+- **Pattern**: `border-radius: 8-16px` + `box-shadow: 0 1-4px ...` on more than 5 elements
+- **Detection**: Count elements with both border-radius and box-shadow, flag if >5
+- **Severity**: P3
+
+### 10. Large Icons Above Every Heading
+- **Pattern**: Decorative icon/emoji placed above section headings, repeated 3+ times
+- **Detection**: Icon component or SVG immediately preceding heading elements, 3+ occurrences
+- **Severity**: P2
+
+### 11. One-Side Border Accent
+- **Pattern**: `border-left: 3-4px solid <accent>` as visual accent on cards/sections
+- **Detection**: Grep for `border-left:\s*\d+px\s+solid` repeated across components
+- **Severity**: P3
+
+### 12. Decorative Sparklines
+- **Pattern**: Tiny inline charts without axis labels, data values, or interactive tooltips
+- **Detection**: Small chart components (<100px height) without label/tooltip props
+- **Severity**: P2
+
+### 13. Bounce/Elastic Easing
+- **Pattern**: `cubic-bezier` with negative control point values, spring/bounce animation keywords
+- **Detection**: Grep for `cubic-bezier\([^)]*-` or animation names containing bounce/spring/elastic
+- **Severity**: P2
+
+### 14. Redundant Copy
+- **Pattern**: Heading text restated in immediately following body paragraph with >50% word overlap
+- **Detection**: Compare heading text with first paragraph text for word overlap
+- **Severity**: P3
+
+### 15. All Buttons Primary
+- **Pattern**: Every button uses same filled/accent treatment, no visual hierarchy
+- **Detection**: All button variants resolve to same background-color, no secondary/tertiary variants
+- **Severity**: P1
+
+### 16. Everything Centered
+- **Pattern**: Body text centered (`text-align: center`), more than 60% of sections centered
+- **Detection**: Count `text-align: center` on non-heading, non-hero elements
+- **Severity**: P2
+
+### 17. Same Spacing Everywhere
+- **Pattern**: >70% of padding/margin values are identical (e.g., all `p-4` or `p-6`)
+- **Detection**: Extract padding/margin values, check distribution uniformity
+- **Severity**: P2
+
+### 18. Monospace as Tech Aesthetic
+- **Pattern**: Monospace font applied to non-code elements (headings, labels, navigation)
+- **Detection**: `font-family: monospace` or code font on non-`<code>`/`<pre>` elements
+- **Severity**: P3
+
+### 19. Modal Overuse
+- **Pattern**: More than 3 modal dialogs for non-critical interactions (settings, confirmations, info)
+- **Detection**: Count modal/dialog component usages, check trigger context
+- **Severity**: P3
+
+### 20. Pure Black/White
+- **Pattern**: #000, #fff, rgb(0,0,0), rgb(255,255,255) as primary background or text colors
+- **Detection**: Grep for exact #000, #fff, rgb(0,0,0), rgb(255,255,255) in color/background properties
+- **Severity**: P1

package/.claude/skills/team-ux-improve/specs/design-standards.md

@@ -1,54 +1,54 @@
-# Visual Design Standards
-
-Reference for visual design quality detection. Scanner and diagnoser use these standards to identify design issues.
-
-## Color Standards
-
-- **OKLCH** for perceptually uniform palettes
-- **Tinted neutrals**: chroma 0.005-0.01, never pure gray (#808080) or pure black/white (#000, #fff)
-- **60-30-10 rule**: 60% neutral, 30% secondary, 10% accent
-- **WCAG AA contrast**: normal text 4.5:1, large text 3:1, UI components 3:1
-- **Text on colored backgrounds**: use `color-mix(in oklch, ...)` not gray text
-
-## Typography Standards
-
-- **Avoid generic fonts**: Inter, Roboto, Open Sans, Lato, Montserrat, Arial
-- **Modular scale** (choose one ratio consistently): 1.125, 1.200, 1.250, 1.333
-- **Fluid sizing**: `clamp()` for display text (xl and above)
-- **Line height**: body 1.5, headings 1.2, small text 1.6
-- **Reading width**: `max-width: 65ch`
-- **Font loading**: `font-display: swap`
-
-## Spacing Standards
-
-- **4pt base scale**: 0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96 px
-- **Rhythm variation**: tight (4-8px), comfortable (16-24px), generous (48-96px)
-- **Sibling spacing**: `gap` over `margin`
-- **No nested cards**. Touch targets: 44x44px min
-
-## Motion Standards
-
-- **Animate ONLY**: transform, opacity, clip-path, background-color, color, box-shadow, filter
-- **NEVER animate**: width, height, top, left, margin, padding
-- **Easing**: ease-out-quart `cubic-bezier(0.25, 1, 0.5, 1)` default. No bounce/elastic/linear
-- **Duration**: instant 100ms, fast 150ms, normal 250ms, slow 400ms
-- **Reduced motion**: `@media (prefers-reduced-motion: reduce)` REQUIRED
-
-## 8 Interaction States
-
-| State | CSS | Requirement |
-|-------|-----|-------------|
-| Default | -- | Base appearance |
-| Hover | `:hover` in `@media(hover:hover)` | Subtle change |
-| Focus | `:focus-visible` | 2px solid accent, offset 2px, 3:1 contrast |
-| Active | `:active` | Scale(0.97) or darker |
-| Disabled | `[disabled]` | Opacity 0.5 |
-| Loading | `[aria-busy]` | Spinner/skeleton |
-| Error | `[aria-invalid]` | Red border + message |
-| Success | custom | Green check |
-
-## Visual Hierarchy
-
-- **Squint test**: blur page, identify top 2 elements + groupings
-- **1 primary CTA** per viewport
-- **Progressive disclosure**: reveal complexity on demand
+# Visual Design Standards
+
+Reference for visual design quality detection. Scanner and diagnoser use these standards to identify design issues.
+
+## Color Standards
+
+- **OKLCH** for perceptually uniform palettes
+- **Tinted neutrals**: chroma 0.005-0.01, never pure gray (#808080) or pure black/white (#000, #fff)
+- **60-30-10 rule**: 60% neutral, 30% secondary, 10% accent
+- **WCAG AA contrast**: normal text 4.5:1, large text 3:1, UI components 3:1
+- **Text on colored backgrounds**: use `color-mix(in oklch, ...)` not gray text
+
+## Typography Standards
+
+- **Avoid generic fonts**: Inter, Roboto, Open Sans, Lato, Montserrat, Arial
+- **Modular scale** (choose one ratio consistently): 1.125, 1.200, 1.250, 1.333
+- **Fluid sizing**: `clamp()` for display text (xl and above)
+- **Line height**: body 1.5, headings 1.2, small text 1.6
+- **Reading width**: `max-width: 65ch`
+- **Font loading**: `font-display: swap`
+
+## Spacing Standards
+
+- **4pt base scale**: 0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96 px
+- **Rhythm variation**: tight (4-8px), comfortable (16-24px), generous (48-96px)
+- **Sibling spacing**: `gap` over `margin`
+- **No nested cards**. Touch targets: 44x44px min
+
+## Motion Standards
+
+- **Animate ONLY**: transform, opacity, clip-path, background-color, color, box-shadow, filter
+- **NEVER animate**: width, height, top, left, margin, padding
+- **Easing**: ease-out-quart `cubic-bezier(0.25, 1, 0.5, 1)` default. No bounce/elastic/linear
+- **Duration**: instant 100ms, fast 150ms, normal 250ms, slow 400ms
+- **Reduced motion**: `@media (prefers-reduced-motion: reduce)` REQUIRED
+
+## 8 Interaction States
+
+| State | CSS | Requirement |
+|-------|-----|-------------|
+| Default | -- | Base appearance |
+| Hover | `:hover` in `@media(hover:hover)` | Subtle change |
+| Focus | `:focus-visible` | 2px solid accent, offset 2px, 3:1 contrast |
+| Active | `:active` | Scale(0.97) or darker |
+| Disabled | `[disabled]` | Opacity 0.5 |
+| Loading | `[aria-busy]` | Spinner/skeleton |
+| Error | `[aria-invalid]` | Red border + message |
+| Success | custom | Green check |
+
+## Visual Hierarchy
+
+- **Squint test**: blur page, identify top 2 elements + groupings
+- **1 primary CTA** per viewport
+- **Progressive disclosure**: reveal complexity on demand

package/.claude/skills/team-ux-improve/specs/heuristics.md

@@ -1,88 +1,88 @@
-# Nielsen's 10 Usability Heuristics
-
-Structured evaluation framework for UX scanning. Score each 0-4.
-
-## 1. Visibility of System Status
-The system should always keep users informed about what is going on.
-- Loading indicators for async operations (> 200ms)
-- Progress bars for multi-step processes
-- State feedback (saved, syncing, error)
-- Timestamps on data ("Updated 5 minutes ago")
-- Active state indicators (selected tab, current page)
-
-## 2. Match Between System and Real World
-Speak the user's language, not technical jargon.
-- Labels use familiar words (not internal terms)
-- Icons match real-world metaphors
-- Information appears in natural/logical order
-- Dates, numbers, currencies in locale format
-
-## 3. User Control and Freedom
-Users need a clearly marked "emergency exit."
-- Undo/redo for destructive or complex actions
-- Back/cancel navigation always available
-- Escape key closes modals/popovers
-- Clear way to deselect, clear filters, reset
-
-## 4. Consistency and Standards
-Same words and actions should mean the same thing.
-- One term per concept (delete/remove/trash → pick one)
-- Same icon for same action across pages
-- Follow platform conventions (links underlined, × means close)
-- Consistent placement of actions (save always top-right, etc.)
-
-## 5. Error Prevention
-Better to prevent errors than show good error messages.
-- Confirmation for destructive actions (with undo preferred)
-- Input validation on blur (not just submit)
-- Disable invalid options (gray out, not hide)
-- Type-ahead/autocomplete for known-value fields
-- Character counts for limited fields
-
-## 6. Recognition Rather Than Recall
-Minimize user memory load.
-- Show options visibly (don't require memorization)
-- Recent items, favorites, search suggestions
-- Breadcrumbs for navigation context
-- Inline help/tooltips for non-obvious fields
-- Persistent important info (don't hide behind clicks)
-
-## 7. Flexibility and Efficiency of Use
-Accelerators for power users without confusing beginners.
-- Keyboard shortcuts for frequent actions
-- Bulk actions (select all, batch edit)
-- Customizable views/layouts
-- Search/filter as primary navigation for large datasets
-
-## 8. Aesthetic and Minimalist Design
-Every extra unit of information competes with relevant units.
-- Remove decorative elements that don't aid comprehension
-- Progressive disclosure (summary → detail on demand)
-- Visual hierarchy: clear primary, secondary, tertiary
-- Information density appropriate for use case
-
-## 9. Help Users Recognize, Diagnose, and Recover from Errors
-Error messages should be expressed in plain language.
-- Formula: what happened + why + how to fix
-- No error codes without explanation
-- Suggest specific corrective action
-- Preserve user input on error (don't clear forms)
-- Retry option for network/server errors
-
-## 10. Help and Documentation
-Easy to search, focused on user's task.
-- Contextual help (tooltips, info icons)
-- Onboarding for first-time users
-- Empty states with guidance and action
-- Keyboard shortcut reference
-- FAQ/search for complex features
-
-## Severity Scale
-
-| Rating | Description |
-|--------|-------------|
-| 0 | Not a usability problem |
-| 1 | Cosmetic — fix if time permits |
-| 2 | Minor — low priority fix |
-| 3 | Major — important to fix, high priority |
-| 4 | Catastrophe — must fix before release |
+# Nielsen's 10 Usability Heuristics
+
+Structured evaluation framework for UX scanning. Score each 0-4.
+
+## 1. Visibility of System Status
+The system should always keep users informed about what is going on.
+- Loading indicators for async operations (> 200ms)
+- Progress bars for multi-step processes
+- State feedback (saved, syncing, error)
+- Timestamps on data ("Updated 5 minutes ago")
+- Active state indicators (selected tab, current page)
+
+## 2. Match Between System and Real World
+Speak the user's language, not technical jargon.
+- Labels use familiar words (not internal terms)
+- Icons match real-world metaphors
+- Information appears in natural/logical order
+- Dates, numbers, currencies in locale format
+
+## 3. User Control and Freedom
+Users need a clearly marked "emergency exit."
+- Undo/redo for destructive or complex actions
+- Back/cancel navigation always available
+- Escape key closes modals/popovers
+- Clear way to deselect, clear filters, reset
+
+## 4. Consistency and Standards
+Same words and actions should mean the same thing.
+- One term per concept (delete/remove/trash → pick one)
+- Same icon for same action across pages
+- Follow platform conventions (links underlined, × means close)
+- Consistent placement of actions (save always top-right, etc.)
+
+## 5. Error Prevention
+Better to prevent errors than show good error messages.
+- Confirmation for destructive actions (with undo preferred)
+- Input validation on blur (not just submit)
+- Disable invalid options (gray out, not hide)
+- Type-ahead/autocomplete for known-value fields
+- Character counts for limited fields
+
+## 6. Recognition Rather Than Recall
+Minimize user memory load.
+- Show options visibly (don't require memorization)
+- Recent items, favorites, search suggestions
+- Breadcrumbs for navigation context
+- Inline help/tooltips for non-obvious fields
+- Persistent important info (don't hide behind clicks)
+
+## 7. Flexibility and Efficiency of Use
+Accelerators for power users without confusing beginners.
+- Keyboard shortcuts for frequent actions
+- Bulk actions (select all, batch edit)
+- Customizable views/layouts
+- Search/filter as primary navigation for large datasets
+
+## 8. Aesthetic and Minimalist Design
+Every extra unit of information competes with relevant units.
+- Remove decorative elements that don't aid comprehension
+- Progressive disclosure (summary → detail on demand)
+- Visual hierarchy: clear primary, secondary, tertiary
+- Information density appropriate for use case
+
+## 9. Help Users Recognize, Diagnose, and Recover from Errors
+Error messages should be expressed in plain language.
+- Formula: what happened + why + how to fix
+- No error codes without explanation
+- Suggest specific corrective action
+- Preserve user input on error (don't clear forms)
+- Retry option for network/server errors
+
+## 10. Help and Documentation
+Easy to search, focused on user's task.
+- Contextual help (tooltips, info icons)
+- Onboarding for first-time users
+- Empty states with guidance and action
+- Keyboard shortcut reference
+- FAQ/search for complex features
+
+## Severity Scale
+
+| Rating | Description |
+|--------|-------------|
+| 0 | Not a usability problem |
+| 1 | Cosmetic — fix if time permits |
+| 2 | Minor — low priority fix |
+| 3 | Major — important to fix, high priority |
+| 4 | Catastrophe — must fix before release |