Documentation

Documentation

Configuration

Theme the components with tokens, switch light and dark, and register icons.

The components take no global configuration file. What you configure is the token layer they read from, the theme they resolve against, and the icon registry.

Rebrand with tokens

Every visual decision resolves through a CSS custom property. Import the public stylesheet and redefine what you want — no component source is involved:

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

:root {
  --brand-on-light: oklch(55% 0.2 280);
  --brand-on-dark: oklch(70% 0.18 280);

  --radius-button: 0.5rem;
}

Color and shadow tokens come in -on-light and -on-dark pairs; shape tokens (--radius-*) are single values. The full list is the token contract, and the Customization guide covers the override rules.

Light and dark

@ds-gn/tokens/theme maps the paired tokens to whichever theme is active. It resolves in this order:

  • :root — dark by default.
  • [data-theme="light"] or .light — light.
  • [data-theme="dark"] or .dark — dark.

So a light-themed application should say so explicitly:

<html data-theme="light">
  <body>
    <!-- everything here resolves against the light theme -->
  </body>
</html>

These variables are set in the light DOM and inherit across shadow boundaries — that inheritance is what carries them into the components’ shadow roots, so set them on :root or an ancestor rather than trying to pierce a component.

Per-component surfaces

Most components also take a surface prop, which reflects a data-theme attribute onto the element itself. That scopes the theme to that subtree, which is how a dark section works inside a light page:

<dsgn-background surface="dark" variant="gradient">
  <dsgn-heading surface="dark" heading-size="h2">On a dark section</dsgn-heading>
  <dsgn-text surface="dark"
    >Slotted content is themed by its own element.</dsgn-text
  >
</dsgn-background>

Setting surface on a container does not theme what you slot into it — each component resolves its own. Set it on both.

Register icons

<dsgn-icon> and any component with an icon-name prop resolve names through a registry you populate once, at your application’s entry point:

import { Icon } from '@ds-gn/ui/icon';
import * as icons from '@ds-gn/ui/icon/icons';

const { iconNames, ...registry } = icons;
Icon.registerIcons(registry);

Register only the icons you use to keep the bundle small, or skip the registry entirely and pass an imported icon as a property:

import { arrowRight } from '@ds-gn/ui/icon/icons';

html`<dsgn-icon .icon=${arrowRight}></dsgn-icon>`;

Custom icons work the same way — any SVGTemplateResult keyed by a name.

Element names

The published components use the dsgn- prefix, and it is not configurable at runtime. Custom prefixes are a scaffolding concern, which is the CLI’s job.

Coming soon. @ds-gn-cli/create will generate a project with a design-system-config.json — choosing your own element prefix, language, styling approach, and tooling, then composing the project from a canonical core plus adapters. It is not released yet. The Create — Coming soon covers the planned capabilities.

Esc