# mCSS: full reference > mCSS is a modern CSS framework and component library for websites: real CSS, real markup, zero build step, built on native cascade layers. It is not a dependency; you copy the files into your project and own them. This file concatenates every docs and components page. A per-page index is at /llms.txt. # Marketing Template > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/template A complete marketing one-pager built from nothing but the framework and the component library: no site CSS, no custom components, no JavaScript beyond what the components ship with. It is both a working template and the proof that the library composes into a real page. **[Open the live template](/templates/marketing)**, and use the switcher in its bottom corner to flip the whole page between the default look and the [wireframe theme](/docs/themes): same markup, one stylesheet swapped. The whole page sits on the base [`.layout` scaffold](/docs/global#layouts): `` wrapping a `.layout_content` main, which gives the header / content / footer app shell with a sticky footer. Inside that shell, from top to bottom: - [Banner](/components/banner) - [Header](/components/header) (sticky, with mobile menu) - [Hero](/components/hero) (full variant on a gradient) - [Section](/components/section) with a [feature grid](/components/featuregrid) ([Tiles](/components/tiles) + FeatureItems), a filled Section of [Testimonials](/components/testimonial) on the grid - [Pricing](/components/pricing) - [FAQ](/components/faq) with exclusive-open items - Closing-CTA [Section](/components/section) - [Footer](/components/footer). ## Using it Copy [`marketing.astro`][srcTemplate] into your own `src/pages/` (as `index.astro`, most likely) and definitely swap the copy, links, and pricing for your own. Everything it needs is listed below; if you copied the whole framework and component library per [Getting started](/docs/start), you already have all of it. Two blocks in the file exist for the docs demo and are safe to touch: - The **theme switcher** at the bottom (marked with a comment) is just for the demo. Delete it. - The **inline `@layer` statement** at the top of `` pins the cascade-layer order before any stylesheet loads. Only needed when a theme is loaded as a separate `` (layer priority is set by first occurrence, and the theme link may parse first). If you activate your theme with an `@import` in your entry CSS instead, you can drop it.
| What | Files | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The page | `src/pages/templates/marketing.astro` ([source][srcTemplate]) | | Astro components | `Banner`, `Header`, `Hero`, `Section`, `Tiles`, `FeatureItem`, `Testimonial`, `Avatar` (used by Testimonial), `PricingCard`, `Faq`, `FaqItem`, `Footer` ([source][srcComponents]) | | Framework CSS | The framework entry `mcss.css` covers every component and layout style used ([source][srcFramework]) | | Theme (optional) | `theme.wireframe.css`, only if you keep the switcher ([source][srcWireframe]) | | Icons | `menu`, `x`, `check`, `circle-check`, `moon-star`, `external-link`, `rotate-ccw`, `mail`, `heart` ([source][srcIcons]) | | Scripts | `src/scripts/utilities.js` (the Header's scroll throttle) ([source][srcScripts]) |
[srcTemplate]: https://github.com/minimaldesign/mCSS/blob/main/src/pages/templates/marketing.astro [srcComponents]: https://github.com/minimaldesign/mCSS/tree/main/src/components [srcFramework]: https://github.com/minimaldesign/mCSS/tree/main/src/styles/framework [srcWireframe]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/theme.wireframe.css [srcIcons]: https://github.com/minimaldesign/mCSS/tree/main/src/assets/icons [srcScripts]: https://github.com/minimaldesign/mCSS/blob/main/src/scripts/utilities.js ## Useful recipes Even if you don't use the whole page, three patterns in it transfer anywhere: - **The closing CTA** is not a component; it is a `Section` with `variant="primary"` and a `.section_actions` row (see the [Section recipes](/components/section)). - **The pricing row** is three [PricingCards](/components/pricing) on the plain [grid](/docs/global#grid) (`col="1" col-md="3"`), with `highlighted` on the recommended tier. - **Exclusive-open FAQ** items share a `name`, so the browser closes one when another opens. Native `
`, no JavaScript. --- # Getting Started > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/start mCSS is both a CSS framework and a methodology. You need to first understand the methodology to use the framework correctly. There are 3 main parts to the methodology. 1. The file structure 1. The CSS syntax 1. The component architecture Once you've read through the basics below, the best way to understand how it all comes together is to have a look at the [source code][src]. (Video tutorial coming soon!) ## mCSS file structure
The file structure is a simplified [ITCSS][1]: files are organized in [layers][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][3] wars and cascading conflicts. mCSS implements this with native [CSS cascade layers][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][helpers], 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/`][framework-src]**: mCSS itself, every file in a named layer. You copy it and mostly leave it alone: customization goes through the `settings.*` tokens, a [theme](/docs/themes), or your own CSS, not through edits scattered across framework files. - **[`site/`][site-src]**: 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][1] principles before delving in. You can also refer to mCSS [own `/site`'s setup][4] 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.
| Layer | Files | What lives there | | ------------- | ------------- | -------------------------------------------------------- | | `settings` | `settings.*` | Tokens, interface tokens, media queries, mixins | | `base` | `base.*` | Reset/normalize | | `elements` | `elements.*` | Default styling of bare HTML elements | | `global` | `global.*` | Grid, wrap, layout scaffolds, prose, a11y | | `components` | `component.*` | One self-contained block per file | | `theme` | `theme.*` | At most one active theme (token overrides + style rules) | | `helpers` | `help.*` | `!important` one-off overrides, last resort | | _(unlayered)_ | your own CSS | Beats every layer above, except helpers |
Two entry files make the split concrete. The framework's own, [`framework/mcss.css`][mcss-entry], declares the layer order and puts every framework file in its layer. You never edit it: ```css /* 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(./component.button.css) layer(components); @import url(./help.spacing.css) layer(helpers); /* etc. */ ``` Your site's entry (this site's is [`_global.css`][4]) pulls in the framework, activates at most one theme, then imports your own CSS unlayered: ```css /* your entry file */ @import url(./framework/mcss.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. */ ``` [cascade-layers]: https://developer.mozilla.org/en-US/docs/Web/CSS/@layer [mcss-entry]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/mcss.css ### How to import mCSS in your project #### Drop-in file Grab [`dist/mcss.css`][dist-css] (or [`dist/mcss.min.css`][dist-min]), the whole framework in one file, no build step needed. The easiest way to import, but the file size won't be optimized to your specific needs. #### Individual files Every framework file is also available pre-processed in [`dist/css/`][dist-dir] (with [`dist/css/mcss.css`][dist-index] as an `@import` index), so you can copy just the layers you need. #### Source files Copy [`src/styles/framework/`][framework-src] if you run PostCSS yourself (the source uses `@custom-media`, which needs [postcss-preset-env][presetEnv]). Run `npm run build:css` in the repo to produce `dist/` from source. [dist-css]: https://github.com/minimaldesign/mCSS/blob/main/dist/mcss.css [dist-min]: https://github.com/minimaldesign/mCSS/blob/main/dist/mcss.min.css [dist-dir]: https://github.com/minimaldesign/mCSS/tree/main/dist/css [dist-index]: https://github.com/minimaldesign/mCSS/blob/main/dist/css/mcss.css [framework-src]: https://github.com/minimaldesign/mCSS/tree/main/src/styles/framework [site-src]: https://github.com/minimaldesign/mCSS/tree/main/src/styles/site ## Detailed description of each layer
### Settings Settings are where all custom properties are set. - [Tokens][5] is where you set default values for sizes, font stacks, colors, transitions, etc. See [the docs][5] for all the values available by default. - [Interface tokens][interfaceTokens] 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][6] include responsive sizes, as well as user preferences like color schemes, reduced motion, etc. See [media queries docs][6]. - **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][7] 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][grid]. - A full feature [wrapper][wrap]. - Common global site [layouts][layout]. - [Typography][prose], via the `.prose` class, for long form text, like articles, etc. - [Accessibility][a11y] (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][components] built on top of mCSS is included. 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 `` is the whole badge, and the `.bt` class can style a `

### Meter ```html 2 out of 10 5 out of 10 8 out of 10 ```

2 out of 10

5 out of 10

8 out of 10

### Progress

70%

## Media
| File name | Source | | -------------------- | ------------------ | | `elements.media.css` | [Github][srcMedia] | [srcMedia]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.media.css
  • Plain `` element Saxophonist playing in Central Park
  • `
    ` element with `` element
    Saxophonist playing in Central Park
  • `
    ` element with `` and `
    ` elements
    Saxophonist playing in Central Park
    Here is a caption for this image.
  • `
    ` element with a `` element
    Saxophonist playing in Central Park
### Audio
### Video
### Canvas canvas
### Inline Frame
### Inline SVG ## Interactive
| File name | Source | | -------------------- | ------------------ | | `elements.interactive.css` | [Github][srcInteractive] | [srcInteractive]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.interactive.css ### Details & Summary
Expand for details

Lorem ipsum dolor sit amet consectetur adipisicing elit. Cum, odio! Odio natus ullam ad quaerat, eaque necessitatibus, aliquid distinctio similique voluptatibus dicta consequuntur animi. Quaerat facilis quidem unde eos! Ipsa.

### Dialog

A random quote you might enjoy…

If you want to awaken all of humanity, then awaken all of yourself. If you want to eliminate the suffering of the world, then eliminate all that is negative in yourself. Truly the greatest gift you have to give is that of your own self-transformation.

 --- # Global Styles > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/global ## Grid
| File name | Source | | ----------------- | ----------------- | | `global.grid.css` | [Github][srcGrid] |
[srcGrid]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/global.grid.css The grid system is extremely easy to use, light weight, and very flexible. It uses the [CSS grid property](https://developer.mozilla.org/en-US/docs/Web/CSS/grid) under the hood, but it lets you set up your layouts directly into your HTML. The implementation is heavily inspired by [Raster](https://github.com/rsms/raster). ### Syntax It's composed of 2 classes: `.grid` for the container, and `.grid_item` for each grid item. The default grid gap is defined as a custom property in [`settings.ui.css`](/docs/tokens#interface-tokens) and is responsive: `16px` (`--sm1`) on small screens, stepping up to `24px` (`--sm3`) at the `--md` breakpoint (768px). You can override `--grid-column-gap` and `--grid-row-gap` globally in your own theme, or on a specific `.grid` element. A `grid-flush` modifier is available if you don't want any gap. Because `.grid` reads its gaps from those two custom properties, overriding a specific grid is just a matter of setting them on the element. Add a class of your own: ```css .photoWall { --grid-column-gap: var(--xs2); --grid-row-gap: var(--xs2); } ``` ```html
    ...
``` You define the amount of columns of your grid with a custom `col` attribute and the position/width of your grid_items with the custom `span` attribute. The `span` property syntax follows these 5 patterns: - `row`: the grid_item spans a full row - `3`: the grid_item start in the next column and spans 3 columns. - `3-5`: the grid_item starts in column 3 and ends in column 5. - `3+5`: the grid_item starts in column 3 and spans for 5 columns. - `3..`: the grid_item starts in column 3 and spans the remainder of rows. Both the `col` and `span` attributes have responsive versions, which use [the "mobile first" approach][1] of the `--*-n-above` media queries. The available tiers are **`-md`, `-lg`, and `-xl`** (`col-md`, `span-lg`, etc.); other suffixes like `col-sm` or `col-xxl` don't exist and are silently ignored. Grids support up to 24 columns. (The file is generated by `src/tools/generate.global.grid.cjs`; add a tier there if you need one.) [1]: /docs/media-queries#recommended-responsive-setup The custom attribute will not validate. If this is important to you, you'll need to change the attributes to `data-col` and `data-span` in both the CSS and HTML. I personally prefer to use shorter, more legible attributes. Check this thread on Github if you'd like to read more than you've ever wanted to know about [custom attributes and validation](https://github.com/whatwg/html/issues/2271). ### Examples #### Different types of spans 9 colum grid, with all types of spans.
2
4-5
6..
2-3
5..
2+3
6+2
row
4+2
```html
2
4-5
6..
2-3
5..
2+3
6+2
row
4+2
``` #### Responsive grid The grid layout follows a "mobile first" approach using `--*-n-above` media queries. The following example goes from 1 → 4 → 9 → 12 columns. (Resize window to see it in action.)
1
2
3
4
5
6
7
8
9
10
11
12
```html
[…]
``` ## Wrap
| File name | Source | | ----------------- | ----------------- | | `global.wrap.css` | [Github][srcWrap] |
[srcWrap]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/global.wrap.css The `.wrap` global class is a simple content wrapper that will center your content on the page and add some left/right padding on small viewports. The content column comes in three width presets, set with a modifier on the wrapper: `.wrap-sm`, `.wrap-md`, and `.wrap-lg`. A bare `.wrap` uses the `md` width (`minmax(200px, 70ch)`). There is also a `.wrap_content-fullBleed` modifier for children that should extend to the full size of the viewport. See [demo](/demos/wrap). ### Syntax ```html
``` ### Settings You can customize 3 diffent sizes of left/right padding for responsive designs as well as the width of your content. The values below are set in `settings.ui.css`.
| token | value | Description | | ----------------- | ---------------------- | -------------------------------- | | `wrap-spacing` | `var(--sm1)` | default left/right padding | | `wrap-md-spacing` | `var(--sm3)` | left/right padding tablet and up | | `wrap-lg-spacing` | `0` | left/right padding laptop and up | | `wrap-width-sm` | `minmax(200px, 55ch)` | narrow column (`.wrap-sm`) | | `wrap-width-md` | `minmax(200px, 70ch)` | reading column (`.wrap-md`) | | `wrap-width-lg` | `minmax(200px, 900px)` | wide column (`.wrap-lg`) | | `wrap-width` | `var(--wrap-width-md)` | width of a bare `.wrap` |
- More info on [themes](/docs/themes). - More info on [responsive setup](/docs/media-queries#recommended-responsive-setup). ## Layouts
| File name | Source | | ------------------- | ------------------- | | `global.layout.css` | [Github][srcLayout] |
[srcLayout]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/global.layout.css Page-level scaffolds: the skeleton between your `body` tag and your content. Every variant extends the same `.layout` base, an app shell with a header, a stretching content area, and a sticky footer. ### Syntax ```html
…
…
…
``` The header and footer are optional: a bare `.layout` with only `.layout_content` still gives you a full-height page (that's what `.layout-cover` relies on). ### The layouts Each thumbnail links to a full-page demo built from labeled color blocks. The demos are the honest version: resize the window to see the breakpoint collapses, sticky footer, and full-viewport behavior that a static diagram can't show.
| Class | What it's for | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.layout` | The base app shell: header / content / footer with a sticky footer. Required by every variant, usable alone. | | `.layout-centered` | A single centered reading column (articles, blog posts, legal pages). Width capped at `--layout-content-width`. | | `.layout-sidebar` | Aside + main from the `--md` breakpoint, single column below it (aside follows source order). | | `.layout-sidebar-end` | Compose with `.layout-sidebar` to move the aside to the reading end. ("End", not "right": columns follow the writing direction.) | | `.layout-docs` | Documentation shell: nav aside + main + TOC aside (`.layout_content_aside-toc`). One column below `--md` with the asides hidden, nav + main from `--md`, TOC from `--lg`. | | `.layout-split` | Two equal full-height panes (the direct children of `.layout_content`), stacked below `--md`. Auth screens, image + content landings. | | `.layout-cover` | Full-viewport (`100dvh`) cover with content centered both ways. Landing, 404, coming-soon pages. |
`.layout-docs` hides both asides below the `--md` breakpoint. That's deliberate: docs navigation belongs in your header menu on small screens (that's how mcss.dev does it). If your aside content has no other way in, use `.layout-sidebar`, which stacks instead of hiding. ### The main column is a container Every scaffold's main column (`.layout_content_main`) is a named [size container](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries) (`container: main / inline-size`). Container-responsive components ([Tiles](/components/tiles)) pick their column count from it instead of the viewport, and your own rules can respond to it with `@container main (width >= …)`. ### Settings Column widths come from three tokens in `settings.ui.css`. `--layout-toc-width` accepts any grid track size; the `1fr` default lets the TOC absorb whatever space the main column doesn't use.
| token | value | Description | | ------------------------ | ------- | ---------------------------------------------------------- | | `--layout-content-width` | `70ch` | main column cap (`.layout-centered`, `.layout-docs`) | | `--layout-aside-width` | `245px` | aside column (`.layout-sidebar`, `.layout-docs`) | | `--layout-toc-width` | `1fr` | TOC column (`.layout-docs`) |
Override them globally in your [theme](/docs/themes), or per-layout with a scoped rule. mcss.dev itself runs its docs on `.layout-docs` and layers its own specifics on top ([source][srcSiteLayout]): a wider `77ch` reading column and sticky side navs. That file is the pattern to copy when a scaffold gets you 90% of the way. [srcSiteLayout]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/site/global.layout.css ## Prose
| File name | Source | | ------------------ | ------------------ | | `global.prose.css` | [Github][srcProse] |
[srcProse]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/global.prose.css The global `.prose` class can be used anywhere you need basic typography for long form text, like articles, blog posts, etc. It makes spacing between paragraphs, lists, tables, etc. consistent. This spacing can be modified in your [theme](/docs/themes) via the `--prose-spacing` token. The `.prose` class also adds extra styling for `ol`, `ul`, and `code` elements. ## Accessibility
| File name | Source | | ----------------- | ----------------- | | `global.a11y.css` | [Github][srcA11y] |
[srcA11y]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/global.a11y.css This is where accessibility specific classes go. Currently a WIP as [components are being created](/components/start). ## Animation
| File name | Source | | ---------------------- | ---------------------- | | `global.animation.css` | [Github][srcAnimation] |
[srcAnimation]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/global.animation.css Basic fade in/out animations with flexible start/end opacity values. (More info about [forwards](/blog/css-animation-fill-modes)) ```css .element { opacity: 0.8; animation: fadeToTransparent 1s forwards; } ``` --- # Helpers > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/helpers Helpers are classes for very targeted "one-off" local overrides. Every helper declaration uses `!important`, and because they live in an mCSS [cascade layer](/docs/start#mcss-file-structure), that beats everything: all framework layers, your own unlayered CSS, even normal inline styles. Think of a helper as inline styling for a single element. That power is exactly why they should be used as little as possible, but they're useful for things like: - Designer's request to "make an exception" - Quick fix until refactor - Temporary test/design Let's say the request is: _"This component just doesn't look right in that context, can we just increase the top and bottom padding?"_ You would use the spacing helper this way: ```html

Content goes here.

``` Using helpers is optional and mCSS will work just fine without them. None of the mCSS components rely on them. If you do use them in your project, it's recommended to use [PurgeCSS](https://purgecss.com/getting-started.html) to keep your CSS size to a minimum. For Astro users, the [astro-purgecss integration](https://github.com/codiume/orbit/tree/main/packages/astro-purgecss) does everything for you out of the box once you install it. Below is a list of all the available helpers. mCSS doesn't include every single CSS property like utility classes frameworks do. It only includes the ones you actually need in those "one-off" situations. I've never needed more than that, but I'm open to add anything that would be useful. Just [open an issue on Github](https://github.com/minimaldesign/mCSS/issues) with your use case and I'll add it in. ## Spacing | File name | Source | | ------------------ | -------------------- | | `help.spacing.css` | [Github][srcSpacing] | [srcSpacing]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/help.spacing.css ### width, height, margin, and padding You can combine these properties with any [dimension token](/docs/tokens#dimension) as well as `0`: | CSS property | Class prefix | | ---------------------- | ------------ | | `width` | `w` | | `height` | `h` | | `margin` | `m` | | `margin-top` | `mt` | | `margin-bottom` | `mb` | | `margin-left` | `ml` | | `margin-right` | `mr` | | `margin-inline-start` | `mis` | | `margin-inline-end` | `mie` | | `padding` | `p` | | `padding-top` | `pt` | | `padding-bottom` | `pb` | | `padding-left` | `pl` | | `padding-right` | `pr` | | `padding-inline-start` | `pis` | | `padding-inline-end` | `pie` | Both directional sets exist on purpose. Use the logical helpers (`mis`, `mie`, `pis`, `pie`) when the spacing follows the reading direction: an icon gap, a list indent, anything that should flip in a right-to-left layout. Use the physical helpers (`ml`, `mr`, `pl`, `pr`) when the offset is a purely visual choice that should stay on the same side no matter the script direction. In a left-to-right layout they resolve identically. #### Examples | Class | Value | | --------- | ---------------------------------- | | `w-lg1` | `width: var(--lg1)` | | `ml-0` | `margin-left: 0` | | `mb-sm1` | `margin-bottom: var(--sm1)` | | `pis-md1` | `padding-inline-start: var(--md1)` | ```html
A component with an extra bottom margin of 48px.
A component with an extra padding of 28px.
``` ## Colors | File name | Source | | ----------------- | ------------------- | | `help.colors.css` | [Github][srcColors] | [srcColors]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/help.colors.css ### color, background-color, and border-color You can combine this properties with any [color token](/docs/tokens#color): | CSS property | Class prefix | | ------------------ | ------------ | | `color` | `c` | | `background-color` | `bgc` | | `border-color` | `bdc` | #### Examples
| Class | Value | | --------------- | ----------------------------------- | | `bgc-base-200` | `background-color: var(--base-200)` | | `bdc-yes-500` | `border-color: var(--yes-500)` | | `c-primary-500` | `color: var(--primary-500)` |

A block with custom colors.

```html

A block with custom colors.

``` ## Layout | File name | Source | | ----------------- | ------------------- | | `help.layout.css` | [Github][srcLayout] | [srcLayout]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/help.layout.css ### overflow
| CSS property | CSS value | Class | Short class | | ------------ | --------- | --------------------- | --------------- | | `overflow` | `auto` | `.overflow-auto` | `.of-auto` | | `overflow` | `hidden` | `.overflow-hidden` | `.of-hidden` | | `overflow` | `clip` | `.overflow-clip` | `.of-clip` | | `overflow` | `visible` | `.overflow-visible` | `.of-visible` | | `overflow` | `scroll` | `.overflow-scroll` | `.of-scroll` | | `overflow-x` | `auto` | `.overflow-x-auto` | `.of-x-auto` | | `overflow-y` | `auto` | `.overflow-y-auto` | `.of-y-auto` | | `overflow-x` | `hidden` | `.overflow-x-hidden` | `.of-x-hidden` | | `overflow-y` | `hidden` | `.overflow-y-hidden` | `.of-y-hidden` | | `overflow-x` | `clip` | `.overflow-x-clip` | `.of-x-clip` | | `overflow-y` | `clip` | `.overflow-y-clip` | `.of-y-clip` | | `overflow-x` | `visible` | `.overflow-x-visible` | `.of-x-visible` | | `overflow-y` | `visible` | `.overflow-y-visible` | `.of-y-visible` | | `overflow-x` | `scroll` | `.overflow-x-scroll` | `.of-x-scroll` | | `overflow-y` | `scroll` | `.overflow-y-scroll` | `.of-y-scroll` |
### position Helper classes for the `position` property.
| CSS value | Class | | ---------- | -------------------- | | `static` | `.position-static` | | `fixed` | `.position-fixed` | | `absolute` | `.position-absolute` | | `relative` | `.position-relative` | | `sticky` | `.position-sticky` |
### visibility Helper classes for the `visibility` property.
| CSS value | Class | | ---------- | ---------------------- | | `visible` | `.visibility-visible` | | `hidden` | `.visibility-hidden` | | `collapse` | `.visibility-collapse` |
### z-index Helper classes for the `z-index` property. See also the [z-index token docs](docs/tokens#z-index).
| Custom Property | CSS Value | Class | | --------------- | ----------- | ----------- | | `--z-bottom` | -1000000000 | `.z-bottom` | | `--z-0` | 0 | `.z-0` | | `--z-1` | 10 | `.z-1` | | `--z-2` | 20 | `.z-2` | | `--z-3` | 30 | `.z-3` | | `--z-4` | 40 | `.z-4` | | `--z-5` | 50 | `.z-5` | | `--z-top` | 1000000000 | `.z-top` |
## Aspect ratios | File name | Source | | ----------------- | ------------------- | | `help.ratios.css` | [Github][srcRatios] | [srcRatios]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/help.ratios.css
| Custom Property | CSS Value | Class | | ----------------- | --------- | ---------------- | | `--ar-square` | 1 | `.ar-square` | | `--ar-landscape` | 4/3 | `.ar-landscape` | | `--ar-portrait` | 3/4 | `.ar-portrait` | | `--ar-widescreen` | 16/9 | `.ar-widescreen` | | `--ar-golden` | 1.618/1 | `.ar-golden` |
## Opacity | File name | Source | | ------------------ | -------------------- | | `help.opacity.css` | [Github][srcOpacity] | [srcOpacity]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/help.opacity.css | Custom Property | CSS Value | Class | | --------------- | --------- | ------ | | `--o-0` | 0 | `.o-0` | | `--o-1` | 0.2 | `.o-1` | | `--o-2` | 0.4 | `.o-2` | | `--o-3` | 0.6 | `.o-3` | | `--o-4` | 0.8 | `.o-4` | | `--o-5` | 1 | `.o-5` | ## Typography | File name | Source | | --------------------- | ----------------------- | | `help.typography.css` | [Github][srcTypography] | [srcTypography]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/help.typography.css ### font-family See the [font stack tokens](/docs/tokens#font-stack) for details.
| Custom Property | Class | | --------------- | --------------- | | `--text` | `.font-text` | | `--display` | `.font-display` | | `--mono` | `.font-mono` |
### font-style | CSS value | Class | | --------- | -------------- | | `italic` | `.font-italic` | | `normal` | `.font-normal` | ### font-weight See the [font weight tokens](/docs/tokens#font-weight) for details.
| Custom Property | Class | | --------------- | ------------------- | | `--extra-light` | `.font-extra-light` | | `--light` | `.font-light` | | `--book` | `.font-book` | | `--semi-bold` | `.font-semi-bold` | | `--bold` | `.font-bold` | | `--black` | `.font-black` |
### font-size See the [font size tokens](/docs/tokens#font-size) for details. | Custom Property | Class | | --------------- | ------------- | | `--text-xs` | `.text-xs` | | `--text-sm` | `.text-sm` | | `--text-md` | `.text-md` | | `--text-lg` | `.text-lg` | | `--text-xl` | `.text-xl` | | `--display-sm` | `.display-sm` | | `--display-md` | `.display-md` | | `--display-lg` | `.display-lg` | | `--display-xl` | `.display-xl` | ### line-height See the [line height tokens](/docs/tokens#line-height) for details. | Custom Property | Class | | --------------- | -------------- | | `--leading-xs` | `.leading-xs` | | `--leading-sm` | `.leading-sm` | | `--leading-md` | `.leading-md` | | `--leading-lg` | `.leading-lg` | | `--leading-xl` | `.leading-xl` | | `--leading-xxl` | `.leading-xxl` | ### text-align | CSS value | Class | | --------- | --------------- | | `left` | `.text-left` | | `center` | `.text-center` | | `right` | `.text-right` | | `justify` | `.text-justify` | | `start` | `.text-start` | | `end` | `.text-end` | Same split as the spacing helpers: `.text-start` and `.text-end` follow the reading direction (they flip in a right-to-left layout), `.text-left` and `.text-right` always mean the visual side. ### text-transform | CSS value | Class | | ------------ | ------------------ | | `uppercase` | `.text-uppercase` | | `lowercase` | `.text-lowercase` | | `capitalize` | `.text-capitalize` | --- # AI Agents > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/ai mCSS is built to be easy for AI coding agents (Claude, Cursor, Copilot, etc.) to work with. The docs are available in machine-readable form, and this page includes a rules block you can paste into your project's agent instructions so generated markup follows mCSS methodology. ## Machine-readable docs Three things exist specifically for agents: - `/llms.txt`: an index of every docs and components page with one-line descriptions, following the [llms.txt](https://llmstxt.org) convention. Most agent tooling checks for this automatically. - `/llms-full.txt`: the entire reference (docs and all components) concatenated into a single markdown file. Point an agent [here](/llms-full.txt) when it needs the whole framework in one fetch. - **Markdown twins**: every docs and components page is also served as plain markdown at the same URL but with the `.md` extension. These are a fraction of the size of the HTML pages. Make sure you tell your agent to fetch the `.md` URLs, not the HTML. ## Add mCSS rules to your agent instructions Paste the block below into your project's `CLAUDE.md`, `AGENTS.md`, or equivalent. It compresses the conventions that matter most when writing mCSS markup and CSS on top of it. ````md ## mCSS conventions This project uses mCSS (https://mcss.dev), a CSS framework copied into the repo. There is no npm package: the files are project code, and the framework's defaults are overridden, never edited. Full reference in one fetch: https://mcss.dev/llms-full.txt Per-page docs: append `.md` to any mcss.dev docs or components URL (e.g. https://mcss.dev/components/card.md). ### Mental model: layers from default to deliberate All framework CSS lives in native cascade layers, declared in `mcss.css` in priority order (later wins): `settings, base, elements, global, components, theme, helpers`. - `settings` through `components` are the framework defaults: what things look like when nobody has an opinion. Never edit these files to restyle; override them from further up the order. - `theme` holds at most one theme file: a deliberate opinion about the defaults. An empty theme layer IS the default look. - Your own unlayered CSS is more deliberate still: it beats every layer, by design. Never use `!important` to win against the framework. - `helpers` (`help.*` files: spacing, color, typography utilities) are the one exception: every declaration carries `!important`, which inverts the cascade, so they beat even unlayered CSS, like inline styles. Use sparingly. `!important` is banned everywhere else. ### Restyling, in order of preference 1. **Theme token overrides.** A theme is one file that restyles the whole site: `@layer theme { :root { ... } }` (self-layered, so it slots correctly however it's loaded). Copy `theme.default.css` to start one; activate exactly one from your CSS entry point, after `mcss.css` (which never imports themes itself). Anything the theme doesn't mention falls back to the defaults. Pick the blast radius per override: raw tokens (`--base-*`, `--text`) shift the whole palette or type scale, interface tokens (`--ui-border-color`, `--heading-font`) change every surface that shares the meaning, component tokens (`--bt-border-radius`, `--card-*`) turn one knob. Most themes never need a selector. 2. **Theme style rules**, only for what tokens can't express (pseudo-elements, `nth-child` rhythm, `text-decoration`). Theme files are the ONE place allowed to select component classes from outside. No `!important` in themes. 3. **Unlayered project CSS** for what belongs to your project rather than to the design: page layouts, one-off blocks. 4. **Helpers** for element-level one-offs. Edit framework files only for structural change: adding a component, or adding a missing token or `Class` prop to an existing one. ### Tokens - `settings.tokens.css`: raw primitives (palettes, type scale, spacing, radii). - `settings.ui.css`: interface tokens, the public API of every component (semantic aliases plus all component defaults). Interface tokens only ever take another token as value; raw values live in `settings.tokens.css`. - Grammar: `--component-part-property`, longhand, kebab-case, no abbreviations: `--bt-background-color-hover`, `--notice-border-width`. - Feedback colors: use the semantic aliases `--success-*`, `--danger-*`, `--warning-*`, not the raw scales they point at. ### Class naming (BEM-like, different separators) - Block: `.componentName` (camelCase for multi-word names) - Element: `.componentName_element` (underscore marks hierarchy inside one block; chains may nest as deep as the block's structure needs) - Modifier: `.componentName-modifier` (hyphen), for build-time variants chosen in markup - State: `.is-*` (`.is-active`, `.is-open`), only for things that change at runtime, always scoped inside the block (`.avatar.is-online`) - Prefer styling an existing ARIA attribute over inventing a state class: `[aria-current]`, `[aria-expanded="true"]`, `[aria-disabled="true"]` - A nested component starts its own block: `.themeToggle_text`, never `.header_nav_themeToggle_text` ### Never couple classes across components (CRITICAL) A selector may only contain classes from its own block. Never write a selector that reaches into another component: not its block, not its elements. Instead, mix your own block's classes onto the component's markup and style those: ```html

Pro

``` ```css /* Don't: couple your block to the card's classes */ .pricing .card { border-color: var(--primary-500); } .pricing .card_title { color: var(--primary-500); } /* Do: style the classes you mixed on */ .pricing_planTitle { color: var(--primary-500); } /* Do: or turn the component's own token knobs from your class */ .pricing_planCard { --card-border-color: var(--primary-500); } ``` When the markup comes from a component you don't write inline, its `Class` props (`titleClass`, `iconClass`, ...) mix your class onto the part the same way. If the prop or token you need doesn't exist, add it to the component; don't reach in with a selector. Bare HTML tags, `.is-*` states, and ARIA attribute selectors are fine inside your own block. Theme files are the only sanctioned exception to this rule. ### Transitions Never `transition: all`; list the properties that actually animate. ```` ## MCP and tooling There is no mCSS MCP server yet. For now, `llms-full.txt` plus the rules block above is the recommended setup. If your agent supports fetching URLs at runtime, the markdown twins are the cheapest way to pull a single component's markup reference into context. --- # Getting started > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/start The mCSS component library is entirely built with the [mCSS framework](/docs/start), and you **own the code**: instead of installing a package, you copy the pieces you want into your project and edit them like anything else you wrote. Every component's docs page starts with a table listing exactly which files, dependencies, and interface tokens it needs. Each component comes in two flavors: - **Plain HTML + CSS.** Copy the `component.*.css` file (or grab the compiled version from [`dist/css/`](https://github.com/minimaldesign/mCSS/tree/main/dist/css)) and use the documented markup. Works with any framework, or none. - **Astro.** Copy the `.astro` file(s) for typed props, slots, and sensible accessibility defaults out of the box. Components stay as pure HTML/CSS as possible. The exceptions ship only the few lines they need: the [header](/components/header)'s mobile menu, the dismissible [banner](/components/banner), the [hero](/components/hero)'s slideshow, the [table of contents](/components/toc)' scrollspy, and the [read progress bar](/components/readprogressbar)'s fallback for browsers without scroll-driven animations. Styling lives in [cascade layers](/docs/start), so your own unlayered CSS always wins, and every visual knob is a documented `--component-*` [interface token](/docs/tokens#interface-tokens). You can see some of the Astro components in action on the [Marketing Template](/templates/marketing) ([code](https://github.com/minimaldesign/mCSS/blob/main/src/pages/templates/marketing.astro)). Spotted a bug, or built something worth sharing? [Issues and discussions](https://github.com/minimaldesign/mCSS/issues) are open. --- # Avatar > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/avatar The `.avatar` component is a visual representation of a user. It shows the user's initials or an image thumbnail. Its default size is 56px. (See the [HTML](#html) section below for all options.) SR
| File | Description | Source | | ---------------------- | ----------- | ----------- | | `component.avatar.css` | All avatar styles (`.avatar`) | [Github][1] |
[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.avatar.css ## Playground
{content}
`} baseClasses="avatar" snippets={{ initials: { preview: "SR", code: "SR" }, image: { preview: `Sonny Rollins`, code: `Sonny Rollins`, }, }} controls={[ { heading: "Variation", items: [ { type: "select", name: "size", label: "Size", default: "", options: [ { label: "Default", value: "" }, { label: "Small", value: "avatar-sm" }, { label: "Medium", value: "avatar-md" }, { label: "Large", value: "avatar-lg" }, { label: "Extra large", value: "avatar-xl" }, ]}, ]}, { heading: "State", items: [ { type: "select", name: "status", label: "Status", default: "", options: [ { label: "None", value: "" }, { label: "Online", value: "is-online" }, { label: "Offline", value: "is-offline" }, ]}, ]}, { heading: "Content", items: [ { type: "select", name: "content", label: "Show", snippet: "content", default: "initials", options: [ { label: "Initials", value: "initials", class: "", snippet: "initials" }, { label: "Image", value: "image", class: "", snippet: "image" }, ]}, ]}, ]} /> ## HTML ### Available modifiers
| Available modifiers | Description | | ----------------------------- | -------------------------- | | `.avatar` | Default - 56px | | `.avatar` + `.avatar-sm` | Small - 24px | | `.avatar` + `.avatar-md` | Medium - 36px | | `.avatar` + `.avatar-lg` | Large - 80px | | `.avatar` + `.avatar-xl` | Extra large - 128px | | `.avatar` + `.is-online` | User is online - green dot | | `.avatar` + `.is-offline` | User is offline - grey dot |
### Custom properties The following custom properties are available in [`settings.ui.css`](/docs/tokens#interface-tokens):
| Property | Color | | ----------------------------------- | --------------------------------- | | `--avatar-color` | Text color (when no image). | | `--avatar-background-color` | Background color (when no image). | | `--avatar-border-color` | Border color. | | `--avatar-border-width` | Border width. | | `--avatar-radius` | Radius. (`0` = square). | | `--avatar-status-dot-color-offline` | Status dot color: offline. | | `--avatar-status-dot-color-online` | Status dot color: online. |
## Astro component
| Prop | Type | Default | Description | | ------------ | --------- | --------- | ----------------------------------------------------------- | | `size` | `string` | undefined | `sm`, `md`, `lg`, `xl` ([px values](#html)) | | `imageSrc` | `string` | undefined | Optional image. | | `status` | `'online' \| 'offline'` | `undefined` | Shows a status dot (green online / grey offline) | | `class` | `string` | undefined | Additional CSS classes, useful for [helper classes](/docs/helpers). |
## Examples
  • ### Full name vs initials Sonny Rollins SR ```astro --- import Avatar from "../../components/Avatar.astro"; --- Sonny Rollins SR ``` The astro component can take initials or a full name and will output initials if an image is not provided. It will output the full name in the `alt` attribute if an image is provided.
  • ### Offline large avatar Sonny Rollins ```astro --- import Avatar from "../../components/Avatar.astro"; import imageSrc from "../../assets/images/sonny.png"; --- Sonny Rollins ```
### HTML examples
  • SR ```html
    SR
    ```
--- # Badge > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/badge The badge is a small label for statuses, categories, and "new" markers. It is a [CSS-only component](/docs/start#components): there is no Astro file because a `` with the `.badge` class is already the whole API.

default  primary  success  danger  warning

| File | Description | Source | | ---------------------------------- | ------------------------------ | ----------- | | `component.badge.css` | All badge styles | [Github][1] | | `--badge-*` block in `settings.ui.css` | Interface tokens (see table below) | [Github][2] |
[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.badge.css [2]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.ui.css ## Playground {label}'} baseClasses="badge" controls={[ { heading: "Variation", items: [ { type: "select", name: "color", label: "Color", default: "", options: [ { label: "Default", value: "" }, { label: "Primary", value: "badge-primary" }, { label: "Success", value: "badge-success" }, { label: "Danger", value: "badge-danger" }, { label: "Warning", value: "badge-warning" }, ]}, ]}, { heading: "Content", items: [ { type: "text", name: "label", label: "Label", default: "new" }, ]}, ]} /> ## HTML ```html default shipped ``` ### Available modifiers
| Class | Description | | ---------------------------- | --------------------------------- | | `.badge` | Default style. Neutral colors. | | `.badge` + `.badge-primary` | Primary colors. | | `.badge` + `.badge-success` | Positive feedback. Greens. | | `.badge` + `.badge-danger` | Negative feedback. Reds. | | `.badge` + `.badge-warning` | Warning. Oranges. |
One-off colors work like every other variant in mCSS: override the local custom property. ```html custom ``` ### Custom properties The following custom properties are available in [`settings.ui.css`](/docs/tokens#interface-tokens):
| Property | Description | | ------------------------------------ | ------------------------------ | | `--badge-font-size` | Font size. | | `--badge-border-radius` | Border radius. | | `--badge-color` | Default text color. | | `--badge-background-color` | Default background color. | | `--badge-primary-color` | Primary variant text color. | | `--badge-primary-background-color` | Primary variant background. | | `--badge-success-color` | Success variant text color. | | `--badge-success-background-color` | Success variant background. | | `--badge-danger-color` | Danger variant text color. | | `--badge-danger-background-color` | Danger variant background. | | `--badge-warning-color` | Warning variant text color. | | `--badge-warning-background-color` | Warning variant background. |
--- # Banner > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/banner The `.banner` component is the thin announcement bar at the very top of the page, optionally dismissible (remembered in `localStorage`).

mCSS v1 is out! Read the announcement
| File | Description | Source | | ----------------------------------- | ------------------------------ | ----------- | | `component.banner.css` | All banner styles | [Github][1] | | `Banner.astro` | The Astro component | [Github][2] | | `icons/x.svg` | Dismiss icon | [Github][3] | | `--banner-*` block in `settings.ui.css` | Interface tokens (see table below) | [Github][4] |
[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.banner.css [2]: https://github.com/minimaldesign/mCSS/blob/main/src/components/Banner.astro [3]: https://github.com/minimaldesign/mCSS/tree/main/src/assets/icons [4]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.ui.css ## Playground
`} baseClasses="section" controls={[ { heading: "Variation", items: [ { type: "select", name: "variant", label: "Variant", default: "", options: [ { label: "Default", value: "" }, { label: "Filled", value: "section-filled" }, { label: "Primary", value: "section-primary" }, ], }, ], }, { heading: "Content", items: [ { type: "text", name: "eyebrow", label: "Eyebrow", default: "Why mCSS", }, { type: "text", name: "title", label: "Title", default: "Everything is a section", }, { type: "text", name: "lede", label: "Lede", default: "Stack a few of these and you have a landing page.", }, ], }, ]} /> ## HTML ```html

Why mCSS

Everything is a section

Stack a few of these and you have a landing page.

``` The header and content each compose `.wrap` with a [width preset](/docs/global#wrap) (`.wrap-sm`, `.wrap-md`, `.wrap-lg`), so they can use different column widths. `wrap-md` on the header and `wrap-lg` on the content is the standard pairing; use `wrap-md` on the content too when it is text meant for reading (an FAQ, for example). ### Available modifiers
| Class | Description | | ------------------------------- | ---------------------------------------------------------------------- | | `.section` | Default. Transparent background, `--section-spacing` vertical padding. | | `.section` + `.section-filled` | Subtle filled band. | | `.section` + `.section-primary` | Primary-colored band; text and links switch to the inverted colors. |
### Elements
| Class | Description | | ------------------ | --------------------------------------------------------------------- | | `.section_header` | Centered eyebrow/title/lede block; composes `.wrap` + a width preset. | | `.section_content` | Content column; composes `.wrap` + a width preset. | | `.section_eyebrow` | Small uppercase kicker. | | `.section_title` | The `h2`. | | `.section_lede` | Intro paragraph. | | `.section_actions` | Centered, wrapping button row (see the closing-CTA recipe below). |
### Custom properties The following custom properties are available in [`settings.ui.css`](/docs/tokens#interface-tokens):
| Property | Description | | ------------------------------------ | ---------------------------------------- | | `--section-spacing` | Vertical padding of the band. | | `--section-header-spacing` | Space between the header and content. | | `--section-eyebrow-color` | Eyebrow text color. | | `--section-lede-color` | Lede text color. | | `--section-filled-background-color` | Background of the filled variant. | | `--section-primary-background-color` | Background of the primary variant. | | `--section-primary-text-color` | Text color on the primary variant. | | `--section-primary-link-color` | Link color on the primary variant. | | `--section-primary-link-color-hover` | Link hover color on the primary variant. | | `--section-primary-eyebrow-color` | Eyebrow color on the primary variant. | | `--section-primary-lede-color` | Lede color on the primary variant. |
## Astro component
| Prop | Type | Default | Description | | -------------- | -------- | ----------- | ------------------------------------------------------------------- | | `eyebrow` | `string` | `undefined` | Small uppercase kicker above the title. | | `title` | `string` | `undefined` | The section's `h2`. | | `lede` | `string` | `undefined` | Intro paragraph under the title. | | `variant` | `string` | `undefined` | `filled`, `primary`. | | `headerWrap` | `string` | `md` | Header column width preset: `sm`, `md`, `lg`. | | `contentWrap` | `string` | `lg` | Content column width preset: `sm`, `md`, `lg`. | | `headerClass` | `string` | `undefined` | Extra classes added to `.section_header`. | | `contentClass` | `string` | `undefined` | Extra classes added to `.section_content`. | | `class` | `string` | `undefined` | Additional CSS classes, useful for [helper classes](/docs/helpers). |
Any other attribute is passed through to the root `
` element (handy for `id` anchors). The default slot is the section content. ## Examples

  • Text and links flip to the inverted palette.

    ```astro --- import Section from "../components/Section.astro"; ---

    Text and links flip to the inverted palette.

    ```
  • By default the content column is wider (`wrap-lg`) than the header (`wrap-md`); set `contentWrap="md"` to keep long-form content at reading width:
    1
    2
    3
    ```astro
    …
    ```
  • The closing CTA every marketing page ends on is not a separate component; it is a Section with a `.section_actions` row:
    Get started
    ```astro
    Get started
    ```
--- # Social Media Links > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/socialmedia
The `.socialMedia` component consists of an unordered list of links to social media accounts and their corresponding icons.
| File | Description | Source | | --------------------------- | ----------- | ----------- | | `component.socialMedia.css` | All social links styles (`.socialMedia`) | [Github][1] |
[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.socialMedia.css The following 4 sizes and 19 icons (18 social media platforms + 1 generic link icon) are available out of the box.
| Platform | Icon | | ----------- | -------------------------------------------- | | Unknown URL | | | Discord | | | Facebook | | | Github | | | Instagram | | | Linkedin | | | Pinterest | | | Reddit | | | Snapchat | | | Telegram | | | Tiktok | | | X | | | Youtube | | | Twitch | | | Odysee | | | Minds | | | Substack | | | Bitchute | | | Bastyon | |
## Playground
  • {x}
  • {github}
  • {youtube}
    • `} baseClasses="socialMedia" snippets={{ x: { preview: xIcon, code: "[…]" }, github: { preview: githubIcon, code: "[…]" }, youtube: { preview: youtubeIcon, code: "[…]" }, }} controls={[ { heading: "Variation", items: [ { type: "select", name: "size", label: "Size", default: "", options: [ { label: "Default", value: "" }, { label: "Medium", value: "socialMedia-md" }, { label: "Large", value: "socialMedia-lg" }, { label: "Extra large", value: "socialMedia-xl" }, ]}, ]}, ]} /> ## HTML
    | Available modifiers | Description | | ---------------------------------- | -------------- | | `.socialMedia` | Default - 24px | | `.socialMedia` + `.socialMedia-md` | 32px | | `.socialMedia` + `.socialMedia-lg` | 44px | | `.socialMedia` + `.socialMedia-xl` | 64px |
    When using the HTML component you'll need to include the SVG icons "manually." All the icons are [available on Github](https://github.com/minimaldesign/mCSS/tree/main/src/assets/icons). If you'd like to use different icons, [Lucide](https://lucide.dev/) is a great resource.
    ## Astro component
    The Astro component ([Github](https://github.com/minimaldesign/mCSS/blob/main/src/components/SocialMedia.astro)) takes 3 props:
    | Prop | Type | Default | Description | | ------------ | -------- | --------- | ----------------------------------------------------------- | | `urls` | `array` | `[]` | An array of urls, or `{ url, label }` objects to override the accessible label (e.g. `"mCSS on GitHub"`). | | `size` | `string` | undefined | `md`, `lg`, `xl`. | | `newTab` | `boolean` | `true` | Open links in a new tab. Set to `false` to opt out. | | `class` | `string` | undefined | Additional CSS classes, useful for [helper classes](/docs/helpers). |
    ## Examples
    • ```astro --- import SocialMedia from "../../components/SocialMedia.astro"; --- ```
    • ```astro --- import SocialMedia from "../../components/SocialMedia.astro"; --- ```
    ### HTML examples --- # Tags > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/tags
    The `.tags` component styles a list of tags. It supports both list and inline layouts, is accessible by default, and customizable via CSS custom properties.
    | File | Description | Source | | -------------------- | ----------- | ----------- | | `component.tags.css` | All tags styles (`.tags`) | [Github][1] |
    [1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.tags.css
    ## Playground
  • css
  • astro
  • basics
    • `} baseClasses="tags" controls={[ { heading: "Variation", items: [ { type: "select", name: "layout", label: "Layout", default: "", options: [ { label: "List", value: "" }, { label: "Inline", value: "tags-inline" }, ]}, ]}, ]} /> ## HTML ### Custom properties The following custom properties are available in [`settings.ui.css`](/docs/tokens#interface-tokens): | Property | Description | | ------------------------------- | --------------------------- | | `--tags-padding` | Tag padding. | | `--tags-font-size` | Tag font size. | | `--tags-color` | Tag text color. | | `--tags-background-color` | Tag background color. | | `--tags-background-color-hover` | Tag hover background color. | | `--tags-radius` | Tag border radius. | ### Available modifiers
    | Modifier | Description | | -------------- | ---------------------------- | | `.tags` | Default style (list layout). | | `.tags-inline` | Inline layout using flex. |
    ## Astro component
    | Prop | Type | Default | Description | | ------------- | ---------- | ----------- | ----------------------------------------------------------- | | `tagList` | `string[]` | `[]` | Array of tag strings to display. | | `variant` | `string` | `inline` | Inline or list layout. | | `url` | `string` | `/blog/tags` | Base URL to prepend to each tag. | | `sort` | `boolean` | `false` | Sort tags alphabetically; input order is preserved by default. | | `class` | `string` | `undefined` | Additional CSS classes, useful for [helper classes](/docs/helpers). | | `ariaLabel` | `string` | `'Tags'` | Accessible label for the tag list. | | `data-testid` | `string` | `'tags'` | Test ID for testing purposes. |
    ## Examples
    • ### Astro example (frontmatter metadata) ```astro --- import Tags from '../components/Tags.astro'; const { frontmatter } = Astro.props; --- ```
    • ### HTML example (list layout) ```html ```
    --- # Testimonial > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/testimonial The `.testimonial` component is a quote with attribution: a `figure` wrapping mCSS's already-styled `blockquote`, plus an [Avatar](/components/avatar) byline. Pure HTML and CSS.

    We deleted four hundred lines of utility classes the week we switched. The cascade does the work now.

    | File | Description | Source | | ----------------------------------------------- | ------------------------------------- | ----------- | | `component.testimonial.css` | Layout + byline styles | [Github][1] | | `elements.text.css` | The `blockquote` styling (dependency) | [Github][2] | | `Testimonial.astro`, `Avatar.astro` | The Astro components | [Github][3] | | `--testimonial-role-color` in `settings.ui.css` | Interface token | [Github][4] |
    [1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.testimonial.css [2]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.text.css [3]: https://github.com/minimaldesign/mCSS/tree/main/src/components [4]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.ui.css ## Playground

    {quote}

    {initials}
    {name} {role}
    `} controls={[ { heading: "Content", items: [ { type: "text", name: "quote", label: "Quote", default: "We deleted four hundred lines of utility classes the week we switched.", }, ], }, { heading: "Byline", items: [ { type: "text", name: "name", label: "Name", default: "Sonny Rollins" }, { type: "text", name: "role", label: "Role", default: "Design lead, Acme", }, { type: "text", name: "initials", label: "Initials", default: "SM" }, ], }, ]} /> ## HTML ```html

    We deleted four hundred lines of utility classes the week we switched.

    Sonny Rollins Design lead, Acme
    ``` ### Custom properties
    | Property | Description | | -------------------------- | ---------------- | | `--testimonial-role-color` | Role text color. |
    The quote itself is themed by the `blockquote` element styles. ## Astro component
    | Prop | Type | Default | Description | | ----------- | ------------------------- | ----------- | ------------------------------------------------------------------------------ | | `name` | `string` | — | Who said it. Required (also feeds the Avatar initials when there is no photo). | | `role` | `string` | `undefined` | Title/company line. | | `avatarSrc` | `ImageMetadata \| string` | `undefined` | Photo for the Avatar. | | `class` | `string` | `undefined` | Additional CSS classes. |
    The default slot is the quote. ## Examples A wall of quotes is just testimonials on the [grid](/docs/global#grid):

    • The copy-paste model means I actually own my components.

      Readable class names. Imagine that.

      Shipped our marketing site in a weekend.
      ```astro --- import Testimonial from "../components/Testimonial.astro"; ---

      The copy-paste model means I actually own my components.
      ```
    --- # Tiles > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/tiles The `.tiles` component lays out repeated, same-size items (cards, feature items, pricing tiers) in equal-height columns. It is container-responsive: columns appear as the nearest [size container](/docs/global#layouts) crosses the size's thresholds, so the count answers the space the list actually has, not the viewport. The same markup is 2-up in this docs column and 4-up on the wide [blog index](/blog), at the same window size.

  • Columns come from the width of the column the list lives in, not the viewport.

  • Tiles in a row stretch to the same height, however long their content runs.

    Like the card right next to this one…
    • | File | Description | Source | | --------------------- | ----------------------------------------------------- | ----------- | | `component.tiles.css` | All tiles styles (`.tiles`), including the thresholds | [Github][1] | | `Tiles.astro` | The Astro component | [Github][2] |
    No dependencies. The [card](/components/card) blog index and the [feature grid](/components/featuregrid) pattern are both built on it. [1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.tiles.css [2]: https://github.com/minimaldesign/mCSS/tree/main/src/components ## Playground

  • One

    Tiles share the row height.

  • Two

    Resize the window to watch the columns respond to this docs column.

  • Three

    The thresholds watch the container, not the browser window.

    • `} baseClasses="tiles" controls={[ { heading: "Layout", items: [ { type: "select", name: "size", label: "Tile size", default: "md", options: [ { label: "md (default)", value: "md", class: "" }, { label: "sm", value: "sm", class: "tiles-sm" }, ], } ], }, ]} /> ## HTML A `ul` with one tile per `
  • `. Items stretch, so tiles in a row share the same height. ```html
    • …
    • …
    ``` ### Available modifiers Sizes name the tile: each one is a set of container thresholds tuned to how much room that tile needs, and columns keep coming as the container crosses them. There is no column cap: the width of the column the list sits in is the cap.
    | Available modifiers | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `.tiles` | Card-sized tiles, roughly `17rem` of room each: 2 columns from a `36rem` container, then 3/4/5/6 every `20rem`. | | `.tiles` + `.tiles-md` | The default size, spelled out. | | `.tiles` + `.tiles-sm` | Small tiles (icon + short copy, roughly `13rem`): 2 columns from `28rem`, then every `16rem`, so columns appear sooner. |
    The thresholds are deliberately not the global `--md`/`--lg` viewport breakpoints: those can't see how wide the column is, and a tile's comfortable width is a property of the component, not of the page. Copy-it-you-own-it applies as usual: retune them in `component.tiles.css`. ### The container The column count responds to the nearest size container. Every [layout scaffold](/docs/global#layouts) declares its main column as one, so inside a `.layout` page it just works. Outside a scaffold the wrapper is required: without a container ancestor the queries never match and the list stays single-column. ```html
      …
    ``` ### Custom properties
    | Property | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--tiles-columns` | The count the thresholds resolved. Pin it on a hook class of your own to opt out (your unlayered CSS wins), or set it from your own `@container`/`@media` rules. |
    ```css /* Exactly three pillars, whatever the container says */ .pillars { --tiles-columns: 3; } ``` Gaps come from the [grid system](/docs/global#grid)'s `--grid-column-gap` and `--grid-row-gap`, so tiles and grids share the same rhythm. ## Astro component Children go in the default slot; wrap each tile in an `
  • `.
    | Prop | Type | Default | Description | | ------------- | -------- | ----------- | ---------------------------------------------------------------------------------- | | `size` | `string` | `undefined` | Tile size: `sm` or `md`. Omitted is `md`. | | `class` | `string` | `undefined` | Additional CSS classes. Pin the count by setting `--tiles-columns` on one of them. | | `data-testid` | `string` | `'tiles'` | Test ID for testing frameworks. |
    ## Examples The blog-index recipe lives on the [card page](/components/card#clickable-cards), the icon + blurb marketing pattern on the [feature grid page](/components/featuregrid). --- # Table of Content > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/toc
    The `.toc` component is an "Astro only" client-side rendered component. It creates a table of content from the headings on the page it's on:
    By default, the TOC includes `H2`s and `H3`s (customizable via props) that have an ` id` attribute and links to them. It's possible to add multiple TOC on the same page, but this will duplicate Javascript and it's not recommended. If you do need to include more than one TOC, you'll need to add a unique `id` to each instance of the component.
    | File | Description | Source | | ------------------- | ----------- | ----------- | | `component.toc.css` | All TOC styles (`.toc`) | [Github][1] |
    [1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.toc.css
    ## HTML This component's main functionality is to create a table of content via JavaScript. It just renders a nested `ul` and it's most useful as an Astro component. ### Custom properties The following custom properties are available in [`settings.ui.css`](/docs/tokens#interface-tokens): | Property | Color | | ------------------- | ------------------------- | | `--toc-color` | Links color. | | `--toc-color-hover` | Links hover color. | | `--toc-spacing` | Links padding. | | `--toc-icon-size` | Icon size. | | `--toc-indentation` | Nested lists indentation. | ## Astro component
    | Prop | Type | Default | Description | | -------------- | --------- | ------------- | ----------------------------------------------------------- | | `id` | `string` | `toc` | Needed to add more than one TOC. | | `selector` | `string` | `main` | HTML element to scan for headings. | | `headings` | `array` | `['h2','h3']` | Heading levels to include. | | `baseUrl` | `string` | `''` | Optional URL to prepend `#id` with. | | `scrollOffset` | `integer` | `0` | Scroll position offset from the top.. | | `description` | `string` | `undefined` | Text above the TOC. | | `icon` | `string` | `''` | Optional inline SVG. (See example.) | | `class` | `string` | `undefined` | Additional CSS classes, useful for [helper classes](/docs/helpers). |
    ## Examples
    • ### TOC with only H2s ```astro --- import Toc from "../../components/Toc.astro"; --- ```
    • ### TOC with H2 — h4 and a ♥︎ icon #### A H4 just as an example ```astro --- import heart from "../../assets/icons/arrow-right-small.svg?raw"; import Toc from "../../components/Toc.astro"; --- ```
    --- # Toggle > Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/toggle The toggle is a [CSS-only component](/docs/start#components) using the `.toggle` class on `` elements of the type `checkbox`.
    | File | Description | Source | | ----------------- | ----------- | ----------- | | `component.toggle.css` | All toggle styles (`.toggle`) | [Github][1] |
    [1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.toggle.css ## Playground '} baseClasses="toggle" controls={[ { heading: "State", items: [ { type: "checkbox", name: "checked", label: "Checked", attr: "checked", default: true }, { type: "checkbox", name: "disabled", label: "Disabled", attr: "disabled", default: false }, ]}, ]} /> ## HTML
    • ```html ```