# 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.

# 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

<section class="docs_section prose">

The file structure is based on [ITCSS][1], but with important differences detailed below. The basic idea is to organize your files in different [layers][layers] so that your CSS [rulesets][2] are organized from global low [specificity][3] 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][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. The only exception is [helper classes][helpers], which use `!important` so they can override anything, including your own CSS. 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][4].)

```css
@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.
   Its normal declarations win over every mCSS layer without fighting
   specificity. One exception: helpers are !important and beat
   unlayered CSS too. */
@import url(./site/myComponent.css);
```

[cascade-layers]: https://developer.mozilla.org/en-US/docs/Web/CSS/@layer

The easiest ways to use mCSS in your own 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.
- **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][7]).

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

### 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.
- [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.
- [Themes][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][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)

### 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][components], 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][components] for more info.

### Pages

Page specific design elements and adjustments. These files are project specific and none are included in mCSS by default. Use `@layer pages { … }` for page rules that should stay below the framework's cascade while still beating the other layers.

### Helpers

[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][helpers] 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, by design.

## mCSS classes syntax

<section class="docs_section prose">

Classes in mCSS are inspired by [BEM][bem], but they're simpler to use and easier to look at.

You can use standard BEM, the even more verbose [BEMIT][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

<div class="docs_oversizedTable">

|          | BEM                  | mCSS               |
| -------- | -------------------- | ------------------ |
| Block    | `site-search`        | `siteSearch`       |
| Element  | `site-search__field` | `siteSearch_field` |
| Modifier | `site-search--full`  | `siteSearch-full`  |

</div>

### States

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

HTML:

```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:

```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.

```css
.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;
}
```

## Components

<section class="docs_section prose">

### 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`):

```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.

```css
/* 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][github] of the [notice component](/components/notice) for a real life example.

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

## Browser support

<section class="docs_section prose">

mCSS targets **[Baseline](https://web.dev/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](/components/readprogressbar) component detects support and falls back to JavaScript automatically.

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

[1]: /blog/what-is-itcss
[2]: https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax#css_rulesets
[3]: https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity
[4]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/_global.css
[5]: /docs/tokens
[6]: /docs/media-queries
[7]: https://github.com/postcss/postcss-mixins
[grid]: /docs/global#grid
[wrap]: /docs/global#wrap
[layout]: /docs/global#layouts
[prose]: /docs/global#prose
[a11y]: /docs/global#accessibility
[components]: /components/start
[helpers]: /docs/helpers
[themes]: /docs/themes
[layers]: /blog/what-is-itcss#the-layers-of-itcss
[bem]: /blog/what-is-bem
[bemit]: https://csswizardry.com/2015/08/bemit-taking-the-bem-naming-convention-a-step-further/
[github]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.notice.css
[src]: https://github.com/minimaldesign/mCSS/tree/main/src/styles
[discussions]: https://github.com/minimaldesign/mCSS/discussions


---

# Tokens

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/tokens

| File name             | Source        |
| --------------------- | ------------- |
| `settings.tokens.css` | [Github][src] |

[src]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.tokens.css

**Design tokens** are the "atoms" of a design system. They define the design elements of a user interface, such as colors, typography, and spacing.

In mCSS, tokens are CSS custom properties that provide a flexible, coherent, and harmonious set of values designed to make implementing UI/UX projects fast and easy.

## How to use tokens

When you start a new project, open `settings.tokens.css` and change the values of as many tokens as necessary to match the design you're planning to implement. (Things like spacing might not need to change, but you'll almost certainly need to customize your `base` and `primary` colors for instance.)

Themes offer an additional layer of abstraction for tokens (ie. `settings.theme.default.css`). These tokens only ever take another token for value and are useful to standardize UI elements in logical groups. For example, you can have a `--light-border-color` with a value of `--base-100`. This allows you to create tokens with meaning and context which makes them more intuitive to use.

`elements.*`, `global.*`, and `page.*` files tend to use abstracted theme tokens, while `component.*` generally use low level tokens. There are no hard and fast rules about the type of token you should use in your custom component. Just try to think where else this style is used in the design and if it comes up in many places with the same context, a new theme token is probably the best option.

## Color

Check out [tints.dev](https://www.tints.dev) if you want to make your own palettes programmatically.

<div class="grid" col="1" col-lg="2">
  <div class="grid_item">
  ### Base

| Token      | Value   | Demo                                      |
| ---------- | ------- | ----------------------------------------- |
| `base-0`   | #fff    | <div class="docs_box bgc-base-0"></div>   |
| `base-50`  | #f6f7f9 | <div class="docs_box bgc-base-50"></div>  |
| `base-100` | #edeef1 | <div class="docs_box bgc-base-100"></div> |
| `base-200` | #d6dbe1 | <div class="docs_box bgc-base-200"></div> |
| `base-300` | #b2bbc7 | <div class="docs_box bgc-base-300"></div> |
| `base-400` | #8897a8 | <div class="docs_box bgc-base-400"></div> |
| `base-500` | #697a8e | <div class="docs_box bgc-base-500"></div> |
| `base-600` | #546375 | <div class="docs_box bgc-base-600"></div> |
| `base-700` | #4a5666 | <div class="docs_box bgc-base-700"></div> |
| `base-800` | #3c4550 | <div class="docs_box bgc-base-800"></div> |
| `base-900` | #353c45 | <div class="docs_box bgc-base-900"></div> |
| `base-950` | #23282e | <div class="docs_box bgc-base-950"></div> |

  </div>
  <div class="grid_item">
  ### Primary

| Token         | Value   | Demo                                         |
| ------------- | ------- | -------------------------------------------- |
| `primary-50`  | #f0f9ff | <div class="docs_box bgc-primary-50"></div>  |
| `primary-100` | #e0f2fe | <div class="docs_box bgc-primary-100"></div> |
| `primary-200` | #bae6fd | <div class="docs_box bgc-primary-200"></div> |
| `primary-300` | #7dd3fc | <div class="docs_box bgc-primary-300"></div> |
| `primary-400` | #38bdf8 | <div class="docs_box bgc-primary-400"></div> |
| `primary-500` | #0ea5e9 | <div class="docs_box bgc-primary-500"></div> |
| `primary-600` | #0284c7 | <div class="docs_box bgc-primary-600"></div> |
| `primary-700` | #0369a1 | <div class="docs_box bgc-primary-700"></div> |
| `primary-800` | #075985 | <div class="docs_box bgc-primary-800"></div> |
| `primary-900` | #0c4a6e | <div class="docs_box bgc-primary-900"></div> |
| `primary-950` | #082f49 | <div class="docs_box bgc-primary-950"></div> |

  </div>
  <div class="grid_item">
  ### Feedback

| Token       | Value   | Demo                                       |
| ----------- | ------- | ------------------------------------------ |
| `yes-100`   | #d5f6e8 | <div class="docs_box bgc-yes-100"></div>   |
| `yes-200`   | #afebd4 | <div class="docs_box bgc-yes-200"></div>   |
| `yes-300`   | #7adbbd | <div class="docs_box bgc-yes-300"></div>   |
| `yes-400`   | #46c4a0 | <div class="docs_box bgc-yes-400"></div>   |
| `yes-500`   | #13886d | <div class="docs_box bgc-yes-500"></div>   |
| `no-100`    | #ffe4e6 | <div class="docs_box bgc-no-100"></div>    |
| `no-200`    | #fecdd3 | <div class="docs_box bgc-no-200"></div>    |
| `no-300`    | #fda4af | <div class="docs_box bgc-no-300"></div>    |
| `no-400`    | #fb7185 | <div class="docs_box bgc-no-400"></div>    |
| `no-500`    | #e11d48 | <div class="docs_box bgc-no-500"></div>    |
| `maybe-100` | #fff7d6 | <div class="docs_box bgc-maybe-100"></div> |
| `maybe-200` | #fff0b3 | <div class="docs_box bgc-maybe-200"></div> |
| `maybe-300` | #ffd64a | <div class="docs_box bgc-maybe-300"></div> |
| `maybe-400` | #ffc220 | <div class="docs_box bgc-maybe-400"></div> |
| `maybe-500` | #f9a007 | <div class="docs_box bgc-maybe-500"></div> |

  </div>
</div>

## Dimension

Dimension tokens can be used anywhere you need to set `margin`, `padding`, `width`, `height`, etc.

<div class="docs_oversizedTable">

| Token   | Value | Demo                                 |
| ------- | ----- | ------------------------------------ |
| `xs1`   | 4px   | <div class="docs_box w-xs1"></div>   |
| `xs2`   | 8px   | <div class="docs_box w-xs2"></div>   |
| `xs3`   | 12px  | <div class="docs_box w-xs3"></div>   |
| `sm1`   | 16px  | <div class="docs_box w-sm1"></div>   |
| `sm2`   | 20px  | <div class="docs_box w-sm2"></div>   |
| `sm3`   | 24px  | <div class="docs_box w-sm3"></div>   |
| `md1`   | 28px  | <div class="docs_box w-md1"></div>   |
| `md2`   | 32px  | <div class="docs_box w-md2"></div>   |
| `md3`   | 36px  | <div class="docs_box w-md3"></div>   |
| `lg1`   | 40px  | <div class="docs_box w-lg1"></div>   |
| `lg2`   | 44px  | <div class="docs_box w-lg2"></div>   |
| `lg3`   | 48px  | <div class="docs_box w-lg3"></div>   |
| `xl1`   | 56px  | <div class="docs_box w-xl1"></div>   |
| `xl2`   | 64px  | <div class="docs_box w-xl2"></div>   |
| `xl3`   | 80px  | <div class="docs_box w-xl3"></div>   |
| `xxl1`  | 96px  | <div class="docs_box w-xxl1"></div>  |
| `xxl2`  | 112px | <div class="docs_box w-xxl2"></div>  |
| `xxl3`  | 128px | <div class="docs_box w-xxl3"></div>  |
| `mega1` | 160px | <div class="docs_box w-mega1"></div> |
| `mega2` | 192px | <div class="docs_box w-mega2"></div> |
| `mega3` | 224px | <div class="docs_box w-mega3"></div> |
| `giga1` | 256px | <div class="docs_box w-giga1"></div> |
| `giga2` | 288px | <div class="docs_box w-giga2"></div> |
| `giga3` | 320px | <div class="docs_box w-giga3"></div> |
| `tera1` | 384px | <div class="docs_box w-tera1"></div> |
| `tera2` | 480px | <div class="docs_box w-tera2"></div> |
| `tera3` | 520px | <div class="docs_box w-tera3"></div> |

</div>

## Aspect ratio

| Token           | Value   | Demo                                       |
| --------------- | ------- | ------------------------------------------ |
| `ar-square`     | 1       | <div class="docs_box ar-square"></div>     |
| `ar-landscape`  | 4/3     | <div class="docs_box ar-landscape"></div>  |
| `ar-portrait`   | 3/4     | <div class="docs_box ar-portrait"></div>   |
| `ar-widescreen` | 16/9    | <div class="docs_box ar-widescreen"></div> |
| `ar-golden`     | 1.618/1 | <div class="docs_box ar-golden"></div>     |

## Typography

### Font stack

There are 3 font stacks set up by default for the `font-family` CSS Property.

| Token       | Value                                                                                                                                                           |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`      | ui-sans-serif, system-ui, sans-serif                                                                                                                            |
| `display`   | Avenir, Montserrat, Corbel, URW Gothic, source-sans-pro, ui-sans-serif, sans-serif                                                                              |
| `monospace` | Dank Mono, Inconsolata, Fira Mono, SF Mono, Monaco, Droid Sans Mono, Source Code Pro, Cascadia Code, Menlo, Consolas, DejaVu Sans Mono, ui-monospace, monospace |

These stacks are optimized for fonts available on device, to maximize for speed and alleviate any layout shifts or flashes. You can find more stacks at [Modern Font Stacks](https://modernfontstacks.com).

If you'd like to bring in your own fonts or [Google fonts](https://fonts.google.com), you can override the `display` and `text` tokens inside your theme file.

<Notice type="info" title="Note" class="mb-sm3">
  In case you're curious, `ui-sans-serif` is the system default, `sans-serif` is
  the browser default, and `system-ui` is the system default, wether serif or
  sans-serif.
</Notice>

### Font size

Check out [typescale.com ](https://typescale.com) if you need help creating your own sizes.

<div class="docs_oversizedTable">

| Token          | Value    | Demo                                           |
| -------------- | -------- | ---------------------------------------------- |
| `text-xs`      | 0.694rem | <div class="text-xs">Sample demo text</div>    |
| `text-sm`      | 0.833rem | <div class="text-sm">Sample demo text</div>    |
| `text-md`      | 1rem     | <div class="text-md">Sample demo text</div>    |
| `text-lg`      | 1.2rem   | <div class="text-lg">Sample demo text</div>    |
| `text-xl`      | 1.44rem  | <div class="text-xl">Sample demo text</div>    |
| `display-sm`   | 1.728rem | <div class="display-sm">Sample demo text</div> |
| `display-md`   | 2.074rem | <div class="display-md">Sample demo text</div> |
| `display-lg`   | 2.488rem | <div class="display-lg">Sample demo text</div> |
| `display-xl`   | 2.986rem | <div class="display-xl">Sample demo text</div> |
| `display-mega` | 3.583rem | <div class="display-mega">Demo text</div>      |
| `display-giga` | 4.299rem | <div class="display-giga">Demo text</div>      |

</div>

### Heading sizes

Headings use dedicated fluid tokens: each `--heading-*` interpolates with `clamp()` from a minimum size (at 480px viewports and below) to a maximum size (from 1024px up), so the type scale tightens on small screens without media queries. The preferred value mixes `rem` with `vw`, which keeps browser text zoom working. Override any of these in your own theme to change how a heading level scales.

<div class="docs_oversizedTable">

| Token       | Min (≤480px)         | Max (≥1024px)           |
| ----------- | -------------------- | ----------------------- |
| `heading-1` | `text-xl` (1.44rem)  | `display-md` (2.074rem) |
| `heading-2` | `text-lg` (1.2rem)   | `display-sm` (1.728rem) |
| `heading-3` | `text-lg` (1.2rem)   | `text-xl` (1.44rem)     |
| `heading-4` | `text-md` (1rem)     | `text-lg` (1.2rem)      |
| `heading-5` | `text-md` (1rem)     | `text-md` (static)      |
| `heading-6` | `text-md` (1rem)     | `text-md` (static)      |

</div>

### Font weight

| Token         | Value | Demo                                            |
| ------------- | ----- | ----------------------------------------------- |
| `extra-light` | 200   | <div class="font-extra-light">Sample demo text</div> |
| `light`       | 300   | <div class="font-light">Sample demo text</div>       |
| `book`        | 400   | <div class="font-book">Sample demo text</div>        |
| `semi-bold`   | 600   | <div class="font-semi-bold">Sample demo text</div>   |
| `bold`        | 700   | <div class="font-bold">Sample demo text</div>        |
| `black`       | 900   | <div class="font-black">Sample demo text</div>       |

### Letter spacing

| Token          | Value   | Demo                                             |
| -------------- | ------- | ------------------------------------------------ |
| `tracking-sm`  | -0.05em | <div class="tracking-sm">Sample demo text</div>  |
| `tracking-md`  | 0.025em | <div class="tracking-md">Sample demo text</div>  |
| `tracking-lg`  | 0.05em  | <div class="tracking-lg">Sample demo text</div>  |
| `tracking-xl`  | 0.075em | <div class="tracking-xl">Sample demo text</div>  |
| `tracking-xxl` | 0.15em  | <div class="tracking-xxl">Sample demo text</div> |

### Line height

| Token         | Value | Demo                                                                |
| ------------- | ----- | ------------------------------------------------------------------- |
| `leading-xs`  | 1     | <div class="docs_lineHeightDemo leading-xs">Sample demo text</div>  |
| `leading-sm`  | 1.15  | <div class="docs_lineHeightDemo leading-sm">Sample demo text</div>  |
| `leading-md`  | 1.375 | <div class="docs_lineHeightDemo leading-md">Sample demo text</div>  |
| `leading-lg`  | 1.5   | <div class="docs_lineHeightDemo leading-lg">Sample demo text</div>  |
| `leading-xl`  | 1.75  | <div class="docs_lineHeightDemo leading-xl">Sample demo text</div>  |
| `leading-xxl` | 2     | <div class="docs_lineHeightDemo leading-xxl">Sample demo text</div> |

## Borders

  <div class="grid" col="1" col-lg="2">
    <div class="grid_item docs_radius">

### Border radius

| Token          | Value | Demo        |
| -------------- | ----- | ----------- |
| `radius-sm`    | 3px   | <div></div> |
| `radius-md`    | 5px   | <div></div> |
| `radius-lg`    | 8px   | <div></div> |
| `radius-xl`    | 12px  | <div></div> |
| `radius-xxl`   | 16px  | <div></div> |
| `radius-round` | 1e5px | <div></div> |

    </div>
    <div class="grid_item docs_border">

      ### Border width

| Token        | Value | Demo        |
| ------------ | ----- | ----------- |
| `border-sm`  | 1px   | <div></div> |
| `border-md`  | 2px   | <div></div> |
| `border-lg`  | 4px   | <div></div> |
| `border-xl`  | 8px   | <div></div> |
| `border-xxl` | 12px  | <div></div> |

    </div>

  </div>

## Drop Shadow

It wouldn't be super useful to list the values here. You can look at them [on Github][githubShadows] if you're curious.

[githubShadows]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.tokens.css#L217

  <div class="docs_shadow">

| Token        | Demo        |
| ------------ | ----------- |
| `shadow-sm`  | <div></div> |
| `shadow-md`  | <div></div> |
| `shadow-lg`  | <div></div> |
| `shadow-xl`  | <div></div> |
| `shadow-xxl` | <div></div> |

  </div>

## Opacity

| Token | Value | Demo                                     |
| ----- | ----- | ---------------------------------------- |
| `o-0` | 0     | <span class="o-0">Opacity level 0</span> |
| `o-1` | 0.2   | <span class="o-1">Opacity level 1</span> |
| `o-2` | 0.4   | <span class="o-2">Opacity level 2</span> |
| `o-3` | 0.6   | <span class="o-3">Opacity level 3</span> |
| `o-4` | 0.8   | <span class="o-4">Opacity level 4</span> |
| `o-5` | 1     | <span class="o-5">Opacity level 5</span> |

## Z-index

| Token      | Value       |
| ---------- | ----------- |
| `z-bottom` | -1000000000 |
| `z-0`      | 0           |
| `z-1`      | 10          |
| `z-2`      | 20          |
| `z-3`      | 30          |
| `z-4`      | 40          |
| `z-5`      | 50          |
| `z-top`    | 1000000000  |

## Transition

| Token             | Value             |
| ----------------- | ----------------- |
| `transition`      | 220ms ease-in-out |
| `transition-fast` | 100ms ease-in-out |


---

# Media Queries

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/media-queries

| File name                    | Source        |
| ---------------------------- | ------------- |
| `settings.media-queries.css` | [Github][src] |

[src]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.media-queries.css

<Notice
  type="info"
  title="PostCSS needed for custom media queries"
  class="mt-sm3 mb-sm3"
>
  [Custom media queries][custom] are not yet available without a [PostCSS
  plugins][postcss]. If you can't or don't want to add a build step to your
  process, you'll have to hard code your breakpoints. (You can still use nesting
  as in the example below though.)
</Notice>

## Available Media Queries

### Dimensions

<div class="docs_oversizedTable">

| Token keyword | Dimension (px) |
| ------------- | -------------- |
| `xxs`         | 0-240          |
| `xs`          | 240-360        |
| `sm`          | 360-480        |
| `md`          | 480-768        |
| `lg`          | 768-1024       |
| `xl`          | 1024-1440      |
| `xxl`         | 1440-1920      |

</div>

### Variations

Using the `md` dimension as an example:

<div class="docs_oversizedTable">

| Token variation | Matches                      |
| --------------- | ---------------------------- |
| `--md-only`     | exact range                  |
| `--md-n-above`  | range top and above          |
| `--md`          | shorthand for `--md-n-above` |
| `--md-n-below`  | range top and below          |
| `--md-phone`    | exact range in portrait only |

</div>

### Examples

<div class="docs_oversizedTable">

| Custom media query        | Value                           |
| ------------------------- | ------------------------------- |
| `@media(--md-only) {}`    | `(480px <= width < 768px);`     |
| `@media(--md) {}`         | `(width >= 768px);`             |
| `@media(--md-n-above) {}` | `(width >= 768px);`             |
| `@media(--md-n-below) {}` | `(width <section 768px);`       |
| `@media(--md-phone) {}`   | `(--md-only) and (--portrait);` |

</div>

## Recommended responsive setup

If you search online for the best approach to responsive design and setting up your breakpoints, you'll come accross the technically true but useless "it depends" answer.

Unless you have a good reason not to, you should use a mobile first approach. What that means is you design will work great on small screen out of the box, without any media queries, and then you add your tweaks for additional sizes.

This is how the CSS of most responsive components should be set up:

```css
.exampleComponent {
  /* default mobile */
  @media (--lg) {
    /* responsive tweaks for desktop */
  }
}
```

Without [PostCSS plugins][postcss]:

```css
.exampleComponent {
  /* default mobile */
  @media (width >= 1024px) {
    /* responsive tweaks for desktop */
  }
}
```

[custom]: https://drafts.csswg.org/mediaqueries-5/#custom-mq
[postcss]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-media


---

# Themes

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/themes

<Notice type="warning" title="Work in progress" class="mt-lg1">
  This feature is still in beta and the implementation details are likely to
  change during the development of mCSS components. However, if you use the mCSS
  framework to build your own components, it is recommended to use a theme as a
  token abstraction layer.
</Notice>

## Default theme

<div class="docs_oversizedTable">

| File name                    | Source               |
| ---------------------------- | -------------------- |
| `settings.theme.default.css` | [Github][srcDefault] |

</div>

[srcDefault]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

Themes offer an additional layer of abstraction for [tokens](/docs/tokens). Theme tokens only ever take another token for value and are useful to standardize UI elements in logical groups. For example, you can have a `--light-border-color` with a value of `--base-100`. This allows you to create tokens with meaning and context which makes them more intuitive to use.


---

# Reset

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/reset

<div class="docs_oversizedTable">

| File name        | Source        |
| ---------------- | ------------- |
| `base.reset.css` | [Github][src] |

</div>

The mCSS reset is kept to a minimum. It does the following:

- It sets the `box-sizing` to `border-box`
- It removes the default `margin` on all elements
- It sets the document's `min-height` to 100%.

The rest of the defaults that would traditionally be included in a "reset" or "normalize" file are handled by the `elements.*.css` files. Refer to the [mCSS File structure][structure] section of _Getting Started_ for more details.

You can find an example of all HTML elements default styling in the [next section](/docs/elements).

[structure]: /docs/start#mcss-file-structure
[src]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/base.reset.css


---

# HTML Elements

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/elements

## Sectioning

<section class="docs_section prose">

<div class="docs_oversizedTable">

| File name                 | Source                  |
| ------------------------- | ----------------------- |
| `elements.sectioning.css` | [Github][srcSectioning] |

</div>

[srcSectioning]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.sectioning.css

  Technically, `address` and `h1` — `h6` are [content sectioning elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element#content_sectioning), like `header`, `section`, etc. But mCSS approach is to prioritize intuitiveness and ease of use rather than technical correctness, so they're included here with the rest of the text elements.

## Text

<section class="docs_section prose">

<div class="docs_oversizedTable">

| File name                 | Source                  |
| ------------------------- | ----------------------- |
| `elements.text.css` | [Github][srcText] |

</div>

[srcText]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.text.css

  ### Headings

  Heading sizes are fluid: they scale smoothly between a mobile minimum and a desktop maximum via the `--heading-1`…`--heading-6` tokens (see [tokens](/docs/tokens)). Resize the viewport to see it in action.

  <h1>Heading One</h1>
  <p>A small paragraph of text to show the heading in context.</p>
  <h2>Heading Two</h2>
  <p>A small paragraph of text to show the heading in context.</p>
  <h3>Heading Three</h3>
  <p>A small paragraph of text to show the heading in context.</p>
  <h4>Heading Four</h4>
  <p>A small paragraph of text to show the heading in context.</p>
  <h5>Heading Five</h5>
  <p>A small paragraph of text to show the heading in context.</p>
  <h6>Heading Six</h6>
  <p>A small paragraph of text to show the heading in context.</p>

  <h1>Consecutive headings get less margin… H1 followed by a H2</h1>
  <h2>H2 right aftert a H1</h2>
  <h3>H3 right aftert a H2</h3>
  <h4>H4 right aftert a H3</h4>

  ### Inline Elements

<div class="docs_oversizedTable">

| Element    | Example                                                                      |
| ---------- | ---------------------------------------------------------------------------- |
| `<a>`      | <a href="#!">This is a text link</a>.                                        |
| `<abbr>`   | Abbreviation: <abbr title="HyperText Markup Language">HTML</abbr> in a sentence.           |
| `<b>`      | The <b>b element</b> is only stylistically different text from normal text.  |
| `<cite>`   | <cite>This is a citation.</cite>                                             |
| `<del>`    | <del>This text is deleted</del>                                              |
| `<dfn>`    | The <dfn>dfn element</dfn> indicates a definition.                           |
| `<em>`     | <em>This text has added emphasis.</em>                                       |
| `<i>`      | The <i>i element</i> is text that is offset from the normal text.            |
| `<ins>`    | <ins>This text is inserted.</ins>                                            |
| `<mark>`   | The <mark>mark element</mark> indicates a highlight.                         |
| `<q>`      | <q cite="https://dub.sh/mdn-html-q">This is a short inline quotation.</q>    |
| `<s>`      | <s>This text has a strikethrough</s>.                                        |
| `<small>`  | <small>This small text is small for fine print, etc.</small>                 |
| `<strong>` | <strong>Strong is used to indicate strong importance.</strong>               |
| `<sub>`    | Subscript for things like H<sub>2</sub>O.                                    |
| `<sup>`    | Superscript<sup>™️</sup>.                                                     |
| `<var>`    | The <var>variable element</var>, such as <var>x</var> = <var>y</var>.        |

</div>

<section class="docs_section prose">
  ### Paragraphs

  A paragraph (from the Greek paragraphos, “to write beside” or “written beside”) is a self-contained unit of a discourse in writing dealing with a particular point or idea. A paragraph consists of one or more sentences.

  Though not required by the syntax of any language, paragraphs are usually an expected part of formal writing, used to organize longer prose.

<section class="docs_section prose">
  ### Definition list

  <dl>
    <dt>Definition List description term</dt>
    <dd>This is a definition list description details</dd>
    <dt>Another description</dt>
    <dd>With the related description details</dd>
  </dl>

  ### Ordered List

  1. List Item
  1. List Item
      1. List Item
      1. List Item
          1. List Item
          1. List Item
      1. List Item
      1. List Item
  1. List Item
  1. List Item

  ### Unordered List

  - List Item
  - List Item
    - List Item
    - List Item
      - List Item
      - List Item
    - List Item
    - List Item
  - List Item
  - List Item

<section class="docs_section prose">
  ### Blockquotes

  <blockquote cite="#!">
    <p>It would be going too far to call our modern offices sensory-deprivation chambers, but they are most certainly sensory-reduction chambers. They may not brainwash, but the elimination of sensory stimuli definitely increases focus on the task at hand, the work to be done, to the exclusion of all else. Modern offices were designed for that very purpose by people who knew what they were doing.</p>
  </blockquote>
  <p>—Jerry Mander, <cite>Four arguments for the elimination of television</cite></p>

<section class="docs_section prose">
  ### Horizontal Rule

  The object of life is not to be on the side of the majority, but to escape finding oneself in the ranks of the insane.

  <hr />

  You have power over your mind — not outside events. Realize this, and you will find strength.

  <section class="docs_section prose">
  ### code

  <p>
    <strong>Keyboard input: </strong>
    <kbd>Cmd</kbd>
  </p>
  <p>
    <strong>Inline code: </strong>
    <code>&lt;div&gt;code&lt;/div&gt;</code>
  </p>
  <p>
    <strong>Sample output: </strong>
    <samp>This is sample output from a computer program.</samp>
  </p>

  ### Pre-formatted text

  <pre>
    P R E F O R M A T T E D T E X T !
    " # $ % &amp; ' ( ) * + , - . / 0 1 2
    3 4 5 6 7 8 9 : ; &lt; = &gt; ? @ A B C
    D E F G H I J K L M N O P Q R S T
    U V W X Y Z [ \ ] ^ _ ` a b c d e
    f g h i j k l m n o p q r s t u v
    w x y z ~
  </pre>

<section class="docs_section">
  ### Address

  <address>
    <p>Retro whimsical default… Because, why not?</p>
    <a href="mailto:sonny@rollins.com">sonny@rollins.com</a>
    <br />
    <a href="tel:+12121231234">+1 (212) 123 1234</a>
  </address>

## Table

<section class="docs_section prose">

<div class="docs_oversizedTable">

| File name            | Source             |
| -------------------- | ------------------ |
| `elements.table.css` | [Github][srcTable] |

</div>

[srcTable]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.table.css

  <table>
    <caption>Numbers of albums recorded</caption>
    <thead>
      <tr>
        <th scope="col">Musician</th>
        <th scope="col">Instrument</th>
        <th scope="col">Albums</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row">Sonny Rollins</th>
        <td>Saxophone</td>
        <td>60</td>
      </tr>
      <tr>
        <th scope="row">John Coltrane</th>
        <td>Saxophone</td>
        <td>56</td>
      </tr>
      <tr>
        <th scope="row">Joe Henderson</th>
        <td>Saxophone</td>
        <td>25</td>
      </tr>
      <tr>
        <th scope="row">Wayne Shorter</th>
        <td>Saxophone</td>
        <td>36</td>
      </tr>
    </tbody>
    <tfoot>
      <tr>
        <th scope="row" colspan="2">Total Albums</th>
        <td>177</td>
      </tr>
    </tfoot>
  </table>

## Form

<section class="docs_section prose">

| File name            | Source           |
| -------------------- | ---------------- |
| `elements.form.css` | [Github][srcForm] |

[srcForm]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.form.css

See [How to structure a web form](https://developer.mozilla.org/en-US/docs/Learn/Forms/How_to_structure_a_web_form) on MDN.

This is just the bare minimum default styles to make any form look consistent out of the box. See the [form component](/components/form) for more.

The `legend` HTML element is notoriously impractical to style. The example below uses the following workaround:

```html
<legend>Example of custom fieldset legend</legend>
<div aria-hidden="true">Example of a fieldset legend</div>
```

```css
fieldset {
  > [aria-hidden] {
    /* [styling goes her…] */
  }
}

legend {
  /*  Visually hidden  */
  position: absolute;
  overflow: hidden;
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
  width: 1px;
  height: 1px;
  white-space: nowrap;
}
```

<section class="docs_section">
  <form class="docs_form">
    <fieldset>
      <legend>Example of custom fieldset legend</legend>
      <div aria-hidden="true">Example of a fieldset legend</div>
      <p>
        <label for="text">Text Input</label>
        <input id="text" type="text" placeholder="Text Input" />
      </p>
      <p>
        <label for="password">Password</label>
        <input id="password" type="password" placeholder="Type your Password" />
      </p>
      <p>
        <label for="webaddress">Web Address</label>
        <input id="webaddress" type="url" placeholder="https://yoursite.com" />
      </p>
      <p>
        <label for="emailaddress">Email Address</label>
        <input id="emailaddress" type="email" placeholder="name@email.com" />
      </p>
      <p>
        <label for="phone">Phone Number</label>
        <input id="phone" type="tel" placeholder="(999) 999-9999" />
      </p>
      <p>
        <label for="search">Search</label>
        <input id="search" type="search" placeholder="Enter Search Term" />
      </p>
      <p>
        <label for="text2">Number Input</label>
        <input id="text2" type="number" placeholder="Enter a Number" />
      </p>
      <p>
        <label for="file">File Input</label>
        <input id="file" type="file" />
      </p>
    </fieldset>
    <fieldset>
      <legend>Select menus</legend>
      <p>
        <label for="select">Select</label>
        <select id="select">
          <optgroup label="Group 1">
            <option>Option One</option>
            <option>Option Two</option>
            <option>Option Three</option>
          </optgroup>
          <optgroup label="Group 2">
            <option>Option One</option>
            <option>Option Two</option>
            <option>Option Three</option>
          </optgroup>
        </select>
      </p>
      <p>
        <label for="select">Select (disabled)</label>
        <select id="select" disabled>
            <option>Not Available</option>
        </select>
      </p>
      <p>
        <label for="select_multiple">Select (multiple)</label>
        <select id="select_multiple" multiple>
          <optgroup label="Group 1">
            <option>Option One</option>
            <option>Option Two</option>
            <option>Option Three</option>
          </optgroup>
          <optgroup label="Group 2">
            <option>Option One</option>
            <option>Option Two</option>
            <option>Option Three</option>
          </optgroup>
        </select>
      </p>
    </fieldset>
    <fieldset>
      <legend>Checkboxes</legend>
      <ul>
        <li>
          <label for="checkbox1">
            <input
              id="checkbox1"
              name="checkbox"
              type="checkbox"
              checked
            /> Choice A
          </label>
        </li>
        <li>
          <label for="checkbox2">
            <input id="checkbox2" name="checkbox" type="checkbox" /> Choice B
          </label>
        </li>
        <li>
          <label for="checkbox3">
            <input id="checkbox3" name="checkbox" type="checkbox" /> Choice C
          </label>
        </li>
      </ul>

      <legend>Radio buttons</legend>
      <ul>
        <li>
          <label for="radio1">
            <input id="radio1" name="radio" type="radio" checked /> Option 1
          </label>
        </li>
        <li>
          <label for="radio2">
            <input id="radio2" name="radio" type="radio" /> Option 2
          </label>
        </li>
        <li>
          <label for="radio3">
            <input id="radio3" name="radio" type="radio" /> Option 3
          </label>
        </li>
      </ul>
    </fieldset>
    <fieldset>
      <legend>Textareas</legend>
      <p>
        <label for="textarea">Textarea</label>
        <textarea
          id="textarea"
          rows="5"
          cols="10"
          placeholder="Enter your message here"
        ></textarea>
      </p>
    </fieldset>
    <fieldset>
      <legend>HTML5 inputs</legend>
      <p>
        <label for="ic">Color input</label>
        <input type="color" id="ic" value="#38bdf8" />
      </p>
      <p>
        <label for="in">Number input</label>
        <input type="number" id="in" min="0" max="10" value="5" />
      </p>
      <p>
        <label for="ir">Range input</label>
        <input type="range" id="ir" value="10" />
      </p>
      <p>
        <label for="idm">Month input</label>
        <input type="month" id="idm" value="2024-06" />
      </p>
      <p>
        <label for="idw">Week input</label>
        <input type="week" id="idw" value="2024-W25" />
      </p>
      <p>
        <label for="idate">Date input</label>
        <input
          type="date"
          id="idate"
          value="2024-06-18"
          min="2024-01-01"
          max="2030-12-31"
        />
      </p>
      <p>
        <label for="itime">Time input</label>
        <input type="time" id="itime" min="09:00" max="18:00" />
      </p>
      <p>
        <label for="idtl">Date & time input</label>
        <input type="datetime-local" id="idtl" value="2024-06-18T00:00" />
      </p>
      <p>
        <label for="idl">Datalist</label>
        <input type="text" id="idl" list="example-list" />
        <datalist id="example-list">
          <option value="Example #1"></option>
          <option value="Example #2"></option>
          <option value="Example #3"></option>
        </datalist>
      </p>
    </fieldset>
    <fieldset>
      <legend>Action buttons</legend>
      <p>
        <input class="bt" type="submit" value="Submit Input" />
        <input class="bt" type="reset" value="Reset Input" />
        <input class="bt" type="submit" value="Disabled Input" disabled />
      </p>
      <p>
        <button class="bt" type="submit">Submit Button</button>
        <button class="bt" type="button">Button</button>
        <button class="bt" type="reset">Reset Button</button>
        <button class="bt" type="button" disabled>Disabled Button</button>
      </p>
    </fieldset>
  </form>

  ### Meter

```html
<meter value="2" min="0" max="10" low="3" high="6" optimum="8">
    2 out of 10
</meter>
<meter value="5" min="0" max="10" low="3" high="6" optimum="8">
    5 out of 10
</meter>
<meter value="8" min="0" max="10" low="3" high="6" optimum="8">
    8 out of 10
</meter>
  ```

<p>
  <meter value="2" min="0" max="10" low="3" high="6" optimum="8">2 out of 10</meter>
</p>
<p>
  <meter value="5" min="0" max="10" low="3" high="6" optimum="8">5 out of 10</meter>
</p>
<p class="mb-lg3">
  <meter value="8" min="0" max="10" low="3" high="6" optimum="8">8 out of 10</meter>
</p>

### Progress

<p class="mb-lg3">
  <label for="progress-bar">Uploading Document: 70%</label>
  <progress id="progress-bar" value="70" max="100">70%</progress>
</p>

## Media

<section class="docs_section prose">

| File name            | Source             |
| -------------------- | ------------------ |
| `elements.media.css` | [Github][srcMedia] |

[srcMedia]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.media.css

  <ul class="docs_section_media">
    <li>
      Plain `<img>` element
      <Image src={img} width="384" alt="Saxophonist playing in Central Park" />
    </li>
    <li>
      `<figure>` element with `<img>` element
      <figure><Image src={img} width="384" alt="Saxophonist playing in Central Park" /></figure>
    </li>
    <li>
      `<figure>` element with `<img>` and `<figcaption>` elements
      <figure>
        <Image src={img} width="384" alt="Saxophonist playing in Central Park" />
        <figcaption>Here is a caption for this image.</figcaption>
      </figure>
    </li>
    <li>
      `<figure>` element with a `<picture>` element
      <figure>
        <picture>
          <source srcset={img.src} width="384" media="(min-width: 800px)" />
          <Image src={imgCrop} width="384" alt="Saxophonist playing in Central Park" />
        </picture>
      </figure>
    </li>
  </ul>

<section class="docs_section">
  ### Audio
  <audio controls>
    <source src={audioFile} type="audio/mpeg" />
    Your browser does not support the audio element.
  </audio>

<section class="docs_section">
  ### Video
  <video controls width="384">
    <source src={videoFile} type="video/mp4" />
    Your browser does not support the video element.
  </video>

<section class="docs_section">
  ### Canvas
  <script src="/_js/triangles.js" type="module"></script>
  <canvas class="triangles docs_canvas">canvas</canvas>

<section class="docs_section">
  ### Inline Frame
  <iframe width="384" height="200" src="https://www.openstreetmap.org/export/embed.html?bbox=115.69423198699953%2C-8.367407790226663%2C115.70669889450075%2C-8.358820459526953&layer=mapnik&marker=-8.363114148527767%2C115.70046544075012"></iframe>

<section class="docs_section prose">
  ### Inline SVG
  <svg width="100px" height="100px">
    <circle cx="50" cy="50" r="50" fill="#0ea5e9"></circle>
  </svg>

## Interactive

<section class="docs_section prose">

| File name            | Source             |
| -------------------- | ------------------ |
| `elements.interactive.css` | [Github][srcInteractive] |

[srcInteractive]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.interactive.css

  ### Details & Summary
  <details>
    <summary>Expand for details</summary>
    <p>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.</p>
  </details>

<section class="docs_section">
  ### Dialog
  <dialog>
    <button aria-label="close pop-up"><Fragment set:html={iconX} /></button>
    <h3>A random quote you might enjoy…</h3>
    <p><q>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.</q></p>
  </dialog>
  <button class="bt">Show the dialog</button>

<script src="/_js/DocsElementsScript.js" type="module"></script>


---

# Global Styles

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/docs/global

## Grid

<section class="docs_section prose">

<div class="docs_oversizedTable">

| File name         | Source            |
| ----------------- | ----------------- |
| `global.grid.css` | [Github][srcGrid] |

</div>

[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 the [default theme](/docs/themes) 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
<ul class="grid photoWall" col="2" col-lg="4">
  ...
</ul>
```

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

<Notice type="info" title="HTML Validation">
  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).
</Notice>

### Examples

#### Different types of spans

9 colum grid, with all types of spans.

<div class="grid docs_grid" col="9">
  <div class="grid_item docs_grid_item" span="2"><span>2</span></div>
  <div class="grid_item docs_grid_item" span="4-5"><span>4-5</span></div>
  <div class="grid_item docs_grid_item" span="6..">6..</div>
  <div class="grid_item docs_grid_item" span="2-3"><span>2-3</span></div>
  <div class="grid_item docs_grid_item" span="5.."><span>5..</span></div>
  <div class="grid_item docs_grid_item" span="2+3"><span>2+3</span></div>
  <div class="grid_item docs_grid_item" span="6+2"><span>6+2</span></div>
  <div class="grid_item docs_grid_item" span="row"><span>row</span></div>
  <div class="grid_item docs_grid_item" span="4+2"><span>4+2</span></div>
</div>

```html
<div class="grid" col="9">
  <div class="grid_item" span="2">2</div>
  <div class="grid_item" span="4-5">4-5</div>
  <div class="grid_item" span="6..">6..</div>
  <div class="grid_item" span="2-3">2-3</div>
  <div class="grid_item" span="5..">5..</div>
  <div class="grid_item" span="2+3">2+3</div>
  <div class="grid_item" span="6+2">6+2</div>
  <div class="grid_item" span="row">row</div>
  <div class="grid_item" span="4+2">4+2</div>
</div>
```

#### 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.)

<div class="grid docs_grid" col="1" col-md="4" col-lg="9" col-xl="12">
  <div class="grid_item docs_grid_item">1</div>
  <div class="grid_item docs_grid_item">2</div>
  <div class="grid_item docs_grid_item">3</div>
  <div class="grid_item docs_grid_item">4</div>
  <div class="grid_item docs_grid_item">5</div>
  <div class="grid_item docs_grid_item">6</div>
  <div class="grid_item docs_grid_item">7</div>
  <div class="grid_item docs_grid_item">8</div>
  <div class="grid_item docs_grid_item">9</div>
  <div class="grid_item docs_grid_item">10</div>
  <div class="grid_item docs_grid_item">11</div>
  <div class="grid_item docs_grid_item">12</div>
</div>

```html
<div class="grid" col="1" col-md="4" col-lg="9" col-xl="12">[…]</div>
```

## Wrap

<section class="docs_section prose">

<div class="docs_oversizedTable">

| File name         | Source            |
| ----------------- | ----------------- |
| `global.wrap.css` | [Github][srcWrap] |

</div>

[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 default `.wrap_content` has a width of `minmax(200px, 70ch)` by default (see below to customize) and there is a modifier `.wrap_content-fullBleed` that will extend to the full size of the viewport. See [demo](/demos/wrap).

### Syntax

```html
<div class="wrap">
  <section class="wrap_content">
    <!-- 800px wide content -->
  </section>
</div>

<div class="wrap">
  <section class="wrap_content wrap_content-fullBleed">
    <!-- Viewport width content -->
  </section>
</div>
```

### 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 the default theme.

<div class="docs_oversizedTable">

| 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`      | `minmax(200px, 70ch)` | 200px minimum, 70ch maximum      |

</div>

- More info on [themes](/docs/themes).
- More info on [responsive setup](/docs/media-queries#recommended-responsive-setup).

## Layouts

<section class="docs_section prose">

<div class="docs_oversizedTable">

| File name           | Source              |
| ------------------- | ------------------- |
| `global.layout.css` | [Github][srcLayout] |

</div>

[srcLayout]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/global.layout.css

This is where your global layouts should go. It's probably too project specific for mCSS to ship with really useful default layouts. But this will change as more [components](/components/start) become available.

<Notice type="warning" title="Work in progress">
  The layouts in this file are specific to mcss.dev docs and blog sections.
  They're not built as templates to use in your own projects but rather as
  examples of how to set it up.
</Notice>

## Prose

<section class="docs_section prose">

<div class="docs_oversizedTable">

| File name          | Source             |
| ------------------ | ------------------ |
| `global.prose.css` | [Github][srcProse] |

</div>

[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 make spacing between paragraphs, lists, tables, etc. consistant. This spacing can be modified in your [theme](/docs/theme) via the `--prose-spacing` token.

The `.prose` class also adds extra styling for `ol`, `ul`, and `code` elements.

## Accessibility

<section class="docs_section prose">

<div class="docs_oversizedTable">

| File name         | Source            |
| ----------------- | ----------------- |
| `global.a11y.css` | [Github][srcA11y] |

</div>

[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

<section class="docs_section animation">

<div class="docs_oversizedTable">

| File name              | Source                 |
| ---------------------- | ---------------------- |
| `global.animation.css` | [Github][srcAnimation] |

</div>

[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
<div class="myComponent pt-lg3 pb-lg3">
  <p>Content goes here.</p>
</div>
```

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/token#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`         |
| `padding`        | `p`          |
| `padding-top`    | `pt`         |
| `padding-bottom` | `pb`         |
| `padding-left`   | `pl`         |
| `padding-right`  | `pr`         |

#### Examples

| Class    | Value                       |
| -------- | --------------------------- |
| `w-lg1`  | `width: var(--lg1)`         |
| `ml-0`   | `margin-left: 0`            |
| `mb-sm1` | `margin-bottom: var(--sm1)` |

```html
<div class="component mb-lg3">
  A component with an extra bottom margin of 48px.
</div>

<div class="component p-md1">
  A component with an extra padding of 28px.
</div>
```

## 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

<div class="docs_oversizedTable">

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

</div>

<div class="c-base-0 bgc-primary-600 p-sm1">
  <p class="mb-0">A block with custom colors.</p>
</div>

```html
<div class="c-base-0 bgc-primary-600">
  <p>A block with custom colors.</p>
</div>
```

## Layout

| File name         | Source              |
| ----------------- | ------------------- |
| `help.layout.css` | [Github][srcLayout] |

[srcLayout]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/help.layout.css

### overflow

<div class="docs_oversizedTable">

| 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`  |

</div>

### position

Helper classes for the `position` property.

<div class="docs_oversizedTable">

| CSS value  | Class                |
| ---------- | -------------------- |
| `static`   | `.position-static`   |
| `fixed`    | `.position-fixed`    |
| `absolute` | `.position-absolute` |
| `relative` | `.position-relative` |
| `sticky`   | `.position-sticky`   |

</div>

### visibility

Helper classes for the `visibility` property.

<div class="docs_oversizedTable">

| CSS value  | Class                  |
| ---------- | ---------------------- |
| `visible`  | `.visibility-visible`  |
| `hidden`   | `.visibility-hidden`   |
| `collapse` | `.visibility-collapse` |

</div>

### z-index

Helper classes for the `z-index` property. See also the [z-index token docs](docs/tokens#z-index).

<div class="docs_oversizedTable">

| 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`    |

</div>

## Aspect ratios

| File name         | Source              |
| ----------------- | ------------------- |
| `help.ratios.css` | [Github][srcRatios] |

[srcRatios]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/help.ratios.css

<div class="docs_oversizedTable">

| 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`     |

</div>

## 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.

<div class="docs_oversizedTable">

| Custom Property | Class           |
| --------------- | --------------- |
| `--text`        | `.font-text`    |
| `--display`     | `.font-display` |
| `--mono`        | `.font-mono`    |

</div>

### font-style

| CSS value | Class          |
| --------- | -------------- |
| `italic`  | `.font-italic` |
| `normal`  | `.font-normal` |

### font-weight

See the [font weight tokens](/docs/tokens#font-weight) for details.

<div class="docs_oversizedTable">

| 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`       |

</div>

### 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`     |

### 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 Code, Cursor, Copilot, and friends) 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 is idiomatic mCSS instead of a plausible-looking guess.

## Machine-readable docs

Three things exist specifically for agents:

- **[/llms.txt](/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](/llms-full.txt)**: the entire reference (docs and all components) concatenated into a single markdown file. Point an agent here 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 with `.md` appended. For example, [/docs/tokens.md](/docs/tokens.md) or [/components/card.md](/components/card.md). These are a fraction of the size of the HTML pages and contain no site chrome.

If you tell your agent one thing, tell it this: 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 copy-it-you-own-it CSS framework.
The framework files live in this repo, not in node_modules; treat them as
project code, not as an immutable dependency.
Full reference: https://mcss.dev/llms-full.txt
Per-page markdown docs: append `.md` to any docs or components URL
(e.g. https://mcss.dev/components/card.md).

### Class naming (BEM-like, different separators)

- Block: `.componentName` (camelCase for multi-word names)
- Element: `.componentName_element` (single underscore; chains may nest as deep
  as the block's own structure needs)
- Modifier: `.componentName-modifier` (single hyphen), for build-time variants
- State: `.is-*` (`.is-active`, `.is-open`), only for things that change at
  runtime, always scoped inside the block
- Prefer styling ARIA attributes over inventing state classes when one exists:
  `[aria-current]`, `[aria-expanded="true"]`, `[aria-disabled="true"]`

### Never couple classes from different components

A selector must only contain classes from its own block. Never write a selector
that reaches into another component (`.myPage .card_title` is banned). To style
a component from outside: mix your own class onto its root in the markup and
style that, or set the component's theme tokens (`--card-*`, `--bt-*`, ...) on
your own hook class. Bare HTML tags, `.is-*`, and ARIA selectors are fine
inside your own block.

### Customization (you own the files)

- Customize by editing the framework files directly, tokens first: change
  `settings.tokens.css` values (colors, type, spacing) before touching
  component CSS.
- Component tokens follow `--component-part-property`, longhand, kebab-case:
  `--bt-background-color-hover`, `--notice-border-width`. No abbreviations.
- Prefer semantic feedback tokens (`--success-*`, `--danger-*`, `--warning-*`).

### Cascade model (native @layer)

- The framework lives in cascade layers; your unlayered project CSS beats all
  of it by design. Never add `!important` to win against the framework.
- The exception: helper classes (`help.*` files, e.g. spacing/color/typography
  utilities) carry `!important` and beat everything, like inline styles.
- Never use `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 has a "What to copy" table listing exactly which files, icons, and theme 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 deliberately close to the platform: almost everything here is zero-JavaScript (the exceptions are the [header](/components/header)'s mobile menu and the dismissible [banner](/components/banner), a few lines each). Styling lives in [cascade layers](/docs/start), so your own unlayered CSS always wins, and every visual knob is a documented `--component-*` token in the [default theme](/docs/themes).

Spotted a bug, or built something worth sharing? [Issues and discussions](https://github.com/minimaldesign/mCSS/issues) are open.


---

# Badge

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/badge

The `.badge` atom is a small label for statuses, categories, and "new" markers. Pure CSS; there is no Astro component because a `<span>` with a class is already the whole API.

<p>
  <span class="badge">default</span>&ensp;
  <span class="badge badge-primary">primary</span>&ensp;
  <span class="badge badge-success">success</span>&ensp;
  <span class="badge badge-danger">danger</span>&ensp;
  <span class="badge badge-warning">warning</span>
</p>

<div class="docs_oversizedTable">

| File                               | Description                    | Source      |
| ---------------------------------- | ------------------------------ | ----------- |
| `atom.badge.css`                   | All badge styles               | [Github][1] |
| `--badge-*` block in default theme | Theme tokens (see table below) | [Github][2] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/atom.badge.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## Playground

<Playground
  client:visible
  template={'<span class="{classes}">{label}</span>'}
  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
<span class="badge">default</span>
<span class="badge badge-success">shipped</span>
```

### Available modifiers

<div class="docs_oversizedTable">

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

</div>

One-off colors work like every other variant in mCSS: override the local custom property.

```html
<span class="badge" style="--badge-background-color: rebeccapurple">custom</span>
```

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

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

</div>


---

# Button

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/button

The `button` [atom](/docs/start#atoms) uses the `.bt` class (canonical; `.button` is kept as an alias). Apply it to `<button>`, `<input type="submit">`, or `<a>` elements for a consistent look. All modifiers use the `bt-` prefix either way.

For accessibility, use `<button>` for actions and `<a>` for navigation. If you use `<a>` as a button, add `role="button"` and `tabindex="0"` and `aria-disabled="true"` if disabled.

<button class="bt bt-lg bt-primary mt-sm1">Sample Large Button</button>

<div class="docs_oversizedTable">

| File              | Description | Source      |
| ----------------- | ----------- | ----------- |
| `atom.button.css` | All button styles (`.button` or `.bt`) | [Github][1] |

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/atom.button.css

</div>

## Playground

<Playground
  client:visible
  template={'<button class="{classes}"{attrs}>{icon}{label}</button>'}
  baseClasses="bt"
  snippets={{ icon: { preview: mail, code: "<svg>[…]</svg> " } }}
  controls={[
    { heading: "Variation", items: [
      { type: "select", name: "size", label: "Size", default: "", options: [
        { label: "Default", value: "" },
        { label: "Medium", value: "bt-md" },
        { label: "Large", value: "bt-lg" },
      ]},
      { type: "select", name: "color", label: "Color", default: "", options: [
        { label: "Default", value: "" },
        { label: "Primary", value: "bt-primary" },
        { label: "Yes", value: "bt-yes" },
        { label: "Maybe", value: "bt-maybe" },
        { label: "No", value: "bt-no" },
        { label: "White", value: "bt-white", previewSurface: "dark" },
        { label: "White outline", value: "bt-outline-white", previewSurface: "dark" },
      ]},
    ]},
    { heading: "Modifiers", items: [
      { type: "checkbox", name: "outline", label: "Outline", value: "bt-outline", default: false },
      { type: "checkbox", name: "text", label: "Text button", value: "bt-text", default: false },
      { type: "checkbox", name: "icon", label: "Icon", snippet: "icon", default: false },
      { type: "checkbox", name: "tightIcon", label: "Tight icon", value: "bt-tightIcon", default: false },
    ]},
    { heading: "Content", items: [
      { type: "text", name: "label", label: "Label", default: "Button" },
    ]},
    { heading: "State", items: [
      { type: "checkbox", name: "disabled", label: "Disabled", attr: "disabled", default: false },
    ]},
  ]}
/>

## HTML

You can combine modifiers in any way you like (see [examples](#examples)).

The `.bt-outline-white` and `.bt-white` (solid, primary text) are special case buttons useful for dark/image/gradient backgrounds such as [Heroes](/components/hero) and don't change between light/dark themes.

<div class="docs_oversizedTable">

| Available modifiers                    | Style                                                                                  |
| -------------------------------------- | -------------------------------------------------------------------------------------- |
| `.bt`                                  | <button class="bt">Default Button</button>                                             |
| `.bt.bt-md`                            | <button class="bt bt-md">Medium Size</button>                                          |
| `.bt.bt-lg`                            | <button class="bt bt-lg">Large Size</button>                                           |
| `.bt.bt-outline`                       | <button class="bt bt-outline">Outline Button</button>                                  |
| `.bt.bt-outline-white`                 | <button class="bt bt-outline-white">White Outline</button>                             |
| `.bt.bt-white`                         | <button class="bt bt-white">Solid White</button>                                       |
| `.bt.bt-primary`                       | <button class="bt bt-primary">Primary CTA</button>                                     |
| `.bt.bt-yes`                           | <button class="bt bt-yes">Action Button</button>                                       |
| `.bt.bt-maybe`                         | <button class="bt bt-maybe">Action Button</button>                                     |
| `.bt.bt-no`                            | <button class="bt bt-no">Action Button</button>                                        |
| SVG inline inside button               | <button class="bt"><Fragment set:html={mail} />Icon Button</button>                    |
| `.bt.bt-tightIcon`                     | <button class="bt bt-tightIcon"><Fragment set:html={arrow} />Icon Button</button>      |
| `.bt.bt-text`                          | <button class="bt bt-text">"Text" Button</button>                                      |
| `disabled` attribute                   | <button class="bt" disabled>Disabled Button</button>                                   |
| `<a>` as button                        | <a class="bt" role="button" tabindex="0"> Link Button</a>                              |
| `<a>` as button (with `aria-disabled`) | <a class="bt" role="button" aria-disabled="true" tabindex="0">Disabled Link Button</a> |

</div>

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                              | Description                       |
| ------------------------------------- | --------------------------------- |
| `--bt-font-size`                      | Font size.                        |
| `--bt-font-size-lg`                   | Large font size.                  |
| `--bt-font-weight`                    | Font weight.                      |
| `--bt-color`                          | Text color.                       |
| `--bt-color-hover`                    | Text color (hover).               |
| `--bt-background-color`               | Background color.                 |
| `--bt-background-color-hover`         | Background color (hover).         |
| `--bt-border-color`                   | Border color.                     |
| `--bt-border-width`                   | Border width.                     |
| `--bt-border-radius`                  | Border radius.                    |
| `--bt-border-radius-lg`               | Large border radius.              |
| `--bt-outline-color-hover`            | Outline text color (hover).       |
| `--bt-outline-background-color-hover` | Outline background color (hover). |
| `--bt-outline-border-color`           | Outline border color.             |
| `--bt-primary-color`                  | Primary text color.               |
| `--bt-primary-color-hover`            | Primary text color (hover).       |
| `--bt-primary-background-color`       | Primary background color.         |
| `--bt-primary-background-color-hover` | Primary background color (hover). |
| `--bt-primary-border-color`           | Primary border color.             |
| `--bt-primary-border-color-hover`     | Primary border color (hover).     |

</div>

### Examples

<ul class="docs_examples">
  <li>
    <a class="bt">This is a Link</a>
    ```html
    <a class="bt">This is a Link</a>
    ```
  </li>
  <li>
    <button class="bt bt-lg bt-primary mr-sm3" type="button">
      <Fragment set:html={mail} />
      Large Button with Icon
    </button>
    <button class="bt bt-lg bt-primary bt-tightIcon" type="button">
      <Fragment set:html={arrow} />
      Large Button with Tight Icon
    </button>
    ```html
    <button class="bt bt-lg bt-primary" type="button">
      <svg>[…]</svg> Large Button with Icon
    </button>
    <button class="bt bt-lg bt-primary bt-tightIcon" type="button">
      <svg>[…]</svg> Large Button with Tight Icon
    </button>
    ```
  </li>
  <li>
    <input
      class="bt bt-md bt-no bt-outline"
      type="submit"
      value="Cancel Input"
    />
    ```html
    <input
      class="bt bt-md bt-no bt-outline"
      type="submit"
      value="Cancel Input"
    />
    ```
  </li>
</ul>


---

# Toggle

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/toggle

The `toggle` [atom](/docs/start#atoms) uses the `.toggle` class on `<input>` elements of the type `checkbox`.

<input class="toggle mt-sm3" type="checkbox" checked />

<div class="docs_oversizedTable">

| File              | Description | Source      |
| ----------------- | ----------- | ----------- |
| `atom.toggle.css` | All toggle styles (`.toggle`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/atom.toggle.css

## Playground

<Playground
  client:visible
  template={'<input class="{classes}" type="checkbox"{attrs} />'}
  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

<ul class="docs_examples">
  <li>
    <input class="toggle" type="checkbox" />
    ```html
    <input class="toggle" type="checkbox" />
    ```
  </li>
</ul>


---

# 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.)

<Avatar status="online" size="xl" imageSrc={imageSrc}>SR</Avatar>

<div class="docs_oversizedTable">

| File                   | Description | Source      |
| ---------------------- | ----------- | ----------- |
| `component.avatar.css` | All avatar styles (`.avatar`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.avatar.css

## Playground

<Playground
  client:visible
  template={`<div class="{classes}">
  <div>{content}</div>
</div>`}
  baseClasses="avatar"
  snippets={{
    initials: { preview: "<span>SR</span>", code: "<span>SR</span>" },
    image: {
      preview: `<img src="${imageSrc.src}" alt="Sonny Rollins">`,
      code: `<img src="sonny.png" alt="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

<div class="docs_oversizedTable">

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

</div>

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

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

</div>

## Astro component

<div class="docs_oversizedTable prose">

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

</div>

## Examples

<ul class="docs_examples prose">
  <li>
    ### Full name vs initials

    <Avatar>Sonny Rollins</Avatar>
    <Avatar>SR</Avatar>

    ```astro
    ---
    import Avatar from "../../components/Avatar.astro";
    ---
    <Avatar>Sonny Rollins</Avatar>
    <Avatar>SR</Avatar>
    ```
    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.

  </li>
  <li>
    ### Offline large avatar

    <Avatar status="offline" size="lg" imageSrc={imageSrc}>Sonny Rollins</Avatar>

    ```astro
    ---
    import Avatar from "../../components/Avatar.astro";
    import imageSrc from "../../assets/images/sonny.png";
    ---
    <Avatar status="offline" size="lg" imageSrc={imageSrc}>Sonny Rollins</Avatar>
    ```

  </li>
</ul>
### HTML examples

<ul class="docs_examples">
  <li>
    <Avatar>SR</Avatar>

    ```html
    <div class="avatar">
      <div>
        <span>SR</span>
      </div>
    </div>
    ```

  </li>
</ul>


---

# 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`).

<Banner>
  <p>mCSS v1 is out! <a href="#">Read the announcement</a></p>
</Banner>

<div class="docs_oversizedTable">

| 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 default theme | Theme tokens (see table below) | [Github][4] |

</div>

[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.theme.default.css

## Playground

<Playground
  client:visible
  template={`<aside class="banner">
  <div class="banner_content">
    <p>{content}</p>
  </div>{close}
</aside>`}
  snippets={{
    close: {
      preview: `<button class="banner_close" aria-label="Dismiss announcement">${xIcon}</button>`,
      code: '<button class="banner_close" aria-label="Dismiss announcement"><svg>[…]</svg></button>',
    },
  }}
  controls={[
    { heading: "Behavior", items: [
      { type: "checkbox", name: "close", label: "Dismissible", snippet: "close", default: true },
    ]},
    { heading: "Content", items: [
      { type: "text", name: "content", label: "Text", default: "mCSS v1 is out!" },
    ]},
  ]}
/>

The playground's dismiss button is inert: the persistence script lives in Banner.astro (see below).

## HTML

```html
<aside class="banner">
  <div class="banner_content">
    <p>mCSS v1 is out! <a href="/blog/v1">Read the announcement</a></p>
  </div>
  <button class="banner_close" aria-label="Dismiss announcement"><svg>[…]</svg></button>
</aside>
```

For a dismissible plain-HTML banner, copy the small inline script from the bottom of [Banner.astro][2]: it removes the banner when the stored key exists (before paint, so an already-dismissed banner never flashes) and stores the key on click.

Looking for the big closing call-to-action band instead? That's a [Section recipe](/components/section), not a separate component.

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                    | Description         |
| --------------------------- | ------------------- |
| `--banner-color`            | Banner text color.  |
| `--banner-background-color` | Banner background.  |

</div>

## Astro component

<div class="docs_oversizedTable">

| Prop           | Type      | Default                   | Description                                             |
| -------------- | --------- | ------------------------- | -------------------------------------------------------- |
| `id`           | `string`  | `undefined`               | Required when dismissible; keys the `localStorage` entry (`mcss-banner-<id>`). Use a new id per campaign so a new announcement shows again. |
| `dismissible`  | `boolean` | `false`                   | Adds the close button + persistence script.              |
| `dismissLabel` | `string`  | `"Dismiss announcement"`  | Accessible name of the close button.                     |
| `class`        | `string`  | `undefined`               | Additional CSS classes.                                  |

</div>

The default slot is the banner content. Place the banner as the first child of `<body>`, above the header.

## Examples

<ul class="docs_examples">
  <li>
    <Banner dismissible id="docs-demo">
      <p>A dismissible banner. Close it and it stays closed on reload (per browser).</p>
    </Banner>

    ```astro
    ---
    import Banner from "../components/Banner.astro";
    ---
    <Banner dismissible id="v1-launch">
      <p>mCSS v1 is out! <a href="/blog/v1">Read the announcement</a></p>
    </Banner>
    ```

  </li>
</ul>


---

# Breadcrumbs

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/breadcrumbs

The `.breadcrumbs` component is a `nav > ol` trail with CSS-only separators, and optional [BreadcrumbList JSON-LD](https://developers.google.com/search/docs/appearance/structured-data/breadcrumb) for search engines.

<Breadcrumbs items={[
  { label: "Home", href: "/" },
  { label: "Components", href: "/components/start" },
  { label: "Breadcrumbs" },
]} />

<div class="docs_oversizedTable">

| File                                     | Description                    | Source      |
| ---------------------------------------- | ------------------------------ | ----------- |
| `component.breadcrumbs.css`              | All breadcrumb styles          | [Github][1] |
| `Breadcrumbs.astro`                      | The Astro component            | [Github][2] |
| `--breadcrumbs-*` block in default theme | Theme tokens (see table below) | [Github][3] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.breadcrumbs.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/components/Breadcrumbs.astro
[3]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## Playground

<Playground
  client:visible
  template={`<nav class="{classes}" aria-label="Breadcrumbs" style="--breadcrumbs-separator: '{sep}'">
  <ol>
    <li><a href="#">Home</a></li>
    <li><a href="#">Components</a></li>
    <li><span aria-current="page">Breadcrumbs</span></li>
  </ol>
</nav>`}
  baseClasses="breadcrumbs"
  controls={[
    { heading: "Style", items: [
      { type: "text", name: "sep", label: "Separator", default: "/" },
    ]},
  ]}
/>

## HTML

```html
<nav class="breadcrumbs" aria-label="Breadcrumbs">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/components/start">Components</a></li>
    <li><span aria-current="page">Breadcrumbs</span></li>
  </ol>
</nav>
```

The last crumb is text, not a link, marked with `aria-current="page"`; the separators are generated content with empty alt text, so screen readers read the trail as a clean list. The separator lives in CSS, not the markup — change it by overriding one token:

```css
:root {
  --breadcrumbs-separator: "→";
}
```

### Custom properties

<div class="docs_oversizedTable">

| Property                        | Description                        |
| ------------------------------- | ---------------------------------- |
| `--breadcrumbs-separator`       | Separator string (default `/`).    |
| `--breadcrumbs-separator-color` | Separator color.                   |
| `--breadcrumbs-color`           | Link color.                        |
| `--breadcrumbs-color-current`   | Current page (last crumb) color.   |

</div>

## Astro component

<div class="docs_oversizedTable prose">

| Prop        | Type                        | Default         | Description                                                        |
| ----------- | --------------------------- | --------------- | ------------------------------------------------------------------ |
| `items`     | `{ label, href? }[]`        | —               | The trail. The last item (or any item without `href`) is text.     |
| `ariaLabel` | `string`                    | `"Breadcrumbs"` | The nav's accessible name.                                          |
| `jsonLd`    | `boolean`                   | `false`         | Emit BreadcrumbList structured data (hrefs resolved to absolute).   |
| `class`     | `string`                    | `undefined`     | Additional CSS classes.                                             |

</div>

## Examples

<ul class="docs_examples">
  <li>
    <Breadcrumbs
      style="--breadcrumbs-separator: '→'"
      items={[
        { label: "Docs", href: "/docs/start" },
        { label: "Global Styles", href: "/docs/global" },
        { label: "Grid" },
      ]}
    />

    ```astro
    ---
    import Breadcrumbs from "../components/Breadcrumbs.astro";
    ---
    <Breadcrumbs
      jsonLd
      items={[
        { label: "Docs", href: "/docs/start" },
        { label: "Global Styles", href: "/docs/global" },
        { label: "Grid" },
      ]}
    />
    ```

  </li>
</ul>


---

# Card

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/card

The `.card` component, in its simplest form, is a container with 3 style options:

- **Default:** transparent background, border outline.
- **Filled:** solid background color.
- **Raised:** drop shadow and hover effect.

Every part is optional: header with title and subtitle, image (inset, or edge-to-edge with the flush modifier), badges, tags, byline with avatar and date, actions footer, clickable body, disabled state, and loading state with skeleton UI. The Astro component makes it easy to use all those features, and `CardList` lays cards out in equal-height responsive columns. This site's own [blog index](/blog) is built from exactly these two components.

<div class="grid" col="1" col-md="2">
  <div class="grid_item">
    <Card variant="filled" title="A simple filled card">
      <p>Natural Law, is a set of universal, non-man-made, binding and unchangeable conditions which govern the consequence of our actions.</p>
    </Card>
  </div>
  <div class="grid_item">
    <Card variant="raised" title="A simple raised card">
      <p>Natural Law, is a set of universal, non-man-made, binding and unchangeable conditions which govern the consequence of our actions.</p>
    </Card>
  </div>
</div>

<div class="docs_oversizedTable">

| File                                | Description                        | Source      |
| ----------------------------------- | ---------------------------------- | ----------- |
| `component.card.css`                | All card styles (`.card`)          | [Github][1] |
| `component.cardList.css`            | Equal-height list layout           | [Github][2] |
| `Card.astro`, `CardList.astro`      | The Astro components               | [Github][3] |
| `Tags.astro`, `Avatar.astro`        | Composed components (dependencies) | [Github][3] |
| `--card-*` block in default theme   | Theme tokens (see below)           | [Github][4] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.card.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.cardList.css
[3]: https://github.com/minimaldesign/mCSS/tree/main/src/components
[4]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## Playground

<Playground
  client:visible
  template={`<article class="{classes}">{media}{tags}
  <header class="card_header">
    <div class="card_header_text">
      <h2 class="card_title">{title}</h2>
      <p>{subtitle}</p>
    </div>{badges}
  </header>
  <section class="card_content">
    <p>{body}</p>
  </section>{byline}{actions}
</article>`}
  baseClasses="card"
  snippets={{
    mediaInset: {
      preview: `<figure class="card_media"><img class="card_image" src="${placeholder.src}" alt="" loading="lazy" /></figure>`,
      code: `<figure class="card_media"><img class="card_image" src="image.jpg" alt="" loading="lazy" /></figure>`,
    },
    mediaFlush: {
      preview: `<figure class="card_media card_media-flush"><img class="card_image" src="${placeholder.src}" alt="" loading="lazy" /></figure>`,
      code: `<figure class="card_media card_media-flush"><img class="card_image" src="cover.jpg" alt="" loading="lazy" /></figure>`,
    },
    badges: {
      preview: '<div class="card_badges"><span class="badge card_badge">new</span></div>',
      code: '<div class="card_badges"><span class="badge card_badge">new</span></div>',
    },
    tags: {
      preview: '<nav aria-label="Tags"><ul class="tags tags-inline card_tags"><li><a href="#">css</a></li><li><a href="#">learn</a></li></ul></nav>',
      code: '<nav aria-label="Tags"><ul class="tags tags-inline card_tags"><li><a href="#">css</a></li><li><a href="#">learn</a></li></ul></nav>',
    },
    byline: {
      preview: '<footer class="card_byline"><div class="avatar avatar-sm"><div><span>SM</span></div></div><div><span class="card_author">Sonny Mueller</span><time datetime="2026-05-02">May 2, 2026</time></div></footer>',
      code: '<footer class="card_byline"><div class="avatar avatar-sm"><div><span>SM</span></div></div><div><span class="card_author">Sonny Mueller</span><time datetime="2026-05-02">May 2, 2026</time></div></footer>',
    },
    actions: {
      preview: '<footer class="card_actions"><a class="bt bt-text" href="#">Details</a><button class="bt bt-primary">Add to cart</button></footer>',
      code: '<footer class="card_actions"><a class="bt bt-text" href="#">Details</a><button class="bt bt-primary">Add to cart</button></footer>',
    },
  }}
  controls={[
    { heading: "Variation", items: [
      { type: "select", name: "variant", label: "Variant", default: "", options: [
        { label: "Default", value: "" },
        { label: "Filled", value: "card-filled" },
        { label: "Raised", value: "card-raised" },
      ]},
      { type: "select", name: "media", label: "Image", default: "", snippet: "media", options: [
        { label: "None", value: "" },
        { label: "Inset", value: "inset", class: "", snippet: "mediaInset" },
        { label: "Flush", value: "flush", class: "", snippet: "mediaFlush" },
      ]},
    ]},
    { heading: "Parts", items: [
      { type: "checkbox", name: "badges", label: "Badges", snippet: "badges", default: false },
      { type: "checkbox", name: "tags", label: "Tags", snippet: "tags", default: false },
      { type: "checkbox", name: "byline", label: "Byline", snippet: "byline", default: false },
      { type: "checkbox", name: "actions", label: "Actions", snippet: "actions", default: false },
    ]},
    { heading: "State", items: [
      { type: "checkbox", name: "disabled", label: "Disabled", value: "is-disabled", default: false },
    ]},
    { heading: "Content", items: [
      { type: "text", name: "title", label: "Title", default: "Card title" },
      { type: "text", name: "subtitle", label: "Subtitle", default: "Category" },
      { type: "text", name: "body", label: "Body", default: "This is where the content goes!" },
    ]},
  ]}
/>

## HTML

### Available modifiers

<div class="docs_oversizedTable">

| Available modifiers                | Description                                        |
| ---------------------------------- | -------------------------------------------------- |
| `.card`                            | Default style. Transparent background with border. |
| `.card` + `.card-filled`           | Filled with a background color.                    |
| `.card` + `.card-raised`           | Drop shadow, animated on hover.                    |
| `.card` + `.is-disabled`           | Lowered opacity. Interactivity disabled.           |
| `.card_media` + `.card_media-flush`| Edge-to-edge image on top of the card.             |

</div>

### Clickable cards

A card carries **one** link: put `.card_link` on a real anchor (usually the title link) and it stretches over the whole card with a `::after`, so screen readers hear one link named by the title. Actions stay clickable because `.card_actions` is positioned and comes later in the DOM; tags stay clickable through their own z-index bump. The blog-index pattern combines this with a flush image, tags, and a byline, wrapped in a `.cardList` over the [grid system](/docs/global#grid):

```html
<ul class="cardList grid" col="1" col-md="2" col-lg="2">
  <li>
    <article class="card">
      <figure class="card_media card_media-flush">
        <img class="card_image" src="cover.jpg" alt="" loading="lazy" />
      </figure>
      <nav aria-label="Tags"><ul class="tags tags-inline card_tags">
        <li><a href="/blog/tags/css">css</a></li>
      </ul></nav>
      <header class="card_header">
        <div class="card_header_text">
          <h3 class="card_title"><a class="card_link" href="/blog/my-post">Designing with cascade layers</a></h3>
        </div>
      </header>
      <div class="card_content"><p>Why layer order beats specificity wars.</p></div>
      <footer class="card_byline">
        <!-- avatar markup, see the Avatar docs -->
        <div>
          <span class="card_author">Sonny Mueller</span>
          <time datetime="2026-05-02">May 2, 2026</time>
        </div>
      </footer>
    </article>
  </li>
</ul>
```

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                      | Color                                        |
| ----------------------------- | -------------------------------------------- |
| `--card-spacing`              | General padding inside the card.             |
| `--card-color`                | Text color.                                  |
| `--card-secondary-text-color` | Subtitle, date, and secondary text color.    |
| `--card-bg-color`             | Background color of the "filled" variant.    |
| `--card-border-radius`        | Border radius.                               |
| `--card-border-color`         | Border color.                                |
| `--card-border-width`         | Border width.                                |
| `--card-shadow`               | Default drop shadow or the "raised" variant. |
| `--card-shadow-hover`         | Hover state drop shadow.                     |
| `--card-aspect-ratio`         | Image aspect ratio (defaults to `--ar-golden`). |
| `--card-loading-bg`           | Loading skeleton background color.           |

</div>

Badge colors come from the [badge atom](/components/badge)'s `--badge-*` tokens.

## Astro component

**Card**

Every part is optional; render only what you pass. Badges and tags can coexist, but they compete for attention: badges are non-interactive status labels pinned top-right, tags are taxonomy links in the content flow. Prefer one or the other on a given card.

<div class="docs_oversizedTable prose">

| Prop           | Type                      | Default        | Description                                                         |
| -------------- | ------------------------- | -------------- | ------------------------------------------------------------------- |
| `variant`      | `string`                  | undefined      | Card’s visual style: `filled`, `raised`.                            |
| `isDisabled`   | `boolean`                 | `false`        | Disabled style. Disabled interactions.                              |
| `isLoading`    | `boolean`                 | `false`        | Loading state with skeleton UI.                                     |
| `href`         | `string`                  | undefined      | Makes the whole card clickable (through the title link, if any).    |
| `title`        | `string`                  | undefined      | Header title text.                                                  |
| `subtitle`     | `string`                  | undefined      | Header subtitle text.                                               |
| `headingLevel` | `number`                  | `2`            | Heading level of the title: `2`, `3`, or `4`.                       |
| `imageSrc`     | `ImageMetadata \| string` | undefined      | Add an image to the card (imported asset or URL/path).              |
| `imageAlt`     | `string`                  | `''`           | Alt text for the image.                                             |
| `aspectRatio`  | `string`                  | `golden`       | Image aspect ratio (available [aspect ratios][ar]).                 |
| `flushImage`   | `boolean`                 | `false`        | Edge-to-edge image on top of the card instead of inset.             |
| `badges`       | `array`                   | `[]`           | Array of objects (see example below).                               |
| `tags`         | `string[]`                | `[]`           | Tag names, rendered with the Tags component.                        |
| `tagsUrl`      | `string`                  | `'/blog/tags'` | Base URL for tag links.                                             |
| `author`       | `string`                  | undefined      | Byline name (also feeds the Avatar initials).                       |
| `avatarSrc`    | `ImageMetadata \| string` | undefined      | Byline avatar image.                                                |
| `date`         | `Date`                    | undefined      | Publication date, rendered as a `<time>` in the byline.             |
| `locale`       | `string`                  | `'en-US'`      | Locale for the formatted date.                                      |
| `data-testid`  | `string`                  | `'card'`       | Test ID for testing frameworks.                                     |
| `class`        | `string`                  | undefined      | Additional CSS classes, useful for [helper classes](/docs/helpers). |

[ar]: /docs/tokens#aspect-ratio

</div>

**CardList**

A `ul` over the [grid system](/docs/global#grid) whose items stretch, so cards in a row share the same height. Children go in the default slot; wrap each card in an `<li>`.

<div class="docs_oversizedTable prose">

| Prop   | Type     | Default | Description                            |
| ------ | -------- | ------- | -------------------------------------- |
| `cols` | `number` | `2`     | Columns from `--lg`: `1`, `2`, or `3`. |

</div>

### Slots

The `Card` component supports the following slots for content projection:

- **Default slot**: Main content area (e.g., text or paragraphs).
- **Actions slot**: Action buttons or links in the footer.

It is recommended to use the [button atom](/components/button) in the `actions` slot, e.g.:

```astro
<Fragment slot="actions">
  <a class="bt bt-text" href="/home">Cancel</a>
  <button class="bt bt-primary">Add to Cart</button>
</Fragment>
```

### Badge Styling

The `badges` prop takes an array of objects. Each object consists of a `label` property which defines the badge's text, and an optional `color` property that defines the badge's background color. If no `color` is provided, it defaults to `--badge-background-color` from the [badge atom](/components/badge).

<div class="grid" col="1" col-md="3">
  <div class="grid_item" span="2">
    <Card
      title="A card with too many badges"
      badges={[
        { label: "Way", color: "#a6b65a" },
        { label: "Too", color: "#86615c" },
        { label: "Many", color: "#81a598" },
        { label: "Badges", color: "#e3863d" },
      ]}
    >
      <p>This is where the content goes. Unless you only want a bunch of badges!</p>
    </Card>
  </div>
</div>

```astro
<Card
  title="A card with too many badges"
  badges={[
    { label: "Way", color: "#a6b65a" },
    { label: "Too", color: "#86615c" },
    { label: "Many", color: "#81a598" },
    { label: "Badges", color: "#e3863d" },
  ]}
>
  <p>This is where the content goes. Unless you only want a bunch of badges!</p>
</Card>
```

## Examples

<ul class="docs_examples">

<li>

### Blog-index pattern

The article-card recipe: flush image, tags, stretched title link, description, and byline, in a `CardList`.

<CardList cols={2}>
  <li>
    <Card href="#" headingLevel={3} flushImage imageSrc={placeholder.src} title="Designing with cascade layers" tags={["css", "learn"]} author="Sonny Mueller" date={new Date("2026-05-02")}>
      <p>Why layer order beats specificity wars, and how mCSS hands the final word to your unlayered CSS.</p>
    </Card>
  </li>
  <li>
    <Card href="#" headingLevel={3} flushImage imageSrc={placeholder.src} title="Tokens all the way down" tags={["design"]} author="Ada Chen" date={new Date("2026-06-11")}>
      <p>One file of custom properties is the whole theming story.</p>
    </Card>
  </li>
</CardList>

```astro
---
import Card from '../components/Card.astro';
import CardList from '../components/CardList.astro';
---
<CardList cols={2}>
  <li>
    <Card
      href="/blog/my-post"
      headingLevel={3}
      flushImage
      imageSrc={cover}
      title="Designing with cascade layers"
      tags={["css", "learn"]}
      author="Sonny Mueller"
      date={new Date("2026-05-02")}
    >
      <p>Why layer order beats specificity wars.</p>
    </Card>
  </li>
</CardList>
```

</li>
<li>

### Card with image and actions

<div class="grid" col="1" col-md="2">
  <div class="grid_item" span="1">
    <Card
      variant="raised"
      href="/product/123"
      title="Product Name"
      subtitle="Category"
      imageSrc={placeholder}
      imageAlt="Product image"
      aspectRatio="widescreen"
    >
      <p>This is a extremely detailed description of the product.</p>
      <Fragment slot="actions">
        <a class="bt bt-md bt-text " href="/details">
          View Details
        </a>
        <button class="bt bt-md bt-primary">Add to Cart</button>
      </Fragment>
    </Card>
  </div>
</div>

```astro
---
import placeholder from "../../assets/images/image.png";
import Card from '../../components/Card.astro';
---
<Card
  variant="raised"
  href="/product/123"
  title="Product Name"
  subtitle="Category"
  imageSrc={placeholder}
  imageAlt="Product image"
  aspectRatio="widescreen"
>
  <p>This is a extremely detailed description of the product.</p>
  <Fragment slot="actions">
    <a class="bt bt-md bt-text " href="/details">
      View Details
    </a>
    <button class="bt bt-md bt-primary">Add to Cart</button>
  </Fragment>
</Card>
```

</li>
<li>

### Loading state

<div class="grid" col="1" col-md="2">
  <div class="grid_item">
    <Card imageSrc={placeholder} imageAlt="Product image" isLoading>
      <p>This is what the card looks like without the `isLoading` prop.</p>
    </Card>
  </div>
  <div class="grid_item">
    <Card imageSrc={placeholder} imageAlt="Product image">
      <p>This is what the card looks like without the `isLoading` prop.</p>
    </Card>
  </div>
</div>

```astro
---
import placeholder from "../../assets/images/image.png";
import Card from '../../components/Card.astro';
---
<Card imageSrc={placeholder} imageAlt="Product image" isLoading>
  <p>This is what the card looks like without the `isLoading` prop.</p>
</Card>
```

</li>
<li>

### Disabled state

<div class="grid" col="1" col-md="2">
  <div class="grid_item">
    <Card
      href="/product/123"
      imageSrc={placeholder}
      imageAlt="Product image"
      isDisabled
    >
      <p>With the `isDisabled` prop, the link doesn't work anymore.</p>
    </Card>
  </div>
  <div class="grid_item">
    <Card href="/product/123" imageSrc={placeholder} imageAlt="Product image">
      <p>Witout the `isDisabled` prop, the link is clickable.</p>
    </Card>
  </div>
</div>

```astro
---
import placeholder from "../../assets/images/image.png";
import Card from '../../components/Card.astro';
---
<Card
  href="/product/123"
  imageSrc={placeholder}
  imageAlt="Product image"
  isDisabled
>
  <p>With the `isDisabled` prop, the link doesn't work anymore.</p>
</Card>
```

</li>
<li>

### HTML example

<div class="grid" col="1" col-md="2">
  <div class="grid_item">
    <Card
      variant="raised"
      href="/product/123"
      title="Product Name"
      subtitle="Category"
      imageSrc={placeholder}
      imageAlt="Product image"
      badges={[{ label: "new" }]}
    >
      <p>This is a extremely detailed description of the product.</p>
      <Fragment slot="actions">
        <a class="bt bt-text " href="/details">
          View Details
        </a>
        <button class="bt bt-primary">Add to Cart</button>
      </Fragment>
    </Card>
  </div>
</div>

```html
<article class="card card-raised" style="--card-aspect-ratio: var(--ar-golden)">
  <header class="card_header">
    <div class="card_header_text">
      <h2 class="card_title">
        <a class="card_link" href="/product/123">Product Name</a>
      </h2>
      <p>Category</p>
    </div>
    <div class="card_badges"><span class="badge card_badge">new</span></div>
  </header>
  <figure class="card_media">
    <img
      class="card_image"
      src="image.jpg"
      alt="Product image"
      loading="lazy"
      decoding="async"
    />
  </figure>
  <section class="card_content">
    <p>This is a extremely detailed description of the product.</p>
  </section>
  <footer class="card_actions">
    <a class="bt bt-text" href="/details">View Details</a>
    <button class="bt bt-primary">Add to Cart</button>
  </footer>
</article>
```

</li>
</ul>


---

# FAQ

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/faq

The `.faq` component groups `details`/`summary` disclosures into the classic FAQ accordion — native behavior, zero JavaScript.

<Faq>
  <FaqItem question="Does this need JavaScript?" name="demo">
    <p>No. The browser's own <code>details</code> element does all the work.</p>
  </FaqItem>
  <FaqItem question="How does exclusive-open work?" name="demo">
    <p>Every item in this group shares <code>name="demo"</code>, so the browser only keeps one open. Remove the name and items open independently.</p>
  </FaqItem>
  <FaqItem question="Is it keyboard accessible?" name="demo">
    <p>Natively: the summary is focusable and toggles with <kbd>Enter</kbd>/<kbd>Space</kbd>.</p>
  </FaqItem>
</Faq>

<div class="docs_oversizedTable">

| File                             | Description                             | Source      |
| -------------------------------- | --------------------------------------- | ----------- |
| `component.faq.css`              | Group spacing                            | [Github][1] |
| `elements.interactive.css`       | The `details`/`summary` styling + chevron | [Github][2] |
| `Faq.astro`, `FaqItem.astro`     | The Astro components                     | [Github][3] |
| `--faq-spacing` in default theme | Theme token                              | [Github][4] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.faq.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.interactive.css
[3]: https://github.com/minimaldesign/mCSS/tree/main/src/components
[4]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## Playground

<Playground
  client:visible
  template={`<div class="faq">
  <details class="faq_item"{group}{open}>
    <summary>Does this need JavaScript?</summary>
    <div class="faq_content">
      <p>No. The browser's own details element does all the work.</p>
    </div>
  </details>
  <details class="faq_item"{group}>
    <summary>How does exclusive-open work?</summary>
    <div class="faq_content">
      <p>Every item shares the same name attribute.</p>
    </div>
  </details>
</div>`}
  snippets={{
    group: { preview: ' name="faq"', code: ' name="faq"' },
    open: { preview: " open", code: " open" },
  }}
  controls={[
    { heading: "Behavior", items: [
      { type: "checkbox", name: "group", label: "Exclusive open", snippet: "group", default: true },
      { type: "checkbox", name: "open", label: "First item open", snippet: "open", default: false },
    ]},
  ]}
/>

## HTML

```html
<div class="faq">
  <details class="faq_item" name="faq">
    <summary>Does this need JavaScript?</summary>
    <div class="faq_content">
      <p>No. The browser's own details element does all the work.</p>
    </div>
  </details>
  <details class="faq_item" name="faq" open>
    <summary>How does exclusive-open work?</summary>
    <div class="faq_content">
      <p>Every item shares the same name attribute.</p>
    </div>
  </details>
</div>
```

Giving every item the same `name` makes the group exclusive-open (opening one closes the others). It is a progressive enhancement: browsers that don't support exclusive accordions simply let several items stay open, which is a perfectly fine FAQ too.

### Custom properties

<div class="docs_oversizedTable">

| Property        | Description         |
| --------------- | ------------------- |
| `--faq-spacing` | Gap between items.  |

</div>

The item visuals come from the `details` element styling; there is nothing FAQ-specific to retheme.

## Astro component

**Faq** takes only `class` and passes everything else to its root `<div>`. Items go in the default slot.

**FaqItem**

<div class="docs_oversizedTable">

| Prop       | Type      | Default     | Description                                                      |
| ---------- | --------- | ----------- | ---------------------------------------------------------------- |
| `question` | `string`  | —           | The summary text. Required.                                      |
| `open`     | `boolean` | `false`     | Render the item open.                                            |
| `name`     | `string`  | `undefined` | Same name on every item of a group = native exclusive-open.      |
| `class`    | `string`  | `undefined` | Additional CSS classes.                                          |

</div>

The default slot is the answer.

## Examples

<ul class="docs_examples">
  <li>
    <Faq>
      <FaqItem question="Independent items" open>
        <p>No `name`, so this group lets several items stay open at once.</p>
      </FaqItem>
      <FaqItem question="Pre-opened with the `open` prop">
        <p>The first item above renders open.</p>
      </FaqItem>
    </Faq>

    ```astro
    ---
    import Faq from "../components/Faq.astro";
    import FaqItem from "../components/FaqItem.astro";
    ---
    <Faq>
      <FaqItem question="Independent items" open>
        <p>No `name`, so several items can stay open at once.</p>
      </FaqItem>
      <FaqItem question="Pre-opened with the `open` prop">
        <p>The first item above renders open.</p>
      </FaqItem>
    </Faq>
    ```

  </li>
</ul>


---

# Feature Grid

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/featuregrid

export const check = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="m9 12 2 2 4-4"/></svg>`;

The `.featureGrid` component is the classic marketing "three columns of icon + title + text" pattern, composed over the mCSS [grid system](/docs/global#grid).

<FeatureGrid>
  <FeatureItem title="Zero JavaScript">
    <Fragment slot="icon" set:html={check} />
    <p>Just an unordered list and the grid you already have.</p>
  </FeatureItem>
  <FeatureItem title="Responsive by default">
    <Fragment slot="icon" set:html={check} />
    <p>1, 2, then n columns as the viewport grows.</p>
  </FeatureItem>
  <FeatureItem title="Tokenized icons">
    <Fragment slot="icon" set:html={check} />
    <p>Icon box size and colors come from the theme.</p>
  </FeatureItem>
</FeatureGrid>

<div class="docs_oversizedTable">

| File                                     | Description                    | Source      |
| ---------------------------------------- | ------------------------------ | ----------- |
| `component.featureGrid.css`              | Feature grid + item styles     | [Github][1] |
| `FeatureGrid.astro`, `FeatureItem.astro` | The Astro components           | [Github][2] |
| `--featureItem-*` block in default theme | Theme tokens (see table below) | [Github][3] |

</div>

Depends on `.grid` (`global.grid.css`), part of the mCSS core. Icons are yours to bring; [Lucide](https://lucide.dev/) is a great resource.

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.featureGrid.css
[2]: https://github.com/minimaldesign/mCSS/tree/main/src/components
[3]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## Playground

<Playground
  client:visible
  template={`<ul class="{classes}" col="1" col-md="2"{attrs}>
  <li class="featureItem">
    <div class="featureItem_icon" aria-hidden="true">{check}</div>
    <h3 class="featureItem_title">Zero JavaScript</h3>
    <div class="featureItem_text">
      <p>Just an unordered list and the grid you already have.</p>
    </div>
  </li>
  <li class="featureItem">
    <div class="featureItem_icon" aria-hidden="true">{check}</div>
    <h3 class="featureItem_title">Responsive by default</h3>
    <div class="featureItem_text">
      <p>1, 2, then n columns as the viewport grows.</p>
    </div>
  </li>
  <li class="featureItem">
    <div class="featureItem_icon" aria-hidden="true">{check}</div>
    <h3 class="featureItem_title">Tokenized icons</h3>
    <div class="featureItem_text">
      <p>Icon box size and colors come from the theme.</p>
    </div>
  </li>
</ul>`}
  baseClasses="featureGrid grid"
  snippets={{
    check: { preview: check, code: "<svg>[…]</svg>" },
  }}
  controls={[
    { heading: "Layout", items: [
      { type: "select", name: "cols", label: "Columns (from --lg)", default: "cols3", options: [
        { label: "2", value: "cols2", class: "", attr: 'col-lg="2"' },
        { label: "3", value: "cols3", class: "", attr: 'col-lg="3"' },
        { label: "4", value: "cols4", class: "", attr: 'col-lg="4"' },
      ]},
    ]},
  ]}
/>

## HTML

One item per `<li>`: one column on mobile, two from `--md`, and 2/3/4 (your pick) from `--lg`.

```html
<ul class="featureGrid grid" col="1" col-md="2" col-lg="3">
  <li class="featureItem">
    <div class="featureItem_icon" aria-hidden="true"><svg>[…]</svg></div>
    <h3 class="featureItem_title">Zero JavaScript</h3>
    <div class="featureItem_text">
      <p>Just an unordered list and the grid you already have.</p>
    </div>
  </li>
  <!-- more items… -->
</ul>
```

The icon box is `aria-hidden`: feature icons are decoration next to a real heading, so screen readers skip them.

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                             | Description                 |
| ------------------------------------ | --------------------------- |
| `--featureItem-icon-box-size`        | Icon container width/height. |
| `--featureItem-icon-size`            | SVG width/height.           |
| `--featureItem-icon-color`           | Icon (stroke/fill) color.   |
| `--featureItem-icon-background-color`| Icon container background.  |
| `--featureItem-icon-border-radius`   | Icon container radius.      |

</div>

## Astro component

**FeatureGrid**

<div class="docs_oversizedTable">

| Prop    | Type     | Default     | Description                                                         |
| ------- | -------- | ----------- | ------------------------------------------------------------------- |
| `cols`  | `number` | `3`         | Columns from the `--lg` breakpoint: `2`, `3`, or `4`.               |
| `class` | `string` | `undefined` | Additional CSS classes, useful for [helper classes](/docs/helpers). |

</div>

**FeatureItem**

<div class="docs_oversizedTable">

| Prop    | Type     | Default     | Description                              |
| ------- | -------- | ----------- | ---------------------------------------- |
| `title` | `string` | `undefined` | The item's `h3`.                         |
| `class` | `string` | `undefined` | Additional CSS classes.                  |

</div>

<div class="docs_oversizedTable">

| Slot      | Description                                          |
| --------- | ---------------------------------------------------- |
| `icon`    | An SVG icon, rendered in the tokenized icon box.     |
| (default) | The item's body text.                                |

</div>

## Examples

<ul class="docs_examples">
  <li>
    <FeatureGrid cols={2}>
      <FeatureItem title="Two columns">
        <Fragment slot="icon" set:html={check} />
        <p>Set `cols` for the large-screen column count.</p>
      </FeatureItem>
      <FeatureItem title="No icon required">
        <p>Skip the `icon` slot and the box disappears.</p>
      </FeatureItem>
    </FeatureGrid>

    ```astro
    ---
    import FeatureGrid from "../components/FeatureGrid.astro";
    import FeatureItem from "../components/FeatureItem.astro";
    import zap from "../assets/icons/zap.svg?raw";
    ---
    <FeatureGrid cols={2}>
      <FeatureItem title="Two columns">
        <Fragment slot="icon" set:html={zap} />
        <p>Set `cols` for the large-screen column count.</p>
      </FeatureItem>
      <FeatureItem title="No icon required">
        <p>Skip the `icon` slot and the box disappears.</p>
      </FeatureItem>
    </FeatureGrid>
    ```

  </li>
</ul>


---

# Form Field

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/field

The `.field` component composes the bare [form elements](/docs/elements) into label + control + hint + error message, with validation states driven entirely by CSS.

<form>
  <Field label="Email" name="demo-email" type="email" required hint="We'll never share it." placeholder="you@example.com" error="That doesn't look like an email address." />
</form>

Type something that isn't an email address and tab away: the hint swaps for the error and the border turns red, no JavaScript involved.

<div class="docs_oversizedTable">

| File                                | Description                             | Source      |
| ----------------------------------- | ---------------------------------------- | ----------- |
| `component.field.css`               | Field structure and states               | [Github][1] |
| `component.fieldRow.css`            | fieldRow composition (own block)         | [Github][5] |
| `elements.form.css`                 | Bare element styles + `:user-invalid` border | [Github][2] |
| `Field.astro`                       | The Astro component                      | [Github][3] |
| `--field-*` block in default theme  | Theme tokens (see table below)           | [Github][4] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.field.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/elements.form.css
[3]: https://github.com/minimaldesign/mCSS/blob/main/src/components/Field.astro
[4]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css
[5]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.fieldRow.css

## Playground

<Playground
  client:visible
  template={`<div class="{classes}">
  <label for="pg-email">{label}</label>
  <input id="pg-email" name="email" type="email"{attrs} aria-describedby="pg-email-hint" />
  <small class="field_hint" id="pg-email-hint">{hint}</small>
  <small class="field_error">{error}</small>
</div>`}
  baseClasses="field"
  controls={[
    { heading: "State", items: [
      { type: "checkbox", name: "required", label: "Required", attr: "required", default: true },
      { type: "checkbox", name: "disabled", label: "Disabled", attr: "disabled", default: false },
      { type: "checkbox", name: "invalid", label: "Invalid", value: "is-invalid", default: false },
    ]},
    { heading: "Content", items: [
      { type: "text", name: "label", label: "Label", default: "Email" },
      { type: "text", name: "hint", label: "Hint", default: "We'll never share it." },
      { type: "text", name: "error", label: "Error", default: "That doesn't look like an email address." },
    ]},
  ]}
/>

## HTML

```html
<div class="field">
  <label for="email">Email</label>
  <input id="email" name="email" type="email" required aria-describedby="email-hint" />
  <small class="field_hint" id="email-hint">We'll never share it.</small>
  <small class="field_error">That doesn't look like an email address.</small>
</div>
```

Errors use `:user-invalid`, so a pristine form never lights up red: only fields the user actually touched and got wrong. The error message is always in the markup and revealed by `.field:has(:user-invalid)`. Add `.is-invalid` on the `.field` wrapper to force the same presentation from markup, for server-side validation results, tests, and demos (that's what the playground's Invalid checkbox does). It is deliberately **not** referenced by `aria-describedby`: screen readers get the browser's native validation message on submit, so wiring the visual error in as a description would double-announce it.

### Custom properties

<div class="docs_oversizedTable">

| Property                       | Description                                |
| ------------------------------ | ------------------------------------------ |
| `--field-spacing`              | Gap between label, control, and messages.  |
| `--field-hint-color`           | Hint text color.                           |
| `--field-error-color`          | Error text color.                          |
| `--input-border-color-invalid` | Border color of a `:user-invalid` control. |

</div>

## Astro component

<div class="docs_oversizedTable">

| Prop       | Type      | Default                | Description                                                        |
| ---------- | --------- | ---------------------- | ------------------------------------------------------------------ |
| `label`    | `string`  | —                      | The visible label. Required.                                       |
| `hint`     | `string`  | `undefined`            | Help text under the control.                                       |
| `error`    | `string`  | `"Please fill out…"`   | Message revealed when the control is `:user-invalid`.              |
| `class`    | `string`  | `undefined`            | Additional CSS classes on the `.field` wrapper.                    |

</div>

Everything else (`type`, `name`, `placeholder`, `required`, `pattern`, `minlength`…) is passed through to the `<input>`. The label's `for` uses `id`, falling back to `name` — set at least one.

To use another control (textarea, select…), put it in the default slot and give it the matching `id`:

```astro
<Field label="Message" id="message">
  <textarea id="message" name="message" required></textarea>
</Field>
```

## Recipes

### Newsletter signup

`.fieldRow` lines fields and buttons up on one wrapping row. Mix `.fieldRow_field` onto each field that should stretch:

<form class="fieldRow">
  <Field class="fieldRow_field" label="Email" name="newsletter-email" type="email" required placeholder="you@example.com" error="That doesn't look like an email address." />
  <button class="bt bt-primary" type="submit">Subscribe</button>
</form>

```html
<form class="fieldRow" method="post" action="/subscribe">
  <div class="field fieldRow_field">
    <label for="email">Email</label>
    <input id="email" name="email" type="email" required />
  </div>
  <button class="bt bt-primary" type="submit">Subscribe</button>
</form>
```

### Contact form

Fieldset + the [grid system](/docs/global#grid) for the two-column row:

<form>
  <fieldset>
    <legend>Contact us</legend>
    <p aria-hidden="true">Contact us</p>
    <div class="grid" col="1" col-md="2" style="margin-bottom: var(--sm1);">
      <Field label="Name" name="contact-name" required />
      <Field label="Email" name="contact-email" type="email" required error="That doesn't look like an email address." />
    </div>
    <Field label="Message" id="contact-message" class="mb-sm1">
      <textarea id="contact-message" name="message" required></textarea>
    </Field>
    <button class="bt bt-primary" type="submit">Send</button>
  </fieldset>
</form>

```astro
---
import Field from "../components/Field.astro";
---
<form method="post" action="/contact">
  <fieldset>
    <legend>Contact us</legend>
    <p aria-hidden="true">Contact us</p>
    <div class="grid" col="1" col-md="2">
      <Field label="Name" name="name" required />
      <Field label="Email" name="email" type="email" required />
    </div>
    <Field label="Message" id="message">
      <textarea id="message" name="message" required></textarea>
    </Field>
    <button class="bt bt-primary" type="submit">Send</button>
  </fieldset>
</form>
```


---

# Footer

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/footer

The `.footer` component is the site-wide bottom section: link columns on the right, a meta area (copyright, credits, version…) on the left. Pure HTML and CSS, no JavaScript.

<Footer style="border-radius: 0 0 var(--radius-lg) var(--radius-lg);">
  <ul>
    <li>
      <h5>Product</h5>
      <ul>
        <li><a href="#">Features</a></li>
        <li><a href="#">Pricing</a></li>
      </ul>
    </li>
    <li>
      <h5>Company</h5>
      <ul>
        <li><a href="#">About</a></li>
        <li><a href="#">Blog</a></li>
      </ul>
    </li>
  </ul>
  <Fragment slot="meta">
    <p class="mt-xs1">© 2026 Acme Inc.</p>
  </Fragment>
</Footer>

<div class="docs_oversizedTable">

| File                                | Description                    | Source      |
| ----------------------------------- | ------------------------------ | ----------- |
| `component.footer.css`              | All footer styles              | [Github][1] |
| `Footer.astro`                      | The Astro component            | [Github][2] |
| `--footer-*` block in default theme | Theme tokens (see table below) | [Github][3] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.footer.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/components/Footer.astro
[3]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## HTML

The footer expects two regions: a `nav` with one `<ul>` whose `<li>` children are the columns (a heading plus a link list each), and a `.footer_meta` section.

```html
<footer class="footer">
  <nav class="footer_nav" aria-label="Footer">
    <ul>
      <li>
        <h5>Documentation</h5>
        <ul>
          <li><a href="/docs">Getting started</a></li>
          <li><a href="/docs/tokens">Tokens</a></li>
        </ul>
      </li>
      <li>
        <h5>Connect</h5>
        <ul>
          <li><a href="https://github.com/…">Github</a></li>
        </ul>
      </li>
    </ul>
  </nav>
  <section class="footer_meta">
    <p>© 2026 Acme Inc.</p>
  </section>
</footer>
```

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                    | Description                                     |
| --------------------------- | ----------------------------------------------- |
| `--footer-background-color` | Background color.                               |
| `--footer-text-color`       | Text color.                                     |
| `--footer-border-width`     | Top border width.                               |
| `--footer-border-color`     | Top border color (transparent in light theme).  |
| `--footer-link-color`       | Link color.                                     |
| `--footer-link-color-hover` | Link hover color.                               |

</div>

## Astro component

<div class="docs_oversizedTable">

| Prop       | Type     | Default     | Description                                                         |
| ---------- | -------- | ----------- | ------------------------------------------------------------------- |
| `navLabel` | `string` | `"Footer"`  | `aria-label` for the footer nav.                                    |
| `class`    | `string` | `undefined` | Additional CSS classes, useful for [helper classes](/docs/helpers). |

</div>

Any other attribute is passed through to the root `<footer>` element.

<div class="docs_oversizedTable">

| Slot      | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| (default) | The link columns: one `<ul>` with one `<li>` per column (heading + `<ul>`). |
| `meta`    | The meta area: copyright, credits, socials…                                  |

</div>

## Examples

<ul class="docs_examples">
  <li>
    <Footer style="border-radius: var(--radius-lg);">
      <ul>
        <li>
          <h5>Product</h5>
          <ul>
            <li><a href="#">Features</a></li>
            <li><a href="#">Pricing</a></li>
          </ul>
        </li>
        <li>
          <h5>Company</h5>
          <ul>
            <li><a href="#">About</a></li>
            <li><a href="#">Blog</a></li>
          </ul>
        </li>
      </ul>
      <Fragment slot="meta">
        <p class="mt-xs1">© 2026 Acme Inc.</p>
      </Fragment>
    </Footer>

    ```astro
    ---
    import Footer from "../components/Footer.astro";
    ---
    <Footer>
      <ul>
        <li>
          <h5>Product</h5>
          <ul>
            <li><a href="/features">Features</a></li>
            <li><a href="/pricing">Pricing</a></li>
          </ul>
        </li>
      </ul>
      <Fragment slot="meta">
        <p>© 2026 Acme Inc.</p>
      </Fragment>
    </Footer>
    ```

  </li>
  <li>
    This site's own footer is the same component; see [SiteFooter.astro](https://github.com/minimaldesign/mCSS/blob/main/src/components/SiteFooter.astro) for a full example with social icons and a version line in the `meta` slot.
  </li>
</ul>


---

# Header

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/header

The `.header` component is the site-wide top bar: logo, primary navigation, optional actions, and a built-in mobile menu behind a hamburger button.

<Header
  navItems={[
    { label: "Home", href: "#" },
    { label: "Features", href: "#features" },
    { label: "Pricing", href: "#pricing" },
    { label: "Blog", href: "#blog" },
  ]}
  style="border: 1px solid var(--theme-border-color); border-radius: var(--radius-lg);"
>
  <a slot="logo" class="header_logo" href="#">✻ Acme</a>
  <a slot="actions" class="bt bt-primary" href="#">Sign up</a>
</Header>

<div class="docs_oversizedTable">

| File                                | Description                      | Source      |
| ----------------------------------- | -------------------------------- | ----------- |
| `component.header.css`              | All header styles                | [Github][1] |
| `Header.astro`                      | The Astro component              | [Github][2] |
| `icons/menu.svg`, `icons/x.svg`     | Mobile menu open/close icons     | [Github][3] |
| `--header-*` block in default theme | Theme tokens (see table below)   | [Github][4] |
| `scripts/utilities.js` (`throttle`) | Used by the sticky-shadow script | [Github][5] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.header.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/components/Header.astro
[3]: https://github.com/minimaldesign/mCSS/tree/main/src/assets/icons
[4]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css
[5]: https://github.com/minimaldesign/mCSS/blob/main/src/scripts/utilities.js

## HTML

The header is a flex row: logo first, desktop nav pushed to the right, actions last. Below the `--md` breakpoint the desktop nav and actions hide and the hamburger appears.

```html
<header class="header is-top header-sticky">
  <a class="header_logo" href="/">✻ Acme</a>
  <nav class="header_nav" aria-label="Main">
    <ul>
      <li><a href="/" aria-current="page">Home</a></li>
      <li><a href="/pricing">Pricing</a></li>
    </ul>
  </nav>
  <nav class="header_navMobile" aria-label="Main menu">
    <button aria-expanded="false" aria-label="Open menu"><svg>[…]</svg></button>
    <div>
      <button aria-label="Close menu"><svg>[…]</svg></button>
      <ul>
        <li><a href="/" aria-current="page">Home</a></li>
        <li><a href="/pricing">Pricing</a></li>
      </ul>
    </div>
  </nav>
  <div class="header_actions"><!-- theme toggle, CTA… --></div>
</header>
```

When using plain HTML you also need the small script that wires the hamburger; copy it from the bottom of [Header.astro][2]. It keeps the menu keyboard operable: `aria-expanded` reflects the state, focus moves into the menu on open and back to the trigger on close, and `Escape` closes it.

### Available modifiers

<div class="docs_oversizedTable">

| Class / state                | Description                                                                |
| ---------------------------- | -------------------------------------------------------------------------- |
| `.header`                    | Base block. Flex row, `--header-height` tall.                              |
| `.header` + `.header-sticky` | Sticks to the top of the viewport with a shadow once the page is scrolled. |
| `.is-top`                    | State set by the script while the page is scrolled to the very top (hides the sticky shadow). |
| `a[aria-current]`            | Current page (`page`) or section (`true`) links are highlighted.           |

</div>

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                         | Description                                        |
| -------------------------------- | -------------------------------------------------- |
| `--header-height`                | Header height (grows at the `--md` breakpoint).    |
| `--header-padding`               | Horizontal padding.                                |
| `--header-background-color`      | Background color.                                  |
| `--header-menu-background-color` | Mobile menu background (always dark by design).    |
| `--header-menu-color`            | Mobile menu link color.                            |
| `--header-menu-color-current`    | Mobile menu current-page link color.               |
| `--header-menu-secondary-color`  | Mobile menu sub-item link color.                   |
| `--header-menu-border-color`     | Mobile menu sub-list border.                       |

</div>

The mobile menu deliberately keeps the same dark surface in both themes; retheme it through the `--header-menu-*` tokens rather than a `light-dark()` override.

## Astro component

<div class="docs_oversizedTable">

| Prop          | Type        | Default             | Description                                                       |
| ------------- | ----------- | ------------------- | ----------------------------------------------------------------- |
| `navItems`    | `NavItem[]` | `[]`                | `{ label, href, children?, mobileOnly? }`. `children` renders as a sub-list in the mobile menu only; `mobileOnly` items are skipped in the desktop nav. |
| `sticky`      | `boolean`   | `false`             | Sticky positioning + scroll shadow.                               |
| `currentPath` | `string`    | `Astro.url.pathname`| Used to set `aria-current`: exact match gets `page`; the item whose `children` contain the page gets `true` (falling back to first-path-segment matching when none does). |
| `navLabel`    | `string`    | `"Main"`            | `aria-label` for the desktop nav.                                 |
| `menuLabel`   | `string`    | `"Main menu"`       | `aria-label` for the mobile nav.                                  |
| `class`       | `string`    | `undefined`         | Additional CSS classes, useful for [helper classes](/docs/helpers). |

</div>

Any other attribute is passed through to the root `<header>` element.

<div class="docs_oversizedTable">

| Slot      | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| `logo`    | Brand link. Use `class="header_logo"` on it to pick up the styles. |
| `actions` | Right-hand side extras (theme toggle, CTA). Desktop only.          |
| `menu`    | Extra content at the top of the mobile menu (e.g. a theme toggle). |

</div>

## Examples

<ul class="docs_examples">
  <li>
    <Header
      navItems={[
        { label: "Docs", href: "#docs" },
        { label: "Blog", href: "#blog" },
      ]}
      style="border: 1px solid var(--theme-border-color); border-radius: var(--radius-lg);"
    >
      <a slot="logo" class="header_logo" href="#">✻ Acme</a>
    </Header>

    ```astro
    ---
    import Header from "../components/Header.astro";
    ---
    <Header
      sticky
      navItems={[
        { label: "Docs", href: "/docs" },
        { label: "Blog", href: "/blog" },
      ]}
    >
      <a slot="logo" class="header_logo" href="/">✻ Acme</a>
    </Header>
    ```

  </li>
  <li>
    This site's own header is the same component; see [SiteHeader.astro](https://github.com/minimaldesign/mCSS/blob/main/src/components/SiteHeader.astro) for a full example with nested mobile navigation, `mobileOnly` sections, and theme toggles in the `actions` and `menu` slots.
  </li>
</ul>


---

# Hero

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/hero

The `Hero` component offers highly flexible, accessible hero sections for landing pages, product sites, and marketing. It supports full, split, and slideshow layouts; accepts image, video, gradient, or canvas backgrounds; provides overlay and text color controls; allows custom aspect ratios and content/media ordering; supports parallax, rounded corners, and a flush layout for the split variant; and is fully slot-based for custom content. ([Full size demo](/demos/hero).)

<Hero
  variant="full"
  height={40}
  media={{ type: "canvas", src: "/_js/triangles.js" }}
  overlayOpacity={0.3}
  overlayColor="--primary-950"
  roundCorners
  textColor="--base-0"
  class="mt-sm3"
>
  <h1>Example Hero</h1>
  <p>This hero uses an animated canvas element as background.</p>
</Hero>

<div class="docs_oversizedTable">

| File                 | Description | Source      |
| -------------------- | ----------- | ----------- |
| `component.hero.css` | All hero styles (`.hero`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.hero.css

#### Full layout (default)

The full layout spans the entire viewport with content centered over a background image, video, gradient, or canvas element. Use the `height` prop to control min-height (in `svh` units).

#### Split layout

The Split layout features an asymmetric split (e.g., `70/30`, `80/20`, etc.) with content on one side and media on the other. The media section fills the available space with an image or video, cropping as needed. The `ratio` prop defines the grid layout, `contentFirst` controls the DOM order of content and media, and `reversed` visually reverses their order (while the grid ratio remains unchanged).

#### Slideshow layout

The Slideshow layout features rotating content and background (same options available as for the Full layout) with pagination dots. Each slide can have its own media and content.

<Notice
  type="info"
  title="Multiple Heroes on a single page"
  class="mt-md3"
>
  Each `Hero` instance generates its own unique `id`, so multiple heroes on one
  page (including JavaScript-driven ones like slideshows) never cross-wire. Pass
  an explicit `id` prop only if you need a stable anchor to link to.
</Notice>

## HTML

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                             | Description                                     |
| ------------------------------------ | ----------------------------------------------- |
| `--hero-radius`                      | Border radius (on/off via `roundCorners` prop). |
| `--hero-content-padding`             | Padding for hero content area.                  |
| `--hero-pagination-dot`              | Pagination dot size.                            |
| `--hero-pagination-dot-color`        | Pagination dot background color.                |
| `--hero-pagination-dot-active-color` | Active pagination dot color.                    |
| `--hero-pagination-opacity`          | Pagination dot default opacity.                 |

</div>

## Astro component

### General props

<div class="docs_oversizedTable">

| Prop           | Type    | Default | Description                                                   |
| -------------- | ------- | ------- | ------------------------------------------------------------- |
| `variant`      | string  | `full`  | Layout variant: Full, Split, and Slideshow.                   |
| `media`        | object  | —       | Image, video, gradient, or canvas background.                 |
| `roundCorners` | boolean | `false` | Whether the hero media has rounded corners.                   |
| `textColor`    | string  | —       | Text color (CSS variable or value).                           |
| `class`   | string  | —       | Additional CSS classes (see [helper classes](/docs/helpers)). |

</div>

### Split variant props

<div class="docs_oversizedTable">

| Prop           | Type    | Default | Description                                                                        |
| -------------- | ------- | ------- | ---------------------------------------------------------------------------------- |
| `ratio`        | string  | `62/38` | Split ratio, e.g. `70/30`, `40/60`, etc.                                           |
| `contentFirst` | boolean | `false` | If true, content appears before media in the DOM (left on desktop, top on mobile). |
| `reversed`     | boolean | `false` | Visually reverses the order set by `contentFirst` (does not change DOM order).     |
| `roundCorners` | boolean | `false` | If true, media has rounded corners.                                                |
| `flush`        | boolean | `false` | Removes outer padding from the content section, making text flush with the edge.   |

</div>

### Full and slideshow variant props

<div class="docs_oversizedTable">

| Prop                  | Type    | Default      | Description                          |
| --------------------- | ------- | ------------ | ------------------------------------ |
| `parallax`            | boolean | `false`      | Parallax effect (full variant only). |
| `height`              | number  | —            | Sets `min-height` in `svh` (0-100).  |
| `overlayOpacity`      | number  | `0`          | Overlay opacity.                     |
| `overlayColor`        | string  | `--base-950` | Overlay color (CSS var or value).    |
| `roundCorners`        | boolean | `false`      | If true, hero has rounded corners.   |
| `textColor`           | string  | —            | Text color (CSS var or value).       |
| `slideshowItems`      | array   | —            | Array of objects (see example).      |
| `slideshowAutoplay`   | boolean | `true`       | Slideshow autoplay.                  |
| `slideshowInterval`   | number  | `5000`       | Slideshow interval (ms).             |
| `slideshowTransition` | number  | `600`        | Slideshow transition speed (ms).     |

</div>

## Examples

<ul class="docs_examples">
  <li>
    ### Animated Canvas
    <Hero
      variant="full"
      height={50}
      media={{ type: "canvas", src: "/_js/triangles.js" }}
      overlayOpacity={0.3}
      overlayColor="--primary-950"
      roundCorners
      textColor="--base-0"
    >
      <h1>Animated Canvas Hero</h1>
      <p>This hero uses an animated canvas element as background.</p>
      <a class="bt bt-lg bt-outline-white mt-md1" href="/demos/hero">Full Size Examples</a>
    </Hero>

```astro
---
import Hero from "../../components/Hero.astro";
---
<Hero
  variant="full"
  height={50}
  media={{ type: "canvas", src: "/_js/triangles.js" }}
  overlayOpacity={0.3}
  overlayColor="--primary-950"
  roundCorners
  textColor="--base-0"
>
  <h1>Animated Canvas Hero</h1>
  <p>Organic Delaunay triangles animated with primary colors.</p>
  <a class="bt bt-primary">Full Size Demo</a>
</Hero>
```

  </li>
  <li>
    ### Gradient background
    <Hero
      variant="full"
      height={50}
      media={{
        type: "gradient",
        src: "linear-gradient(120deg, #f0f 0%, #0ff 100%)",
      }}
      overlayOpacity={0.3}
      roundCorners
      textColor="--base-0"
    >
      <h1>Gradient Background Hero</h1>
      <p>Showcase your brand with a beautiful, vibrant gradient background.</p>
      <a class="bt bt-lg bt-outline-white mt-md1" href="/demos/hero">Full Size Examples</a>
    </Hero>

```astro
---
import Hero from "../../components/Hero.astro";
---
<Hero
  variant="full"
  height={50}
  media={{
    type: "gradient",
    src: "linear-gradient(120deg, #f0f 0%, #0ff 100%)",
  }}
  overlayOpacity={0.3}
  roundCorners
  textColor="--base-0"
>
  <h1>Gradient Background Hero</h1>
  <p>Showcase your brand with a beautiful, vibrant gradient background.</p>
  <a class="bt bt-lg bt-outline-white mt-md1" href="/demos/hero">Full Size Examples</a>
</Hero>
```

  </li>
  <li>
    ### Background image
    <Hero
      variant="full"
      height={50}
      media={{ type: "image", src: triangle01, alt: "Background Example" }}
      overlayColor="--primary-950"
      overlayOpacity={0.4}
      roundCorners
      textColor="--base-0"
    >
      <h1>Image Background Hero</h1>
      <p>This hero uses a static image as the background.</p>
      <a class="bt bt-lg bt-outline-white mt-md1" href="/demos/hero">Full Size Examples</a>
    </Hero>

```astro
---
import Hero from "../../components/Hero.astro";
import triangle01 from "../../assets/images/triangles.svg";
---
<Hero
  variant="full"
  height={50}
  media={{ type: "image", src: triangle01, alt: "Background Example" }}
  overlayColor="--primary-950"
  overlayOpacity={0.4}
  roundCorners
  textColor="--base-0"
>
  <h1>Image Background Hero</h1>
  <p>This hero uses a static image as the background.</p>
  <a class="bt bt-lg bt-outline-white mt-md1" href="/demos/hero">Full Size Examples</a>
</Hero>
```

  </li>
  <li>
  ### Slideshow
  <Hero
    id="heroSlideshow"
    variant="slideshow"
    height={40}
    overlayOpacity={0.6}
    overlayColor="--primary-950"
    textColor="--base-0"
    roundCorners
    slideshowInterval={4000}
    slideshowTransition={600}
    slideshowItems={[
      {
        media: { type: 'image', src: triangle01, alt: 'Triangle 01' },
      },
      {
        media: { type: 'image', src: triangle02, alt: 'Triangle 02' },
      },
      {
        media: { type: 'image', src: triangle03, alt: 'Triangle 03' },
      },
    ]}>
    <ul>
      <li>
        <h1>First Slide</h1>
        <p>This is the first slide of the slideshow.</p>
      </li>
      <li>
        <h1>Second Slide</h1>
        <p>This is the second slide of the slideshow.</p>
      </li>
      <li>
        <h1>Third Slide</h1>
        <p>This is the third slide of the slideshow.</p>
      </li>
    </ul>
  </Hero>

```astro
---
import Hero from "../../components/Hero.astro";
import triangle01 from "../../assets/images/triangle-01.svg";
import triangle02 from "../../assets/images/triangle-02.svg";
import triangle03 from "../../assets/images/triangle-03.svg";
---
<Hero
  id="heroSlideshow"
  variant="slideshow"
  height={40}
  overlayOpacity={0.6}
  overlayColor="--primary-950"
  textColor="--base-0"
  roundCorners
  slideshowInterval={4000}
  slideshowTransition={600}
  slideshowItems={[
    {
      media: { type: 'image', src: triangle01, alt: 'Triangle 01' },
    },
    {
      media: { type: 'image', src: triangle02, alt: 'Triangle 02' },
    },
    {
      media: { type: 'image', src: triangle03, alt: 'Triangle 03' },
    },
  ]}>
  <ul>
    <li>
      <h1>First Slide</h1>
      <p>This is the first slide of the slideshow.</p>
    </li>
    <li>
      <h1>Second Slide</h1>
      <p>This is the second slide of the slideshow.</p>
    </li>
    <li>
      <h1>Third Slide</h1>
      <p>This is the third slide of the slideshow.</p>
    </li>
  </ul>
</Hero>
```

  </li>
  <li>
    ### Default split
    <Hero
      variant="split"
      roundCorners
      media={{ type: "image", src: triangle01, alt: "Split Example" }}
    >
      <h1>Split Hero (Content Right)</h1>
      <p>Default split with content on the right and media on the left.</p>
    </Hero>

```astro
---
import Hero from "../../components/Hero.astro";
import triangle01 from "../../assets/images/triangles.svg";
---
<Hero
  variant="split"
  roundCorners
  media={{ type: "image", src: triangle01, alt: "Split Example" }}
>
  <h1>Split Hero (Content Right)</h1>
  <p>Default split with content on the right and media on the left.</p>
</Hero>
```

  </li>
  <li>
    ### Content first split
    <Hero
      variant="split"
      ratio="62/38"
      contentFirst
      flush
      roundCorners
      media={{ type: "image", src: triangle01, alt: "Split Example" }}
    >
      <h1>Split Hero (Content First)</h1>
      <p>This example uses the <code>contentFirst</code> prop to place content before media in the DOM (left on desktop, top on mobile).</p>
    </Hero>

```astro
---
import Hero from "../../components/Hero.astro";
import triangle01 from "../../assets/images/triangles.svg";
---
<Hero
  variant="split"
  ratio="62/38"
  contentFirst
  flush
  roundCorners
  media={{ type: "image", src: triangle01, alt: "Split Example" }}
>
  <h1>Split Hero (Content First)</h1>
  <p>This example uses the <code>contentFirst</code> prop to place content before media in the DOM (left on desktop, top on mobile).</p>
</Hero>
```

  </li>
  <li>
    ### Content first reversed split
    <Hero
      variant="split"
      ratio="62/38"
      reversed
      flush
      roundCorners
      media={{ type: "image", src: triangle01, alt: "Split Example" }}
    >
      <h1>Split Hero (Reversed)</h1>
      <p>This example uses the <code>reversed</code> prop to visually flip the order of content and media, without changing their DOM order. The <code>flush</code> prop removes left padding.</p>
    </Hero>

```astro
---
import Hero from "../../components/Hero.astro";
import triangle01 from "../../assets/images/triangles.svg";
---
<Hero
  variant="split"
  ratio="60/40"
  reversed
  flush
  roundCorners
  media={{ type: "image", src: triangle01, alt: "Split Example" }}
>
  <h1>Split Hero (Reversed)</h1>
  <p>This example uses the <code>reversed</code> prop to visually flip the order of content and media, without changing their DOM order. The <code>flush</code> prop removes left padding.</p>
</Hero>
```

  </li>
</ul>


---

# Notice

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/notice

The `.notice` component is useful to bring something to the attention of the reader/user, as well as provide feedback on user interaction.

<Notice title="Example notice component">
  <p>This is the the default notice style, without a modifier class.</p>
</Notice>

<div class="docs_oversizedTable">

| File                   | Description | Source      |
| ---------------------- | ----------- | ----------- |
| `component.notice.css` | All notice styles (`.notice`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.notice.css

## Playground

<Playground
  client:visible
  template={`<aside class="{classes}">
  <div class="notice_title">
    {icon}
    <strong>{title}</strong>
  </div>
  <p>{body}</p>
</aside>`}
  baseClasses="notice"
  snippets={{
    info: { preview: infoIcon, code: "<svg>[…]</svg>" },
    danger: { preview: dangerIcon, code: "<svg>[…]</svg>" },
    warning: { preview: warningIcon, code: "<svg>[…]</svg>" },
    confirm: { preview: confirmIcon, code: "<svg>[…]</svg>" },
  }}
  controls={[
    { heading: "Variation", items: [
      { type: "select", name: "type", label: "Type", snippet: "icon", default: "", options: [
        { label: "Default", value: "", snippet: "info" },
        { label: "Info", value: "notice-info", snippet: "info" },
        { label: "Danger", value: "notice-danger", snippet: "danger" },
        { label: "Warning", value: "notice-warning", snippet: "warning" },
        { label: "Confirm", value: "notice-confirm", snippet: "confirm" },
      ]},
    ]},
    { heading: "Content", items: [
      { type: "text", name: "title", label: "Title", default: "Pro tip!" },
      { type: "text", name: "body", label: "Body", default: "Notices work without JavaScript." },
    ]},
  ]}
/>

## HTML

### Available modifiers

<div class="docs_oversizedTable">

| Available modifiers           | Description                   |
| ----------------------------- | ----------------------------- |
| `.notice`                     | Default style. Base colors.   |
| `.notice` + `.notice-info`    | Information. Primary colors.  |
| `.notice` + `.notice-danger`  | Error/Danger. Reds.           |
| `.notice` + `.notice-warning` | Warning. Oranges.             |
| `.notice` + `.notice-confirm` | Confirmation/Success. Greens. |

</div>

When using HTML, 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.

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                    | Color                     |
| --------------------------- | ------------------------- |
| `--notice-spacing`          | Padding inside Notice.    |
| `--notice-text-color`       | Default text color.       |
| `--notice-background-color` | Default background color. |
| `--notice-border-color`     | Default border color.     |
| `--notice-border-width`     | Default border width.     |
| `--notice-border-radius`    | Default border radius.    |

</div>

## Astro component

<div class="docs_oversizedTable prose">

| Prop         | Type     | Default     | Description                                                 |
| ------------ | -------- | ----------- | ----------------------------------------------------------- |
| `title`      | `string` | `undefined` | Text for the notice header. (Optional.)                     |
| `type`       | `string` | `undefined` | `info`, `danger`, `warning`, `confirm`.                     |
| `class` | `string` | `undefined` | Additional CSS classes, useful for [helper classes](/docs/helpers). |

</div>

## Examples

<ul class="docs_examples">
  <li>
    <Notice type="warning">
      <p>This is a warning notice without a `title` prop.</p>
    </Notice>

    ```astro
    ---
    import Notice from "../../components/Notice.astro";
    ---
    <Notice type="warning">
      <p>This is a warning notice without a `title` prop.</p>
    </Notice>
    ```

  </li>
  <li>
    <Notice title="Congratulation" type="confirm">
      <p>You've read this notice until the end!</p>
    </Notice>

    ```astro
    ---
    import Notice from "../../components/Notice.astro";
    ---
    <Notice title="Congratulation!" type="confirm">
      <p>You've read this notice until the end!</p>
    </Notice>
    ```

  </li>
</ul>

### HTML examples

<ul class="docs_examples">
  <li>
    <Notice title="Default Notice">
      <p>This is the the default notice style, without a modifier class.</p>
    </Notice>

    ```html
    <aside class="notice">
      <div class="notice_title">
        <svg>[…]</svg>
        <strong>Default Notice</strong>
      </div>
      <p>This is the the default […].</p>
    </aside>
    ```

  </li>
</ul>


---

# Pagination

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/pagination

Two navigation patterns for content sites: `.pagination` is the numbered kind for blog indexes, `.prevNext` the pair of cards at the bottom of a post. Both are pure HTML and CSS.

<Pagination currentPage={5} lastPage={12} baseUrl="#" pageUrl={(p) => `#page-${p}`} />

<PrevNext class="mt-sm3" prev={{ title: "Designing with cascade layers", href: "#" }} next={{ title: "Tokens all the way down", href: "#" }} />

<div class="docs_oversizedTable">

| File                                          | Description                    | Source      |
| --------------------------------------------- | ------------------------------ | ----------- |
| `component.pagination.css`                    | Numbered pagination styles     | [Github][1] |
| `component.prevNext.css`                      | Prev/next styles               | [Github][2] |
| `Pagination.astro`, `PrevNext.astro`          | The Astro components           | [Github][3] |
| `icons/chevron-down.svg`                      | Arrow icon (rotated in CSS)    | [Github][4] |
| `--pagination-*`, `--prevNext-*` theme blocks | Theme tokens (see table below) | [Github][5] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.pagination.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.prevNext.css
[3]: https://github.com/minimaldesign/mCSS/tree/main/src/components
[4]: https://github.com/minimaldesign/mCSS/tree/main/src/assets/icons
[5]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## Playground

The numbered pagination's markup is generated by windowing logic (see [HTML](#html)), so the playground covers the `.prevNext` pattern: toggle either link off and the layout holds its columns.

<Playground
  client:visible
  template={`<nav class="prevNext" aria-label="Previous and next">{prev}{next}
</nav>`}
  snippets={{
    prev: {
      preview: '<a class="prevNext_link prevNext_link-prev" href="#"><small>Previous</small><span>Designing with cascade layers</span></a>',
      code: '<a class="prevNext_link prevNext_link-prev" href="#"><small>Previous</small><span>Designing with cascade layers</span></a>',
    },
    next: {
      preview: '<a class="prevNext_link prevNext_link-next" href="#"><small>Next</small><span>Tokens all the way down</span></a>',
      code: '<a class="prevNext_link prevNext_link-next" href="#"><small>Next</small><span>Tokens all the way down</span></a>',
    },
  }}
  controls={[
    { heading: "Parts", items: [
      { type: "checkbox", name: "prev", label: "Previous link", snippet: "prev", default: true },
      { type: "checkbox", name: "next", label: "Next link", snippet: "next", default: true },
    ]},
  ]}
/>

## HTML

The numbers are windowed around the current page, so long lists stay short.

```html
<nav class="pagination" aria-label="Pagination">
  <ul>
    <li><a class="pagination_arrow pagination_arrow-prev" href="/blog/4" aria-label="Previous page"><svg>[…]</svg></a></li>
    <li><a href="/blog" aria-label="Page 1">1</a></li>
    <li><span class="pagination_ellipsis" aria-hidden="true">…</span></li>
    <li><a href="/blog/4" aria-label="Page 4">4</a></li>
    <li><a href="/blog/5" aria-current="page" aria-label="Page 5">5</a></li>
    <li><a href="/blog/6" aria-label="Page 6">6</a></li>
    <li><span class="pagination_ellipsis" aria-hidden="true">…</span></li>
    <li><a href="/blog/12" aria-label="Page 12">12</a></li>
    <li><a class="pagination_arrow pagination_arrow-next" href="/blog/6" aria-label="Next page"><svg>[…]</svg></a></li>
  </ul>
</nav>
```

At the ends, the arrows stay in place but become disabled `<span aria-disabled="true">` elements instead of links, so the layout never jumps. Every target is at least `--pagination-size` (36px) square.

```html
<nav class="prevNext" aria-label="Previous and next">
  <a class="prevNext_link prevNext_link-prev" href="/blog/layers">
    <small>Previous</small>
    <span>Designing with cascade layers</span>
  </a>
  <a class="prevNext_link prevNext_link-next" href="/blog/tokens">
    <small>Next</small>
    <span>Tokens all the way down</span>
  </a>
</nav>
```

A lone next link keeps its right-hand column.

### Custom properties

<div class="docs_oversizedTable">

| Property                               | Description                       |
| -------------------------------------- | --------------------------------- |
| `--pagination-size`                    | Minimum width/height of a target. |
| `--pagination-border-radius`           | Target border radius.             |
| `--pagination-color`                   | Number/arrow color.               |
| `--pagination-color-current`           | Current page text color.          |
| `--pagination-background-color-current`| Current page background.          |
| `--pagination-background-color-hover`  | Hover background.                 |
| `--prevNext-border-color`              | Card border.                      |
| `--prevNext-border-color-hover`        | Card border on hover.             |
| `--prevNext-label-color`               | "Previous"/"Next" label color.    |

</div>

## Astro component

**Pagination**

<div class="docs_oversizedTable">

| Prop          | Type                       | Default          | Description                                              |
| ------------- | -------------------------- | ---------------- | --------------------------------------------------------- |
| `currentPage` | `number`                   | —                | The page being rendered. Required.                        |
| `lastPage`    | `number`                   | —                | Total number of pages. Required.                          |
| `baseUrl`     | `string`                   | —                | Index URL; page 1 is `baseUrl`, page n is `baseUrl/n`.    |
| `pageUrl`     | `(page: number) => string` | see `baseUrl`    | Override the URL scheme entirely.                         |
| `windowSize`  | `number`                   | `1`              | Pages shown on each side of the current one.              |
| `ariaLabel`   | `string`                   | `"Pagination"`   | The nav's accessible name.                                |

</div>

With Astro's `paginate()`, pass `page.currentPage`, `page.lastPage`, and your index route as `baseUrl`.

**PrevNext**

<div class="docs_oversizedTable">

| Prop        | Type                       | Default               | Description                       |
| ----------- | -------------------------- | --------------------- | ---------------------------------- |
| `prev`      | `{ title, href }`          | `undefined`           | Previous post link.                |
| `next`      | `{ title, href }`          | `undefined`           | Next post link.                    |
| `prevLabel` | `string`                   | `"Previous"`          | Small label above the prev title.  |
| `nextLabel` | `string`                   | `"Next"`              | Small label above the next title.  |
| `ariaLabel` | `string`                   | `"Previous and next"` | The nav's accessible name.         |

</div>

Renders nothing when both links are missing.

## Examples

<ul class="docs_examples">
  <li>
    <Pagination currentPage={1} lastPage={3} baseUrl="#" pageUrl={(p) => `#page-${p}`} />

    ```astro
    ---
    import Pagination from "../components/Pagination.astro";
    const { page } = Astro.props; // from paginate()
    ---
    <Pagination currentPage={page.currentPage} lastPage={page.lastPage} baseUrl="/blog" />
    ```

  </li>
  <li>
    <PrevNext next={{ title: "Only a next link", href: "#" }} />

    ```astro
    <PrevNext next={{ title: "Only a next link", href: "/blog/tokens" }} />
    ```

  </li>
</ul>


---

# Pricing

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/pricing

The `.pricingCard` component is one tier of a pricing table: name, price, feature list, and a CTA pinned to the bottom so a row of tiers lines up. A pricing table is a row of these on the [grid](/docs/global#grid), with `highlighted` marking the recommended tier.

<div class="grid" col="1" col-md="3">
  <PricingCard name="Starter" price="$0" period="/month" description="For side projects." features={["1 site", "Community support"]} ctaHref="#" />
  <PricingCard name="Pro" price="$29" period="/month" description="For professionals." features={["10 sites", "Email support", "Custom themes"]} ctaHref="#" highlighted badge="Popular" />
  <PricingCard name="Team" price="$99" period="/month" description="For agencies." features={["Unlimited sites", "Priority support", "Custom themes", "SSO"]} ctaHref="#" />
</div>

<div class="docs_oversizedTable">

| File                                      | Description                         | Source      |
| ------------------------------------------ | ----------------------------------- | ----------- |
| `component.pricing.css`                    | Tier layout + highlight styles      | [Github][1] |
| `component.card.css`, `atom.badge.css`, `atom.button.css` | Base visuals (dependencies) | [Github][2] |
| `PricingCard.astro`                        | The Astro component                 | [Github][3] |
| `icons/check.svg`                          | Feature list check icon             | [Github][4] |
| `--pricingCard-*` block in default theme   | Theme tokens (see table below)      | [Github][5] |

</div>

It extends the [card](/components/card) and uses the [badge](/components/badge) and [button](/components/button) atoms.

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.pricing.css
[2]: https://github.com/minimaldesign/mCSS/tree/main/src/styles/framework
[3]: https://github.com/minimaldesign/mCSS/blob/main/src/components/PricingCard.astro
[4]: https://github.com/minimaldesign/mCSS/tree/main/src/assets/icons
[5]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## Playground

<Playground
  client:visible
  template={`<article class="{classes}">
  <header class="pricingCard_header">
    <h3 class="pricingCard_name">{name}</h3>{badge}
  </header>
  <p class="pricingCard_price">
    <span class="pricingCard_amount">{price}</span>
    <span class="pricingCard_period">/month</span>
  </p>
  <p class="pricingCard_description">{description}</p>
  <ul class="pricingCard_features">
    <li><span class="pricingCard_check" aria-hidden="true">{check}</span>10 sites</li>
    <li><span class="pricingCard_check" aria-hidden="true">{check}</span>Email support</li>
  </ul>
  <div class="pricingCard_cta">
    <a class="bt bt-primary" href="#">Get started</a>
  </div>
</article>`}
  baseClasses="card pricingCard"
  snippets={{
    check: { preview: checkIcon, code: "<svg>[…]</svg>" },
    badge: { preview: '<span class="badge badge-primary">Popular</span>', code: '<span class="badge badge-primary">Popular</span>' },
  }}
  controls={[
    { heading: "Modifiers", items: [
      { type: "checkbox", name: "highlighted", label: "Highlighted", value: "pricingCard-highlighted", default: false },
    ]},
    { heading: "Content", items: [
      { type: "checkbox", name: "badge", label: "Badge", snippet: "badge", default: false },
      { type: "text", name: "name", label: "Name", default: "Pro" },
      { type: "text", name: "price", label: "Price", default: "$29" },
      { type: "text", name: "description", label: "Description", default: "For professionals." },
    ]},
  ]}
/>

## HTML

```html
<article class="card pricingCard pricingCard-highlighted">
  <header class="pricingCard_header">
    <h3 class="pricingCard_name">Pro</h3>
    <span class="badge badge-primary">Popular</span>
  </header>
  <p class="pricingCard_price">
    <span class="pricingCard_amount">$29</span>
    <span class="pricingCard_period">/month</span>
  </p>
  <p class="pricingCard_description">For professionals.</p>
  <ul class="pricingCard_features">
    <li><span class="pricingCard_check" aria-hidden="true"><svg>[…]</svg></span>10 sites</li>
    <li><span class="pricingCard_check" aria-hidden="true"><svg>[…]</svg></span>Email support</li>
  </ul>
  <div class="pricingCard_cta">
    <a class="bt bt-primary" href="/signup">Get started</a>
  </div>
</article>
```

The highlight is a border-color swap plus a same-color ring (`box-shadow`), so the highlighted tier doesn't shift the row's layout.

### Custom properties

<div class="docs_oversizedTable">

| Property                              | Description                          |
| ------------------------------------- | ------------------------------------ |
| `--pricingCard-highlight-border-color` | Border/ring color of the highlight.  |
| `--pricingCard-check-color`            | Feature list check icon color.       |

</div>

Everything else comes from the [card tokens](/components/card).

## Astro component

<div class="docs_oversizedTable">

| Prop          | Type       | Default         | Description                                            |
| ------------- | ---------- | --------------- | ------------------------------------------------------- |
| `name`        | `string`   | —               | Tier name. Required.                                    |
| `price`       | `string`   | —               | Price as text (`"$29"`, `"Free"`…). Required.           |
| `period`      | `string`   | `undefined`     | Suffix after the price (`"/month"`).                    |
| `description` | `string`   | `undefined`     | One-liner under the price.                              |
| `features`    | `string[]` | `[]`            | Feature list, one check per entry.                      |
| `ctaLabel`    | `string`   | `"Get started"` | CTA button text.                                        |
| `ctaHref`     | `string`   | `undefined`     | CTA link; no CTA renders without it (or the `cta` slot).|
| `highlighted` | `boolean`  | `false`         | Recommended tier: primary ring + primary CTA.           |
| `badge`       | `string`   | `undefined`     | Badge text next to the name (`"Popular"`).              |
| `class`       | `string`   | `undefined`     | Additional CSS classes.                                 |

</div>

<div class="docs_oversizedTable">

| Slot  | Description                                          |
| ----- | ----------------------------------------------------- |
| `cta` | Replace the default CTA button with your own markup.  |

</div>


---

# Read Progress Bar

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/readprogressbar

<div class="prose">
  The `.readProgressBar` component creates a reading progress bar at the top of
  the page that represents the user's scroll position, growing as the user
  scrolls down and decreasing as they scroll up. This helps users understand
  their progress through the content and how much remains to be read. This component uses pure CSS when supported by the browser, and has a polyfill for [browsers that don't support](https://caniuse.com/?search=animation-timeline) `animation-timeline`.

(Scroll this page to see the component in action.)

</div>

<ReadProgressBar />

<div class="prose">

<div class="docs_oversizedTable">

| File                            | Description | Source      |
| ------------------------------- | ----------- | ----------- |
| `component.readProgressBar.css` | All progress bar styles (`.readProgressBar`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.readProgressBar.css

</div>

## HTML

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

| Property                   | Description                    |
| -------------------------- | ------------------------------ |
| `--readProgressBar-height` | Progress bar height.           |
| `--readProgressBar-color`  | Progress bar background color. |

## Examples

<ul class="docs_examples">

<li>

### Astro Component

The live demo is the bar at the top of this very page (a fixed element can only be demoed once, so the examples below don't embed extra instances).

```astro
---
import ReadProgressBar from '../components/ReadProgressBar.astro';
---
<ReadProgressBar />
```

</li>
<li>

### HTML

```html
<div class="readProgressBar" aria-hidden="true">
  <div></div>
</div>
```

If you're using HTML and would like to us the polyfill for [browsers that don't support](https://caniuse.com/?search=animation-timeline) `animation-timeline`, add the following JavaScript to your code:

```js
function throttle(func, delay) {
  let lastCall = 0;
  let timerId;

  return function (...args) {
    const now = new Date().getTime();
    if (now - lastCall < delay) {
      clearTimeout(timerId);
      timerId = setTimeout(() => {
        lastCall = now;
        func.apply(this, args);
      }, delay);
    } else {
      lastCall = now;
      func.apply(this, args);
    }
  };
}

function supportsScrollTimeline() {
  return CSS.supports("animation-timeline: scroll(root y)");
}

function updateProgressBar() {
  const bar = document.querySelector(".readProgressBar > div");
  if (!bar) return;
  const scrollTop = window.scrollY || document.documentElement.scrollTop;
  const docHeight = document.documentElement.scrollHeight - window.innerHeight;
  const progress = docHeight > 0 ? scrollTop / docHeight : 0;
  bar.style.width = progress * 100 + "%";
}

function enableJSProgressBar() {
  const bar = document.querySelector(".readProgressBar > div");
  if (!bar) return;
  // Remove any inline width set by CSS animation
  bar.style.animation = "none";
  bar.style.animationTimeline = "none";
  updateProgressBar();
  const throttledUpdate = throttle(updateProgressBar, 10);
  window.addEventListener("scroll", throttledUpdate, { passive: true });
  window.addEventListener("resize", throttledUpdate);
}

if (typeof window !== "undefined" && !supportsScrollTimeline()) {
  document.addEventListener("DOMContentLoaded", enableJSProgressBar);
}
```

</li>
</ul>


---

# Section

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/section

The `.section` component is the workhorse wrapper marketing pages are made of: a full-width band with vertical rhythm, an optional eyebrow/title/lede header, and background variants.

<Section eyebrow="Why mCSS" title="Everything is a section" lede="Stack a few of these and you have a landing page." variant="filled" style="border-radius: var(--radius-lg);">
  <p class="text-center">Section content goes here.</p>
</Section>

<div class="docs_oversizedTable">

| File                                 | Description                    | Source      |
| ------------------------------------ | ------------------------------ | ----------- |
| `component.section.css`              | All section styles             | [Github][1] |
| `Section.astro`                      | The Astro component            | [Github][2] |
| `--section-*` block in default theme | Theme tokens (see table below) | [Github][3] |

</div>

Depends on `.wrap` (`global.wrap.css`), part of the mCSS core: children align to the same content column as the rest of the page, and the `wide` preset lets grids escape the reading column.

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.section.css
[2]: https://github.com/minimaldesign/mCSS/blob/main/src/components/Section.astro
[3]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/settings.theme.default.css

## Playground

<Playground
  client:visible
  template={`<section class="{classes}">
  <header class="section_header">
    <p class="section_eyebrow">{eyebrow}</p>
    <h2 class="section_title">{title}</h2>
    <p class="section_lede">{lede}</p>
  </header>
  <p class="text-center">Section content goes here.</p>
</section>`}
  baseClasses="section wrap"
  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: "Layout", items: [
      { type: "checkbox", name: "wide", label: "Wide", value: "section-wide", default: false },
    ]},
    { 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
<section class="section wrap section-filled">
  <header class="section_header">
    <p class="section_eyebrow">Why mCSS</p>
    <h2 class="section_title">Everything is a section</h2>
    <p class="section_lede">Stack a few of these and you have a landing page.</p>
  </header>
  <!-- content: paragraphs, grids, cards… -->
</section>
```

### Available modifiers

<div class="docs_oversizedTable">

| 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. |
| `.section` + `.section-wide`      | Widens the content column to `--section-wide-width`.               |

</div>

### Elements

<div class="docs_oversizedTable">

| Class              | Description                                                     |
| ------------------ | ---------------------------------------------------------------- |
| `.section_header`  | Centered eyebrow/title/lede block.                               |
| `.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). |

</div>

### Custom properties

The following custom properties are available in the [default theme](/docs/themes):

<div class="docs_oversizedTable">

| Property                             | Description                              |
| ------------------------------------ | ---------------------------------------- |
| `--section-spacing`                  | Vertical padding of the band.            |
| `--section-header-spacing`           | Space between the header and content.    |
| `--section-wide-width`               | Content column width of the wide preset. |
| `--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.       |

</div>

## Astro component

<div class="docs_oversizedTable">

| 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`.                                                |
| `width`   | `string` | `undefined` | `wide`.                                                             |
| `class`   | `string` | `undefined` | Additional CSS classes, useful for [helper classes](/docs/helpers). |

</div>

Any other attribute is passed through to the root `<section>` element (handy for `id` anchors). The default slot is the section content.

## Examples

<ul class="docs_examples">
  <li>
    <Section eyebrow="Pricing" title="Primary band" variant="primary" style="border-radius: var(--radius-lg);">
      <p class="text-center">Text and <a href="#">links</a> flip to the inverted palette.</p>
    </Section>

    ```astro
    ---
    import Section from "../components/Section.astro";
    ---
    <Section eyebrow="Pricing" title="Primary band" variant="primary">
      <p>Text and <a href="/docs">links</a> flip to the inverted palette.</p>
    </Section>
    ```

  </li>
  <li>
    <Section title="Wide section" width="wide" variant="filled" style="border-radius: var(--radius-lg);">
      <div class="grid" col="3">
        <div class="docs_box">1</div>
        <div class="docs_box">2</div>
        <div class="docs_box">3</div>
      </div>
    </Section>

    ```astro
    <Section title="Wide section" width="wide" variant="filled">
      <div class="grid" col="3">…</div>
    </Section>
    ```

  </li>
  <li>
    The closing CTA every marketing page ends on is not a separate component; it is a Section with a `.section_actions` row:

    <Section title="Ready to own your CSS?" lede="Copy the framework, edit the tokens, ship the site." variant="primary" style="border-radius: var(--radius-lg);">
      <div class="section_actions">
        <a class="bt bt-lg bt-outline-white" href="#">Get started</a>
      </div>
    </Section>

    ```astro
    <Section title="Ready to own your CSS?" lede="Copy the framework, edit the tokens, ship the site." variant="primary">
      <div class="section_actions">
        <a class="bt bt-lg bt-outline-white" href="/docs/start">Get started</a>
      </div>
    </Section>
    ```

  </li>
</ul>


---

# Social Media Links

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/socialmedia

<div class="prose">

The `.socialMedia` component consists of an unordered list of links to social media accounts and their corresponding icons.

</div>

<SocialMedia
  size="md"
  urls={[
    "https://www.instagram.com/amandaoleander/",
    "https://www.tiktok.com/@samdoesarts",
    "https://www.youtube.com/@ProkoTV",
  ]}
/>

<div class="prose">

<div class="docs_oversizedTable">

| File                        | Description | Source      |
| --------------------------- | ----------- | ----------- |
| `component.socialMedia.css` | All social links styles (`.socialMedia`) | [Github][1] |

</div>

[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.

</div>

<div class="docs_examples_icons24">

<div class="docs_oversizedTable">

| Platform    | Icon                                         |
| ----------- | -------------------------------------------- |
| Unknown URL | <Fragment set:html={linkIcon} alt="" />      |
| Discord     | <Fragment set:html={discordIcon} alt="" />   |
| Facebook    | <Fragment set:html={facebookIcon} alt="" />  |
| Github      | <Fragment set:html={githubIcon} alt="" />    |
| Instagram   | <Fragment set:html={instagramIcon} alt="" /> |
| Linkedin    | <Fragment set:html={linkedinIcon} alt="" />  |
| Pinterest   | <Fragment set:html={pinterestIcon} alt="" /> |
| Reddit      | <Fragment set:html={redditIcon} alt="" />    |
| Snapchat    | <Fragment set:html={snapchatIcon} alt="" />  |
| Telegram    | <Fragment set:html={telegramIcon} alt="" />  |
| Tiktok      | <Fragment set:html={tiktokIcon} alt="" />    |
| X           | <Fragment set:html={xIcon} alt="" />         |
| Youtube     | <Fragment set:html={youtubeIcon} alt="" />   |
| Twitch      | <Fragment set:html={twitchIcon} alt="" />    |
| Odysee      | <Fragment set:html={odyseeIcon} alt="" />    |
| Minds       | <Fragment set:html={mindsIcon} alt="" />     |
| Substack    | <Fragment set:html={substackIcon} alt="" />  |
| Bitchute    | <Fragment set:html={bitchuteIcon} alt="" />  |
| Bastyon     | <Fragment set:html={bastyonIcon} alt="" />   |

</div>

</div>

## Playground

<Playground
  client:visible
  template={`<ul class="{classes}">
  <li><a href="https://x.com/_yannb_" aria-label="X">{x}</a></li>
  <li><a href="https://github.com/minimaldesign" aria-label="Github">{github}</a></li>
  <li><a href="https://www.youtube.com/@ProkoTV" aria-label="YouTube">{youtube}</a></li>
</ul>`}
  baseClasses="socialMedia"
  snippets={{
    x: { preview: xIcon, code: "<svg>[…]</svg>" },
    github: { preview: githubIcon, code: "<svg>[…]</svg>" },
    youtube: { preview: youtubeIcon, code: "<svg>[…]</svg>" },
  }}
  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

<div class="prose">

<div class="docs_oversizedTable">

| Available modifiers                | Description    |
| ---------------------------------- | -------------- |
| `.socialMedia`                     | Default - 24px |
| `.socialMedia` + `.socialMedia-md` | 32px           |
| `.socialMedia` + `.socialMedia-lg` | 44px           |
| `.socialMedia` + `.socialMedia-xl` | 64px           |

</div>

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.

</div>

## Astro component

<div class="prose">

The Astro component ([Github](https://github.com/minimaldesign/mCSS/blob/main/src/components/SocialMedia.astro)) takes 3 props:

<div class="docs_oversizedTable">

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

</div>
</div>

## Examples

<ul class="docs_examples">
  <li>
    <SocialMedia
      urls={[
        "https://www.instagram.com/amandaoleander/",
        "https://www.tiktok.com/@samdoesarts",
        "https://www.youtube.com/@ProkoTV",
      ]}
      class="mb-sm1"
    />

    ```astro
    ---
    import SocialMedia from "../../components/SocialMedia.astro";
    ---
    <SocialMedia
      urls={[
        "https://www.instagram.com/amandaoleander/",
        "https://www.tiktok.com/@samdoesarts",
        "https://www.youtube.com/@ProkoTV",
      ]}
    />
    ```

  </li>
  <li>
    <SocialMedia
      size="lg"
      urls={[
        "https://x.com/_yannb_",
        "https://github.com/minimaldesign",
        "https://www.youtube.com/@ProkoTV",
      ]}
      class="mb-sm1"
    />

    ```astro
    ---
    import SocialMedia from "../../components/SocialMedia.astro";
    ---
    <SocialMedia
      size="lg"
      urls={[
        "https://x.com/_yannb_",
        "https://github.com/minimaldesign",
        "https://www.youtube.com/@ProkoTV",
      ]}
    />
    ```

  </li>
</ul>

### HTML examples

<ul class="docs_examples">
  <li>
    <SocialMedia
      urls={[
        "https://www.instagram.com/amandaoleander/",
        "https://www.tiktok.com/@samdoesarts",
        "https://www.youtube.com/@ProkoTV",
      ]}
      class="mb-sm1"
    />

    ```html
    <ul class="socialMedia">
      <li>
        <a href="https://www.instagram.com/amandaoleander/" target="_blank" rel="noopener noreferrer" aria-label="Instagram">
         <svg>[…]</svg>
        </a>
      </li>
      <li>
        <a href="https://www.tiktok.com/@samdoesarts" target="_blank" rel="noopener noreferrer" aria-label="Tiktok">
         <svg>[…]</svg>
        </a>
      </li>
      <li>
        <a href="https://www.youtube.com/@ProkoTV" target="_blank" rel="noopener noreferrer" aria-label="YouTube">
         <svg>[…]</svg>
        </a>
      </li>
    </ul>
    ```

  </li>
</ul>


---

# Tags

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/tags

<div class="prose">
  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.
</div>

<Tags tagList={["css", "astro", "basics"]} class="mt-sm2 mb-sm2" />

<div class="prose">

<div class="docs_oversizedTable">

| File                 | Description | Source      |
| -------------------- | ----------- | ----------- |
| `component.tags.css` | All tags styles (`.tags`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.tags.css

</div>

## Playground

<Playground
  client:visible
  template={`<ul class="{classes}">
  <li><a href="#">css</a></li>
  <li><a href="#">astro</a></li>
  <li><a href="#">basics</a></li>
</ul>`}
  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 the [default theme](/docs/themes):

| 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

<div class="docs_oversizedTable">

| Modifier       | Description                  |
| -------------- | ---------------------------- |
| `.tags`        | Default style (list layout). |
| `.tags-inline` | Inline layout using flex.    |

</div>

## Astro component

<div class="docs_oversizedTable prose">

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

</div>

## Examples

<ul class="docs_examples">
<li>

### Astro example (frontmatter metadata)

<Tags tagList={["css", "astro", "basics"]} url="/blog/tags" />

```astro
---
import Tags from '../components/Tags.astro';
const { frontmatter } = Astro.props;
---
<Tags tagList={frontmatter.tags} url="/blog/tags" />
```

</li>

<li>

### HTML example (list layout)

<ul class="tags">
  <li>
    <a href="/blog/tags/css">css</a>
  </li>
  <li>
    <a href="/blog/tags/astro">astro</a>
  </li>
  <li>
    <a href="/blog/tags/basics">basics</a>
  </li>
</ul>

```html
<ul class="tags">
  <li>
    <a href="/blog/tags/css">css</a>
  </li>
  <li>
    <a href="/blog/tags/astro">astro</a>
  </li>
  <li>
    <a href="/blog/tags/basics">basics</a>
  </li>
</ul>
```

</li>
</ul>


---

# 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.

<Testimonial name="Sonny Mueller" role="Design lead, Acme">
  <p>We deleted four hundred lines of utility classes the week we switched. The cascade does the work now.</p>
</Testimonial>

<div class="docs_oversizedTable">

| 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 default theme | Theme token                       | [Github][4] |

</div>

[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.theme.default.css

## Playground

<Playground
  client:visible
  template={`<figure class="testimonial">
  <blockquote class="testimonial_quote">
    <p>{quote}</p>
  </blockquote>
  <figcaption class="testimonial_byline">
    <div class="avatar avatar-sm">
      <div><span>{initials}</span></div>
    </div>
    <div>
      <span class="testimonial_name">{name}</span>
      <span class="testimonial_role">{role}</span>
    </div>
  </figcaption>
</figure>`}
  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 Mueller" },
      { type: "text", name: "role", label: "Role", default: "Design lead, Acme" },
      { type: "text", name: "initials", label: "Initials", default: "SM" },
    ]},
  ]}
/>

## HTML

```html
<figure class="testimonial">
  <blockquote class="testimonial_quote">
    <p>We deleted four hundred lines of utility classes the week we switched.</p>
  </blockquote>
  <figcaption class="testimonial_byline">
    <!-- avatar markup, see the Avatar docs -->
    <div>
      <span class="testimonial_name">Sonny Mueller</span>
      <span class="testimonial_role">Design lead, Acme</span>
    </div>
  </figcaption>
</figure>
```

### Custom properties

<div class="docs_oversizedTable">

| Property                   | Description       |
| -------------------------- | ----------------- |
| `--testimonial-role-color` | Role text color.  |

</div>

The quote itself is themed by the `blockquote` element styles.

## Astro component

<div class="docs_oversizedTable">

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

</div>

The default slot is the quote.

## Examples

A wall of quotes is just testimonials on the [grid](/docs/global#grid):

<ul class="docs_examples">
  <li>

    <div class="grid" col="1" col-md="3">
      <Testimonial name="Ada Chen" role="Freelance">
        <p>The copy-paste model means I actually own my components.</p>
      </Testimonial>
      <Testimonial name="Sam Ortiz">
        <p>Readable class names. Imagine that.</p>
      </Testimonial>
      <Testimonial name="Mia Kim" role="Founder, Studio K">
        <p>Shipped our marketing site in a weekend.</p>
      </Testimonial>
    </div>

    ```astro
    ---
    import Testimonial from "../components/Testimonial.astro";
    ---
    <div class="grid" col="1" col-md="3">
      <Testimonial name="Ada Chen" role="Freelance">
        <p>The copy-paste model means I actually own my components.</p>
      </Testimonial>
      <!-- … -->
    </div>
    ```

  </li>
</ul>


---

# Table of Content

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/toc

<div class="prose">
  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:

</div>

<Toc id="example1" class="mb-sm2" />

<div class="prose">

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.

<div class="docs_oversizedTable">

| File                | Description | Source      |
| ------------------- | ----------- | ----------- |
| `component.toc.css` | All TOC styles (`.toc`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.toc.css

</div>

## 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 the [default theme](/docs/themes):

| 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

<div class="docs_oversizedTable prose">

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

</div>

## Examples

<ul class="docs_examples">

<li>

### TOC with only H2s

<Toc
  id="example2"
  selector=".docs"
  headings={["h2"]}
  scrollOffset={800}
  description={"Just H2s"}
/>

```astro
---
import Toc from "../../components/Toc.astro";
---
<Toc
  id="example2"
  selector=".docs"
  headings={["h2"]}
  scrollOffset={80}
  description={"Just H2s"}
/>
```

</li>
<li>

### TOC with H2 — h4 and a ♥︎ icon

#### A H4 just as an example

<Toc
  id="example3"
  selector=".docs"
  headings={["h2", "h3", "h4"]}
  scrollOffset={80}
  icon={heart}
/>

```astro
---
import heart from "../../assets/icons/arrow-right-small.svg?raw";
import Toc from "../../components/Toc.astro";
---
<Toc
  id="example3"
  selector=".docs"
  headings={["h2", "h3", "h4"]}
  scrollOffset={80}
  icon={heart}
/>
```

</li>
</ul>