# CSS variables

Source: https://iriscss.com/documentation/customize/css-variables/

Every value in Iris CSS comes from a `--i-` custom property. Change one and everything that reads it follows.

Classes have no prefix, but custom properties are global and inherited. The `--i-` prefix keeps them clear of your own variables and of other libraries.

## Change a value everywhere

Set the variable on `:root` in your own stylesheet. It wins over Iris without `!important`, see [cascade layers](https://iriscss.com/documentation/overview/cascade-layers/index.html.md).

```css
:root {
  --i-border-radius: 0.5rem;
  --i-spacing: 1.25rem;
  --i-font-family: "Inter", var(--i-font-sans);
}
```

## Change a value in one place

Set it on any element. Only that element and its children see the new value.

```html
<div class="cluster" style="--i-border-radius: 0; --i-color-primary: #7c3aed; --i-color-primary-inverse: #fff">
  <button class="primary">Square and violet</button>
  <input type="text" placeholder="Square input" aria-label="Example">
</div>
```

## Theme colors

Colors that change with the theme are `light-dark()` pairs. Override them with a pair of your own, or with one value to use it in both themes. See [themes](https://iriscss.com/documentation/customize/themes/index.html.md) for the full list.

```css
:root {
  --i-color-primary: light-dark(#6d28d9, #a78bfa);
}
```

## Naming

- **Owner first**: `--i-{owner}-{part}-{state}-{property}`, for example `--i-navbar-brand-font-size` or `--i-table-row-hover-color-background`. Part and state are optional.
- **Colors end in a role**: `color-text`, `color-background`, `color-border` or `color-outline`, for example `--i-input-color-border`.
- **Global tokens start with a category**: `--i-color-primary`, `--i-font-family`, `--i-spacing`, `--i-border-radius`. Many elements read them.
- **Private variables**: Names that start with `--_` switch values inside one element. They are not part of the API and can change at any time.

## Global variables

The tokens below are read across the framework. Each element and component page ends with a table of its own variables.

### Typography

| Variable | Default | Note |
| --- | --- | --- |
| `--i-font-emoji` | `"Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Twemoji Mozilla", "Noto Color Emoji"` | Font stacks: each platform's system font, then generic fallbacks |
| `--i-font-sans` | `system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Helvetica Neue", Arial, "Noto Sans", sans-serif, var(--i-font-emoji)` |  |
| `--i-font-mono` | `ui-monospace, "Cascadia Mono", SFMono-Regular, Menlo, Consolas, "Roboto Mono", "Liberation Mono", "Courier New", monospace, var(--i-font-emoji)` |  |
| `--i-font-family` | `var(--i-font-sans)` |  |
| `--i-line-height` | `1.5` | Base text. The root size starts at the size the user set in the browser and grows to 112.5% between a 576px and a 1280px wide viewport. |
| `--i-font-weight` | `400` |  |
| `--i-font-size` | `clamp(100%, 89.75% + 0.285svw, 112.5%)` |  |
| `--i-text-underline-offset` | `0.125em` |  |

### Spacing

| Variable | Default |
| --- | --- |
| `--i-spacing` | `1rem` |
| `--i-typography-spacing` | `1rem` |
| `--i-section-spacing-block` | `var(--i-spacing)` |
| `--i-section-spacing-inline` | `var(--i-spacing)` |

### Borders

| Variable | Default | Note |
| --- | --- | --- |
| `--i-border-radius-small` | `0.125rem` | Border radius scale |
| `--i-border-radius` | `0.25rem` |  |
| `--i-border-radius-medium` | `0.375rem` |  |
| `--i-border-radius-large` | `0.5rem` |  |
| `--i-border-radius-xlarge` | `0.75rem` |  |
| `--i-border-radius-pill` | `9999px` |  |
| `--i-border-width` | `0.0625rem` | Border widths |
| `--i-focus-ring-width` | `0.125rem` |  |

### Motion

| Variable | Default | Note |
| --- | --- | --- |
| `--i-duration` | `0.2s` | Transitions |
| `--i-easing` | `ease-in-out` |  |

### Icons

SVG data URIs with the color baked in. Replace the whole value to change an icon or its color.

| Variable | Default |
| --- | --- |
| `--i-svg-checkmark` | `url("data:image/svg+xml,…")` |
| `--i-svg-chevron-down` | `url("data:image/svg+xml,…")` |
| `--i-svg-close` | `url("data:image/svg+xml,…")` |
| `--i-svg-dash` | `url("data:image/svg+xml,…")` |
| `--i-svg-date` | `url("data:image/svg+xml,…")` |
| `--i-svg-invalid` | `url("data:image/svg+xml,…")` |
| `--i-svg-loading` | `url("data:image/svg+xml,…")` |
| `--i-svg-menu` | `url("data:image/svg+xml,…")` |
| `--i-svg-search` | `url("data:image/svg+xml,…")` |
| `--i-svg-time` | `url("data:image/svg+xml,…")` |
| `--i-svg-valid` | `url("data:image/svg+xml,…")` |