component-api-design
/component-api-design
Design clean, composable React/Vue component APIs with accessibility built in. Use when designing or reviewing a component's props, composition, events or accessibility, or when a component API has grown hard to use.
- Author
- SkillMedev ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 13.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Design clean, composable React/Vue component APIs with accessibility built in. Use when designing or reviewing a component's props, composition, events or accessibility, or when a component API has grown hard to use.
Original author description
Design clean, composable React/Vue component APIs with accessibility built in. Use when designing or reviewing a component's props, composition, events or accessibility, or when a component API has grown hard to use.
How it works
- Principles
- Step 1: Name the responsibilities
- Step 2: Choose the composition model
- Step 3: Design the props
- Step 4: Events
- Step 5: Accessibility contract
- Step 6: Write the usage examples first
- Output
SKILL.md preview
---
name: component-api-design
description: Design clean, composable React/Vue component APIs with accessibility built in. Use when designing or reviewing a component's props, composition, events or accessibility, or when a component API has grown hard to use.
metadata:
title: "Component API Design"
---
# Component API Design
Use this skill to design the public API of a UI component before writing
implementation. A good API is learnable, hard to misuse, and composable.
## Principles
1. **Make the common case effortless, the complex case possible.**
2. **Prefer composition over configuration** - slots beat boolean explosions.
3. **The prop name is documentation** - it should read aloud as English.
4. **Accessibility is not a prop** - it is the default behavior.
## Step 1: Name the responsibilities
List every job the component does. If it does more than one thing that could vary
independently, split it. A `Menu` that also manages a button is two components:
`Menu` and `MenuTrigger`.
## Step 2: Choose the composition model
Pick one and stay consistent:
- **Props model** - flat config for simple, leaf components (`Badge`, `Avatar`).
- **Compound components** - shared context for related parts (`Tabs`, `Tab`, `TabPanel`).
- **Render props / slots** - when the consumer must control rendering.
## Step 3: Design the props
For each prop, decide:
- **Controlled vs uncontrolled.** Offer both with the `value` / `defaultValue` pair
plus `onChange`. Never silently switch modes.
- **Type.** Prefer string unions over booleans: `variant="ghost"` not `ghost={true}`.
- **Default.** Every optional prop needs a sensible default documented in one place.
Avoid these smells:
- More than two boolean props that interact (combinatorial explosion).
- Props named after implementation (`useFlexbox`) instead of intent (`align`).
- A `style` or `className` escape hatch as the only customization path.
## Step 4: Events
- Name handlers `onSomethingHappened`, past or present tense consistently.
- Pass semantic payloads, not raw DOM events: `onSelect(item)` beats `onClick(e)`.
- Make events cancelable only when the consumer can meaningfully prevent default.
## Step 5: Accessibility contract
- Forward `ref` to the focusable root.
- Spread remaining props (`...rest`) onto the semantic element so `aria-*` works.
- Manage focus, roles, and keyboard interaction internally; expose hooks to override.
- Document the rendered semantics (role, tab order) in the API notes.
## Step 6: Write the usage examples first
Before implementing, write three example call sites: the trivial case, the typical
case, and the hardest case you expect. If any reads awkwardly, revise the API now -
it is free to change before code exists and expensive after.
## Output
Deliver a typed interface (TypeScript props or Vue `defineProps`), three usage
examples, and a one-paragraph rationale for the composition model chosen.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · SkillMedev/skills | 100 | MIT |
| segunadebayo/design-eng-skills | 85 | MIT |
Database snapshot: 13.11.2026 · package version 0fcec0ceeed9 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90frontend-design-system
Use this skill when the user says 'design system', 'design tokens', 'component library', 'theme', 'colors', 'typography system', 'spacing system', 'component API design', 'variant system', or when creating or extending a frontend design system. This skill enforces: three-tier… - 100web-component-design
Master React, Vue, and Svelte component patterns including CSS-in-JS, composition strategies, and reusable component architecture. Use when building UI component libraries, designing component APIs, or implementing frontend design systems. - 100web-component-design
Master React, Vue, and Svelte component patterns including CSS-in-JS, composition strategies, and reusable component architecture. Use when building UI component libraries, designing component APIs, or implementing frontend design systems. - 100figma-design-react
Design React components from Figma files. Use when given a Figma URL to analyze a design and propose React component architecture, props API, and variant handling. Outputs design analysis and suggested API - does not build components. Also triggers on phrases like "analyze this… - 100component-api-and-library-build
Design and build an accessible, composable library component with a contract-grade public API — deciding composition vs configuration and controlled vs uncontrolled, baking in roles/focus/keyboard from v1, and shipping a story and usage docs. Traverses the component-API branch… - 100design-systems
Builds and maintains design systems and shared component libraries, covering design tokens, theming and dark mode, component API design, loading, empty, error and disabled states, built-in accessibility, documentation, visual regression tests and semver releases with…