@bttrlabs/tokens

Semantic design tokens and theming primitives for the bttr design system. The package provides a ThemeProvider, ready-to-consume CSS variables, and utilities for synchronising themes across React, Storybook, and vanilla environments.

Features

• Light and dark themes mapped to accessible colour palettes with WCAG contrast targets.
• Responsive spacing, typography, radius, and shadow scales exposed as CSS custom properties.
• Zero-runtime theme switching via data-theme attributes with hydration-safe fallbacks.
• Helper hooks (useTheme, usePrefersReducedMotion, etc.) for reading and updating the current theme.
• Type-safe token generation backed by Style Dictionary.

Installation

pnpm add @bttrlabs/tokens

Use the provider at the root of your application.

import { ThemeProvider, useTheme } from '@bttrlabs/tokens';

export function App() {
  return (
    <ThemeProvider>
      <Dashboard />
    </ThemeProvider>
  );
}

function Dashboard() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Toggle theme
    </button>
  );
}

Token usage

All tokens are exposed as CSS custom properties under the --color-*, --space-*, --font-*, and --shadow-* namespaces. Consume them directly in CSS or through utility libraries such as Tailwind, Vanilla Extract, or Stitches.

.button {
  background-color: var(--color-interactive-primary);
  color: var(--color-text-inverse);
  padding-inline: var(--space-4);
  box-shadow: var(--shadow-md);
}

Extending themes

• Duplicate src/theme/default.json to seed additional brand themes.
• Run pnpm build in the tokens package to regenerate the CSS artifacts.
• Update ThemeProvider to recognise the new theme key and provide switching affordances in Storybook (apps/storybook/.storybook/preview.tsx).

Development

• pnpm build compiles tokens through Style Dictionary and emits CSS modules consumed by the UI package.
• pnpm watch runs the generator in watch mode while you iterate on JSON source files.
• Unit smoke tests live in packages/tokens/tests to ensure generated bundles import correctly in Node and ESM environments.

License

MIT © bttrlabs