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
- TokensNamed decisions:
color.,action. primary space.,inset. md radius.. Light, dark and compact live here.control - ComponentsButton, text field, sailing card, passenger row. Designed in Figma and built in code, with the same names and the same properties.
- PatternsComponents put together for a job: checking in a passenger, choosing a sailing, showing a delay.
- Guidelines and docsWhen to use what, and when not to. Content, accessibility, motion and imagery rules live next to the parts.
- ProductsThe booking app and the staff console: what passengers and port staff actually use.
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):
- A core design system, with design tokens ("think of them as brand variables"), icons, UI components and a reference website.
- Technology-specific implementations: the same components wrapped for React, iOS or Android.
- Recipes: "composed UI components to be used consistently across specific contexts (like a product or product family)". Not shared across the whole company.
- Smart components: components "wrapped in logic, functionality, or other smarts", like form validation or a data table.
- 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)
- Write down five things your team asked the system for (or would ask, if it existed).
- Put each one in a layer: token, component, pattern, guideline, or people and process.
- 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
- Brad Frost: The Design System Ecosystem (2023)
- NN/g, Therese Fessenden: Design Systems 101 (2021)
- How public systems lay out their layers: IBM Carbon · Atlassian Design System · Adobe Spectrum
Books, courses and videos to go deeper
- Atomic DesignBrad Frost2016, free online (Amazon)
- Design SystemsAlla KholmatovaBook · Smashing Media, 2017 (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
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