| name | interaction-design |
| department | advocate |
| description | Use when designing component interaction specs with visual states, transitions, and accessibility requirements. Covers state matrices, responsive behavior, ARIA compliance, and content constraints. Do not use for multi-step user journey mapping (use journey-mapping). |
| version | 1 |
| triggers | ["component","UI","interaction","modal","form","button","dropdown","toast","dialog","input","state","hover","focus","animation"] |
Interaction Design
Purpose
Design component interaction specs with all visual states, transitions, and accessibility requirements.
Scope Constraints
Reads component requirements, design system documentation, and platform guidelines for interaction analysis. Does not modify files or execute code. Does not access running applications or browser environments directly.
Inputs
- Component name and purpose
- Context where it appears (page, modal, sidebar, etc.)
- User actions it must support
- Existing design system or component library (if any)
- Platform constraints (web, mobile, both)
Input Sanitization
No user-provided values are used in commands or file paths. All inputs are treated as read-only analysis targets.
Procedure
Progress Checklist
Step 1: Define Component Purpose
- What job does this component do?
- What user need does it serve?
- Where does it appear in the UI hierarchy?
- What is the minimal viable version?
Step 2: Enumerate All Visual States
| State | Visual Treatment | When Active |
|---|
| Default/Rest | Base styling | No interaction |
| Hover | Subtle highlight, cursor change | Mouse over (desktop) |
| Focus | Visible focus ring | Keyboard navigation, tab |
| Active/Pressed | Depressed/accent state | Mouse down, touch |
| Loading/Pending | Spinner, skeleton, disabled input | Async operation in progress |
| Success/Confirmed | Green accent, checkmark, brief flash | Operation completed |
| Error/Invalid | Red accent, error message, icon | Validation failed, API error |
| Disabled | Muted colors, no pointer events | Precondition not met |
| Empty/Placeholder | Placeholder text, illustration | No data or content yet |
Step 3: Define Transitions Between States
For each state change:
- Trigger: What causes the transition (click, hover, data load, timer, keyboard)
- Animation: Duration and easing (subtle and purposeful, not gratuitous)
- Micro-interactions: 100-200ms
- State changes: 200-300ms
- Layout shifts: 300-500ms
- Feedback mechanism: Color change, icon swap, text update, motion
Step 4: Specify Accessibility Requirements
- ARIA roles and labels:
role attribute (button, dialog, alert, etc.)aria-label or aria-labelledby for non-text elementsaria-describedby for supplementary descriptionsaria-live regions for dynamic updates
- Keyboard navigation:
- Tab order (logical, matches visual order)
- Enter/Space behavior (activate buttons, submit forms)
- Escape behavior (close modals, cancel operations)
- Arrow key behavior (navigate lists, tabs, menus)
- Screen reader announcements:
- State changes announced (loading, success, error)
- Dynamic content updates via
aria-live
- Visual accessibility:
- Color contrast: WCAG AA minimum (4.5:1 text, 3:1 UI elements)
- Focus indicators visible and high contrast
- Information not conveyed by color alone
Step 5: Define Responsive Behavior
- Desktop (1024px+):
- Full layout, hover interactions available
- Keyboard shortcuts active
- Tablet (768px - 1023px):
- Adjusted spacing, simplified hover states
- Touch-friendly but more screen real estate than mobile
- Mobile (< 768px):
- Touch targets minimum 44x44px
- Swipe gestures where appropriate
- Bottom-sheet instead of dropdown where needed
- Simplified layout, stacked elements
Step 6: Specify Content Constraints
- Character limits for labels, descriptions, error messages
- Truncation strategy (ellipsis, fade, wrap)
- Internationalization considerations (text expansion 30-50% for translations)
- Number formatting, date formatting
Compaction resilience: If context was lost during a long session, re-read the Inputs section to reconstruct what component is being designed, check the Progress Checklist for completed steps, then resume from the earliest incomplete step.
Output Format
State Matrix
| State | Background | Border | Text | Icon | Cursor | Shadow |
|---|
| Default | ... | ... | ... | ... | ... | ... |
| Hover | ... | ... | ... | ... | ... | ... |
| Focus | ... | ... | ... | ... | ... | ... |
| Active | ... | ... | ... | ... | ... | ... |
| Loading | ... | ... | ... | ... | ... | ... |
| Success | ... | ... | ... | ... | ... | ... |
| Error | ... | ... | ... | ... | ... | ... |
| Disabled | ... | ... | ... | ... | ... | ... |
Transition Diagram
[Default] ←→ [Hover] → [Active] → [Loading] → [Success]
↓ ↓
[Focus] [Error]
↓
[Active]
Accessibility Checklist
Component API
Props:
- variant: 'primary' | 'secondary' | 'ghost'
- size: 'sm' | 'md' | 'lg'
- disabled: boolean
- loading: boolean
- ...
Events:
- onClick / onPress
- onFocus / onBlur
- ...
Slots:
- icon (leading/trailing)
- children (content)
- ...
Handoff
- Hand off to journey-mapping if user flow analysis is needed for the broader context where the component appears.
- Hand off to craftsman/pattern-analysis if code implementation patterns are needed for the designed component.
Quality Checks
Evolution Notes
