27 — Design Systems — Deciding Once, Not Every Time

"A component library" was how I confused design systems, which made the "system" part invisible. The model that separated them: a design system is a single source of truth that encodes design decisions once, so every team composes from the same foundations instead of re-deciding them. [1]

The confusion cost me. On every new screen I'd re-pick a blue, re-argue the button radius, re-guess the gap between a label and its input. Three teams working in parallel produced three slightly different buttons and four slightly different "brand blues." None of it was wrong individually; the whole was incoherent. The fix wasn't more discipline — it was moving the decision up front, into shared foundations, and never making it again [2].

Here's the whole model unfolded into its three layers, before I walk through them one at a time:

Three layers, one source of truth. The order matters — tokens feed components, components feed guidelines, and together they're what stops a fifth "brand blue" from ever being invented.

Layer 1 — Design tokens: the variables

The first layer is the part I'd been missing entirely. Design tokens are the raw design decisions, captured as named values: the brand color, the spacing unit, the type scale (the set of font sizes), the corner radius [3]. Instead of scattering #3b82f6 and 16px and 0.5rem across a thousand files, you name them once — --color-brand, --space-4, --radius-md — and everything else references the name.

This is the layer that makes "one place to change brand blue" literal. When the brand color shifts, you change one token; every component that consumed it follows. That's the whole point of a token: a decision with a name, referenced instead of repeated. A token isn't a CSS variable specifically — it's the concept of a named decision; CSS custom properties, Tailwind theme config, and a Figma variable are all ways the same token gets materialized in different tools.

Layer 2 — The component library: the built parts

The second layer is the one I used to mistake for the whole system. The component library is the set of pre-built UI parts — buttons, inputs, cards, modals, dialogs — constructed from the tokens [1][2]. A button doesn't hardcode #3b82f6; it applies --color-brand. So when the token changes, the button changes with it, automatically.

The distinction I had to internalize: a component library alone is not a design system. It's one layer. A drawer full of buttons that each hardcode their own blue is a component library with no system underneath — change "brand blue" and you're back to grepping (searching) the codebase by hand. The tokens are what turn a pile of components into a system.

This is exactly the split I see in this very portfolio. The project uses shadcn/ui for components and Tailwind for tokens [4]. Tailwind's theme config is the token layer — named colors, spacing, radii, type scale — and shadcn/ui components are built to consume those tokens rather than fight them. I don't hand-tune a button's color or radius; I reach for the component, which already references the theme. That pairing is a design system in miniature: tokens (Tailwind) feeding a component library (shadcn/ui), even without a formal docs site.

Layer 3 — Guidelines and docs: how to use them

The third layer is the one engineers most often skip, and it's why "we have a component library" still produces inconsistent UI. Guidelines and documentation are the rules of composition: when to use a primary button versus a secondary, when a modal is appropriate and when it isn't, what the spacing rhythm should be between elements [2].

Components and tokens give teams the ingredients. Guidelines are what stop two engineers from assembling the same ingredients into two different-looking screens. A button component exists, but without a rule like "one primary action per surface," every surface ends up with three competing CTAs (calls to action). The docs are where "consistent at scale" actually gets enforced — not by the code, but by shared agreement on how the code is used.

This is also the layer that explains those sub-nodes on the roadmap I started from — Astro, Next.js, Vuepress, Eleventy, Nuxt.js [5]. Those aren't design-system concepts; they're the site-builders teams reach for to publish this documentation layer. A docs site is just the rendered, browsable form of the guidelines — the place where tokens, components, and usage rules are shown side by side. Next.js or Nuxt.js might host it as an interactive app; Eleventy or Vuepress render it as fast static markdown; Astro can do either with partial hydration (shipping JavaScript only for the interactive bits). The framework is where the docs live, not what makes the system a system.

Why this is worth the overhead

The honest trade-off: a design system is real overhead. You pay for it in upfront design work, a docs site, and a maintenance owner. For a single screen built once, it's overkill.

The payoff is consistency at scale and one place to change anything [1][2]. Once more than one team — or more than one surface — ships UI from the same foundations, the math flips:

• Consistency. Every screen composes from the same tokens and components, so the product looks like one thing, not a collage.
• One place to change. Rebrand, accessibility pass, dark mode — each is a change to the token or component layer, not a thousand-file find-and-replace.
• Speed. Teams stop re-deciding spacing and color and start at "compose from the parts," which is where the actual product work begins.

I felt this directly on the portfolio. Once Tailwind tokens and shadcn/ui components were in place, adding a new page stopped being a design exercise and became assembly. The decisions had already been made — I just compose from them.

How I use this

The habit these notes left me with is a single pause before I write a style: has this decision already been made? If there's a token for the color, the spacing, or the radius, I use it; if there's a component for the part, I reach for it; if neither exists, I ask whether it should — because hardcoding it now means re-deciding it later, somewhere else. A design system isn't a tool you install. It's the discipline of deciding once and referencing forever, and the three layers are just where those once-made decisions live.

References

[1] Figma, "Design systems 101: What is a design system?," Figma Blog, 2024. [Online]. Available: https://www.figma.com/blog/design-systems-101-what-is-a-design-system/

[2] Nielsen Norman Group, "Design systems 101," NN/g, 2024. [Online]. Available: https://www.nngroup.com/articles/design-systems-101/

[3] W3C Community Group, "Design Tokens Format Module," 2024. [Online]. Available: https://www.w3.org/community/design-tokens/

[4] "ave-space — project instructions," CLAUDE.md, 2024. [Online]. Available: https://github.com/aveshina/ave-space

[5] roadmap.sh, "Design Systems," 2024. [Online]. Available: https://roadmap.sh/frontend/design-systems