Interaction Design

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

From dtsong/claude-code-wsl-setup, MIT.