# Builder.io Design System

> Machine-readable reference for LLMs, engineers, and designers.  
> Canonical source: https://www.builder.io/brand  
> Route: /brand — Brand assets hub with logos, colors, typography, and icons.

---

## Visual Theme

Builder.io uses a dark-first design language built on warm near-blacks, cool accent blues, and the Geist type family. The aesthetic is modern, technical, and clean.

- **Background**: Near-black `#0A0A0A` (not pure black)
- **Primary text**: Off-white `#FAF9F5` (not pure white)
- **Accent**: Electric cyan `#01C8F1`
- **Font**: Geist (sans-serif), Geist Mono (monospace)

---

## Design Token System

All tokens use the `--b-` prefix and are scoped to `.builder-brand-tokens`. The design system is opt-in — apply the class to any container to activate tokens.

### Semantic Color Tokens

Semantic tokens use the `--b-` prefix and map to primitive values. Token names follow `--b-{group}-{role}`.

**bg**

| Name           | Token                | Hex         |
| -------------- | -------------------- | ----------- |
| bg/page        | `--b-bg-page`        | `#0A0A0A`   |
| bg/surface     | `--b-bg-surface`     | `#0A0A0A`   |
| bg/raised      | `--b-bg-raised`      | `#0F0F0F`   |
| bg/prominent   | `--b-bg-prominent`   | `#1A1A1A`   |
| bg/translucent | `--b-bg-translucent` | `#0A0A0AE6` |
| bg/alternative | `--b-bg-alternative` | `#00161B`   |

**text**

| Name           | Token                | Hex       |
| -------------- | -------------------- | --------- |
| text/primary   | `--b-text-primary`   | `#FAF9F5` |
| text/secondary | `--b-text-secondary` | `#9A9997` |
| text/muted     | `--b-text-muted`     | `#5E5E5E` |
| text/highlight | `--b-text-highlight` | `#E0E0D7` |
| text/link      | `--b-text-link`      | `#BEF0F5` |
| text/eyebrow   | `--b-text-eyebrow`   | `#01C8F1` |

**border**

| Name           | Token                | Hex         |
| -------------- | -------------------- | ----------- |
| border/default | `--b-border-default` | `#1A1A1A`   |
| border/subtle  | `--b-border-subtle`  | `#FFFFFF0D` |

**action**

| Name                    | Token                         | Hex           |
| ----------------------- | ----------------------------- | ------------- |
| action/primary/bg       | `--b-action-primary-bg`       | `#01C8F1`     |
| action/primary/hover    | `--b-action-primary-hover`    | `#00DFF6`     |
| action/primary/text     | `--b-action-primary-text`     | `#0A0A0A`     |
| action/primary/border   | `--b-action-primary-border`   | `#00DFF6`     |
| action/primary/effect   | `--b-action-primary-effect`   | `#01C8F166`   |
| action/secondary/bg     | `--b-action-secondary-bg`     | `transparent` |
| action/secondary/hover  | `--b-action-secondary-hover`  | `#1A1A1A`     |
| action/secondary/text   | `--b-action-secondary-text`   | `#FAF9F5`     |
| action/secondary/border | `--b-action-secondary-border` | `#5E5E5E`     |
| action/tab/bg           | `--b-action-tab-bg`           | `#0A0A0A`     |
| action/tab/bg-active    | `--b-action-tab-bg-active`    | `#00161B`     |
| action/tab/bg-hover     | `--b-action-tab-bg-hover`     | `#0F0F0F`     |
| action/tab/text         | `--b-action-tab-text`         | `#5E5E5E`     |
| action/tab/text-active  | `--b-action-tab-text-active`  | `#BEF0F5`     |
| action/tab/text-hover   | `--b-action-tab-text-hover`   | `#FAF9F5`     |
| action/tab/indicator    | `--b-action-tab-indicator`    | `#01C8F1`     |

### Color Primitives

Raw color scale. Semantic tokens reference these values. Token names follow `--c-{family}-{weight}`.

