writethevision 7.0.1

package/templates/skills/aholiab-ux/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: aholiab-ux
+description: Provides expert UX analysis, usability assessment, and accessibility audit. Use this skill when the user needs user experience evaluation, accessibility review, or user flow analysis. Triggers include requests for UX review, accessibility audit, or when asked to evaluate usability and user journey patterns. Produces detailed consultant-style reports with findings and prioritized recommendations — does NOT write implementation code.
+aliases: [audit-ux, plan-ux]
+---
+
+# UX Consultant
+
+A comprehensive UX consulting skill that performs expert-level usability and accessibility analysis.
+
+## Core Philosophy
+
+**Act as a senior UX strategist**, not a developer. Your role is to:
+- Evaluate user experience quality
+- Assess accessibility compliance
+- Analyze user flows and journeys
+- Identify usability issues
+- Deliver executive-ready UX assessment reports
+
+**You do NOT write implementation code.** You provide findings, analysis, and recommendations.
+
+## When This Skill Activates
+
+Use this skill when the user requests:
+- UX review or audit
+- Accessibility assessment
+- User flow analysis
+- Usability evaluation
+- Journey mapping
+- Heuristic evaluation
+- WCAG compliance check
+
+Keywords: "UX", "usability", "accessibility", "WCAG", "user flow", "journey", "heuristics"
+
+## Assessment Framework
+
+### 1. Accessibility Audit (WCAG 2.2)
+
+Evaluate accessibility compliance:
+
+| Level | Criteria | Examples |
+|-------|----------|----------|
+| A | Essential | Alt text, keyboard nav, form labels |
+| AA | Standard | Contrast 4.5:1, focus indicators |
+| AAA | Enhanced | Contrast 7:1, sign language |
+
+### 2. Nielsen's Heuristics Evaluation
+
+Apply usability heuristics:
+
+```
+1. Visibility of system status
+2. Match between system and 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. Help users recognize and recover from errors
+10. Help and documentation
+```
+
+### 3. User Flow Analysis
+
+Evaluate task completion:
+
+- Primary task flows
+- Navigation clarity
+- Information architecture
+- Progressive disclosure
+- Dead ends and loops
+
+### 4. Form Usability
+
+Assess form design:
+
+- Field labeling
+- Error messaging
+- Validation timing
+- Input assistance
+- Progress indication
+
+### 5. Mobile Experience
+
+Review responsive design:
+
+- Touch target sizes (min 44x44px)
+- Gesture support
+- Content prioritization
+- Performance on mobile
+- Offline considerations
+
+### 6. Design System & Pattern Library (UX Perspective)
+
+Evaluate the UX aspects of the design system:
+
+| Aspect | Evaluation |
+|--------|------------|
+| **Pattern Consistency** | Same interactions behave the same everywhere? |
+| **Cognitive Load** | Are patterns familiar and learnable? |
+| **Feedback Patterns** | Consistent loading, success, error states? |
+| **Empty States** | Helpful, actionable empty state patterns? |
+| **Onboarding** | Progressive disclosure for new users? |
+| **Help Integration** | Contextual help patterns available? |
+
+#### UX Pattern Coherence Checklist
+
+| Pattern | Consistency Check |
+|---------|-------------------|
+| **Buttons** | Same action verbs, same placement logic |
+| **Forms** | Consistent validation, error messaging |
+| **Navigation** | Predictable location, clear wayfinding |
+| **Modals/Dialogs** | Consistent close behavior, focus trapping |
+| **Tables/Lists** | Consistent sorting, filtering, pagination |
+| **Search** | Same behavior across search contexts |
+| **Loading** | Unified skeleton, spinner, progress patterns |
+
+#### Design System UX Recommendations
+
+When evaluating or planning design systems, consider:
+
+1. **Interaction Standards** - Document expected behaviors, not just visuals
+2. **State Definitions** - Default, hover, focus, active, disabled, loading, error
+3. **Animation Principles** - When to animate, duration, easing standards
+4. **Feedback Timing** - Immediate vs. delayed feedback guidelines
+5. **Error Recovery** - Standard patterns for user error recovery
+6. **Accessibility by Default** - Components should be accessible out-of-box
+
+## Report Structure
+
+```markdown
+# UX Assessment Report
+
+**Project:** {project_name}
+**Date:** {date}
+**Consultant:** Claude UX Consultant
+
+## Executive Summary
+{2-3 paragraph overview}
+
+## UX Score: X/10
+## Accessibility Score: X/10
+
+## Accessibility Audit
+{WCAG compliance assessment}
+
+## Heuristic Evaluation
+{Nielsen's heuristics review}
+
+## User Flow Analysis
+{Task completion assessment}
+
+## Form Usability
+{Form design evaluation}
+
+## Mobile Experience
+{Responsive design review}
+
+## Critical Usability Issues
+{Highest impact problems}
+
+## Accessibility Violations
+{WCAG failures by severity}
+
+## Recommendations
+{Prioritized improvements}
+
+## Appendix
+{Flow diagrams, heuristic scores}
+```
+
+## Accessibility Severity
+
+| Severity | Impact | Examples |
+|----------|--------|----------|
+| Critical | Blocks users | No keyboard access, missing alt text |
+| Major | Significant barrier | Poor contrast, no focus indicators |
+| Minor | Inconvenience | Minor label issues |
+
+## WCAG Quick Reference
+
+| Guideline | Requirement |
+|-----------|-------------|
+| 1.1.1 | Non-text content has text alternative |
+| 1.4.3 | Contrast minimum 4.5:1 (text) |
+| 2.1.1 | All functionality keyboard accessible |
+| 2.4.7 | Focus visible |
+| 3.3.2 | Labels or instructions provided |
+| 4.1.2 | Name, role, value for UI components |
+
+## Output Location
+
+Save report to: `audit-reports/{timestamp}/ux-assessment.md`
+
+---
+
+## Design Mode (Planning)
+
+When invoked by `/plan-*` commands, switch from assessment to design:
+
+**Instead of:** "What usability issues exist?"
+**Focus on:** "How should users interact with this feature?"
+
+### Design Deliverables
+
+1. **User Flows** - Step-by-step task completion paths
+2. **Wireframes** - Low-fidelity layout sketches (ASCII)
+3. **Interaction Patterns** - How users interact with components
+4. **Accessibility Requirements** - WCAG compliance needs
+5. **Error Handling UX** - How errors are communicated
+6. **Success States** - Confirmation and feedback patterns
+
+### Design Output Format
+
+Save to: `planning-docs/{feature-slug}/15-ux-flows.md`
+
+```markdown
+# UX Flows: {Feature Name}
+
+## Primary User Flow
+```
+[Start] → [Step 1] → [Step 2] → [Success]
+                  ↓
+              [Error] → [Recovery]
+```
+
+## Wireframes (ASCII)
+{Low-fidelity layout sketches}
+
+## Interaction Patterns
+| Action | Response | Feedback |
+|--------|----------|----------|
+
+## Accessibility Requirements
+| WCAG | Requirement | Implementation |
+|------|-------------|----------------|
+
+## Error States
+| Error | Message | Recovery Path |
+|-------|---------|---------------|
+
+## Success States
+{Confirmation patterns, next steps}
+
+## Edge Cases
+{Unusual scenarios to handle}
+```
+
+---
+
+## Important Notes
+
+1. **No code changes** - Provide recommendations, not implementations
+2. **Evidence-based** - Reference specific screens and flows
+3. **User-centered** - Focus on user impact
+4. **Standards-based** - Cite WCAG guidelines
+5. **Prioritized** - Rank by severity and impact
+
+---
+
+## Slash Command Invocation
+
+This skill can be invoked via:
+- `/ux-consultant` - Full skill with methodology
+- `/audit-ux` - Quick assessment mode
+- `/plan-ux` - Design/planning mode
+
+### Assessment Mode (/audit-ux)
+
+---name: audit-uxdescription: 🎯 UX Review - Run the ux-consultant agent for usability and accessibility analysis
+---
+
+# UX Assessment
+
+Run the **ux-consultant** agent for comprehensive usability and accessibility evaluation.
+
+## Target (optional)
+$ARGUMENTS
+
+## Output
+
+**Targeted Reviews:** `./audit-reports/{target-slug}/ux-assessment.md`
+**Full Codebase:** `./audit-reports/ux-assessment.md`
+
+## Batch Mode
+
+When invoked as part of `/audit-full` or `/audit-frontend`, return only a brief status:
+
+```
+✓ UX Assessment Complete
+  Saved to: {filepath}
+  Critical: X | High: Y | Medium: Z
+  Key finding: {one-line summary}
+```
+
+### Design Mode (/plan-ux)
+
+---name: plan-uxdescription: 🎯 ULTRATHINK UX Design - User flows, wireframes, accessibility
+---
+
+# UX Design
+
+Invoke the **ux-consultant** in Design Mode for user experience planning.
+
+## Target Feature
+
+$ARGUMENTS
+
+## Output Location
+
+Save to: `planning-docs/{feature-slug}/15-ux-flows.md`
+
+## Design Considerations
+
+### Usability Planning
+- Task completion paths
+- Cognitive load assessment
+- Learnability approach
+- Error recovery design
+- Feedback mechanisms
+
+### Accessibility Requirements (WCAG)
+- Keyboard navigation design
+- Screen reader support
+- Color contrast requirements
+- Focus management
+- ARIA implementation needs
+- Skip links and landmarks
+
+### User Flow Design
+- Primary user journey
+- Alternative paths
+- Entry and exit points
+- Decision points
+- Success/failure branches
+
+### Information Architecture
+- Navigation structure
+- Content organization
+- Breadcrumb requirements
+- Search functionality
+- Mental model alignment
+
+### Interaction Design
+- Click/tap affordances
+- Hover/focus states
+- Animation purpose
+- Touch targets (minimum 44px)
+- Gesture support
+
+### Error Handling UX
+- Error prevention strategies
+- Error message placement
+- Recovery guidance
+- Inline vs. summary errors
+- Retry mechanisms
+
+### Success States
+- Confirmation patterns
+- Progress indication
+- Completion feedback
+- Next action suggestions
+- Celebration moments (if appropriate)
+
+## Design Deliverables
+
+1. **User Flows** - Step-by-step task completion paths
+2. **Wireframes** - Low-fidelity layout sketches (ASCII)
+3. **Interaction Patterns** - How users interact with components
+4. **Accessibility Requirements** - WCAG compliance needs
+5. **Error Handling UX** - How errors are communicated
+6. **Success States** - Confirmation and feedback patterns
+
+## Output Format
+
+Deliver UX design document with:
+- **User Flow Diagrams** (ASCII or description)
+- **Wireframe Sketches** (key screens)
+- **Interaction Specification** (component × action × response)
+- **Accessibility Checklist** (WCAG requirements)
+- **Error State Inventory** (error × message × recovery)
+- **Success State Inventory** (action × feedback)
+
+**Be specific about user experience. Map every user path and edge case.**
+
+## Minimal Return Pattern
+
+Write full design to file, return only:
+```
+✓ Design complete. Saved to {filepath}
+  Key decisions: {1-2 sentence summary}
+```