# CSS variables

> Every color, size and spacing is a --pico-* custom property. Override one in your own CSS, on the page or on a single element.

Page: https://pico.rusticstack.com/docs/customization/css-variables

Pico Reforged keeps its design values in CSS custom properties. They all start with `--pico-`, and the names are the same as in Pico CSS v2.1.1 by Lucas Larroche, so an old override keeps working. Change a variable and every rule that reads it follows.

Most customization needs no build step. Write the override in your own stylesheet, after the Pico link.

## Override a variable

Declare the variable on `:root` to change it for the whole page.

```css
:root {
  --pico-border-radius: 0;
  --pico-font-family: Georgia, serif;
  --pico-spacing: 0.75rem;
}
```

> **Unlayered CSS wins**
>
> Your CSS is not inside a cascade layer, so it wins over Pico without `!important` or a heavier selector. See [Cascade layers and overriding](/docs/customization/cascade-layers).

### Scope a change to one element

A variable set on an element applies to that element and everything inside it.

**Example: Variables on one element**

```html
<article style="--pico-border-radius: 1.5rem; --pico-primary-background: oklch(0.55 0.2 25); --pico-primary-border: oklch(0.55 0.2 25); --pico-primary-hover-background: oklch(0.48 0.2 25); --pico-primary-hover-border: oklch(0.48 0.2 25);">
  <h3>A rounder card with a red button</h3>
  <p>The rest of the page keeps its defaults.</p>
  <button>Primary</button>
</article>
<article>
  <h3>A regular card</h3>
  <p>Same page, no overrides.</p>
  <button>Primary</button>
</article>
```

> **Variables resolve where they are declared**
>
> `--pico-block-spacing-vertical` is declared on `:root` as `calc(var(--pico-spacing) * 1.25)`, so setting `--pico-spacing` on a single `<article>` does not change it. Set `--pico-block-spacing-vertical` and its horizontal sibling on the element instead.

Some elements set their own values. Headings set `--pico-font-size` and `--pico-line-height` per level (for example `h1 { --pico-font-size: 2.25rem }`), and buttons set `--pico-background-color` and `--pico-border-color` from the primary, secondary and contrast tokens. To change a heading size, write the rule on the heading, not on `:root`.

```css
h1 {
  --pico-font-size: 2.5rem;
}
```

## Reference

Type in the field to filter every list on this page by name or description. Defaults and swatches are read from the build, so they match the current release.



## Typography

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-font-family` | `var(--pico-font-family-sans-serif)` | Font stack of the page. |
| `--pico-font-family-sans-serif` | `system-ui, "Segoe UI", Roboto, ...` | The system sans-serif stack, with the emoji stack at the end. |
| `--pico-font-family-monospace` | `ui-monospace, SFMono-Regular, ...` | Stack for code, kbd, samp and pre. |
| `--pico-font-family-emoji` | `"Apple Color Emoji", "Segoe UI Emoji", ...` | Emoji fonts, appended to the other stacks. |
| `--pico-font-size` | `100%` | Root font size. It takes one step to 106.25% from 1536px. Headings override it per level. |
| `--pico-font-weight` | `400` | Body font weight. |
| `--pico-line-height` | `1.5` | Body line height. |
| `--pico-text-underline-offset` | `0.1rem` | Offset of link underlines. |
| `--pico-typography-spacing-vertical` | `1rem` | Space under paragraphs, lists and headings. |
| `--pico-form-label-font-weight` | `var(--pico-font-weight)` | Font weight of form labels. |

To change the font, set `--pico-font-family` and nothing else.

**Example: A serif page**

```html
<style>
  :root {
    --pico-font-family: Georgia, "Times New Roman", serif;
    --pico-line-height: 1.65;
  }
