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. Below is an overview of each layer. The full documentation of most layers is available from the sidebar.

This how mCSS is organized. (Github source.)

@import url(./settings.tokens.css);
@import url(./settings.media-queries.css);
@import url(./settings.mixins.css);
@import url(./settings.theme.default.css);

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

@import url(./elements.sectioning.css);
@import url(./elements.text.css);
@import url(./elements.text.quotes.css);
@import url(./elements.media.css);
@import url(./elements.table.css);
@import url(./elements.form.css);
@import url(./elements.interactive.css);

@import url(./global.grid.css);
@import url(./global.wrap.css);
@import url(./global.layout.css);
@import url(./global.prose.css);

@import url(./atom.button.css);

/* Your content - start. */

@import url(./component.header.css);
/* etc. */

@import url(./page.blog.css);
/* etc. */

@import url(./external.astro.css);
/* etc. */

/* Your content - end. */

@import url(./help.layout.css);
@import url(./help.spacing.css);
@import url(./help.typography.css);
@import url(./help.colors.css);

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.

Atoms

Atoms are similar to components. The main distinction between components and an atoms is that the atoms don’t have a corresponding HTML/Astro component. For example, the .button atom can be added to a <button> or a <a> HTML element.

• .button (with a .bt shorthand) button.

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.

External

The external layer is where all the CSS you don’t have control over should go. This includes CSS from npm packages, plugins, etc.

Helpers

Helpers provide high specificity 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. Read the docs for more info on this.

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 {
}

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!