| Name            | Token                 | Hex         |
| --------------- | --------------------- | ----------- |
| Violet 400      | `--c-violet-400`      | `#A8C1FF`   |
| Blue 100        | `--c-blue-100`        | `#BEF0F5`   |
| Blue 200        | `--c-blue-200`        | `#7BE8F5`   |
| Blue 300        | `--c-blue-300`        | `#00DFF6`   |
| Blue 400        | `--c-blue-400`        | `#00D6F6`   |
| Blue 500        | `--c-blue-500`        | `#01C8F1`   |
| Blue 500 40%    | `--c-blue-500-40p`    | `#01C8F166` |
| Blue 600        | `--c-blue-600`        | `#009CCC`   |
| Blue 900        | `--c-blue-900`        | `#00161B`   |
| Green 400       | `--c-green-400`       | `#0FDFBA`   |
| Yellow 400      | `--c-yellow-400`      | `#DEC75F`   |
| Red 400         | `--c-red-400`         | `#FFA27D`   |
| Pink 400        | `--c-pink-400`        | `#FA9BF2`   |
| Neutral 50      | `--c-neutral-50`      | `#FAF9F5`   |
| Neutral 100     | `--c-neutral-100`     | `#E0E0D7`   |
| Neutral 200     | `--c-neutral-200`     | `#CAC9C6`   |
| Neutral 500     | `--c-neutral-500`     | `#9A9997`   |
| Neutral 600     | `--c-neutral-600`     | `#5E5E5E`   |
| Neutral 800     | `--c-neutral-800`     | `#2E2E2E`   |
| Neutral 900     | `--c-neutral-900`     | `#1A1A1A`   |
| Neutral 925     | `--c-neutral-925`     | `#0F0F0F`   |
| Neutral 950     | `--c-neutral-950`     | `#0A0A0A`   |
| Neutral 950 90% | `--c-neutral-950-90p` | `#0A0A0AE6` |
| White 5%        | `--c-white-5p`        | `#FFFFFF0D` |

### Typography Tokens

Fonts: **Geist** (sans, headings/body) and **Geist Mono** (labels/code).
Token names follow `--b-t-{category}-{scale}`. The full style notation includes a weight suffix: `-md` (Medium), `-rg` (Regular), `-sb` (SemiBold).

**Scale variables** (font-size only; responsive — desktop shown, mobile at `≤768px`):

| Token                  | Design notation    | Font       | Weight       | lh   | ls      | Desktop | Mobile |
| ---------------------- | ------------------ | ---------- | ------------ | ---- | ------- | ------- | ------ |
| `--b-t-heading-1`      | `t-heading/1-md`   | Geist      | 500 Medium   | 1.05 | -0.02em | 56px    | 32px   |
| `--b-t-heading-2`      | `t-heading/2-md`   | Geist      | 500 Medium   | 1.05 | -0.02em | 46px    | 28px   |
| `--b-t-heading-3`      | `t-heading/3-md`   | Geist      | 500 Medium   | 1.05 | -0.02em | 37px    | 24px   |
| `--b-t-heading-4`      | `t-heading/4-md`   | Geist      | 500 Medium   | 1.15 | -0.02em | 28px    | 22px   |
| `--b-t-heading-5`      | `t-heading/5-md`   | Geist      | 500 Medium   | 1.15 | -0.02em | 23px    | 19px   |
| `--b-t-heading-6`      | `t-heading/6-md`   | Geist      | 500 Medium   | 1.15 | -0.02em | 18px    | 16px   |
| `--b-t-paragraph-1`    | `t-paragraph/1-rg` | Geist      | 400 Regular  | 1.3  | —       | 18px    | 16px   |
| `--b-t-paragraph-2`    | `t-paragraph/2-rg` | Geist      | 400 Regular  | 1.4  | —       | 15px    | 15px   |
| `--b-t-paragraph-2-md` | `t-paragraph/2-md` | Geist      | 500 Medium   | 1.4  | —       | 15px    | 15px   |
| `--b-t-paragraph-3`    | `t-paragraph/3-rg` | Geist      | 400 Regular  | 1.4  | —       | 12px    | 12px   |
| `--b-t-label-1`        | `t-label/1-sb`     | Geist Mono | 600 SemiBold | 1.2  | +0.02em | 14px    | 14px   |
| `--b-t-label-2`        | `t-label/2-md`     | Geist Mono | 500 Medium   | 1.2  | +0.04em | 11px    | 11px   |

### Border Radius

| Design notation | Token             | Value    |
| --------------- | ----------------- | -------- |
| `radius/none`   | `--b-radius-none` | `0px`    |
| `radius/sm`     | `--b-radius-sm`   | `3px`    |
| `radius/md`     | `--b-radius-md`   | `6px`    |
| `radius/lg`     | `--b-radius-lg`   | `12px`   |
| `radius/full`   | `--b-radius-full` | `9999px` |

