# 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 <code>!&#8288;important</code> and overrides everything else. 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.

Below is a list of all the available helpers. mCSS doesn't include every single CSS property like utility class 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 adding 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/default-theme#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. Use the physical helpers (`ml`, `mr`, `pl`, `pr`) when the spacing is purely visual and should stay in the same position no matter the script direction.

#### 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 these properties with any [color token](/docs/default-theme#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/default-theme#z-index).

<div class="docs_oversizedTable">

| Custom Property | CSS Value   | Class       |
| --------------- | ----------- | ----------- |
| –               | auto        | `.z-auto`   |
| `--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/default-theme#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/default-theme#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/default-theme#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`   |
| `--display-mega` | `.display-mega` |
| `--display-giga` | `.display-giga` |

### letter-spacing

See the [letter spacing tokens](/docs/default-theme#letter-spacing) for details.

| Custom Property  | Class           |
| ---------------- | --------------- |
| `--tracking-sm`  | `.tracking-sm`  |
| `--tracking-md`  | `.tracking-md`  |
| `--tracking-lg`  | `.tracking-lg`  |
| `--tracking-xl`  | `.tracking-xl`  |
| `--tracking-xxl` | `.tracking-xxl` |

### line-height

See the [line height tokens](/docs/default-theme#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 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` |