Context
Ranium builds frontend for multiple client projects in parallel. Each project was re-implementing the same buttons, forms, and tables — the same decisions, made slightly differently, every time.
Problem & baseline
Duplicated components mean duplicated bugs, inconsistent UI between projects, and time spent rebuilding solved problems. The baseline was the delivery pace before the system existed.
Options & trade-offs
The realistic options: adopt an existing component library and theme it, build a thin token layer over a headless library, or own the full system. Adjacent to that, the distribution question — copy components between repos, publish versioned packages, or keep consumers in one monorepo.
Interventions
- Design tokens — color, spacing, and typography decisions captured as tokens rather than hardcoded values, so client theming is a token swap, not a fork.
- Component library — shared Vue components with typed props and documented variants.
- Storybook documentation — every component's states and variants rendered as living docs, doubling as the design review surface.
- Versioned releases — semantic versioning with changelogs so consuming projects upgrade deliberately instead of absorbing breakage.
Enforcement
A design system nobody is forced to use is a suggestion. Adoption holds because the checks make the right path the cheap one.
Results
Feature delivery on consuming projects is 20% faster — teams assemble from the library instead of rebuilding primitives, and UI consistency between projects stopped being a review argument.
What I'd do differently
Write-up in progress.