Open most design systems and the tokens are a flat list: a few hundred names, each holding a colour or a number. It works until you need dark mode, or a rebrand, or one component to behave a little differently, and then you are editing the same value in twenty places and hoping you caught them all. The problem is not the values. It is that nothing says how they relate. A design system that lasts is not a pile of values, it is a small number of layers that build on each other, so a change made once flows everywhere it should and nowhere it should not.

Every Zaklad project is built on three such layers: foundation, semantic and component. The set is fixed, the structure inside each layer is yours, and the relationship between them is what does the work. This guide walks through what each layer is for, why a semantic token points at a value instead of holding one, and why that single idea is what lets a system change cleanly.

TL;DR

  • Foundation holds the raw material: real values, and the calculations that derive them. This is the only layer where maths lives.
  • Semantic names colour and size by role (text.default, border.interactive), and each semantic token aliases a foundation token, with one value per theme.
  • Component is the last mile: tokens scoped to a single component, pointing at semantic tokens, for the cases where one part needs to differ.
  • Because semantic tokens reference rather than copy, dark mode and rebrands become one change that cascades, not a hunt through hundreds of values.
  • The three layers are fixed; the names and structure inside them are entirely yours.

What this covers

The three layers

The three layers are an order, not just a grouping. Foundation is the raw material of the system. Semantic gives that material a role: not slate.900 but text.default. Component narrows a role down to a single part: the label on a particular button. Each layer refers to the one beneath it, so a value defined once at the bottom is the value everything above it resolves to. Read across the editor and you can see the whole chain: foundation on the left, semantic in the middle pointing back at it, components on the right pointing at semantics.

The token editor showing three columns: Foundation, Semantic and Component, with reference lines connecting them
The three layers, side by side. Foundation holds the raw scales, semantic names them by role, and each component maps its tokens onto semantics. The lines are references: one value, resolved everywhere it is used.
A diagram: a foundation value flows into a semantic role, which resolves to different values per theme, then into a component token
The chain in the abstract. A foundation value is named by a semantic role, the role resolves to a different foundation step per theme, and a component token points at the role. Change the bottom, and the top follows.

Foundation: the raw material

Foundation is where the real values live: every step of every colour scale, every size on the dimension scale, every font size and weight. It is the system's vocabulary, the full set of values anything else is allowed to use. Crucially, it is also the only layer where calculation happens. A foundation token can hold a plain value, or it can derive its value from another foundation token, and those calculations can chain as deep as you like. That is how a single base number can drive a whole spacing and radius scale. The rule is simple: raw quantities and the maths that relates them stay at the bottom, where they belong.

What foundation does not do is express intent. slate.900 is a near-black; it does not know whether it is body text, a border or a heading. That is deliberate. Keeping foundation free of meaning means you can build the palette and the scales once, completely, and decide what they are for separately. The platform's dimension calculations and palette generation all produce foundation values; everything above simply chooses among them.

Semantic: naming by role

The semantic layer is where a system becomes usable. Instead of asking a designer or a developer to remember that body text is slate.900 in light theme and slate.50 in dark, you give the role a name, text.default, and let it carry the decision. A semantic token does not hold a colour. It points at a foundation token, and it can point at a different one in each theme.

A semantic colour token, color.background.inverse.default, mapping to color.slate.900 in light theme and color.slate.0 in dark theme
A semantic token is an alias with a value per theme. Here color.background.inverse.default points at slate.900 in light and slate.0 in dark. It holds no colour of its own, only a reference, so it follows whatever those foundation steps become.

This is the layer you design and build against. A button uses background.inverse.default, not slate.900. A heading uses text.default, not a hex value. The role is stable even as the value behind it shifts by theme, by brand, or over time. You can read the whole mapping in the editor, and the why aliases, not raw values note in the docs spells out the reasoning in full.

Why aliases, not values

Everything turns on this one choice, so it is worth being concrete about what it buys you. Because a semantic token references a foundation step rather than copying its value, the hard, system-wide changes become single edits.

  • Dark mode is not a second set of values you maintain by hand. It is the same semantic roles pointing at the other end of the same scales: text.default reaching for a near-black step in light and a near-white one in dark. Build against the role and both themes come for free.
  • A rebrand is not a find-and-replace across the product. Change the foundation colour and every semantic role that referenced it inherits the new value, because it only ever referred to a step by name.
  • A single tweak stays local: adjust one foundation step, or repoint one semantic role, and only what depends on it moves.

A flat system cannot do any of this in one move, because every value is a separate copy with no memory of where it came from. The alias is the memory. It is the difference between a relationship you define once and a list you maintain forever. The same idea drives theme inheritance: a child theme overrides only the roles it needs and inherits the rest, so a third or fourth theme is a handful of decisions rather than a full rebuild.

Component: the last mile

Most of the time, semantic tokens are as far as you need to go. But occasionally a single component wants a value that does not belong to the shared vocabulary: a control with its own indicator colour, a card with a particular surface. The component layer exists for exactly that. Component tokens are scoped to one component and not exposed anywhere else, so they keep these local decisions from leaking into the rest of the system.

A component token still points at something, and the strong recommendation is that it points at a semantic token, not straight at foundation. That keeps the component inside the system's roles: it still gets theming, still follows a rebrand, still benefits from the cascade. Reaching past semantics to grab a raw value is possible, but it is how a component quietly falls out of step with everything else. Use the component layer for genuine exceptions, lean on semantics for the rest.

What is fixed, what is yours

The layering is the one thing the platform holds firm: foundation, semantic, component, in that order, always. Semantic and component are optional in the sense that a tiny system could lean almost entirely on foundation, but both are strongly encouraged, because they are where the leverage lives. Skipping semantics to save time is borrowing against every future theme and rebrand.

Everything else is yours. The platform imposes no naming convention inside a layer: group and name tokens to match how your team actually thinks, whether that is your first system or your fifth. Call the group text or content or ink; nest it however suits you. The token naming schema and the what is fixed and what is yours page lay out the boundary precisely. You can also lock a token or a whole group once it is settled, so the shared parts of the system are not changed by accident while the rest stays open to edit.

Why it scales

The point of three layers is not tidiness, it is leverage. Foundation gives you one place for every raw value and the maths between them. Semantic gives you a stable set of roles to design and build against, each able to resolve differently per theme. Component gives you a safe place for the exceptions. Put together, they mean the routine changes that wreck flat systems, a new theme, a brand refresh, a density tweak, become a small number of edits at the right layer that flow outward on their own.

For whoever owns the system, that is the difference between maintaining a list and steering a model. For everyone downstream, a designer pulling a role in the library or a developer using tokens directly in code, it just means the names stay stable while the values stay correct. The full reasoning lives under why this approach scales in the docs.

All of this is set up from the first day of a project: point a new project at a brand colour and you get a complete foundation, a semantic layer mapped across light and dark, and component tokens for the shipped components, ready to rename and extend. Start a project and open the token editor, or read the tokens documentation for the full reference.