# 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/tokens#dimension) as well as `0`:

| CSS property           | Class prefix |
| ---------------------- | ------------ |
| `width`                | `w`          |
| `height`               | `h`          |
| `margin`               | `m`          |
| `margin-top`           | `mt`         |
| `margin-bottom`        | `mb`         |
| `margin-left`          | `ml`         |
| `margin-right`         | `mr`         |
| `margin-inline-start`  | `mis`        |
| `margin-inline-end`    | `mie`        |
| `padding`              | `p`          |
| `padding-top`          | `pt`         |
| `padding-bottom`       | `pb`         |
| `padding-left`         | `pl`         |
| `padding-right`        | `pr`         |
| `padding-inline-start` | `pis`        |
| `padding-inline-end`   | `pie`        |

Both directional sets exist on purpose. Use the logical helpers (`mis`, `mie`, `pis`, `pie`) when the spacing follows the reading direction: an icon gap, a list indent, anything that should flip in a right-to-left layout. Use the physical helpers (`ml`, `mr`, `pl`, `pr`) when the offset is a purely visual choice that should stay on the same side no matter the script direction. In a left-to-right layout they resolve identically.

#### Examples

| Class     | Value                              |
| --------- | ---------------------------------- |
| `w-lg1`   | `width: var(--lg1)`                |
| `ml-0`    | `margin-left: 0`                   |
| `mb-sm1`  | `margin-bottom: var(--sm1)`        |
| `pis-md1` | `padding-inline-start: var(--md1)` |

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

Same split as the spacing helpers: `.text-start` and `.text-end` follow the reading direction (they flip in a right-to-left layout), `.text-left` and `.text-right` always mean the visual side.

### text-transform

| CSS value    | Class              |
| ------------ | ------------------ |
| `uppercase`  | `.text-uppercase`  |
| `lowercase`  | `.text-lowercase`  |
| `capitalize` | `.text-capitalize` |