# Design tokens

**Work in progress:**

The Pulumi Design System token set is early and expanding. Higher-level tokens — semantic theme roles, component colors (buttons, cards, inputs), radius, and shadows — will land in [`pulumi/pulumi-design-system`](https://github.com/pulumi/pulumi-design-system) over time. The current typography tokens (beyond the root typefaces) and spacing tokens are Pulumi Cloud-specific; values for marketing and docs are coming soon. This page tracks what the repo publishes today.

The machine-readable source of truth for the Pulumi design tokens is [`pulumi/pulumi-design-system`](https://github.com/pulumi/pulumi-design-system) (`@pulumi/design-tokens`), shared across Pulumi properties. It publishes the core layers documented on this page: color primitives (light + dark), per-palette semantic roles, shared color semantics, typography, and spacing. The same tokens also ship as a [`design.md`](#designmd) file (paired with usage rules, for AI agents generating UI).

  
  pulumi-design-system

  
  design.md

## Color primitives

The canonical reference for color is the [color system](/identity/color/): 8 palettes × 11 steps (50–950), published as `primitives.json` (light) and `primitives-dark.json` (dark, the same scale inverted by position). A token keeps the same step reference in both modes and resolves against the mode's palette — `{gray.200}` resolves to `#e0dfe2` in light and `#56535a` in dark.

Utility colors sit outside the palettes and do not flip:

| Token | Value | Notes |
| ----- | ----- | ----- |
| `white` | `#ffffff` | |
| `black` | `#000000` | |
| `utility.service-black` | `#1f1b21` | The brand's darkest neutral — the dark-mode page background. Not a text color; body text is `{gray.950}`. |

## Per-palette roles

Every palette carries the same four semantic roles (`palette-semantics.json`). For violet — the primary brand color — they resolve to:

| Role | Step | Violet | Notes |
| ---- | ---- | ------ | ----- |
| `primary` | 700 | `#5a30c5` | Use for the majority of color needs |
| `accent` | 500 | `#9077f3` | Emphasis and visual interest |
| `muted` | 200 | `#dedbff` | Secondary elements and bolder backgrounds |
| `background` | 50 | `#f5f5ff` | Tinted backgrounds and surfaces |

In dark mode the same references resolve against the inverted palette, so `primary` lifts to Violet 300 (`#c3bdff`), `muted` deepens to Violet 800 (`#492e8e`), and so on.

## Shared color semantics

Cross-property color aliases (`semantic.json`). Each references a primitive step, so the same token resolves per mode:

| Token | Reference | Light | Dark |
| ----- | --------- | ----- | ---- |
| `brand-violet` | `{violet.700}` | `#5a30c5` | `#c3bdff` |
| `brand-orange` | `{orange.500}` | `#f96c0b` | `#f96c0b` |
| `brand-blue` | `{blue.700}` | `#1e57eb` | `#a3d0ff` |
| `brand-yellow` | `{yellow.500}` | `#f49709` | `#f49709` |
| `success` | `{green.800}` | `#165a31` | `#b6fbce` |
| `failure` | `{red.800}` | `#96171e` | `#ffc7ca` |
| `warning` | `{yellow.800}` | `#933d0d` | `#fde38a` |
| `info` | `{blue.800}` | `#1e47c2` | `#cce4ff` |
| `disabled` | `{gray.500}` | `#9997a0` | `#9997a0` |
| `foreground` | `{gray.950}` | `#2e2932` | `#fafafa` |
| `foreground-muted` | `{gray.700}` | `#6a6675` | `#cbcace` |
| `text-body` | `{gray.950}` | `#2e2932` | `#fafafa` |
| `text-heading` | `{gray.700}` | `#6a6675` | `#cbcace` |
| `text-detail` | `{gray.800}` | `#56535a` | `#e0dfe2` |
| `text-sub-heading` | `{gray.800}` | `#56535a` | `#e0dfe2` |
| `background` | — (literal) | `#ffffff` | light-mode anchor; the dark page background is `utility.service-black` |

Steps at the 500 pivot (`brand-orange`, `brand-yellow`, `disabled`) resolve to the same value in both modes. Use the status tokens only for their meaning, never as decoration.

## Typography

Font families, weights, and line-heights from `typography.json`. The font families are brand-wide. Everything else in this section — the weights, line-heights, and type ramp — is Pulumi Cloud-specific today; values for marketing and docs are coming soon.

| Token | Value |
| ----- | ----- |
| `fontFamily.primary` | `Inter, sans-serif` |
| `fontFamily.code` | `Monaspace Neon, menlo, consolas, ui-monospace, monospace` |
| `fontWeight.normal` | 400 |
| `fontWeight.bold` | 600 |
| `fontWeight.code` | 500 |
| `lineHeight.body` | 1.5 |
| `lineHeight.display` | 1.2 |

The type ramp (`fontSize`):

| Group | Sizes |
| ----- | ----- |
| `display` | `xxlarge` 28px · `xlarge` 20px · `large` 16px · `medium` 15px · `small` 14px · `xsmall` 12px |
| `heading` | `h1` 24px · `h2` 20px · `h3` 18px |
| `body` | `xlarge` 18px · `large` 16px · `medium` 14px · `small` 12px · `small-v2` 11px · `xsmall` 10px |
| `code` | `large` 14px · `medium` 13px · `small` 12px |

The file also carries Material-compatible levels for Material-based apps (Pulumi Cloud) — don't use those for brand surfaces. For the brand's typographic usage rules — heading tracking, OpenType features, when mono steps outside code — see [Typography](/identity/typography/); those rules win for marketing, docs, and brand work.

## Spacing

The spacing scale, semantic spacing, and dialog widths from `spacing.json`. These are Pulumi Cloud-specific today; values for marketing and docs are coming soon.

| Token | Value |
| ----- | ----- |
| `scale.xs` | `2px` |
| `scale.s` | `4px` |
| `scale.m` | `8px` |
| `scale.l` | `12px` |
| `scale.xl` | `16px` |
| `scale.2x` | `24px` |
| `scale.3x` | `32px` |
| `scale.4x` | `48px` |

| Semantic token | Reference | Value |
| -------------- | --------- | ----- |
| `semantic.card-margin-bottom` | `{scale.3x}` | `32px` |
| `semantic.hud-row-gap` | `{scale.m}` | `8px` |

| Dialog width | Value |
| ------------ | ----- |
| `dialogWidth.small` | `632px` |
| `dialogWidth.medium` | `752px` |
| `dialogWidth.large` | `872px` |

## design.md

The core tokens are also published as a [`design.md`](/brand-assets/design.md) file — the [DESIGN.md format](https://github.com/google-labs-code/design.md) for describing a design system in a single self-contained document that AI agents can read and apply when generating UI.

Both describe the same tokens, but for different consumers. The [`pulumi-design-system`](https://github.com/pulumi/pulumi-design-system) JSON files are the **normative token data** — canonical hex values and shared semantics, built to feed token pipelines. `design.md` distills them and pairs them with the **rules for applying them** — color hierarchy, type by purpose, and spacing rhythm. It's the one file to hand a coding agent so it generates on-brand design in a single pass, rather than guessing.

It's a distillation, not the full guidelines. For anything it doesn't cover, agents should reach for the [MCP server](/mcp-server/) or the guidelines pages.

  
  design.md

## For AI agents

These tokens are available the same way as the rest of the brand system:

- **Core tokens (source of truth):** [`pulumi/pulumi-design-system`](https://github.com/pulumi/pulumi-design-system) on GitHub (`@pulumi/design-tokens`)
- **Stable download:** [`/brand-assets/design.md`](/brand-assets/design.md) (DESIGN.md format)
- **MCP:** `brand://tokens` / `get_design_tokens` (core tokens) and the `design-tokens` guideline section (this page) on the [brand MCP server](/mcp-server/) (`https://brand.pulumi.com/mcp`)
- This page is included in [`/llms.txt`](/llms.txt) and [`/llms-full.txt`](/llms-full.txt), and its markdown is at [`/foundations/design-tokens.md`](/foundations/design-tokens.md)