`--b-radius` (legacy alias for `--b-radius-md`) is kept for backwards compatibility.

### Spacing Scale

Spacing tokens use the `--spacing-{n}` pattern where the token key × 4px = base desktop value. Larger values compress on mobile.

| Design notation | Token          | Desktop | Mobile |
| --------------- | -------------- | ------- | ------ |
| `spacing/0`     | `--spacing-0`  | 0px     | 0px    |
| `spacing/1`     | `--spacing-1`  | 4px     | 4px    |
| `spacing/2`     | `--spacing-2`  | 8px     | 8px    |
| `spacing/3`     | `--spacing-3`  | 12px    | 12px   |
| `spacing/4`     | `--spacing-4`  | 16px    | 12px   |
| `spacing/5`     | `--spacing-5`  | 20px    | 16px   |
| `spacing/6`     | `--spacing-6`  | 24px    | 20px   |
| `spacing/8`     | `--spacing-8`  | 32px    | 24px   |
| `spacing/10`    | `--spacing-10` | 40px    | 24px   |
| `spacing/12`    | `--spacing-12` | 48px    | 24px   |
| `spacing/16`    | `--spacing-16` | 64px    | 24px   |
| `spacing/20`    | `--spacing-20` | 80px    | 32px   |
| `spacing/24`    | `--spacing-24` | 96px    | 32px   |
| `spacing/30`    | `--spacing-30` | 120px   | 72px   |
| `spacing/35`    | `--spacing-35` | 150px   | 88px   |
| `spacing/50`    | `--spacing-50` | 200px   | 80px   |

### Button Tokens

| Token                      | Value                       |
| -------------------------- | --------------------------- |
| `--b-btn-primary-bg`       | `#FAF9F5`                   |
| `--b-btn-primary-fg`       | `#0A0A0A`                   |
| `--b-btn-primary-hover`    | `#E2E1DD`                   |
| `--b-btn-hover-bg`         | `rgba(255, 255, 255, 0.08)` |
| `--b-btn-sec-hover-border` | `#CAC9C6`                   |

### Toggle Tokens

| Token                  | Value     |
| ---------------------- | --------- |
| `--b-toggle-active-bg` | `#FAF9F5` |
| `--b-toggle-active-fg` | `#0A0A0A` |

### Gradient

```css
--b-gradient-blue: linear-gradient(
  90deg,
  #18b4f4 0%,
  #19b9f5 6.25%,
  #1bbdf5 12.5%,
  #1cc2f6 18.75%,
  #1ec7f7 25%,
  #1fcbf7 31.25%,
  #21d0f8 37.5%,
  #22d5f9 43.75%,
  #24d9f9 50%,
  #25defa 56.25%,
  #26e3fb 62.5%,
  #28e8fc 68.75%,
  #29ecfc 75%,
  #2bf1fd 81.25%,
  #2cf6fe 87.5%,
  #2efafe 93.75%,
  #2fffff 100%
);
```

Apply as background with `.blue-gradient`.  
Apply as clipped text fill with `.blue-gradient-text`.

---

## Components

See live showcase: https://www.builder.io/brand/components

### Buttons

Six variants. All use `border-radius: var(--b-radius-md)` (6px) and Geist Mono SemiBold for labels.
Focus state ring: `outline: 2px solid var(--b-text-primary)` (white `#FAF9F5`).

| Variant             | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| CTA                 | Cyan fill + diagonal arrow icon. Highest emphasis.                      |
| Primary             | Cyan fill, label only. Standard primary action.                         |
| Primary Alternative | Near-white fill (`--b-text-primary`), dark text. Light-context primary. |
| Primary Icon        | Cyan fill, icon-only square (38×38px).                                  |
| Secondary           | Transparent bg, `--b-action-secondary-border` border, light text.       |
| Secondary Icon      | Transparent bg, border, icon-only square (38×38px).                     |

**CTA / Primary**

```css
background: var(--b-action-primary-bg); /* #01C8F1 */
color: var(--b-action-primary-text); /* #0A0A0A */
border: none;
/* hover */
background: var(--b-action-primary-hover); /* #00DFF6 */
box-shadow: 0 0 16px var(--b-action-primary-effect);
```

**Primary Alternative**

```css
background: var(--b-text-primary); /* #FAF9F5 */
color: var(--b-bg-page); /* #0A0A0A */
/* hover */
background: var(--c-neutral-100); /* #E0E0D7 */
```

**Secondary**

