> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olonjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OlonJS design tokens: colors, typography, and layout values

> Complete reference for OlonJS design tokens in theme.json: color semantics, typography families, border radius, spacing dimensions, and z-index layers.

All visual design in OlonJS is controlled by tokens in `src/data/config/theme.json`. Every color, typeface, radius, spacing value, and z-index layer used across your site derives from this single file. This page is the complete reference for every token available.

***

## Color tokens

Color tokens live under `tokens.colors`. Every token maps to a semantic role rather than a raw hue, so you can retheme your site by changing values here without touching any component code.

The default palette is optimized for **dark mode**. Light mode overrides are described in [Light mode overrides](#light-mode-overrides) below.

| Token | Default (dark) | Description |
| - | - | - |
| `background` | `#101014` | Page canvas — the outermost background color |
| `foreground` | `#ece9e2` | Default body text color |
| `card` | `#17171d` | Surface color for card and panel components |
| `card-foreground` | `#ece9e2` | Text color used inside cards |
| `elevated` | `#1d1d25` | Slightly raised surface, one step above `card` |
| `overlay` | `#22222b` | Modal and drawer backdrop surface |
| `primary` | `#e0745c` | Brand accent — buttons, links, highlights |
| `primary-foreground` | `#14100e` | Text rendered on top of `primary` surfaces |
| `primary-light` | `#eb9480` | Lighter tint of the primary color for hover states |
| `primary-dark` | `#b85a45` | Darker shade of the primary color for active states |
| `accent` | `#9db4e8` | Secondary accent color for decorative highlights |
| `accent-foreground` | `#10131c` | Text rendered on top of `accent` surfaces |
| `secondary` | `#23232c` | Secondary surface — subtle section backgrounds |
| `secondary-foreground` | `#d8d5cd` | Text color on secondary surfaces |
| `muted` | `#1b1b22` | Muted surface for disabled or low-emphasis areas |
| `muted-foreground` | `#97948c` | Low-emphasis text — captions, placeholders, metadata |
| `border` | `#26262f` | Default border color for dividers and component edges |
| `border-strong` | `#34343f` | Stronger border for focus rings and table rules |
| `input` | `#1d1d25` | Background color for form input fields |
| `ring` | `#e0745c` | Focus ring color — matches `primary` by default |
| `destructive` | `#e5484d` | Color for destructive actions and error states |
| `destructive-foreground` | `#fff0f0` | Text on destructive/error surfaces |
| `success` | `#4cc38a` | Color for success states and positive feedback |
| `success-foreground` | `#06130c` | Text on success surfaces |
| `warning` | `#f5b944` | Color for warning states and cautionary feedback |
| `warning-foreground` | `#171105` | Text on warning surfaces |
| `info` | `#6ba6f5` | Color for informational states and neutral callouts |
| `info-foreground` | `#081321` | Text on info surfaces |

***

## Light mode overrides

`tokens.modes.light.colors` overrides any color token when the user's system or site preference is set to **light mode**. You only need to list the tokens whose values differ from the dark defaults — unlisted tokens fall through to their dark-mode values.

<Expandable title="Light mode color table">
  | Token | Light mode value | Description |
  | - | - | - |
  | `background` | `#faf8f4` | Warm off-white page canvas |
  | `foreground` | `#1d1c1a` | Near-black body text |
  | `card` | `#ffffff` | White card surface |
  | `card-foreground` | `#1d1c1a` | Dark text inside cards |
  | `elevated` | `#f2efe8` | Slightly warm elevated surface |
  | `overlay` | `#e8e4da` | Warm overlay surface |
  | `primary` | `#c1543c` | Darker, higher-contrast primary for light backgrounds |
  | `primary-foreground` | `#fdf6f3` | Light text on primary surfaces |
  | `primary-light` | `#d4765f` | Lighter primary tint |
  | `primary-dark` | `#9c4230` | Darker primary shade |
  | `accent` | `#4a66b0` | Deeper accent for light backgrounds |
  | `accent-foreground` | `#f5f7fd` | Light text on accent surfaces |
  | `secondary` | `#ece8df` | Warm light secondary surface |
  | `secondary-foreground` | `#37352f` | Dark text on secondary surfaces |
  | `muted` | `#f0ede5` | Light warm muted surface |
  | `muted-foreground` | `#6d6a61` | Mid-tone low-emphasis text |
  | `border` | `#e0dcd1` | Subtle warm border |
  | `border-strong` | `#c9c4b6` | Stronger warm border |
  | `input` | `#ffffff` | White input background |
  | `ring` | `#c1543c` | Matches light-mode `primary` |
  | `destructive` | `#d33c41` | Adjusted destructive red |
  | `destructive-foreground` | `#fff5f5` | Light text on destructive surfaces |
  | `success` | `#1f7a4d` | Dark green for light backgrounds |
  | `success-foreground` | `#f0fbf5` | Light text on success surfaces |
  | `warning` | `#a86a0b` | Dark amber for light backgrounds |
  | `warning-foreground` | `#fffaf0` | Light text on warning surfaces |
  | `info` | `#2563c4` | Dark blue for light backgrounds |
  | `info-foreground` | `#f0f6ff` | Light text on info surfaces |
</Expandable>

To add or change a light mode override, edit `tokens.modes.light.colors` in `src/data/config/theme.json`:

```json src/data/config/theme.json theme={null}
{
  "tokens": {
    "modes": {
      "light": {
        "colors": {
          "primary": "#c1543c",
          "background": "#faf8f4"
        }
      }
    }
  }
}
```

***

## Typography tokens

Typography tokens live under `tokens.typography`. They control the font families used for body text, monospace contexts, display headings, and the site wordmark.

| Token | Default | Description |
| - | - | - |
| `fontFamily.primary` | `'Instrument Sans', system-ui, sans-serif` | Default font for body copy, UI labels, and most running text |
| `fontFamily.mono` | `'JetBrains Mono', monospace` | Monospace font for code blocks, inline code, and technical strings |
| `fontFamily.display` | `'Bricolage Grotesque', system-ui, sans-serif` | Display font for large headings and hero text |
| `wordmark.fontFamily` | `'Bricolage Grotesque', system-ui, sans-serif` | Font family used to render the site wordmark in the header and footer |
| `wordmark.weight` | `"800"` | Font weight for the wordmark — extra-bold by default |

<Note>
  OlonJS does not automatically load custom web fonts. Add your font imports to your global CSS or `_document` file and then reference them here by name.
</Note>

***

## Border radius

Border radius tokens live under `tokens.borderRadius`. Use these tokens in your custom components to stay visually consistent with the system.

| Token | Value | Usage |
| - | - | - |
| `sm` | `4px` | Subtle rounding for tags, badges, and small chips |
| `md` | `8px` | Standard rounding for buttons and input fields |
| `lg` | `14px` | Card and panel corners |
| `xl` | `20px` | Large containers and modal dialogs |
| `full` | `9999px` | Fully pill-shaped elements |

***

## Spacing

Spacing tokens live under `tokens.spacing`. They define the key layout dimensions used throughout the site shell.

| Token | Value | Description |
| - | - | - |
| `container-max` | `1200px` | Maximum width of the main content container |
| `section-y` | `96px` | Default vertical padding applied to page sections |
| `header-h` | `80px` | Fixed height of the global header bar |
| `sidebar-w` | `240px` | Width of the Studio sidebar and any page sidebars |

***

## Z-index

Z-index tokens live under `tokens.zIndex`. They establish a consistent stacking order so components never accidentally appear above layers they should sit behind.

| Token | Value | Description |
| - | - | - |
| `base` | `0` | Default document flow — no explicit stacking |
| `elevated` | `10` | Slightly raised elements like sticky table headers |
| `dropdown` | `100` | Dropdown menus and autocomplete panels |
| `sticky` | `200` | Sticky header and floating toolbars |
| `overlay` | `300` | Full-screen overlay backdrops |
| `modal` | `400` | Modal dialogs and drawers |
| `toast` | `500` | Toast notifications — always on top |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.