v10/skills/write-design-doc/references/components.md

Component Spec Guidance

Guidance for writing component design docs. Think of these as proto-user-facing docs — the API surface spec that eventually feeds into the docs site.

When to Use

• New UI components
• Component API changes
• Interaction patterns (keyboard, touch, focus)
• Accessibility requirements

Templates

Template	Use For
templates/component-basic.md	Single-element components (Button, Icon, Badge)
templates/component-compound.md	Multi-part components (Slider, Menu, Dialog)

Structure

Design docs for components should read like what a user would eventually see in reference docs, plus the store/state context needed for implementation.

Basic component: Problem → Usage → API Surface → State & Store → Accessibility

Compound component: Problem → Anatomy → API Surface → State & Store → Accessibility

Everything lives in a single index.md. If significant decisions were debated, add a decisions.md alongside it.

What Goes in the API Surface

The API surface section is the core of the doc. It covers everything a consumer needs:

• Props / Attributes — What the component accepts
• Data Attributes — Styling hooks for component states
• CSS Custom Properties — Theming and customization points
• Events / Callbacks — What the component emits

For compound components, highlight important part-specific details inline rather than creating a separate parts file. The anatomy section already shows the structure — call out anything noteworthy per part within the API surface.

State & Store

Every component design should call out its store integration:

• What store features/slices does it require?
• What state does it read? What state does it write?
• Does it introduce new state? What's the shape?
• Any store subscriptions or side effects?

Accessibility

Accessibility is first-class, not an afterthought:

• ARIA roles and attributes — What role does each part play?
• Keyboard interactions — Full keyboard table
• Focus management — Tab order, focus trapping, focus restoration
• Screen reader announcements — Live regions, aria-live, status updates
• Touch behavior — Mobile-specific interactions

Reference WAI-ARIA Authoring Practices for the relevant pattern.

Tips

1. Anatomy first (compound) — Show component structure before API details
2. Minimal examples — Only show what's different, use {/* ... */} for the rest
3. Data attributes — Essential for styling component states
4. No separate parts file — API surface covers everything; highlight noteworthy parts inline
5. No implementation log — Temporary mechanics go in .agents/plans/

Prior Art

Research prior art before drafting. Two tiers:

API Patterns (how we design)

• Base UI — Primary reference. Check API shape, prop naming, composition model, data attributes. If Base UI has the component, start there.
• WAI-ARIA Authoring Practices — Canonical accessibility pattern. Required for keyboard, ARIA roles, and focus management.
• Radix UI — Fallback when Base UI doesn't have the pattern.

Player Context (what we need to know)

These aren't API references — look at them for edge cases, feature requirements, platform quirks, and lessons learned:

• Media Chrome — Media-specific UI edge cases, attribute-based API, shadow DOM tradeoffs
• Vidstack — Feature requirements, what they got right, signals approach
• Video.js v8 — Legacy context, what worked and what didn't, migration considerations
• Plyr — Minimal implementations, what a simple player needs