Use when defining reusable component anatomy, variants, states, slots, composition, APIs, or component documentation. Use design-tokens-and-naming for shared values and figma-and-tooling-workflow for tool-specific library operations.
Use when defining reusable component anatomy, variants, states, slots, composition, APIs, or component documentation. Use design-tokens-and-naming for shared values and figma-and-tooling-workflow for tool-specific library operations.
Defining the structure of a component library: what is an atom vs molecule vs organism, and what belongs in the library at all vs in product code.
Designing a single component's API surface: its variants (e.g. primary | secondary | ghost | destructive), sizes, and the props/slots that drive them.
Specifying full interactive-state coverage for a component — every state in the matrix (default, hover, focus-visible, active, disabled, loading, selected, error, read-only) is named and given a token-backed treatment, not left to chance.
Choosing a composition strategy — compound components / slots vs a flat prop list — to avoid prop-explosion and boolean-soup.
Writing the per-component documentation so designers and engineers consume the component the same way (anatomy, when-to-use, do/don't, a11y, the variant API).
Do Not Use When
You are defining the token tiers, naming, or export (primitive → semantic → component tokens, CSS vars / Style Dictionary). Use design-tokens-and-naming — this skill consumes those tokens.
You are producing Figma-to-dev redlines / measured handoff sheets for a specific screen. Use design-handoff-and-dev-spec.
You are designing dark-mode / multi-brand theming of the same components. Use dark-mode-and-theming (this skill keeps every value token-referenced precisely so theming stays free).
You are auditing WCAG conformance of a built UI. Use accessibility-wcag-2-2-compliance; here you build a11y in rather than audit it.
You only need the copy inside a control (labels, button text). Use ux-writing-and-microcopy.
Required Inputs
Input
Source
Required?
Evidence
Semantic tokens and supported themes
design-tokens-and-naming
yes
Token source and theme map
Component inventory and priority
Product and engineering owners
yes
Ranked use cases and consumers
Platform and accessibility contract
Target repositories and WCAG policy
yes
Framework constraints and required states
A token layer to consume — at minimum semantic tokens for color, space, radius, type, elevation, motion (design-tokens-and-naming). If absent, stop and build tokens first; a component library built on hex literals cannot be themed and is not a system.
The target platform(s) — web (HTML/CSS, React/Vue/Web Components), or cross-platform — because composition mechanics (slots, children, named regions) differ.
The scope: which components, and the priority order (foundations first: Button, Input/Field, Icon, Text, then molecules: Field-with-label, Select, then organisms).
The system boundary and operating owner: consuming products/teams, accountable maintainer, contribution route, and review authority. If these are unknown, record a component proposal rather than a maintained system.
An accessibility floor — WCAG 2.2 AA is the minimum (doctrine/references/wcag-2.2-criteria.md).
Workflow
Set the boundary before building the library. Confirm the products, platforms, consumers, owner, contribution path, and maintenance capacity. Inventory repeated patterns, then prioritise the smallest high-frequency/high-risk component set; do not build a catalogue for its own sake.
Place the component on the atomic ladder before designing it. Atom (indivisible: Button, Input, Icon, Text, Avatar), Molecule (a small bonded group with one job: Field = Label + Input + HelpText + Error; SearchBar = Input + Button), Organism (a self-contained section: Header, Card, DataTable, Form). The level dictates whether it owns layout or only fills a slot. See references/atomic-structure.md. Do not let an atom grow a layout or a molecule grow business logic — that is the #1 architecture smell.
Define the variant model along orthogonal axes — never one mega-enum. Separate the axes that vary independently: intent/variant (primary/secondary/ghost/destructive), size (sm/md/lg), state (interactive, below), and modifiers (icon-only, full-width, loading). A component's API is the product of independent axes, expressed as small enums + booleans, not a variant="primary-large-loading-icon" string. State the axes explicitly so the matrix is finite and reviewable.
Cover the FULL interactive-state set — this is non-negotiable. For every interactive component enumerate and give a token-backed treatment to: default, hover, focus-visible, active/pressed, disabled, loading, selected/checked, error/invalid, read-only (only the states the component can actually enter). Two rules from doctrine's a11y floor:
focus-visible is mandatory and must be visible — a real indicator with ≥ 3:1 contrast against its background, and not obscured by sticky chrome (WCAG 2.2 2.4.7, 2.4.11, 1.4.11; see doctrine/references/wcag-2.2-criteria.md). Never outline: none without a replacement.
disabled ≠ invisible — disabled controls are exempt from contrast minimums but must still be perceivable; communicate state with more than color alone (1.4.1), and prefer not removing them from the tab/AX tree when their presence carries meaning. loading must expose aria-busy/a live status, and error must pair the color with text + aria-invalid + aria-describedby.
Choose composition over configuration. When a component accumulates >~5 booleans, or needs to inject arbitrary content, switch from props to : slots / named regions / compound components (, , + ). Expose layout regions as slots; keep behavior in the parent. See §Composition. This is the doctrine "authored, not templated" lever applied to APIs — a small composable primitive beats a fat configurable one.
Decision Rules
Condition
Architecture choice
Wrong-choice failure
Variations are mutually exclusive
One typed variant axis
Boolean soup permits contradictory combinations
Consumer supplies structured content
Slot or compound composition
Content props expand into an unmaintainable API
Behaviour and semantics differ materially
Separate components sharing primitives
One mega-component accumulates conditional branches
Difference is only visual role
Same component with semantic variant
Duplicate components drift in behaviour and accessibility
A component is requested outside the agreed boundary
Record it as a proposal and route it through contribution review
Silent scope growth makes the system unmaintainable
The library has no owner, docs, or review route
Stop release and assign the operating controls
An ownerless library becomes a second source of truth
Capability Contract
Read and search are required across tokens, usage, components, and accessibility tests. Editing is allowed only for authorised implementation. Execution is required to claim state, API, visual-regression, or accessibility compatibility; publishing a library requires separate authority.
Degraded Mode
Without repository access, return a proposed inventory, API, and state matrix rather than claiming compatibility. Without test or render capability, mark keyboard, assistive-technology, responsive, and theme evidence unverified and block publication.
Anti-Patterns
State gaps. Shipping default + hover and forgetting focus-visible, loading, disabled, or error. The matrix exists so nothing is forgotten; an empty cell is a bug, not a default.
outline: none with no replacement — a WCAG 2.4.7 failure and the single most common a11y regression in component libraries.
Prop-explosion / boolean soup. A Button with isPrimary, isSecondary, isGhost, isDanger booleans (mutually exclusive states as separate flags) instead of one variant enum; switch to enums + composition.
The mega-variant enum.variant="primary-lg-loading" collapses orthogonal axes into one string — un-typed, un-composable, combinatorially exploding.
Hard-coded values. Any literal hex/px in a component body — it can't theme, can't go dark, can't rebrand. Token it.
Atomic-level creep. An atom that owns page layout; a molecule that fetches data; an organism duplicated three ways because no one documented the first.
Disabled-by-color-only / error-by-color-only — fails 1.4.1; pair with text, icon, or shape.
Undocumented component — no anatomy, no API table, no do/don't → it forks the moment a second person touches it.
Ownerless or overbuilt system — dozens of low-use components with no maintainer, contribution route, or adoption signal. Fix: start with the smallest high-value set and assign operating ownership before expanding.
Outputs
Artefact
Consumer
Evidence and acceptance condition
Component inventory and composition map
Design-system owners
Scope, dependencies, and ownership are explicit
Variant, state, slot, and API contracts
Designers and engineers
Reachable combinations are finite, typed, token-backed, and accessible
Component documentation and verification record
Consumers and QA
Examples, theme renders, interaction tests, and known gaps are recorded
System operating record
Design-system owner and consuming teams
Scope, owner, contribution status, release change, adoption/quality signals, and review date are visible
An atomic inventory classifying each component (atom/molecule/organism) with composition relationships.
A variant model per component — the orthogonal axes (variant × size × state × modifier) as small enums + booleans.
A full state matrix per interactive component with a token-backed treatment for every reachable state.
A prop/slot API table and composition contract (slots vs props decision recorded).
A per-component spec doc following references/component-doc-template.md, with the a11y contract referencing WCAG 2.2 criteria.
Examples
examples/button-component-spec.md — a complete, concrete Button spec: 4 variants × 3 sizes × 9 states, every cell mapped to semantic tokens, the prop/slot API, the focus-ring and target-size a11y contract, and do/don't pairs. Use it as the pattern for any new component. (See CONTRIBUTING.md — examples are mandatory and never lorem.)
References
doctrine/design-doctrine.md — the anti-slop charter; §0 "looks human-made" applied to API design (composition over configuration, one authored choice applied systematically).
Bind every value to a semantic token. Padding, color, radius, type, border, shadow, motion durations — all reference tokens (--color-action-bg, --space-3, --radius-control, --duration-fast), never literals. This is what makes the component themeable, dark-mode-ready, and multi-brand for free. Map per-component tokens to semantic ones (per design-tokens-and-naming); a hard-coded #2563eb in a component is a defect.
Meet the interaction minimums. Pointer target ≥ 24×24 CSS px (aim 44×44 touch / 48dp) — WCAG 2.2 2.5.8; honour prefers-reduced-motion on any state transition (2.3.3); every drag affordance has a single-pointer alternative (2.5.7). All from doctrine/references/wcag-2.2-criteria.md. Motion durations come from motion tokens, not magic numbers.
Document the component to the template. Produce the per-component spec: anatomy diagram (named parts), when-to-use / when-not, the variant × size × state matrix, the prop/slot API table, a11y contract, and do/don't pairs. Use references/component-doc-template.md. A component without this doc is not "done" — undocumented variants get reinvented and the library forks.
Resist anti-slop sameness (doctrine/design-doctrine.md). The default-looking Button (flat fill, generic radius, blue) is the convergent AI mean. Make the one authored choice — a deliberate radius, a considered pressed-state shift, a focus ring that belongs to the brand — and apply it systematically through tokens so it reads as one skilled hand, not a template.
Run the system as a product. Before marking a library release complete, record component status (draft, in review, approved, needs work), documentation/a11y checks, version/changelog impact, consumer notification, and the next review date. Track adoption/reuse, one-off exceptions, defects, and drift as signals for the next priority.
