The component library is the easy part. The contract is what makes a design system survive a team change.
A contract here means: what the component accepts, what it promises, and what you'll never change without a major version.
Practically:
- Props are public API. Rename one and you've broken someone's page.
- Deprecation needs a date and a codemod, not a note in a doc.
- Docs are generated from the code, because handwritten docs drift within a sprint.
- Version the package, even internally. "Just pull main" is how a design system becomes a fork.
The hard part is saying no. Every component request is a request to own another contract.
The best design systems I've used felt small, and the docs explained the why, not just the props.
Do you version your internal design system?
