Skip to content

mCSS structure and organization

Published on

File structure

Update (2026): mCSS now uses native CSS cascade layers: each file is imported into a named @layer, and the layer name decides priority instead of the import order. The former “atoms” layer was also folded into components for v1 (a badge or a button is just a CSS-only component now). The list below reflects the current structure, and your own unlayered CSS always wins over the framework. See the Getting Started docs for the current setup.

If you look at the imports in mcss.css on Github, you’ll get the basic idea behind mCSS structure. Each file belongs to a layer, and the layers keep the cascade working for us as opposed to specificity wars and cascading conflicts. This architecture is based on ITCSS. The basic idea is to organize CSS from least specific/broadest reach to most specific/local override so you get a smooth specificity graph trending upward.

  • Settings: where all the global variables are set (tokens and interface tokens).
  • Base: your reset and normalize rules.
  • Elements: HTML elements defaults, without any classes.
  • Global: layouts like .wrap and .grid and global styling like .prose.
  • Components: component specific styling, from single-class pieces like .bt buttons to full structures.
  • Theme: a swappable theme, one file of token overrides that reskins the whole site.
  • Helpers: local overrides (last layer, so they beat everything above).
  • Your own CSS imports unlayered, after the framework, and wins over all of it.

For more details on what each section does, have a look in the docs.

CSS organization

The idea is to be able to scan a selector’s property at a glance and be able to roughly know what it does and where to find what you need. It doesn’t need to be super strict, but you should think about it as “outside → in” or “general → specific.”

So you first write what affect your element on the page, like positioning, then what affects the element itself, like size, passing, etc. Then what affects what’s inside your element, like text.

Some of it is a little arbitrary, like putting margin after width and height. But as long as the related properties are grouped together mostly logically, the rest is more about personal preference. It doesn’t affect readability.

And please, don’t order them alphabetically… Unless you’re a robot, it won’t help.

.selector {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;


  /* Display & Box Model */
  display: inline-block;
  overflow: hidden;
  width: 100px;
  height: 100px;
  margin: 10px;
  padding: 10px;
  border: 10px solid #333;


  /* Text */
  text-align: right;
  font-family: sans-serif;
  font-size: 16px;
  line-height: 1.4;


  /* Color */
  background: #000;
  color: #fff;


  /* Other */
  cursor: pointer;
  z-index: 10;
}
Reply by email