Documentation.

Zaklad is flexible about how you structure your tokens. Two things are fixed by the platform: the layer order (Foundation feeds Semantic, Semantic feeds Component) and the XS–XL sizing context. Everything else is up to you: naming conventions, which layers you actually use, whether you adopt calculated dimensions.

The sections below describe how the wizard and built-in templates are set up, and why. They are explanations of an approach, not requirements.

This is the naming schema the wizard and all built-in templates use. You are not required to follow it; any naming convention works in Zaklad.

The Modifier slot is optional. When a token has no distinct variant, the third slot acts as the modifier and the path stays three segments: color.text.default. When both variant and modifier are present, paths are four segments: color.background.primary.default.

The layer order is fixed: Foundation feeds Semantic, Semantic feeds Component. Which layers you actually populate is up to you. Foundation is the only requirement. Add Semantic to unlock theming. Add Component to enable per-component fine-tuning. Most projects benefit from all three.

An edit flows downward through the chain: update a foundation value and every semantic token referencing it resolves the new value immediately, carrying that change into every component token, every theme, every platform output, and every Figma variable in one operation.

Semantic tokens reference foundation tokens by path, not by value. The reason is cognitive load. When a developer or designer looks at the chain:

button.bg.default → color.bg.primary → foundation.color.brand.500

They can trace the intent at every level without needing to know the hex. Debugging a theme inconsistency means following a chain of named references, not grepping for a colour value through hundreds of files.

It also means changing the entire system's primary colour is a single edit to one foundation token. Every semantic and component token that references it via the chain updates automatically, across every theme, every platform, every output simultaneously.

The XS–XL sizing context is a fixed part of the platform. It is how Zaklad handles responsive and cross-platform sizing: a single mechanism that covers every device class, from smartwatch to 4K, without any platform-specific logic. We settled on this because it solves all real-world responsive use cases on both web and React Native under one model.

It does not correspond to viewport widths. It describes the density and spatial intent of a surface. Text styles and components carry a separate set of dimension tokens per tier, so font size, line height, spacing, and icon size all step together as the active tier changes.

• XSIoT, smartwatch, and extremely space-constrained surfaces
• SPhone-sized UIs where density matters
• MTablet or compact desktop
• LStandard desktop
• XLLarge desktop and 4K displays

Text styles and components each carry a separate set of dimension tokens per tier: font size, line height, spacing, and icon size all step up or down as the active tier changes. You can lock a platform or screen to specific tiers: use only XS for a smartwatch, XS–S for a mobile-only product, or the full XS–XL spread for a responsive web app. On web, the provider maps viewport widths to tiers automatically; on React Native you supply the active tier directly.

The system is deliberately open-ended. If you are building web only, treat the tiers like CSS breakpoints and let container width drive which tier is active. On cross-platform products, use the tier to communicate intended density independent of the viewport.

All foundation dimension steps derive from a single anchor: dimension.base, which is 16px — the same as 1rem in CSS. Every step is a calculated multiple of that base, so changing the base shifts the entire scale proportionally with no manual updates.

The step names are the multiplier value. dimension.100 means 100 × base ÷ 100 = 16px. dimension.50 = 8px, dimension.200 = 32px, and so on.

Semantic tokens like spacing.margin.small, spacing.margin.large, and spacing.margin.larger reference these foundation steps by path rather than hardcoding a pixel value. Component tokens then reference those semantic tokens. The result is a single change to dimension.base cascades through every spacing value in the system at once.

When you use semantic aliases and calculated foundations together, the system ends up with very few genuine inputs: brand colours, a base dimension, a type scale ratio, a few key font choices. Everything else is derived from those.

A brand refresh becomes a small, predictable changeset. Update the brand colours and the dimension base; the entire system follows. No manual audit of hundreds of token values for inconsistencies.

A new component slots into the existing semantic vocabulary rather than inventing new names. It uses color.bg.primary (the same token as everything else) rather than a new newComponent.primaryBackground that would need to be kept in sync manually.