</style>
<h3>Set in Georgia</h3>
<p>One variable changes the font of every element, forms and buttons included.</p>
<button>Button</button>
```

## Borders, transitions and spacing

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-border-radius` | `0.5rem` | Corner radius of buttons, inputs and code blocks. Small parts such as checkboxes and tooltips use a fraction of it. |
| `--pico-card-border-radius` | `calc(var(--pico-border-radius) * 1.5)` | Corner radius of cards, modals, menus, popovers and the extras surfaces. 1.5 times `--pico-border-radius`; the modal box uses 4/3 of it. |
| `--pico-border-width` | `0.0625rem` | Width of borders. |
| `--pico-outline-width` | `0.125rem` | Width of focus rings. |
| `--pico-transition` | `150ms cubic-bezier(0.2, 0, 0, 1)` | Timing of hover and focus transitions. A build with transitions turned off sets it to 0s. |
| `--pico-spacing` | `1rem` | Base spacing unit. |
| `--pico-block-spacing-vertical` | `var(--pico-spacing)` | Vertical padding of cards and modals. Larger from 576px up when the responsive spacings option is on. |
| `--pico-block-spacing-horizontal` | `var(--pico-spacing)` | Horizontal padding of the same blocks. |
| `--pico-grid-column-gap` | `var(--pico-spacing)` | Column gap of .grid. |
| `--pico-grid-row-gap` | `var(--pico-spacing)` | Row gap of .grid. |
| `--pico-form-element-spacing-vertical` | `0.75rem` | Vertical padding of inputs, selects, textareas and buttons. |
| `--pico-form-element-spacing-horizontal` | `1rem` | Horizontal padding of the same elements. |
| `--pico-form-element-disabled-opacity` | `0.5` | Opacity of disabled form elements. |
| `--pico-loading-spinner-opacity` | `0.5` | Opacity of the aria-busy spinner. |

## Container

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-container-max-width` | `100%` | Max width of .container and the semantic container. Set per breakpoint: 510px from 576px, 700px from 768px, 950px from 1024px, 1200px from 1280px and 1450px from 1536px. |

The fluid builds set it to `100%` at every width. See [Building a custom bundle](/docs/customization/custom-bundle).

## Navigation

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-nav-element-spacing-vertical` | `1rem` | Vertical padding of nav items. |
| `--pico-nav-element-spacing-horizontal` | `0.5rem` | Horizontal padding of nav items. |
| `--pico-nav-link-spacing-vertical` | `0.5rem` | Vertical padding of nav links. |
| `--pico-nav-link-spacing-horizontal` | `0.5rem` | Horizontal padding of nav links. |
| `--pico-nav-breadcrumb-divider` | `">"` | Divider between breadcrumb items. |

## Modal

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-modal-overlay-backdrop-filter` | `blur(0.375rem)` | Backdrop filter behind an open dialog. |
| `--pico-scrollbar-width` | `0px` | Right padding added to html while .modal-is-open is set, so a hidden scrollbar does not shift the page. Set it from a script if you need it. |

## Shadows

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-box-shadow` |  | The soft layered shadow behind cards and dropdowns. Its colors use light-dark(). |
| `--pico-card-box-shadow` | `var(--pico-box-shadow)` | Shadow of cards. |
| `--pico-dropdown-box-shadow` | `var(--pico-box-shadow)` | Shadow of dropdown menus. |
| `--pico-button-box-shadow` | `0 0 0 oklch(0 0 0 / 0)` | Resting shadow of buttons. Empty by default. |
| `--pico-button-hover-box-shadow` | `0 0 0 oklch(0 0 0 / 0)` | Shadow of buttons on hover. Empty by default. |
| `--pico-group-box-shadow` | `0 0 0 oklch(0 0 0 / 0)` | Shadow of a role="group" container. |
| `--pico-switch-thumb-box-shadow` |  | Shadow of the switch thumb. Part of a theme. |

## Icons

