Designing a Component Library That Scales Across Teams

Every design system I've seen fail, failed the same way: it started as documentation of what already existed instead of a contract for what should exist.

What actually scales

• Tokens before components — color, spacing, and type scale first
• One variant axis per prop, never boolean soup
• Every component ships with its accessibility behavior, not as a follow-up ticket

If a new engineer can't guess the API from the design file alone, the contract has already broken down.