component

Component Architecture Patterns

Build accessible, headless UI components using proven patterns from Base UI, Radix, and Ark UI. These patterns are framework-agnostic — core concepts apply across React, Vue, Svelte, Solid, and vanilla JS.

Primary sources:

• Base UI Handbook
• Ark UI — Cross-framework implementation
• Zag.js — State machines for UI components

Framework-specific: react.md | lit.md

Core Principles

1. Headless over styled — Separate behavior from presentation
2. Compound over monolithic — Small composable parts over config-heavy megacomponents
3. Controlled + uncontrolled — Support both state ownership models
4. Accessible by default — ARIA, keyboard nav, focus management built-in
5. State via attributes — Expose state through data-* for framework-agnostic styling

Pattern 1: Compound Components

What: Components as related parts sharing state through context, each mapping 1:1 to DOM elements.

Why:

• Declarative — assemble like building blocks, reorder/omit parts freely
• Each part is an independent styling target
• DOM structure maps directly to ARIA roles

Standard hierarchies:

Ref: Base UI Composition

Pattern 2: Controlled & Uncontrolled State

What: Support external state control OR internal state with consistent prop naming.

Why:

• Flexibility for simple and complex use cases
• Predictable API across components
• Change details enable fine-grained control (cancel changes, track reasons)

Convention:

Change details: { reason, event, cancel() }

Ref: Base UI Customization

Pattern 3: Prop Getters

What: Functions returning HTML attributes for DOM elements, abstracting logic from rendering.

Why:

• Portable across frameworks (React, Vue, Svelte, Solid)
• Clean separation of concerns
• Composable via mergeProps()

Example: getTriggerProps() returns { aria-expanded, aria-haspopup, onClick, onKeyDown }

Ref: Zag.js, Downshift

Pattern 4: State via Data Attributes

What: Expose state through data-* attributes for CSS targeting.

Why:

• Framework-agnostic styling
• No JS needed for state-based styles
• Inspectable in DevTools

Standard attributes:

• data-open / data-closed — Visibility
• data-checked / data-unchecked — Toggle state
• data-highlighted — Focus within group
• data-disabled, data-valid, data-invalid
• data-side, data-align — Positioning

CSS variables: --available-height, --anchor-width, --transform-origin

Ref: Base UI Styling

Pattern 5: Accessibility

What: ARIA, keyboard navigation, focus management built into architecture.

Why:

• Accessibility is structural, not decorative
• Users expect standard keyboard interactions
• Consistent patterns reduce errors

Key concerns:

• ARIA attributes — Auto-managed from state
• Focus trapping — Modals trap focus within
• Roving tabindex — One tabbable item, arrows navigate
• Virtual focus — aria-activedescendant for long lists
• Typeahead — A-Z jumps to matches

Ref: Base UI Accessibility, WAI-ARIA Practices

For detailed accessibility patterns, load the aria skill.

Pattern 6: Floating Positioning

What: Position popups relative to triggers with collision detection.

Why: Handles viewport boundaries, scroll, resize automatically.

Config: side, align, sideOffset, collision (flip/shift), trackAnchor

Ref: Floating UI

API Conventions

Imperative actions: actionsRef exposing open(), close(), toggle()

See props.md for naming conventions.

Reference Files

For accessibility patterns (ARIA, keyboard, focus), load the aria skill.

Review

For structured component reviews, load the review workflow:

Implementation Sources

Related Skills