The icons are SVG data URIs, so you can swap one for your own.

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-icon-checkbox` |  | Checkmark in checked checkboxes. |
| `--pico-icon-minus` |  | Dash in indeterminate checkboxes. |
| `--pico-icon-chevron` |  | Arrow of selects, accordions and dropdown summaries. |
| `--pico-icon-date` |  | Date input icon. |
| `--pico-icon-time` |  | Time input icon. |
| `--pico-icon-search` |  | Search input icon. |
| `--pico-icon-close` |  | Close button of modals. |
| `--pico-icon-loading` |  | Spinner shown by aria-busy="true". |
| `--pico-icon-valid` |  | Icon of an input with aria-invalid="false". It has a light and a dark version. |
| `--pico-icon-invalid` |  | Icon of an input with aria-invalid="true". It has a light and a dark version. |

## Colors

The semantic color tokens are written once with `light-dark()`, so each holds a light and a dark value. In the tables below the first value is the light scheme and the second the dark one. A single value, or a `var()`, means both schemes use it. Hex values are approximations of the OKLCH colors in the source. How the schemes switch is explained in [Color schemes](/docs/customization/color-schemes).

The primary tokens belong to the theme. The values shown are for Azure, the default. Another theme replaces them, see [Themes](/docs/customization/themes).

### Page

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-background-color` | `#ffffff / #13171f` | Page background color. |
| `--pico-color` | `#373c44 / #c2c7d0` | Default text color. |
| `--pico-muted-color` | `#646b79 / #7b8495` | Muted text color for secondary information. |
| `--pico-muted-border-color` | `#e7eaef / #202632` | Border color of separators and quiet surfaces. |

### Primary

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-primary` | `#0172ad / #01aaff` | Primary text and link color. |
| `--pico-primary-background` | `#0172ad` | Primary fill color. |
| `--pico-primary-border` | `var(--pico-primary-background)` | Primary border color. |
| `--pico-primary-underline` | `#0172ad (alpha 0.5) / #01aaff (alpha 0.5)` | Primary link underline color. |
| `--pico-primary-hover` | `#015887 / #79c0ff` | Primary hover color. |
| `--pico-primary-hover-background` | `#02659a / #017fc0` | Primary hover fill color. |
| `--pico-primary-hover-border` | `var(--pico-primary-hover-background)` | Primary hover border color. |
| `--pico-primary-hover-underline` | `var(--pico-primary-hover)` | Primary hover link underline color. |
| `--pico-primary-focus` | `#029ae8 (alpha 0.5) / #01aaff (alpha 0.375)` | Primary focus ring color. |
| `--pico-primary-inverse` | `#ffffff` | Primary text color on a filled background. |
| `--pico-text-selection-color` | `#029ae8 (alpha 0.25) / #01aaff (alpha 0.1875)` | Background of selected text. |

### Secondary

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-secondary` | `#5d6b89 / #969eaf` | Secondary text and link color. |
| `--pico-secondary-background` | `#525f7a` | Secondary fill color. |
| `--pico-secondary-border` | `var(--pico-secondary-background)` | Secondary border color. |
| `--pico-secondary-underline` | `#5d6b89 (alpha 0.5) / #969eaf (alpha 0.5)` | Secondary link underline color. |
| `--pico-secondary-hover` | `#48536b / #b3b9c5` | Secondary hover color. |
| `--pico-secondary-hover-background` | `#48536b / #5d6b89` | Secondary hover fill color. |
| `--pico-secondary-hover-border` | `var(--pico-secondary-hover-background)` | Secondary hover border color. |
| `--pico-secondary-hover-underline` | `var(--pico-secondary-hover)` | Secondary hover link underline color. |
| `--pico-secondary-focus` | `#5d6b89 (alpha 0.25) / #909ebe (alpha 0.25)` | Secondary focus ring color. |
| `--pico-secondary-inverse` | `#ffffff` | Secondary text color on a filled background. |

