AGENTS.md

1# UX Designer — Complete Agent Rules
2 
3This document compiles all rules, guidelines, and best practices for the UX Designer skill, organized by priority.
4 
5---
6 
7## Priority 1: User Research (CRITICAL)
8 
9> Full details: [rules/research.md](rules/research.md)
10 
11### Conducting User Interviews
12- Always start with research before opening a design tool
13- Use open-ended questions: *"Walk me through the last time you [did the task]"*
14- Follow the "5 Whys" technique to uncover root motivations
15- Synthesize findings into themes using affinity mapping, not individual anecdotes
16 
17### Creating Effective Personas
18- Base on real research data, never assumptions
19- Limit to 3-5 primary personas per product
20- Include goals, pain points, behaviors, and context
21- Update as you learn more about users
22 
23**Anti-Patterns:** Demographic-only personas · Aspirational personas · Too many personas · Stale personas
24 
25---
26 
27## Priority 2: Accessibility (CRITICAL)
28 
29> Full details: [rules/accessibility.md](rules/accessibility.md)
30 
31### WCAG AA Requirements
32- **Perceivable:** Color contrast 4.5:1 for text, 3:1 for large text; alt text for images; captions for video
33- **Operable:** Full keyboard access; 44×44px touch targets; visible focus states; no seizure triggers
34- **Understandable:** Visible form labels; descriptive error messages; consistent navigation
35- **Robust:** Semantic HTML; ARIA only when needed; screen reader compatible
36 
37### Inclusive Design
38- Design for one-handed mobile use
39- Support light/dark modes and 200% zoom
40- Use plain language (6th-8th grade reading level)
41- Never use color as the only indicator of meaning
42- Design for RTL languages and text expansion
43 
44---
45 
46## Priority 3: Information Architecture (HIGH)
47 
48> Full details: [rules/information-architecture.md](rules/information-architecture.md)
49 
50### Navigation
51- Limit primary navigation to 5-7 items
52- Group by user mental models, not org charts
53- Use breadcrumbs for hierarchies deeper than 2 levels
54- Mobile: bottom nav for 3-5 primary actions; hamburger for secondary only
55 
56### Content Organization
57- **Progressive disclosure:** Show only what's needed; reveal details on demand
58- **Scannability:** Clear headings, short paragraphs, visual breaks
59- Place the most important content in high-visibility areas
60- Validate labels with card sorting and tree testing
61 
62---
63 
64## Priority 4: Interaction Design (HIGH)
65 
66> Full details: [rules/interaction-design.md](rules/interaction-design.md)
67 
68### User Flows
69- Map the happy path first, then errors and edge cases
70- Minimize steps; provide progress indicators for 3+ step flows
71- Allow going back without losing data; auto-save when possible
72- Confirm destructive actions with specific consequences
73 
74### Microcopy
75- Use specific verbs for buttons: "Save Draft", "Create Account" (not "Submit", "OK")
76- Error messages: explain what happened AND how to fix it
77- Confirmation dialogs: asymmetric labels ("Delete Project" / "Keep Project", not "Yes" / "No")
78- Empty states: explain why it's empty and what to do
79 
80**Common flow problems:** Dead ends · Loops · Forced registration before value · Missing error recovery
81 
82---
83 
84## Priority 5: Visual Design (MEDIUM)
85 
86> Full details: [rules/visual-design.md](rules/visual-design.md)
87 
88### Visual Hierarchy
891. **Size** — larger elements attract attention first
902. **Contrast** — high contrast for key actions
913. **Color** — saturated for emphasis, muted for secondary
924. **Position** — top-left scanned first (LTR); F-pattern / Z-pattern
935. **Whitespace** — isolation creates emphasis
94 
95### Design System Essentials
96- **Color:** Primary, secondary, neutral, semantic (success/error/warning/info)
97- **Typography:** 3-4 sizes per screen, consistent scale ratio
98- **Spacing:** 8px base grid applied consistently
99- **Components:** Document purpose, states, variants, responsive behavior, accessibility
100 
101---
102 
103## Cross-Functional Collaboration
104 
105### Working with Product Managers
106- Share research findings early; align on user needs vs. business goals
107- Use data to support design decisions in priority discussions
108 
109### Working with Developers
110- Provide detailed specs with all states and edge cases
111- Be available during implementation; review against specs before release
112 
113### Working with Stakeholders
114- Present design rationale, not just deliverables
115- Use prototypes to make abstract ideas concrete
116 
117---
118 
119## Tools & Workflow
120 
121### Recommended Tools (2025-2026)
122- **Design:** Figma (primary), Sketch (macOS)
123- **Prototyping:** Figma prototyping, ProtoPie
124- **Research:** Maze, UserTesting, Lookback
125- **Analytics:** Hotjar, FullStory, Google Analytics
126