Skip to content
UX Atlas
Design systemCraft conventionAdvanced

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.

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 page
  1. Definition
  2. Principles
  3. Continue from here

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.

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.