Docs :: Getting Started

The file structure is based on ITCSS, but with important differences detailed below. The basic idea is to organize your files in different layers so that your CSS rulesets are organized from global low specificity to local high specificity. 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, and not specificity) decides who wins. Anything you write outside the layers beats the framework by default, so mCSS always gets out of your way. Below is an overview of each layer. The full documentation of most layers is available from the sidebar.

This is how mCSS is organized. (Github source.)

@layer settings, base, elements, global, atoms, components, pages, 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.theme.default.css) layer(settings);

@import url(./base.reset.css) layer(base);

@import url(./elements.sectioning.css) layer(elements);
@import url(./elements.text.css) layer(elements);
/* etc. */

@import url(./global.grid.css) layer(global);
@import url(./global.wrap.css) layer(global);
/* etc. */

@import url(./atom.button.css) layer(atoms);
/* etc. */

@import url(./component.notice.css) layer(components);
/* etc. */

@import url(./help.spacing.css) layer(helpers);
/* etc. */

/* Your site's own CSS imports UNLAYERED, after the framework:
   it wins over every mCSS layer without fighting specificity. */
@import url(./site/myComponent.css);

The easiest ways to use mCSS in your own project:

• Drop-in file: grab dist/mcss.css (or dist/mcss.min.css), the whole framework in one file, no build step needed.
• Individual files: every framework file is also available pre-processed in dist/css/ (with dist/css/mcss.css as an @import index), so you can copy just the layers you need.
• Source files: copy src/styles/framework/ if you run PostCSS yourself (the source uses @custom-media, which needs postcss-preset-env).

Run npm run build:css in the repo to produce dist/ from source.

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.
• 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.
• Themes is an abstraction level to stadardize common values accross elements and components. For instance, you could use --light-border-color throughout your components instead of the lower level token --base-200.

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 inlcluded 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)

Atoms

Atoms are the smallest explicit styling units in mCSS, applying CSS classes to individual HTML elements without needing a dedicated HTML/Astro component. For example, the .button atom can style a <button> or <a> element, but since not all <a> tags are buttons, atoms provide targeted styling flexibility.

Find atoms documentation in the components section, as they’re designed to work together seamlessly.

Components

Self contained syles of single components. The mCSS framework is designed to be used on its own, allowing you to create your own components. But a collections of components built on top of mCSS is in developement.

See the components section for more info.

Pages

Page specific design elements and adjustments. These files are project specific and none are included in mCSS by default. The pages layer sits just below helpers, so it’s also the right place for your own rules that helper classes should still be able to override (@layer pages { … }).

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. Because helpers is the last framework layer, they beat every other mCSS layer without needing !important, but your own unlayered CSS still beats them. 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, so you never fight the framework’s specificity.

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="formInput" type="text" />
  <input class="formSubmit is-disabled" type="submit" />
</form>

CSS:

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

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

One gotcha to keep in mind: nesting a state inside its block compiles to a two-class selector (.formSubmit.is-disabled), which beats single-class modifiers like .formSubmit-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;
}

Targetting 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 propertie 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.

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