```css
background: var(--b-action-secondary-bg); /* transparent */
color: var(--b-action-secondary-text); /* #FAF9F5 */
border: 1px solid var(--b-action-secondary-border); /* #5E5E5E */
/* hover */
background: var(--b-action-secondary-hover); /* #1A1A1A */
border-color: var(--c-neutral-500); /* #9A9997 */
```

### Toggle / Segmented Control

```css
border: 1px solid var(--b-border-raised);
border-radius: var(--b-radius-none);
overflow: hidden;
```

Active option: `background: var(--b-toggle-active-bg)` (`#FAF9F5`), `color: var(--b-toggle-active-fg)` (`#0A0A0A`)  
Inactive: `color: var(--b-text-secondary)`  
Hover (inactive): `background: var(--b-btn-hover-bg)`

---

## Layout

- **Topbar**: 50px tall, sticky, `background: var(--b-bg-page)`, `border-bottom: 1px solid var(--b-border-default)`
- **Left sidebar**: 220px wide, sticky, `height: calc(100vh - 50px)`, hidden below `900px`
- **Right sidebar**: 192px wide, sticky, "On this page" navigation, hidden below `1140px`
- **Main content**: flex 1, padding `48px 48px 96px`

### Pages

| Route               | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `/brand`            | Logo, colors, typography, icons, spacing, radius         |
| `/brand/components` | Component showcase (buttons, future: inputs, tabs, etc.) |

Anchor sections use `scroll-margin-top: 50px` to clear the sticky topbar:

- `#builder-logo` — Logo download
- `#colors` — Color palette
- `#typography` — Type scale
- `#icons` — Icon library
- `#spacing` — Spacing scale
- `#radius` — Border radius
- `#buttons` — Button variants (on `/brand/components`)

---

## Icons

All icons are from `@tabler/icons-react`. Use outlined variants only — no `*Filled` icons.  
Default stroke width: `1.5`. Available on the /brand page with search, copy-as-JSX, and copy-as-SVG.

---

## Do's and Don'ts

### Do

- Use `--b-accent` (`#01C8F1`) for interactive elements, links, and highlights
- Use `--b-text` (`#FAF9F5`) for primary body text
- Use `--b-text-secondary` for supporting copy
- Use `--b-font-sans` (Geist) for all UI text
- Use `--b-font-mono` (Geist Mono) for code, tokens, and technical strings
- Use `border-radius: var(--b-radius)` on buttons, `var(--b-radius-none)` on everything else

### Don't

- Do not use pure black (`#000`) or pure white (`#FFF`) — use `#0A0A0A` and `#FAF9F5`
- Do not approximate accent colors — use exact hex values
- Do not use icon fills (`*Filled` variants) — use outlined Tabler icons only
- Do not modify Builder logos or wordmarks

---

## Appendix — Full Token CSS

