Installation

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() on each @import is load-bearing: tokens.css ships unlayered, and unlayered CSS beats layered CSS — so without layer(bds-tokens) the client theme in @layer client-theme could never override it. Once every file is assigned a layer, the @layer declaration order (not the import order) governs the cascade.

What each file contains, and the rule against redefining BDS tokens: 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 to the same block — it ships unlayered on purpose, so it decorates on top without touching the token cascade:

@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);
@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.