Design Tokens

Design tokens are the fundamental design decisions of the NYS Design System — colors, spacing, typography, radii, shadows — stored as named values. Instead of hardcoding #154973 for a button background, a component references --nys-color-theme. When the agency theme changes or the design system updates its palette, every component that uses that token updates automatically.

Tokens are the mechanism that connects design decisions to working code. They are what make it possible to restyle an entire application by switching a single data-theme attribute.

Token Architecture

NYSDS tokens are organized in three layers. Each layer serves a different purpose, and understanding them will help you choose the right token for your CSS.

Primitive tokens

Raw values with no opinion about how they should be used. These are the building blocks — full color palettes, a type scale, spacing increments.

--nys-color-neutral-900: #1b1b1b;
--nys-color-state-blue-700: #154973;
--nys-font-size-md: 1rem;
--nys-space-200: 1rem;

Do not use primitive tokens directly in your stylesheets. Primitive tokens are the raw material that semantic and theme tokens are built from. If you reference --nys-color-state-blue-700 in your CSS, that value will not change when an agency theme is applied. Use semantic or theme tokens instead.

Semantic (applied) tokens

Purpose-driven tokens that describe what a value is used for, not what the value is. These are the tokens you should use in your CSS.

--nys-color-text: #1b1b1b;          /* Primary text color */
--nys-color-link: #004dd1;          /* Default link color */
--nys-color-success: #1e752e;       /* Success state indicator */
--nys-color-surface: #ffffff;       /* Default page background */
--nys-color-focus: #004dd1;         /* Focus ring color */

Semantic tokens point to primitive tokens under the hood. --nys-color-text resolves to --nys-color-neutral-900 which resolves to #1b1b1b. But because your code references the semantic name, the system can change the underlying value without breaking your styles.

NYSDS semantic tokens cover colors for text, links, surfaces, status states (success, info, warning, danger, emergency), ink, focus, and base UI elements. Each category includes intensity variants — default, weak, strong — so you can express visual hierarchy without picking arbitrary colors.

Theme tokens

A special set of semantic tokens that change based on the active agency theme. When you apply data-theme="environment" to your page, every --nys-color-theme-* token remaps to the Environment color palette.

/* Default theme (NY.gov) */
--nys-color-theme: #154973;         /* State Blue 700 */

/* With data-theme="environment" */
--nys-color-theme: #233f2b;         /* Environment Green 700 */

Theme tokens use a seven-step intensity scale — faint, weaker, weak, mid, default (no suffix), strong, stronger — giving every component the range it needs for hover states, backgrounds, text, and borders. See Agency Themes for the full list of available themes and how to apply them.

Which Tokens to Use

Use semantic tokens for anything that has a defined purpose in the system:

/* Correct — adapts to themes and future system updates */
.card-header {
  color: var(--nys-color-text);
  background-color: var(--nys-color-theme-faint);
  border-bottom: var(--nys-border-width-sm) solid var(--nys-color-base);
  padding: var(--nys-space-200) var(--nys-space-300);
}

/* Wrong — bypasses the token system, ignores themes */
.card-header {
  color: #1b1b1b;
  background-color: #f7fafd;
  border-bottom: 1px solid #62666a;
  padding: 1rem 1.5rem;
}

Use theme tokens (--nys-color-theme-*) when a color should change with the agency theme — branded headings, accent backgrounds, active states. Use non-theme semantic tokens (--nys-color-text, --nys-color-success, --nys-color-link) for colors that should stay consistent regardless of theme — body text, status indicators, focus rings.

Use spacing, size, and radius tokens to keep your layouts aligned with the system's scale:

.benefits-form-section {
  margin-bottom: var(--nys-space-600);
  border-radius: var(--nys-radius-md);
  padding: var(--nys-space-400);
}

Reverse and Dark Surfaces

NYSDS provides reverse-variant tokens for content on dark backgrounds — footers, dark hero sections, inverted cards. These are semantic tokens, not a separate "dark mode":

.agency-footer {
  background-color: var(--nys-color-surface-reverse);  /* Dark background */
  color: var(--nys-color-text-reverse);                 /* White text */
}

.agency-footer a {
  color: var(--nys-color-link-reverse);                 /* Light link color */
}

Reverse tokens are designed for sections within a light-mode page that need dark backgrounds. They are not a system-wide dark mode toggle. The token names make the intent clear: -reverse means "use this on a dark surface."

How Components Use Tokens

Every NYSDS component references semantic and theme tokens internally. A button uses --nys-color-theme for its background. An alert uses --nys-color-danger for error states. A text input uses --nys-color-text for its value.

Components also expose CSS custom properties that let you override specific values without breaking the token chain. These component-level custom properties are documented on each component page.

For details on how to install the stylesheets that deliver these tokens to your application, see Get Started as a Developer. For a deeper look at the CSS framework that bundles tokens with resets, typography, and utilities, see Styles Framework.

Token Reference

Ready to browse all tokens? The interactive token reference lets you see every token in the system with live previews.