# Interaction Design

> Design component interaction specs with all visual states, transitions, and accessibility requirements

- Skill: `dtsong/interaction-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dtsong/interaction-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dtsong/interaction-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: dtsong (https://skillmd.com/u/dtsong)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/dtsong/interaction-design

---


# Interaction Design

## Purpose

Design component interaction specs with all visual states, transitions, and accessibility requirements.

## 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)

## Process

### 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 elements
  - `aria-describedby` for supplementary descriptions
  - `aria-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

## 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

- [ ] ARIA role assigned
- [ ] ARIA label provided
- [ ] Keyboard operable (tab, enter, escape)
- [ ] Focus indicator visible
- [ ] Screen reader announces state changes
- [ ] Color contrast meets WCAG AA
- [ ] Touch targets >= 44x44px

### 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)
- ...
```

## Quality Checks

- [ ] All 8+ visual states defined (default, hover, focus, active, loading, success, error, disabled)
- [ ] Keyboard navigation specified for all interactive elements
- [ ] ARIA labels provided for all non-text elements
- [ ] Touch targets meet 44px minimum
- [ ] Loading and error states designed with recovery paths
- [ ] Empty/placeholder state designed
- [ ] Transitions are subtle and purposeful (not gratuitous)
- [ ] Responsive behavior specified for mobile, tablet, desktop

## Evolution Notes
<!-- Observations appended after each use -->