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.

Interface tokens offer an additional layer of abstraction over the raw tokens. They only ever take another token for value and standardize UI decisions in logical groups: semantic aliases like --ui-border-color (with a value of --base-200) or --success-*, plus every component’s token defaults (--bt-*, --card-*, …). This gives tokens meaning and context, which makes them more intuitive to use, and it’s what makes themes powerful: override one interface token and every rule that consumes it follows.

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.

Heading sizes

Headings use dedicated fluid tokens: each --heading-* interpolates with clamp() from a minimum size (at 480px viewports and below) to a maximum size (from 1024px up), so the type scale tightens on small screens without media queries. The preferred value mixes rem with vw, which keeps browser text zoom working. Override any of these in your own theme to change how a heading level scales.

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.