Marcus Andrey Study
Ler em português Library

Design Systems · Step 1 · 6 min read

Anatomy of a design system

Tokens, components, patterns, guidelines and the people around them: the layers of a design system, what lives in each, the rule that holds them together, and how Brad Frost's ecosystem adds framework code, recipes and smart components on top. Mapped onto Harbour.

A design system is layers that point at each other, plus the people who keep the pointers right. A product uses components. Components use tokens. Guidelines explain all of them. And a team decides what changes and when. Take out any layer and the others start to drift again. Knowing the layers tells you where a problem belongs, which is half of fixing it.

What you'll be able to do after reading:

  • Name the layers of a design system and what lives in each
  • Explain the one rule that keeps them working together
  • Map Brad Frost's design system ecosystem onto a real system
  • Say which layer a request or a bug belongs to

1. The layers

  1. TokensNamed decisions: color.action.primary, space.inset.md, radius.control. Light, dark and compact live here.
  2. ComponentsButton, text field, sailing card, passenger row. Designed in Figma and built in code, with the same names and the same properties.
  3. PatternsComponents put together for a job: checking in a passenger, choosing a sailing, showing a delay.
  4. Guidelines and docsWhen to use what, and when not to. Content, accessibility, motion and imagery rules live next to the parts.
  5. ProductsThe booking app and the staff console: what passengers and port staff actually use.
People and process Who owns Harbour, how a team asks for a new part, how changes are released and announced, how old parts are retired. Without this column the stack of parts is a UI kit that goes out of date.
Harbour, from the smallest decisions to the products. Each layer is built on the one before it in this list and never skips it: a product doesn't pick a hex colour, it uses a component, which uses a token. The dashed column runs alongside every layer.Layers adapted from Brad Frost, The Design System Ecosystem (2023), and NN/g, Design Systems 101 (2021). Diagram: Marcus Andrey, CC BY 4.0.

In What a design system is you met four parts: tokens, components, guidelines and governance. Here they're laid out as layers, with patterns added between components and guidelines, and governance drawn as a column, because it touches everything.

NN/g describes a system's repository as often containing "a style guide, a component library, and a pattern library", and stresses that the people who manage it are part of the system too (NN/g, Design Systems 101, 2021).


2. What lives in each layer

Layer In Harbour Lives in Covered in
Tokens color.action.primary, space.inset.md, radius.control, with light, dark and compact Figma variables, token files, CSS custom properties Step 2
Components Button, text field, select, checkbox, sailing card A Figma library and a code package, with the same names Steps 3 and 5
Patterns Check in a passenger, choose a sailing, show a delay Docs, examples, sometimes code templates Step 4
Guidelines and docs When to use each part, content rules, accessibility notes A documentation site Steps 4 and 6
People and process An owner, a contribution path, releases, deprecation Docs, a changelog, a request form, meetings Steps 6 and 7

Some guidelines have whole lessons elsewhere on this site: motion in Documenting motion in a design system and Motion tokens, imagery in An image style guide in your design system.


3. The rule that holds it together

Each layer only uses the layer it is built on, and never reaches past it. A product doesn't pick #1F5FAE; it uses a Harbour button. The button doesn't pick #1F5FAE either; it reads button.primary.background, which points to color.action.primary, which points to color.blue.600.

That rule is what makes change cheap. When the console needs a dark mode, only the token layer changes. When the button needs a better focus ring, only the component changes. When a product team skips a layer, by hard-coding a colour or detaching a component, they make a place where the next change won't reach.

It also tells you where a request belongs:

  • "This blue is too dark in dark mode" → token layer.
  • "The button needs a loading state" → component layer.
  • "We keep building the same delay banner" → pattern layer.
  • "Nobody knows when to use ghost buttons" → guidelines.
  • "We asked for a date picker three months ago" → people and process.

4. Brad Frost's ecosystem

Frost describes the layers in more detail for bigger organisations (Frost, The Design System Ecosystem, 2023):

  1. A core design system, with design tokens ("think of them as brand variables"), icons, UI components and a reference website.
  2. Technology-specific implementations: the same components wrapped for React, iOS or Android.
  3. Recipes: "composed UI components to be used consistently across specific contexts (like a product or product family)". Not shared across the whole company.
  4. Smart components: components "wrapped in logic, functionality, or other smarts", like form validation or a data table.
  5. The product: "the actual websites and apps that we ship".

He's clear that most of these layers are optional. For Harbour today, the core is enough. The console's passenger table might become a smart component later; the booking app's fare cards might be a recipe that only that app uses. Knowing the layers exists means you can say "that's a recipe, it lives in the console's code, not in Harbour" and save the core team from owning everything.


5. Design and code are twins

Every component and token exists twice: once in Figma, once in code. The system works when the two have the same names, the same properties and the same behaviour. When the Figma button has a "size" property with small, medium and large, and the code button has size="sm" | "md" | "lg", handoff becomes a lookup, not a translation (see Handoff to developers). Step 5 is about keeping the twins in step.


6. Common mistakes

  • Calling a Figma library "the design system", with no code twin and no owner.
  • Letting products use primitive colours directly, which skips the token layer.
  • Putting every team's one-off part into the core, until the core is a junk drawer.
  • Writing guidelines in a separate place nobody visits, far from the components they describe.
  • Forgetting the people column: no one to ask, no way to contribute.

7. Vocabulary

Term Meaning
Layer One level of a system: tokens, components, patterns, guidelines
Pattern Components put together to solve a recurring task
Core The parts shared across the whole organisation
Recipe A composition shared within one product or family, not the whole company (Frost)
Smart component A component with logic built in, like validation (Frost)
Reference website The documentation site where the system is explained

8. Try it (no tools needed)

  1. Write down five things your team asked the system for (or would ask, if it existed).
  2. Put each one in a layer: token, component, pattern, guideline, or people and process.
  3. Look for the layer with the most requests. That's where the system is weakest.

Reflection questions: Which layer does your team skip most often? What would make skipping it unnecessary?


9. If you already practise

  • Label every issue in your system's backlog with its layer. The pattern of labels is a map of where to invest.
  • Write down which parts are core and which are recipes. Moving a recipe into the core should be a decision, not an accident.
  • Check that every component has its twin, with matching property names, and list the ones that don't.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

What a design system is · The interface inventory · Token tiers · Anatomy and API of a component · From components to patterns · Contribution models · Handoff to developers

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close