Docs :: Getting Started

The file structure is a simplified ITCSS: files are organized in layers going from broad and generic (tokens, element defaults) to specific and local (components, one-off helpers). When done right, it takes care of all the common “shortcomings” of CSS such as specificity wars and cascading conflicts.

mCSS implements this with native CSS cascade layers: every framework file is imported into a named @layer, and the layer order (not the import order or specificity) decides who wins. Anything you write outside the layers beats the framework by default, so mCSS always gets out of your way. The only exception is helper classes, which use !important so they can override anything, including your own CSS.

Two folders

The styles live in two folders, and the split is the methodology in miniature:

• framework/: mCSS itself, every file in a named layer. You copy it and mostly leave it alone: customization goes through the settings.* tokens, a theme, or your own CSS, not through edits scattered across framework files.
• site/: this site’s own CSS, imported unlayered, after the framework, so it wins without specificity games. Because those files are unlayered, the order you import them in is important so make sure you have a clear mental model of ITCSS principles before delving in. You can also refer to mCSS own /site’s setup as a reference.

The layers, in order

Each layer only ever loses to the ones after it. The sections below detail each one; most have full docs in the sidebar.

The framework’s own entry, framework/mcss.css, makes the split concrete: it declares the layer order and puts every core framework file in its layer. You never edit it:

/* framework/mcss.css (abridged) */
@layer settings, base, elements, global, components, theme, helpers;

/* Build-time only (media queries + mixins definitions) */
@import url(./settings.media-queries.css);
@import url(./settings.mixins.css);

@import url(./settings.tokens.css) layer(settings);
@import url(./settings.ui.css) layer(settings);
@import url(./base.reset.css) layer(base);
@import url(./elements.text.css) layer(elements);
@import url(./global.grid.css) layer(global);
@import url(./help.spacing.css) layer(helpers);
/* etc. — note: no component.* and no theme.* imports here */

Two layers are declared but never filled by this entry. The theme slot is yours (see below), and the components slot belongs to the component library, which lives in its own entry, framework/mcss.components.css. Import it alongside mcss.css for the full library, or skip it and build your own components; the layer order declared in mcss.css decides priority either way, so import order between the two doesn’t matter.

Your site’s entry (this site’s is _global.css) pulls in the framework, activates at most one theme, then imports your own CSS unlayered:

/* your entry file */
@import url(./framework/mcss.css);

/* Optional: the mCSS component library. Skip it if you build
   your own components. */
@import url(./framework/mcss.components.css);

/* Optional: activate ONE theme, a swappable style. Theme files are
   self-layered (@layer theme inside the file), so no layer()
   annotation. None imported = the default look. */
/* @import url(./framework/theme.wireframe.css); */

/* Your own CSS: UNLAYERED, after the framework. Its normal
   declarations win over every mCSS layer without fighting
   specificity. One exception: helpers are !important and beat
   unlayered CSS too. */
@import url(./site/global.layout.css);
@import url(./site/component.header.css);
@import url(./site/page.blog.css);
/* etc. */

Settings

Settings are where all custom properties are set.

• Tokens is where you set default values for sizes, font stacks, colors, transitions, etc. See the docs for all the values available by default.
• Interface tokens are an abstraction level to standardize common values across elements and components. For instance, components use --ui-border-color instead of the lower level token --base-200, so one override restyles every bordered surface.
• Media queries include responsive sizes, as well as user preferences like color schemes, reduced motion, etc. See media queries docs.
• Mixins is optional. It is not used in other parts of mCSS by default but can be useful to streamline your own components’ code. It requires a PostCSS plugin to work.

Base

• Simple reset/normalize.

HTML Elements

The default styling of all HTML elements, without classes.

• Sectioning: header, footer, etc.
• Text: a, p, etc.
• Quotes: adds the correct quotes depending on language.
• Media: img,video, etc.
• Table: table, th, etc.
• Form: input, button, etc.
• Interactive: dialog, details.

Global

Global styles included out of the box:

• A responsive grid system.
• A full feature wrapper.
• Common global site layouts.
• Typography, via the .prose class, for long form text, like articles, etc.
• Accessibility (A11Y) specific classes.
• Basic @keyframes animations (e.g., fade in/out)

Components

Self-contained styles for single components, one block per file. The mCSS framework is designed to be used on its own, allowing you to create your own components, but a collection of components built on top of mCSS is included. It ships in its own entry file (mcss.components.css, or dist/mcss.components.css as a drop-in): mcss.css only declares the components layer slot, so the library is opt-in.

Some components are CSS-only: a single class on a single element, with no Astro component because there is no markup structure to encapsulate. For example, the .badge class on a <span> is the whole badge, and the .bt class can style a <button> or an <a> (styling that has to be opt-in, since not all links are buttons). Their docs live in the components section like everything else, marked “CSS-only”.

Theme

This is the one layer the framework declares but never fills: mcss.css imports no theme, and the default look IS the empty theme layer. The theme itself is really part of your CSS: one theme.*.css file of token overrides plus optional style rules that you activate from your own entry file, whether it’s a shipped theme like theme.wireframe.css or one you wrote yourself. See the theme docs for how themes work and how to build one.

