Design systems that survive 160 engineers

A component library used by six engineers is a folder. A component library used by 160 engineers is a treaty. Rosetta taught me that the second kind is barely a technical artifact at all — it's an agreement about how an organization decides what things should look like, dressed up as an npm package.

01APIs are promises, not conveniences

Every prop you ship is a promise you'll keep for years. The most durable components in Rosetta were the ones with the fewest opinions: a variant enum instead of a dozen boolean flags, tokens instead of raw hex values, composition instead of configuration.

// One enum, three themes, zero surprises.
const VARIANTS = ['primary', 'secondary', 'ghost'] as const;

export function Button({ variant = 'primary', ...props }: ButtonProps) {
  const tokens = useTheme().button[variant];
  return <StyledButton data-variant={variant} tokens={tokens} {...props} />;
}

02Theming is a data problem

Rosetta shipped three themes from one component tree. That only works when themes are pure data — no theme-specific components, no if (theme === 'dark') branches hiding in render functions. The theme object is the single source of truth; components are just projections of it.

export const dark: Theme = {
  surface: { base: '#0B0D11', raised: '#11141A' },
  text: { primary: '#F5F7FA', muted: '#9099A8' },
  button: {
    primary: { bg: '#F5F7FA', fg: '#07080B' },
    ghost: { bg: 'transparent', fg: '#F5F7FA' },
  },
} satisfies Theme;

The library you ship is the smaller half of the work. The library people keep choosing is built in code review, office hours, and changelogs.

03The politics of shared code

Adoption is never mandated; it's earned. What worked: migration codemods with every breaking release, a public roadmap anyone could comment on, and treating internal teams like customers with churn risk. What didn't: decrees, and any sentence that started with "going forward, all teams must."

Show, don't mandate

Nothing moved adoption like a live walkthrough of a real team's migration. Recorded sessions became the library's best sales channel.

Thirteen years in, this is the part I'd tell my younger self first: the system survives when the people using it feel like its owners, not its subjects.

Let's write the
next chapter.