@ds-gn/tokens

CSS variables, themes, Tailwind integration, and typed JavaScript values for the DS-GN Design System.

This package is the design-token dependency for @ds-gn/ui. Install it directly when your application imports the token stylesheets or customizes the DS-GN theme.

Public Beta · Website · Documentation · Token reference · Changelog

Install

Choose your package manager:

npm install @ds-gn/tokens
pnpm add @ds-gn/tokens
bun add @ds-gn/tokens

Using the DS-GN UI components? Install both packages as direct dependencies:

npm install @ds-gn/ui @ds-gn/tokens

Quick start

Load the public token definitions and the semantic light/dark theme, in that order:

@import '@ds-gn/tokens/public';
@import '@ds-gn/tokens/theme';

Using the DS-GN components as well? Add the custom-property registrations, which must be loaded on the document rather than inside a component:

@import '@ds-gn/tokens/properties';

Tokens are also available as typed named JavaScript exports:

import { breakpointLg, breakpointMd } from '@ds-gn/tokens';

console.log(breakpointMd); // "768px"
console.log(breakpointLg); // "1024px"

Import order matters

Each file builds on the one before it, and the last definition of a custom property wins:

1. /public sets every token's default value on :root.
2. /theme points the unsuffixed tokens at the light or dark value, keyed on [data-theme] or a .light / .dark class.
3. your overrides replace the defaults from step 1.

/properties is order-independent — it only registers types.

Light and dark

Themed tokens ship as a pair of override targets, --<name>-on-light and --<name>-on-dark, plus an unsuffixed name that components actually read. /theme is what connects them:

:root,
[data-theme='dark'],
.dark {
  --color-text-primary: var(--text-primary-on-dark);
}

[data-theme='light'],
.light {
  --color-text-primary: var(--text-primary-on-light);
}

Dark is the default. Switch by setting data-theme="light" on any element — the tokens inherit, so a subtree can carry a different theme than the page.

Tokens with no meaningful per-theme value — durations, easing curves, corner radii, and the deliberately dark terminal chrome — are single-value. They have one unsuffixed override target, no -on-* variants, and no entry in /theme.

Customize the theme

Override public CSS custom properties in your own stylesheet. Load the override file after the DS-GN token styles so your values win the cascade:

@import '@ds-gn/tokens/public';
@import '@ds-gn/tokens/theme';
@import './brand-overrides.css';

In brand-overrides.css, define the variants you want to change:

:root {
  /* Themed — override each side */
  --brand-on-light: oklch(55% 0.2 280);
  --brand-on-dark: oklch(70% 0.18 280);

  --accent-on-light: oklch(60% 0.25 30);
  --accent-on-dark: oklch(72% 0.22 30);

  /* Single-value — one override */
  --radius-button: 0.5rem;
  --duration-moderate: 300ms;
}

Each token has a default, so you only need to define the values you want to replace. Overrides apply everywhere the tokens are used, including inside DS-GN component shadow roots.

Start from the complete override template

The package includes a commented template containing every supported override:

cp node_modules/@ds-gn/tokens/dist/tokens.overrides.template.css \
  ./src/brand-overrides.css

brand-overrides.css is the recommended consumer filename, not a generated package artifact; applications may choose another local name. Uncomment and edit the required values, then import the copied file after @ds-gn/tokens/theme. The template is also exposed as @ds-gn/tokens/template for tools that resolve package exports.

Package exports

| Export | Purpose | | -------------------------- | -------------------------------------------------- | | @ds-gn/tokens | Typed JavaScript token values | | @ds-gn/tokens/public | Public CSS custom-property definitions | | @ds-gn/tokens/theme | Semantic light and dark theme mappings | | @ds-gn/tokens/tailwind | Tailwind CSS theme integration | | @ds-gn/tokens/properties | Typed CSS custom-property registrations | | @ds-gn/tokens/template | Starter file for application-level token overrides |

This table is the complete supported surface. Anything else inside dist is an internal build artifact with no compatibility promise — read it and a patch release may break you.

Tailwind

@ds-gn/tokens/tailwind is a Tailwind v4 @theme block, so every token also generates utilities:

@import 'tailwindcss';
@import '@ds-gn/tokens/tailwind';

<div class="bg-surface-elevated text-text-primary rounded-card">…</div>

You still need /public and /theme on the document. The @theme entries carry each token's default as a var() fallback so utilities render correctly on their own, but theme switching and your overrides come from the document stylesheets.

Breakpoints are the exception: they are emitted as literal rem values rather than var() references, because a custom property cannot be used in a media query. They are not override targets.

What is and is not overridable

Override targets. The --<name>-on-light / --<name>-on-dark pairs and the single-value tokens — everything the overrides template lists. These are the supported API.

Color primitives (--color-orange-500, --color-neutral-900, …) are declared on :root and stable, but they are the raw palette the semantic tokens are built from. Overriding one shifts everything derived from it. Rebrand through the semantic tokens instead.

Structural tokens — breakpoints and the default font families — are JavaScript exports only. They never appear as overridable custom properties.

Internal variables are prefixed --dsgn-src-. They exist so a token's default and a consumer override both survive the crossing into a component's shadow root. Never set one; override the public token it reads, and the mirror follows.

Versioning

Both public packages are 0.x, so a minor version may contain a breaking change and a patch never does.

Against that, tokens carry these rules:

• Adding a token is a minor.
• Changing a token's value is a minor. Values are design decisions, not API, but a rebrand-by-default is disruptive enough to deserve the bump.
• Renaming or removing a token, and collapsing a themed pair to a single value or the reverse, is a minor and requires a migration note in CHANGELOG.md naming the old and new custom properties. A token you can no longer set is indistinguishable from one that silently stopped working, so the changelog entry is the only thing standing between a consumer and a mystery.
• Adding or removing an export subpath is a minor.

Relationship to @ds-gn/ui

@ds-gn/ui depends on an exact @ds-gn/tokens version, and the two are versioned in lockstep. Your package manager therefore installs a matching pair on its own.

Install @ds-gn/tokens directly anyway when you import the stylesheets or override tokens — depending on a transitive package's file layout is what breaks on an unrelated upgrade. Keep the two at the same version when you do: a ui newer than its tokens reads tokens that do not exist yet, which renders as missing colors rather than as an error.

Support

Search or report package issues in the public issue tracker. For questions, email [email protected].

License

This package is available under the MIT License included in LICENSE. Third-party materials included in the distribution remain subject to the licenses listed in THIRD_PARTY_NOTICES.