Design tokens

The machine-readable source of truth for the Pulumi design tokens is 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 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: 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; 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 file — the DESIGN.md format 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 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 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 on GitHub (@pulumi/design-tokens)
Stable download: /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 (https://brand.pulumi.com/mcp)
This page is included in /llms.txt and /llms-full.txt, and its markdown is at /foundations/design-tokens.md