```css
.builder-brand-tokens {
  /* Fonts */
  --b-font-sans: 'Geist', system-ui, sans-serif;
  --b-font-mono: 'Geist Mono', monospace;

  /* bg */
  --b-bg-page: #0a0a0a;
  --b-bg-surface: #0a0a0a;
  --b-bg-raised: #0f0f0f;
  --b-bg-prominent: #1a1a1a;
  --b-bg-translucent: #0a0a0ae6;
  --b-bg-alternative: #00161b;

  /* text */
  --b-text-primary: #faf9f5;
  --b-text-secondary: #9a9997;
  --b-text-muted: #5e5e5e;
  --b-text-highlight: #e0e0d7;
  --b-text-link: #bef0f5;
  --b-text-eyebrow: #01c8f1;

  /* border */
  --b-border-default: #1a1a1a;
  --b-border-subtle: #ffffff0d;

  /* action */
  --b-action-primary-bg: #01c8f1;
  --b-action-primary-hover: #00dff6;
  --b-action-primary-text: #0a0a0a;
  --b-action-primary-border: #00dff6;
  --b-action-primary-effect: #01c8f166;
  --b-action-secondary-bg: transparent;
  --b-action-secondary-hover: #1a1a1a;
  --b-action-secondary-text: #faf9f5;
  --b-action-secondary-border: #5e5e5e;
  --b-action-tab-bg: #0a0a0a;
  --b-action-tab-bg-active: #00161b;
  --b-action-tab-bg-hover: #0f0f0f;
  --b-action-tab-text: #5e5e5e;
  --b-action-tab-text-active: #bef0f5;
  --b-action-tab-text-hover: #faf9f5;
  --b-action-tab-indicator: #01c8f1;

  /* Color primitives */
  --c-violet-400: #a8c1ff;
  --c-blue-100: #bef0f5;
  --c-blue-200: #7be8f5;
  --c-blue-300: #00dff6;
  --c-blue-400: #00d6f6;
  --c-blue-500: #01c8f1;
  --c-blue-500-40p: #01c8f166;
  --c-blue-600: #009ccc;
  --c-blue-900: #00161b;
  --c-green-400: #0fdfba;
  --c-yellow-400: #dec75f;
  --c-red-400: #ffa27d;
  --c-pink-400: #fa9bf2;
  --c-neutral-50: #faf9f5;
  --c-neutral-100: #e0e0d7;
  --c-neutral-200: #cac9c6;
  --c-neutral-500: #9a9997;
  --c-neutral-600: #5e5e5e;
  --c-neutral-800: #2e2e2e;
  --c-neutral-900: #1a1a1a;
  --c-neutral-925: #0f0f0f;
  --c-neutral-950: #0a0a0a;
  --c-neutral-950-90p: #0a0a0ae6;
  --c-white-5p: #ffffff0d;

  /* Border radius */
  --b-radius: 6px;
  --b-radius-none: 0px;
  --b-radius-sm: 3px;
  --b-radius-md: 6px;
  --b-radius-lg: 12px;
  --b-radius-full: 9999px;

  /* Buttons */
  --b-btn-primary-bg: #faf9f5;
  --b-btn-primary-fg: #0a0a0a;
  --b-btn-primary-hover: #e2e1dd;
  --b-btn-hover-bg: rgba(255, 255, 255, 0.08);
  --b-btn-sec-hover-border: #cac9c6;

  /* Toggles */
  --b-toggle-active-bg: #faf9f5;
  --b-toggle-active-fg: #0a0a0a;

  /* Typography — desktop */
  --b-t-heading-1: 56px;
  --b-t-heading-2: 46px;
  --b-t-heading-3: 37px;
  --b-t-heading-4: 28px;
  --b-t-heading-5: 23px;
  --b-t-heading-6: 18px;
  --b-t-paragraph-1: 18px;
  --b-t-paragraph-2: 15px;
  --b-t-paragraph-2-md: 15px;
  --b-t-paragraph-3: 12px;
  --b-t-label-1: 14px;
  --b-t-label-2: 11px;
}

@media (max-width: 768px) {
  .builder-brand-tokens {
    --b-t-heading-1: 32px;
    --b-t-heading-2: 28px;
    --b-t-heading-3: 24px;
    --b-t-heading-4: 22px;
    --b-t-heading-5: 19px;
    --b-t-heading-6: 16px;
    --b-t-paragraph-1: 16px;
  }
}
```

---

## Appendix B - Builder Logo SVG

### Icon (116x130)

```svg
<svg width="116" height="130" viewBox="0 0 116 130" fill="none" xmlns="http://www.w3.org/2000/svg">
  <path d="M115.14 39C115.14 17.36 97.58 0 76.14 0H10.27C4.58002 0 0 4.62002 0 10.27C0 20.79 22.2899 28.78 22.2899 65C22.2899 101.22 0 109.21 0 119.73C0 125.38 4.58002 130 10.27 130H76.14C97.58 130 115.14 112.64 115.14 91C115.14 75.1 105.59 65.41 105.21 65C105.58 64.59 115.14 54.9 115.14 39ZM13.58 11.1504H76.14C83.58 11.1504 90.58 14.0501 95.84 19.3101C101.1 24.5701 104 31.5703 104 39.0103C104 46.4503 101.26 53.0102 96.38 58.1602L13.59 11.1504H13.58ZM95.83 110.7C90.57 115.96 83.57 118.86 76.13 118.86H13.5699L96.36 71.8501C101.24 77.0001 103.98 83.8 103.98 91C103.98 98.2 101.08 105.44 95.8199 110.7H95.83ZM25.7 99.1602C26.36 97.7802 33.4199 84.08 33.4199 65C33.4199 45.92 26.36 32.2203 25.7 30.8403L85.86 65L25.7 99.1602Z" fill="white"/>
</svg>
```

Change `fill="white"` to `fill="black"` for light-background use.

### Wordmark (608x130)

Download the wordmark SVG from https://www.builder.io/brand - use the Download SVG button with the Wordmark asset type selected.

---

_Last updated: 2025. Always verify token values against the live /brand page._