When a component is ready to be in the system

The pull request for a new design system component has been open for three weeks. The component works. It looks right. The engineers who needed it are waiting on it. The pressure is real: can we just ship it now and come back to the documentation?

The answer, delivered with some friction almost every time: no. Not because documentation is bureaucratic box-checking, but because a component published to the system without documentation is a component that will be misused, extended incorrectly, and will generate support load that takes more time than the documentation would have. The pressure to ship early is understandable. The cost of shipping early is usually paid by whoever is on the other end of "how does this work."

What "ready" actually means

A component is ready for the system when a developer who has never seen it before can use it correctly without asking anyone. That's the bar. Everything else follows from it.

This means the component needs: a clear description of what it's for and when to use it, working code examples for the common cases, documented props with descriptions that explain not just the type but the intent, and some indication of what not to do with it. These don't have to be long. A 200-word description and two code examples is enough for a simple component. The question is whether they exist.

A component without this can still be shipped internally, into a consuming repo for the specific product team that asked for it. What it shouldn't do is join the published library, where other teams will find it and use it as a model, because a poorly documented component in the library teaches by example that poor documentation is acceptable.

The accessibility bar

Accessibility completeness is a harder readiness criterion than documentation because it's easier to get partway through and declare done.

A button component with visible focus styles, correct type attribute defaulting, and keyboard activation support is most of the way to accessible. It's not all the way. Does it correctly forward aria-* attributes from the consumer? Does it handle the case where the button label is an icon with no visible text? The consumer needs to provide aria-label in that case, and the documentation should say so. Does it work correctly with screen readers when used as a toggle, passing aria-pressed through?

These questions are annoying to think about before shipping. They're worse to answer after shipping, when fixing them may require API changes that break existing consumers.

The useful check before publishing: test the component in isolation with VoiceOver or NVDA, keyboard-only, and in high contrast mode. Not to write a comprehensive accessibility report, just to find the obvious gaps. The obvious gaps are usually the ones that will become issues.

API stability is a readiness criterion

The component's prop API is a contract. Once it ships to the system, changing it is a breaking change that requires a migration path. This means the API should be reviewed. Not just "does it work" but "is this how we'd design it if we were starting fresh, knowing everything we know now."

In practice this means: before publishing, look at every prop and ask whether the name, the type, and the default value would be the same if the component were being designed today with no time pressure. Prop names that were convenient to implement (contentText instead of label, styleVariant instead of variant, onClickHandler instead of onClick) become permanent friction when published.

The most common post-ship regret is an API that was shaped by the implementation rather than by the consumer experience. The developer implementing the component knows how it works internally; the consumer doesn't and shouldn't have to.

Partial coverage is not a reason to wait

One common readiness trap: the component isn't published because it doesn't yet cover all the cases the design calls for. The dropdown handles single select but not multi-select. The table handles basic data but not sorting. The badge doesn't have all the size variants specified in the design.

Waiting for complete coverage is usually the wrong call. A component that handles the common case correctly and documents its limitations clearly is more useful than a perfect component on an undefined timeline. Ship the single-select dropdown with a clear note that multi-select is not yet supported. Document the intent for later phases. The engineering team that needed single select can use the system version. The team that needs multi-select knows they're building custom for now and contributing back later.

Waiting usually means a different team builds multi-select themselves, and the system ends up with two competing implementations when the team finally ships the component.

The minimum bar in writing

Because this question comes up constantly, it's worth stating the minimum bar plainly: a component is ready to publish when it has working code examples, a prop table with intent descriptions (not just type signatures), a usage note covering when to use it, and passing automated accessibility tests. That's the floor. Everything else (design guidelines, visual examples, edge case documentation, "don't do this" guidance) makes the component more valuable, but shouldn't be a gate on shipping the floor.

Teams that set the bar too high publish nothing and then wonder why engineers are building custom components. Teams that set it too low publish components that create more problems than they solve. The floor is the answer to both.