| name | ui-component |
| description | Design and review frontend UI components — props API, state management, loading/error/empty states, accessibility, performance. Trigger on /ui-component, or when building components, reviewing UI code, or debugging rendering issues. |
| user-invocable | true |
| allowed-tools | Read, Grep, Glob, Bash, Edit, Browser |
UI Component
Design and review frontend components systematically. Covers the full surface area of a component — not just the happy path.
Workflow
1. Component API design
- Props — minimal surface. Prefer few, well-named props over many optional ones.
- Defaults — every prop should have a sensible default or be required.
- Children — support composition via
children or slot where appropriate.
- Variants — use variant props (e.g.
size, variant) instead of boolean flags when there are 3+ visual states.
- Forwarding — forward
ref and spread extra props to the root DOM element when expected by users.
2. State coverage
Every component handles these states — check each:
| State | What to check | Example |
|---|
| Loading | Skeleton/spinner shown? Layout shift prevented? | Table with 20 rows skeleton |
| Empty | Clear message shown? CTA to add content? | "No items yet. Create one." |
| Error | Error message + retry action? | "Failed to load. Try again." |
| Partial | Partial data displayed gracefully? | 5 of 10 items loaded |
| Edge | Very long text, many items, special chars? | Username overflow, 1000 items |
3. Accessibility (a11y)
- Semantic HTML — use
<button>, <nav>, <heading> instead of <div> with roles.
- Keyboard — all interactive elements reachable and operable via keyboard.
- Focus management — focus moves predictably after actions (modal open/close, navigation).
- ARIA — labels on icon-only buttons, live regions for dynamic content,
aria-expanded for toggles.
- Color contrast — text meets WCAG AA (4.5:1 for normal text, 3:1 for large).
- Reduced motion — respect
prefers-reduced-motion for animations.
- Touch targets — minimum 44x44px for interactive elements.
4. Performance
- Render frequency — is the component re-rendering too often? Memoize if needed.
- List rendering — use virtualization for long lists (react-window, tanstack-virtual).
- Bundle size — lazy-load heavy components. Avoid large dependencies in shared components.
- Images — lazy loading, proper sizing, responsive formats (WebP/AVIF).
5. Error handling
- Boundary — wrap in error boundary to catch render errors gracefully.
- Fallback — error boundary shows a meaningful fallback UI.
- Retry — offer retry action where appropriate (network-dependent components).
- Logging — errors logged to console or monitoring (not swallowed).
Rules
- Do not add state management (Redux, Zustand, Context) for prop-drilling that's only 1-2 levels deep.
- Keep components focused — one component, one responsibility.
- Do not optimize prematurely. Profile first, then optimize.
- Test component states (loading, empty, error) not just the happy path.
Experience Log
This skill learns from experience. Mechanism:
- Read
.claude/experience/ui-component.md at skill start to benefit from past lessons.
- Write to
.claude/experience/ui-component.md after use if you learned something new.
- Format:
YYYY-MM-DD: <lesson> — one line per entry.
- Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.
