Docs :: Default Theme

Every design value in mCSS (colors, fonts, spacing, component styling) lives in the default theme. Your own theme should be imported after it and just override what it needs.

Never edit the default theme files. Keep your design decisions in your own theme, so updating the framework is easy.

Activate the default theme right after the framework, then (optionally) your own theme:

@import url(./framework/mcss.css);
@import url(./framework/mcss.components.css); /* optional */
@import url(./framework/theme.default.css);
@import url(./site/theme.starter.css); /* your theme */

Theme files are self-layered and your theme goes in the theme.user layer:

@layer theme.user {
  /* […] */
}

mCSS is set up so that, regardless of how you load your theme (@import, <link>, or bundler), it always overrides the default theme.

Copy theme.starter.css and start overriding:

• Tokens first. Most themes never need a selector: raw tokens for the palette and type, UI tokens for general UI changes, and component tokens for details.
• Style rules only for what tokens can’t express: pseudo-elements, nth-child rhythm, font smoothing, text-wrap, etc. Your theme file is the one place where overriding framework classes and HTML elements from other files is ok.
• Check tokens before writing a style rule. The page is already painted from --body-background-color, --text-color, and --text: set those instead of writing a body rule for background, color, or font.
• No !important. It will break the layer system. And if you need !important, it’s a sign you’re doing something wrong.

A theme can also be a complete, distributable style. mCSS ships with the theme.wireframe.css example. (Flip the switcher on the marketing template to see it live.)

A full theme is an entry that imports the default theme itself and overrides on top, so you activate it INSTEAD of the default:

@import url(./framework/mcss.css);
/* theme.default.css is swapped */
@import url(./framework/theme.wireframe.css);

The wireframe file is a good read if you’re planning a full theme. Token overrides do most of the work (grayscale palette, handwriting font stack, “paper cutout” shadows), a few style rules cover the rest (wavy underlines, tilted cards), and it’s deliberate about what it leaves alone: the focus ring stays crisp, and text stays high-contrast.

Tokens are CSS custom properties, split in two files:

• Raw tokens are named for what they are: raw values like colors, type sizes, spacing, radii, etc.
• UI tokens are named for what they’re for: they map raw tokens to elements and components.

Because components read var(--ui-border-color) instead of a raw hex value, one override can have three levels of blast radius:

@layer theme.user {
  :root {
    /* Whole palette shifts */
    --base-950: #1a1208;

    /* Every bordered surface at once */
    --ui-border-color: light-dark(var(--base-300), var(--base-600));

    /* Single component override */
    --bt-border-radius: 0;
  }
}

That’s why small theme files can go far with a handful of token overrides.

When you start a new project, put your design’s raw token values in your own theme: your base and primary colors, your font stacks, and whatever else your design calls for. The defaults are sensible and things like spacing might not need to change.

Then continue overriding UI tokens provided by mCSS as you go, and creating your own when needed. Do not add hard-coded “magic numbers” anywhere else but in your theme’s tokens.

UI tokens are named for what they’re for: semantic aliases (--ui-border-color), element defaults (--heading-font, --input-padding, etc.), and every component’s defaults (--badge-color, --card-spacing, etc.).

A UI token usually takes another token for value: a UI token when the meaning is shared (--input-border-color is --ui-border-color), or a raw token when the value should stay in sync with the rest of the design (--fieldset-padding is --sm3). Hard-coded values are for the few places where that sync would be wrong: content (separator strings, icon URLs), geometry tuned to one control (--toggle-width), and element-relative em measures.

For your own components, there’s no hard and fast rule about which kind of token to use. If the same style comes up in several places with the same meaning, a new UI 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 UI 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.