Component Definition of Done: The Shipping Checklist

Why it exists

Design systems exist to let product teams ship faster by reusing decisions. But a component that looks right in Storybook can still fail in production if it lacks accessibility, responsive states, or migration guidance. The Definition of Done exists because code-complete is not enough; without a shared checklist, every adoption becomes a bespoke integration and the system slowly rots from partial reuse.

The mental model

Think of a component like a library book. Writing the manuscript is only half the job; it still needs an ISBN, a cover, a barcode, and a catalog entry before a patron can borrow it. A component Definition of Done is the cataloging step. It is the contract that says this piece is ready for strangers to depend on, not just for its author to demo.

How it works

A team agrees on a checklist that covers the full surface area of a component. Typical items include visual parity with the design spec, design token integration, keyboard and screen-reader accessibility, responsive behavior, unit and interaction tests, Storybook or documentation site examples, a changelog entry, and migration notes if it replaces a legacy pattern. The checklist is enforced at pull-request time, often by a maintainer or a bot, and the component is only merged into the release branch when every box is ticked. This shifts quality left and prevents half-finished work from leaking into consuming apps.

When to use it

Use a Definition of Done whenever a design system team ships a component that more than one product squad will consume. It is especially critical before a major version release, during a design-token migration, or when onboarding a new platform like mobile web. It also matters for component variants; adding a new size to a button should trigger the same checklist as building the button from scratch.

When not to use it

Do not apply a heavyweight Definition of Done to experimental or sandbox components that are explicitly built for rapid prototyping. A strict checklist kills iteration speed in discovery phases. Similarly, do not let the checklist grow into bureaucratic theater; if items are not enforced or do not add value to consumers, they become noise and teams will ignore the whole list.

One canonical example

A design system team finishes coding a new date-picker. The developer opens a pull request, but the Definition of Done blocks merge because the component lacks focus-trap behavior and the docs site has no usage example for range selection. The developer adds the missing pieces, the maintainer verifies the checklist, and the date-picker ships. Two weeks later, a product team adopts it in a checkout flow without filing a support ticket because the accessibility and API documentation were already complete.