Documentation

Documentation

Customization

How to rebrand DS-GN by overriding design tokens.

DS-GN’s visual identity is fully customizable through CSS custom properties. Override tokens to match your brand without modifying component source code.

Override Tokens

Import the public token stylesheet and override any variable in your own CSS:

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

:root {
  /* Override brand color to your own */
  --brand-on-light: oklch(55% 0.2 280);
  --brand-on-dark: oklch(70% 0.18 280);

  /* Override accent color */
  --accent-on-light: oklch(60% 0.25 30);
  --accent-on-dark: oklch(72% 0.22 30);
}

Shape and depth, not just color

Corner radius and shadow are tokens too, and override the same way. They are namespaced (--radius-*, --shadow-*) rather than stripped like colors, so the name you override is the full one:

:root {
  /* Every elevated surface — card, modal, popover */
  --radius-surface: 1.5rem;

  /* Or a single component */
  --radius-button: 0.5rem;
  --radius-input: 0.25rem;

  --shadow-card-on-light: 0 18px 40px rgb(15 23 42 / 0.12);
  --shadow-card-on-dark: 0 20px 44px rgb(2 6 23 / 0.45);
}

Note the two shapes. Radius has no -on-light / -on-dark variants: a corner radius has no meaningful per-theme answer, so it is a single-value token with one override. Shadow does vary by theme, so it keeps the pair. The overrides template is the authoritative list of which is which.

Each token ships a baked-in default, so components render correctly before you override anything; setting the token on :root replaces that default everywhere it is used, including inside component shadow roots.

Override Template

DS-GN provides a template file with all overridable tokens:

# Copy the override template to your project
cp node_modules/@ds-gn/tokens/dist/tokens.overrides.template.css ./my-brand.css

This file contains every token with its default value, ready to be customized.

Surface System

Components support surface="light" and surface="dark" props. The token system automatically selects the correct *-on-light or *-on-dark variant:

<!-- Light surface (default) -->
<dsgn-button surface="light">Light Button</dsgn-button>

<!-- Dark surface -->
<dsgn-button surface="dark">Dark Button</dsgn-button>

Token Layers

Tokens are organized in three layers:

  1. Primitives — Raw color values (--color-blue-500)
  2. Semantic — Purpose-driven tokens (--brand-on-light)
  3. Component — Component-specific tokens (--button-solid-bg-on-light)

Override at the semantic layer for broad changes, or at the component layer for surgical control.

Primitives are the exception: they are the palette the semantic tokens are built from, so overriding one shifts everything derived from it. Rebrand at the semantic layer instead.

What you cannot override

Variables prefixed --dsgn-src- are internal. They carry a token’s value across into component shadow roots, and setting one has no reliable effect — override the public token it reads and the internal mirror follows.

Breakpoints and the default font families are exported as JavaScript values only; they are not overridable custom properties.

Esc