Your Components Are an API

Early on, a component is a drawing. You change it, everyone gets the update, nobody notices. In a mature library that stops being true. Components are linked from tickets, used across product files and built into screens nobody is looking at. At that point a component is an API, and it deserves the same discipline.

The cost of a small change

Renaming a variant feels harmless. In practice it can break links from tickets, reset overrides on instances you’ve never seen, and change screens that are already approved. The person who pays for that is rarely the person who made the change.

Additive by default

My rule: IDs, names and variant properties don’t change. New behaviour arrives as new properties, switched off by default, so every existing instance looks exactly as it did. If the structure genuinely has to change, I build the new version alongside the old one and migrate on purpose.

That’s how a toast gained a Short/Long text length mode with a 512px maximum, and how an action link gained a card mode with an ID, a status badge and a description, without a single existing screen moving.

If you can’t measure the blast radius, you’re not done

• Count overrides before and after. Across 57 toast instances and 73 action link instances, none were lost.

• Compare exports. All 18 existing action link variants stayed pixel-identical.

• Test on temporary instances first: long text, every state, every variant switch. Then delete them.

The tool will surprise you

• Cloning a variant can silently drop its property references. Check them after every copy.

• A maximum width on a component’s root doesn’t make its text wrap; it has to sit on the text’s direct parent.

• A label that must stay on one line needed a fixed height and truncation. A line limit alone didn’t hold it.

Trust is the actual product of a design system. Every change either builds it or spends it.