Helpers

Helpers provide classes for “one-off” local overrides. They’re similar to utility classes from other frameworks, with a critical difference: they’re meant to be used as a last resort and as sparingly as possible. Helper declarations use !important, and important declarations inside a layer beat unlayered CSS, so a helper class overrides everything on that element, including your own CSS. Read the docs for more info on this.

Your CSS (unlayered)

Everything you write outside the mCSS layers (your components, page styles, and any third-party CSS you don’t control) simply imports after the framework, unlayered. Unlayered CSS wins over all layered CSS for normal declarations, so you never fight the framework’s specificity. The one exception is helper classes: their !important declarations win even over unlayered CSS.

It goes inside your site/ folder, in this order:

• theme.*.css for your theme, at most one active. This is the one file of yours that is not unlayered: a theme wraps its own content in @layer theme, deliberately dropping into the framework’s theme slot so it restyles the framework defaults while the rest of your CSS below still beats it.
• global.*.css for site-wide additions to the framework’s globals.
• component.*.css for your own blocks (most of your CSS should end up here)
• page.*.css for the rare page-specific styles
• external.*.css for CSS you don’t control, ie. plugins

Because those files are unlayered, the order you import them in is important, so make sure you have a clear mental model of ITCSS principles before delving in. You can also refer to mCSS own /site’s setup as a reference.

Page classes go on the <body>, next to the layout scaffold classes, not on <main>:

<body class="layout layout-centered blog blog-index"></body>

A page class is mostly a scope for token overrides, and tokens only inherit down: from the body they reach the whole scaffold, while a class on <main> can’t touch anything above or beside it (.layout_content, the header, the footer). This site’s blog index is the worked example: articles keep the default reading column, and one body class widens the listing page.

.blog-index {
  --layout-content-width: 100%;
}

Classes in mCSS are inspired by BEM, but they’re simpler to use and easier to look at.

You can use standard BEM, the even more verbose BEMIT, or any other syntax you’d like. But the mCSS syntax gets you 90% of the same benefits without any drawbacks, even on large projects involving many devs.

Blocks, elements, and modifiers

States

Here’s how you implement a state in BEM vs. mCSS.

HTML:

<!-- BEM -->
<form class="form">
  <input class="form__input" type="text" />
  <input class="form__submit form__submit--disabled" type="submit" />
</form>

<!-- mCSS -->
<form class="form">
  <input class="form_input" type="text" />
  <input class="form_submit is-disabled" type="submit" />
</form>

CSS:

/* BEM */
.form__submit--disabled {
}

/* mCSS */
.form_submit {
  &.is-disabled {
  }
}

One gotcha to keep in mind: nesting a state inside its block compiles to a two-class selector (.form_submit.is-disabled), which beats single-class modifiers like .form_submit-lg. That’s usually what you want: states describe what’s happening right now, so they should win. But it means a state block is the wrong place to declare default values for custom properties. Declare defaults on the block itself, let modifiers override them, and only use the properties inside the state. Otherwise your size and color modifiers will mysteriously stop working the moment the state class shows up.

.avatar {
  /* ✅ defaults live on the block… */
  --status-dot-size: 12px;

  &.is-online {
    /* ❌ …not here: this would override .avatar-xl's dot size */
    &::after {
      /* ✅ states just consume the properties */
      width: var(--status-dot-size);
    }
  }
}

.avatar-xl {
  /* modifiers can now override the default */
  --status-dot-size: 20px;
}

Targeting HTML elements within a component

When using mCSS syntax within a component, it’s considered overkill to create a class for every single HTML element you need to target.

For example, this is acceptable (and recommended) CSS for the tags component (component.tags.css):

.tags {
  li {
    […]
  }

  a {
    […]
    &:hover {
      […]
    }
  }
}

Modifiers and component variations

When using modifiers to create different variations of a component, it’s recommended to use local custom properties if possible instead of overriding the CSS directly.

/* Don't do that */
.component {
  color: blue;
}

.component-variation {
  color: red;
}

/* Do that instead */
.component {
  --color: blue;
  color: var(--color);
}

.component-variation {
  --color: red;
}

See the implementation of the notice component for a real life example.

Any questions or feedback? Head over to the Github discussions!

mCSS targets Baseline 2024: it freely uses cascade layers (@layer), nesting, :has(), light-dark(), @scope, text-wrap: balance, and relative color syntax, all natively, with no polyfills. In practice that means the current versions of Chrome, Edge, Firefox, and Safari, going back roughly two years.

How things degrade in older browsers:

• Cascade layers, nesting, :has() (2022–2023): load-bearing. Browsers without them are not supported.
• light-dark() (mid-2024): colors fall back to the light palette.
• @scope (mid-2024): only affects .prose internals; spacing between prose blocks and headings loses one refinement.
• Scroll-driven animations: the ReadProgressBar component detects support and falls back to JavaScript automatically.
• sibling-index(), CSS random(), SVG displacement filters: used only by the wireframe theme for per-element sketch variation; without them the theme keeps its fixed hand-drawn look.

The exact compile floor lives in .browserslistrc (defaults and supports css-cascade-layers).