Thirty-five components, one set of shadows
Our design system had shadows picked by hand in every component. Turning them into named elevation tokens made the whole library feel like one thing.
Shadows are where design systems quietly fall apart. Colours and spacing usually get tokens early. Shadows get typed in by hand: one component uses a small shadow, the next a slightly larger one, a third a custom value someone tuned on a Friday. Each looks fine on its own. Together, the interface looks like it was assembled from different kits.
That was the state of our open-source design system. About thirty-five components (buttons, cards, dialogs, popovers, selects, date pickers, tooltips, inputs) each chose their own shadow.
Name the levels, not the values
Instead of describing shadows by their numbers, we described them by what they mean: how far something sits above the page. The idea, in simplified form:
- Flat: part of the page. Most fields and cards.
- Raised: sits slightly above, like a card you can click.
- Overlay: floats over content, like a popover or menu.
- Modal: the top layer, like a dialog.
A small module exported these named levels, and every component switched from its hand-picked utility class to the level that described its role.
What changed
- Consistency for free. A new component asks “what level am I?” rather than “which shadow looks right?”.
- One place to tune. When the shadows felt too heavy in one product, we changed the levels once instead of editing thirty-five files.
- Clear rules. We wrote down which elements may float. Filter chips, for example, were flattened back to the field level, because a row of floating chips looked busy.
The lesson
Tokens aren’t only for colours. Anything that repeats and carries meaning (elevation, motion durations, focus rings) is worth naming. The name is a decision you only have to make once.