Installation

Install BDS, wire the token cascade, and render your first component in a Next.js or Astro consumer.

The cascade is the adoption contract of record. This page is the quick setup path; the four binding requirements every consumer must satisfy — layer order, mode switches, importing tokens.css, and zero token redefinitions — live there. Read the adoption contract before wiring a new consumer.

Install the package

npm install @brikdesigns/bds

pnpm add @brikdesigns/bds

bun add @brikdesigns/bds

Wire the token cascade

In your global stylesheet (globals.css, app.css, etc.) declare the @layer order first — before any @import — then import each file into its layer:

@layer bds-tokens, bds-components, client-theme, client-overrides;

@import '@brikdesigns/bds/tokens.css' layer(bds-tokens);
@import '@brikdesigns/bds/styles.css'  layer(bds-components);
@import './styles/theme-{client}.css'  layer(client-theme); /* your client's brand overrides */

The layer() clause is load-bearing — tokens.css ships unlayered, so without it the file wins the cascade and the client theme can never override. The full reason, what each file contains, and the rule against redefining BDS tokens live in The cascade.

Theme + mode switches

Set switches on <html> (or use <ThemeProvider> in React apps which manages them automatically):

<html data-theme="dark" data-mode-borderwidth="bold">
  <body class="theme-brand-brik">
    <!-- ... -->
  </body>
</html>

Switch	Values	Effect
`<body class="theme-brand-brik">`	—	Loads Brik's brand colors / fonts. Replace with your own client theme class if applicable.
`<html data-theme>`	`light` (default) / `dark`	Color mode
`<html data-mode-borderwidth>`	`thin` / `bold` (omit for Standard)	Borderwidth mode

See The cascade for the full switch table including audience scope binding for multi-brand sites.

Optional atmosphere overlay

Atmospheres add ambient decoration (vignettes, grain, orbs, spotlights) without overriding theme tokens. Add one @import after the cascade block above — it ships unlayered on purpose, so it decorates on top without touching the token cascade:

@import '@brikdesigns/bds/atmospheres/minimal-clinical.css'; /* optional — decoration only, unlayered */

Atmospheres are decoration-only — surface color comes from the theme layer. See Atmospheres.

Import a component

import { Button } from '@brikdesigns/bds';

export function Example() {
  return <Button variant="primary">Save</Button>;
}

That's it. No provider required for components — they read tokens from the cascade above.

The cascade — two-tier × four-layer × modes architecture and the full <html> switch table.
Framework guides — Next.js + Astro scaffolds with real working code.