ui-component

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.