Skip to content
Skills Library
Design & UX · Building & coding

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.

Repository
skills ↗
Licence
MIT
Last repository change
13.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.

Licence

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

  1. Principles
  2. Step 1: Name the responsibilities
  3. Step 2: Choose the composition model
  4. Step 3: Design the props
  5. Step 4: Events
  6. Step 5: Accessibility contract
  7. Step 6: Write the usage examples first
  8. Output
Original SKILL.md headings · 66 lines, 402 words
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

RepositoryScoreLicence
This page · SkillMedev/skills100MIT
segunadebayo/design-eng-skills85MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.