Component API Design for React/Vue

You are a UI component library architect who has designed component APIs for libraries used by thousands of developers, prioritizing developer experience and flexibility.

Component: [COMPONENT NAME AND PURPOSE]
Framework: [REACT/VUE/ANGULAR/SVELTE/WEB COMPONENTS]
Design system context: [STANDALONE/PART OF DESIGN SYSTEM/EXTENDING EXISTING LIBRARY]
Complexity: [SIMPLE ATOM/COMPOUND MOLECULE/COMPLEX ORGANISM]
Composability needs: [FIXED STRUCTURE/PARTIALLY COMPOSABLE/FULLY COMPOSABLE]

Design the complete component API:

**1. Props / Attributes**
For each prop:
- Name (following naming conventions)
- Type (string literal union, boolean, number, ReactNode, function)
- Default value
- Required or optional
- Description and usage context
- Validation rules

Organize by category:
- Appearance props (variant, size, color)
- Content props (label, description, icon)
- Behavior props (disabled, loading, readonly)
- Event handler props (onChange, onClose, onSubmit)
- Accessibility props (aria-label, role)
- Style override props (className, style, sx)

**2. Composition / Slots**
- Children/slot content options
- Named slots (header, footer, actions, icon)
- Render props for custom rendering
- Compound component pattern (Parent + Parent.Child)
- When to use slots vs props for content

**3. State Management**
- Controlled vs uncontrolled pattern
- Internal state (what the component manages)
- State that must be lifted (parent-controlled)
- Default values for uncontrolled mode
- Ref forwarding and imperative handle

**4. Events / Callbacks**
- Event naming convention (onAction, onChange)
- Callback signatures (what arguments they receive)
- Event object shape
- Prevent default behavior
- Async event handling

**5. Accessibility API**
- Required ARIA attributes
- Keyboard interaction table (key, action)
- Focus management behavior
- Screen reader announcements
- Role assignment

**6. TypeScript Interface**
- Complete type definition
- Generic types (if polymorphic)
- Discriminated unions for variant-specific props
- Exported types for consumer use

**7. Usage Examples**
- Basic usage (minimal props)
- Common configurations (3-4 real scenarios)
- Advanced/custom usage
- Composition with other components
- Error handling patterns

**8. Do's and Don'ts**
- API design decisions and rationale
- Common misuse patterns to prevent
- Performance considerations
- Migration notes from previous versions

The API should be intuitive enough that developers rarely need documentation. Provide the complete TypeScript interface and 5+ usage examples.