Driving Design System Adoption
Strategies to migrate consumers, measure adoption, and sustain buy-in across an organization.
Design SystemsIntermediate
Why
A design system nobody uses is just a repo. Adoption is the hard part — teams have legacy code, deadlines, and skepticism.
A deliberate migration plan with quick wins turns a shelf-ware system into real leverage.
When
Start adoption work once the core 10 components exist and are documented. Don't wait for completeness — migrate the easiest consumer first to build a success story.
How
1. Inventory consumers — list apps, their stack, component usage, owner team
2. Pick a pilot — greenfield or low-risk app, enthusiastic team, 2-week migration
3. Codemod the easy wins — Button/Input/Tag are 80% of usages, automate the swap
4. Measure — track % of apps importing @myorg/ui, publish a dashboard
5. Office hours — weekly 1h slot where maintainers help unblock consumers
6. Deprecate the old — internal "ui-legacy" package prints migration link on install
7. Celebrate — showcase migration stories in company all-hands
Example
// adoption-dashboard.ts — track real usage
import { readFileSync } from "fs";
const apps = JSON.parse(readFileSync("apps.json", "utf8"));
const report = apps.map((a) => ({
app: a.name,
usingDS: a.deps.includes("@myorg/ui"),
pctComponents: a.imports.filter((i) => i.startsWith("@myorg/ui")).length / a.imports.length,
}));
// Output: 18/24 apps (75%) import @myorg/ui, avg 62% of components migrated
// codemod.button.cjs — jscodeshift transform
module.exports = function (file, api) {
const j = api.jscodeshift;
return j(file.source)
.find(j.JSXOpeningElement, { name: { name: "Btn" } })
.forEach((p) => { p.value.name.name = "Button"; })
.toSource();
};
Common Problems
- ⚠Big-bang migration — team tries to swap 200 components in one PR, blocked for months
- ⚠No measurement — leadership can't see progress, funding gets cut
- ⚠Maintainers unreachable — consumers hit a bug, no response for 2 weeks, they fork
Best Practices
- ✓Migrate one component type at a time — ship Button everywhere, then Input, then Card
- ✓Publish an adoption dashboard — % of apps, % of components, visible to leadership
- ✓Offer weekly office hours — predictable support slot beats ad-hoc Slack pings