### Contrast

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-contrast` | `#181c25 / #dfe3eb` | Contrast text and link color. |
| `--pico-contrast-background` | `#181c25 / #eff1f4` | Contrast fill color. |
| `--pico-contrast-border` | `var(--pico-contrast-background)` | Contrast border color. |
| `--pico-contrast-underline` | `#181c25 (alpha 0.5) / #dfe3eb (alpha 0.5)` | Contrast link underline color. |
| `--pico-contrast-hover` | `#000000 / #ffffff` | Contrast hover color. |
| `--pico-contrast-hover-background` | `#000000 / #ffffff` | Contrast hover fill color. |
| `--pico-contrast-hover-border` | `var(--pico-contrast-hover-background)` | Contrast hover border color. |
| `--pico-contrast-hover-underline` | `var(--pico-secondary-hover)` | Contrast hover link underline color. |
| `--pico-contrast-focus` | `#5d6b89 (alpha 0.25) / #cfd5e2 (alpha 0.25)` | Contrast focus ring color. |
| `--pico-contrast-inverse` | `#ffffff / #000000` | Contrast text color on a filled background. |

### Headings and text

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-h1-color` | `#2d3138 / #f0f1f3` | Color of h1. |
| `--pico-h2-color` | `#373c44 / #e0e3e7` | Color of h2. |
| `--pico-h3-color` | `#424751 / #c2c7d0` | Color of h3. |
| `--pico-h4-color` | `#4d535e / #b3b9c5` | Color of h4. |
| `--pico-h5-color` | `#5c6370 / #a4acba` | Color of h5. |
| `--pico-h6-color` | `#646b79 / #8891a4` | Color of h6. |
| `--pico-mark-background-color` | `#fce6bf / #014063` | mark element. |
| `--pico-mark-color` | `#0f1114 / #ffffff` | mark element. |
| `--pico-ins-color` | `#1c6954 / #62af9a` | ins and del elements. |
| `--pico-del-color` | `#883835 / #ce7e7b` | ins and del elements. |
| `--pico-blockquote-border-color` | `var(--pico-muted-border-color)` | blockquote element. |
| `--pico-blockquote-footer-color` | `var(--pico-muted-color)` | blockquote element. |
| `--pico-code-background-color` | `#f3f4f7 / #1a1e28` | Background of inline code, kbd and samp, and of code blocks. |
| `--pico-code-color` | `#646b79 / #8891a4` | Text color of inline code and samp, and of code blocks. |
| `--pico-code-kbd-background-color` | `var(--pico-color)` | Background of `kbd`, a key or shortcut. |
| `--pico-code-kbd-color` | `var(--pico-background-color)` | Text color of `kbd`. |
| `--pico-table-border-color` | `var(--pico-muted-border-color)` | Table. |
| `--pico-table-row-stripped-background-color` | `#6f7887 (alpha 0.0375)` | Table. |

### Form elements

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-form-element-background-color` | `#fbfbfc / #1c212c` | Form element color. |
| `--pico-form-element-selected-background-color` | `#dfe3eb / #2a3140` | Form element color. |
| `--pico-form-element-border-color` | `#cfd5e2 / #2a3140` | Form element color. |
| `--pico-form-element-color` | `#23262c / #e0e3e7` | Form element color. |
| `--pico-form-element-placeholder-color` | `var(--pico-muted-color)` | Form element color. |
| `--pico-form-element-active-background-color` | `#ffffff / #1a1e28` | Form element color. |
| `--pico-form-element-active-border-color` | `var(--pico-primary-border)` | Form element color. |
| `--pico-form-element-focus-color` | `var(--pico-primary-border)` | Form element color. |
| `--pico-form-element-invalid-border-color` | `#b86a6b / #964a50` | Form element color in the invalid state. |
| `--pico-form-element-invalid-active-border-color` | `#c84f48 / #b73f3b` | Form element color in the invalid state. |
| `--pico-form-element-invalid-focus-color` | `var(--pico-form-element-invalid-active-border-color)` | Form element color in the invalid state. |
| `--pico-form-element-valid-border-color` | `#4c9a8a / #2a7b6f` | Form element color in the valid state. |
| `--pico-form-element-valid-active-border-color` | `#279977 / #16896a` | Form element color in the valid state. |
| `--pico-form-element-valid-focus-color` | `var(--pico-form-element-valid-active-border-color)` | Form element color in the valid state. |
| `--pico-switch-background-color` | `#bfc7d9 / #333c4e` | Switch control. |
| `--pico-switch-checked-background-color` | `var(--pico-primary-background)` | Switch control. |
| `--pico-switch-color` | `#ffffff` | Switch control. |
| `--pico-range-border-color` | `#dfe3eb / #202632` | Range input. |
| `--pico-range-active-border-color` | `#bfc7d9 / #2a3140` | Range input. |
| `--pico-range-thumb-border-color` | `var(--pico-background-color)` | Range input. |
| `--pico-range-thumb-color` | `var(--pico-secondary-background)` | Range input. |
| `--pico-range-thumb-active-color` | `var(--pico-primary-background)` | Range input. |

