Design Tokens

Design tokens are the shared values that define the visual language of the Portland Design System — colors, spacing, typography, and breakpoints. They are the single source of truth for all design decisions, ensuring consistency across every product built on this system.

Tokens are managed with Style Dictionary and published as the @cityofportland/design-tokens npm package.

Installation

pnpm add @cityofportland/design-tokens

Usage

CSS Custom Properties

The primary way to use tokens is via CSS custom properties. Import the base stylesheet to get all default tokens:

@import "@cityofportland/design-tokens/css/base.css";

Tokens are then available as CSS variables on :root:

.my-element {
  color: var(--color-primary-vivid);
  padding: var(--scale-400);
}

Variant stylesheets

Additional stylesheets are available for dark mode and large-breakpoint overrides. Apply them to a selector or media query as needed:

/* Dark color theme */
@import "@cityofportland/design-tokens/css/dark.css";

/* Extra-large breakpoint scale overrides */
@import "@cityofportland/design-tokens/css/xl.css";

/* Raw primitive values (no semantic mapping) */
@import "@cityofportland/design-tokens/css/primitives.css";

JavaScript / TypeScript

Token values are also exported as ES module constants:

import { COLOR_PRIMARY_VIVID, SCALE_400 } from "@cityofportland/design-tokens";

Or import a specific variant file:

import { COLOR_PRIMARY_VIVID } from "@cityofportland/design-tokens/js/base.js";

JSON

If you need the raw token data (e.g. to feed a design tool or generate documentation):

import baseTokens from "@cityofportland/design-tokens/json/base.json" assert { type: "json" };

Storybook

Explore all token values visually in the Token Storybook.

How tokens are updated

Tokens are managed in Zeroheight. When a designer publishes changes there, a GitHub Action automatically processes the incoming token files and opens a pull request with the updated dist/ output. Once merged, a new version is published to npm.

See the design-tokens README for full details on the build pipeline.