Imported from pulumi/pulumi-design-system (AGENTS.md). Install upstream with npx skills add pulumi/pulumi-design-system. Copyright stays with the author.

AGENTS.md — @pulumi/design-tokens

Guide for AI agents and contributors working in this repo.

Quick start

Prefer the bundled import when you need multiple token layers:

import tokens from "@pulumi/design-tokens/tokens/core/tokens.json";

const { primitives, primitivesDark, semantic, paletteSemantics, typography, spacing } = tokens;

Individual files remain available for tree-shaking or targeted updates:

import primitives from "@pulumi/design-tokens/tokens/core/primitives.json";
import primitivesDark from "@pulumi/design-tokens/tokens/core/primitives-dark.json";
import semantic from "@pulumi/design-tokens/tokens/core/semantic.json";
import paletteSemantics from "@pulumi/design-tokens/tokens/core/palette-semantics.json";
import typography from "@pulumi/design-tokens/tokens/core/typography.json";
import spacing from "@pulumi/design-tokens/tokens/core/spacing.json";

Token files (tokens/core/)

Reference syntax

Semantic tokens reference other tokens with {group.name}:

{ "success": "{green.800}", "text-body": "{gray.950}" }

• Color palettes: {family.shade} (e.g. {violet.700})
• Utility colors: {utility.name} (e.g. {utility.service-black})
• Spacing: {scale.name} (e.g. {scale.3x})

Dark mode

1. Use primitives-dark.json instead of primitives.json for palette hex values.
2. Resolve semantic.json tokens against dark primitives (same shade references, inverted hex).

Palette semantics (palette-semantics.json) use the same shade references in both modes. Mode-specific cases (e.g. brand-yellow hex, foreground/background flips) belong in consumer repos.

Editing workflow

1. Edit the relevant file under tokens/core/ (not tokens.json directly).
2. Run node scripts/sync-tokens.mjs to regenerate primitives-dark.json and tokens.json.
3. Bump version in package.json and add a CHANGELOG.md entry.

primitives-dark.json is derived from primitives.json by inverting shade positions (50↔950, 100↔900, …). Do not edit it by hand.

Consumers

Properties translate JSON to local SCSS, Tailwind, or CSS variables:

• pulumi-service — cmd/pulumi-design-system/scripts/build-color-tokens.mjs
• pulumi/docs — theme/scripts/build-color-theme.mjs

Property-specific tokens (console button palettes, docs docs-* colors) stay in consumer repos.

Brand reference

Color scale and palette semantics follow brand.pulumi.com/identity/color:

• 11 steps: 50–950 (950 is darkest in light mode, lightest in dark mode)
• Per palette: primary = 700, accent = 500, muted = 200, background = 50