### Components

| Variable | Default | Description |
| --- | --- | --- |
| `--pico-accordion-border-color` | `var(--pico-muted-border-color)` | Accordion summary. |
| `--pico-accordion-active-summary-color` | `var(--pico-primary-hover)` | Accordion summary. |
| `--pico-accordion-close-summary-color` | `var(--pico-color)` | Accordion summary. |
| `--pico-accordion-open-summary-color` | `var(--pico-muted-color)` | Accordion summary. |
| `--pico-card-background-color` | `var(--pico-background-color)` | Card surface. |
| `--pico-card-border-color` | `var(--pico-muted-border-color)` | Card surface. |
| `--pico-card-sectioning-background-color` | `#fbfbfc / #1a1e28` | Card surface. |
| `--pico-dropdown-background-color` | `#ffffff / #181c25` | Dropdown menu surface. |
| `--pico-dropdown-border-color` | `#eff1f4 / #202632` | Dropdown menu surface. |
| `--pico-dropdown-color` | `var(--pico-color)` | Dropdown menu surface. |
| `--pico-dropdown-hover-background-color` | `#eff1f4 / #202632` | Dropdown menu surface. |
| `--pico-modal-overlay-background-color` | `#e8eaed (alpha 0.75) / #07080a (alpha 0.75)` | Modal overlay. |
| `--pico-progress-background-color` | `#dfe3eb / #202632` | Progress bar. |
| `--pico-progress-color` | `var(--pico-primary-background)` | Progress bar. |
| `--pico-tooltip-background-color` | `var(--pico-contrast-background)` | Tooltip bubble. |
| `--pico-tooltip-color` | `var(--pico-contrast-inverse)` | Tooltip bubble. |

## Color palette

The full OKLCH palette is not in `pico.css`. It lives in `pico.colors.css`, which defines `--pico-color-<hue>-<step>` for the 20 hues and the steps 50 to 950 in increments of 50, for example `--pico-color-azure-550`. A bare `--pico-color-azure` is the 550 step, and `--pico-color-black` and `--pico-color-white` are there too. The same file adds the `.pico-color-*` and `.pico-background-*` classes. Link it after `pico.css`.

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@rusticstack/pico-reforged@2/css/pico.colors.min.css"
/>
```

**Example: Palette variables and classes**

```html
<p class="pico-color-red-550">Text in red 550, from a class.</p>
<p class="pico-background-jade-600" style="padding: 0.5rem 1rem;">A jade 600 background.</p>
<p style="color: var(--pico-color-amber-450);">Amber 450, read from the variable.</p>
```

## Extras

The opt-in extras declare their own tokens, named `--pico-<extra>-*`, for example `--pico-tabs-indicator-color` and `--pico-badge-background-color`. They are listed on the page of each extra, starting from [Extras](/docs/extras/overview).