@ds-gn/ui

Framework-agnostic web components and React wrappers for the DS-GN Design System.

Public Beta · Website · Documentation · Component reference · Changelog · Public repository

npm's Repository link points to our private build repository, which is required for Trusted Publishing. For examples and issue reporting, visit our public design-system repository.

Install

Choose your package manager:

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 directly because your application imports its stylesheets. Both packages come from public npm and require no .npmrc or entitlement token.

Quick start

Import the design tokens once in your application stylesheet:

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

All three are required. properties registers the typed custom properties the components' styles depend on — a shadow root cannot register @property itself, so without this import those styles are silently dropped rather than erroring (transforms stop applying, anchored panels land in the wrong place).

Then import only the components you use. Importing a component registers its custom element:

import '@ds-gn/ui/button';

<dsgn-button appearance="outline">Get started</dsgn-button>

React

Official React wrappers are generated for every component. React is an optional peer dependency, so install it in your application.

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

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

The wrappers retain their plain component names (Button, Input, and so on). Alias an import if it conflicts with a local component:

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

Custom events are exposed as on<EventName> props named after their underlying dsgn-* events, such as onDsgnInput and onDsgnImageError.

Package exports

The string helpers inherit currentColor for theme-aware lettering and keep the slash orange. Use getLogoHtml({ size: 24 }) to render the full artwork at a given height with its accessible name.

Server rendering

• Node SSR hosts (including Next, Remix, Nuxt, SvelteKit, Astro, and TanStack Start on Node): importing @ds-gn/ui/react during server rendering is safe. The server emits an inert <dsgn-*> tag that upgrades on the client. Declarative Shadow DOM is not emitted, so a brief unstyled frame is possible before upgrade; the pre-upgrade stylesheets below cover the layout components. Reactive properties are applied client-side; pass id, class, and similar values as normal attributes.
• Cloudflare workerd (including TanStack Start on Workers): full SSR is not currently supported because the custom element cannot be evaluated in the worker runtime. Load the wrapper client-only, such as behind a ClientOnly boundary with a lazy import.

Before components register

When your HTML is rendered before the component scripts run (server rendering or static pages), import the optional pre-upgrade stylesheets in your page CSS:

@import '@ds-gn/ui/layout.css';
@import '@ds-gn/ui/hero/fallback.css'; /* only if you use dsgn-hero */

They apply only until each element registers. layout.css holds Container, Nav, FeatureTabs and Footer to their final gutters and section spacing, reserves the nav bar's height, and keeps the nav's links and dropdowns hidden until it lays them out. hero/fallback.css does the same for every Hero layout. Without them, content can shift or flash as unstyled text while the scripts load.

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.