Documentation

Documentation

Installation

Install the public component and token packages and wire up their stylesheets.

@ds-gn/ui and @ds-gn/tokens are published to public npm. Neither requires a DS-GN account, an entitlement token, or a custom .npmrc.

Install

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

Install the tokens package explicitly, even though the components depend on it — your application imports its stylesheets directly.

Peer dependencies

  • lit (^3.3.1) is required. The components are Lit elements. Modern package managers install peer dependencies automatically; add it yourself if yours does not.
  • react (>=18) is optional, and only needed if you use the React wrappers from @ds-gn/ui/react.

The packages ship tree-shakable ESM with type declarations and work with any bundler — Vite, Astro, Next, or Webpack. A bundler is required: the modules import their dependencies by bare specifier (lit, clsx), which a browser cannot resolve from a plain <script type="module"> without an import map.

Load the tokens

Import all three token stylesheets once, in your application’s entry stylesheet:

@import '@ds-gn/tokens/public';
@import '@ds-gn/tokens/theme';
@import '@ds-gn/tokens/properties';
  • public is the override API — every token you are allowed to redefine.
  • theme maps those tokens to their light and dark values.
  • properties registers the typed custom properties the components’ styles depend on.

properties is not optional, and skipping it fails quietly rather than loudly. A component’s styles live in a shadow root, and a shadow root’s stylesheet cannot register @property — only the document can. Without this import those properties have no registered default, so any declaration reading one is invalid at computed-value time and is dropped: transforms do not apply, panels anchor to the wrong place, hover scales do nothing. Nothing errors and most of the component still looks right, which makes it a slow thing to debug.

Components render without the first two, but they fall back to built-in defaults, so load all three before judging how anything looks.

Import a component

Importing a component module registers its custom element. Import only what you use — nothing is registered globally on your behalf.

import '@ds-gn/ui/button';
<dsgn-button appearance="solid">Get started</dsgn-button>

React

React wrappers are generated for every component and keep their plain names:

import { Button } from '@ds-gn/ui/react';

export function Cta() {
  return <Button appearance="outline">Get started</Button>;
}

Custom events arrive as on<EventName> props named after the underlying dsgn-* event — onDsgnInput, onDsgnImageError, and so on.

Importing the React entry during a Node server render is safe: the server emits an inert <dsgn-*> tag that upgrades on the client. Cloudflare workerd cannot evaluate the elements on the server at all — load the wrappers client-only there, behind a lazy import.

Next

Coming soon. @ds-gn-cli/create, the CLI that scaffolds an entire design system, is not released yet — there is no install command for it. Everything on this page works without it.

Esc