Skip to content
UX Atlas
Plate SYS·002 · Design systemGrid C4 · Rev. 2026-09-14

Component API Design

The props a component exposes determine whether it gets used correctly or forked, which is the main failure mode of design systems.

Design systemCraft conventionAdvanced

Definition

A component's API is the set of properties, slots and events it exposes. It encodes which variations are supported and, by omission, which are not. Getting it wrong produces either rigidity that causes forking or flexibility that dissolves consistency.

Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.

On this plate
  1. 1Definition
  2. 2Principles
  3. 3Answering a request for flexibility
  4. 4Designing the surface
  5. 5Commonly confused with
  6. 6Local chart
  7. 7Continue from here

Reach for this when

  • Designing a shared component.
  • Reviewing why teams are not adopting the system.
  • Deciding whether to add a variant.

Common mistakes

  • Prop explosion from accumulated edge cases.
  • Style escape hatches that undermine consistency.
  • APIs that allow inaccessible configurations.
  • Variants named after their appearance.

Principles

  • Prefer composition to configuration. A card with slots beats a card with twenty props.
  • Constrain variants to a defined set rather than accepting arbitrary values. variant="primary" not colour="#0055ff".
  • Do not expose a style escape hatch by default. Once one exists, it becomes the path of least resistance.
  • Make the accessible path the default. If a prop can produce an inaccessible result, reconsider the prop.
  • Name props for meaning, not implementation: tone, emphasis, size, rather than colour codes.
  • Provide sensible defaults so the common case needs no configuration at all.

Answering a request for flexibility

Most API damage is done one reasonable request at a time. The first answer matters more than the eventual one.

RequestFirst answerWhy
We need this button in purpleName the meaning insteadPurple is a brand decision, not a property of this button. If the meaning is genuinely new, the variant set is what needs changing.
We need one more element inside the cardA slotComposition absorbs content you did not predict. A prop only absorbs the case in front of you.
Ours behaves differently on submitA callback, not a booleanEvents let the consumer own their workflow without the component learning it.
We need to override the paddingNot through a style propDensity is a system decision. If two densities are legitimate, ship a size.
It has to look completely different hereA different componentTwo designs sharing only a name are two components. Forcing them together is how prop explosion starts.

Designing the surface

Do

  • Write the call sites for three real usages before writing the component.
  • Make invalid combinations impossible to express, so a variant that requires an icon takes that icon as a required prop.
  • Keep boolean props independent. Two booleans that can never both be true were always one enum.
  • Forward the underlying element's props for cases you did not predict, rather than inventing a pass-through for each one.

Do not

  • Do not name a prop after a team, a screen or a release.
  • Do not treat an arbitrary class name as the general answer to customisation.
  • Do not change behaviour implicitly based on the type of children. Rules that cannot be stated cannot be documented.
  • Do not ship a variant whose name does not survive being said out loud to someone outside the team.

Commonly confused with

Close neighbours that get substituted for each other. The difference is stated first, then the condition that picks one over the other.

vs.

Component Anatomy, States and Variants

Design system

The named parts of a component, its states, and why each variant exists.

Key difference

Anatomy and variants describe what a component is and which alternatives exist. The API is how anyone gets at them in code. One is the decision, the other is the surface that exposes it, and a good decision with a bad API still gets forked.

Use Component API Design when

  • People are overriding styles or forking to get what they need.
  • The question is which variations to support and which to refuse.
  • The work touches naming, defaults and breaking changes.

Use Component Anatomy, States and Variants when

  • Two teams have built near-duplicates because nothing was written down.
  • The question is which states and variants are legitimate.
  • The work is documentation and design, before any props are named.

Learn about Component Anatomy, States and Variants

Local chart

SYS·002 · Region VI · Grid C4

This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.

Consistency and StandardsHEUR·004 · PRINCIPLES BEHIND THISChromaticTOOL·041 · OFTEN USED WITHFigmaTOOL·001 · OFTEN USED WITHStorybookTOOL·037 · OFTEN USED WITHComponent Anatomy, States and VariantsSYS·009 · COMMONLY CONFUSED WITHMigrating Product Teams onto a Design SystemCASE·003 · PRACTICAL EXAMPLEAtomic DesignTERM·086 · SHORT DEFINITIONComponentTERM·037 · SHORT DEFINITIONComponent LibraryTERM·085 · SHORT DEFINITIONContainer QueryTERM·070 · SHORT DEFINITIONSemantic VersioningTERM·090 · SHORT DEFINITIONDesign System to DocumentationAI·007 · RELATED CONCEPT

Continue from here

Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.

Principles behind this

The reasoning this solution is an application of.

Often used with

These usually appear in the same screen or the same decision.

Practical example

A worked decision where this was the deciding factor.

Short definition

The one-paragraph version, for when that is all you need.

Related concept

Connected closely enough to change how you apply this.