Docs :: Tokens

Design tokens are the “atoms” of a design system. They define the design elements of a user interface, such as colors, typography, and spacing.

In mCSS, tokens are CSS custom properties that provide a flexible, coherent, and harmonious set of values designed to make implementing UI/UX projects fast and easy.

When you start a new project, open settings.tokens.css and change the values of as many tokens as necessary to match the design you’re planning to implement. (Things like spacing might not need to change, but you’ll almost certainly need to customize your base and primary colors for instance.) For deviations you want to keep swappable, put the overrides in a theme instead of editing the defaults.

The same discipline applies to the CSS you write on top of the framework: no raw color and no raw type size in a component.*.css file. If your theme does not name the value you need, add a token to the theme and use that. A #8a5500 or a 1.0625rem sitting in a component is a design decision nobody can find, and the second use of it will be a slightly different number. Spacing is more forgiving (a 2px optical nudge is a property of that component and belongs to it), but color and type size are the design system, and the design system lives in one file.

Interface tokens are the decisions layer over the raw scales. Every one is named for what it’s for (an element, a component, or a shared meaning) and standardizes UI decisions in logical groups: semantic aliases like --ui-border-color or --success-*, element defaults (--heading-*, --input-*, …), plus every component’s token defaults (--bt-*, --card-*, …). That naming is the whole split between the two files: a token named for what it is (a step on a scale, like --sm1 or --base-500) lives in settings.tokens.css; a token named for what it’s for lives in settings.ui.css. This gives tokens meaning and context, and it’s what makes themes powerful: override one interface token and every rule that consumes it follows.

An interface token usually takes another token for value: another interface token when the meaning is shared (--input-border-color is --ui-border-color), or a scale token when the value should follow the system scales (--fieldset-padding is --sm3). A raw value is correct only where following the scales would be wrong: content like separator strings and icon URLs, geometry tuned to one control (--toggle-width), and element-relative measures like the em heading spacing, which tracks each heading’s own size instead of the page scale. The test: if a theme retuned the scales, should this value follow?

elements.* and global.* files tend to use interface tokens, while component.* files mix them with low level tokens. There are no hard and fast rules about the type of token you should use in your custom component. Just try to think where else this style is used in the design and if it comes up in many places with the same context, a new interface token is probably the best option.

Check out tints.dev if you want to make your own palettes programmatically.

Dimension tokens can be used anywhere you need to set margin, padding, width, height, etc.

Font stack

There are 3 font stacks set up by default for the font-family CSS Property.

These stacks are optimized for fonts available on device, to maximize for speed and alleviate any layout shifts or flashes. You can find more stacks at Modern Font Stacks.

If you’d like to bring in your own fonts or Google fonts, you can override the display and text tokens inside your theme file.

Font size

Check out typescale.com if you need help creating your own sizes.

The heading font sizes (--heading-font-size-h1…-h6) build on this scale but are interface tokens; they’re documented with the headings themselves.

Font weight

Letter spacing

Line height

It wouldn’t be super useful to list the values here. You can look at them on Github if you’re curious.