@brightlocal/tokens

BrightLocal Design System tokens package containing design tokens, CSS variables, and Tailwind CSS v4 presets.

Compatibility

Important: This package uses Tailwind CSS v4 directives (@import "tailwindcss", @theme inline, @variant). It is not compatible with Tailwind CSS v3.

Installation

npm install @brightlocal/tokens --registry=https://npm.pkg.github.com

This package is published to GitHub Packages. You'll need to authenticate with GitHub Packages to install it.

Quick Start (Golden Path)

Follow these steps to integrate the tokens package into your project:

1. Install the package

npm install @brightlocal/tokens tailwindcss@^4.1.18

2. Import the preset in your main CSS file

/* app.css / globals.css */
@import "@brightlocal/tokens/tailwind-preset.css";

This single import gives you:

• Tailwind CSS v4 base styles
• All semantic color tokens (light + dark mode)
• Typography, spacing, radius, and shadow tokens
• Tailwind utility mappings for all tokens
• Self-hosted fonts — @font-face rules and woff2 files for Inter, Poppins, and Geist Mono are bundled in, so font-sans, font-display, and font-mono render correctly for end users with no extra setup (no Google Fonts <link>, no manual @font-face). See Self-hosted fonts.

3. Enable dark mode

Add the .dark class to your root element:

<!-- Light mode (default) -->
<html>
  <body class="bg-background text-foreground">...</body>
</html>

<!-- Dark mode -->
<html class="dark">
  <body class="bg-background text-foreground">...</body>
</html>

4. Use with @brightlocal/ui-components

import { Button } from "@brightlocal/ui-components/button";

// Components automatically use the semantic tokens from the preset
<Button variant="default">Primary Action</Button>

Usage

Core Tokens (CSS Variables)

Import individual token CSS files for granular control:

@import "@brightlocal/tokens/core-tokens/colors.css";
@import "@brightlocal/tokens/core-tokens/spacing.css";
@import "@brightlocal/tokens/core-tokens/typography.css";

Tailwind CSS Presets

/* Standard preset (recommended) */
@import "@brightlocal/tokens/tailwind-preset.css";

/* Lab preset (experimental features) */
@import "@brightlocal/tokens/tailwind-preset-lab.css";

Available Exports

Token Reference

Semantic Colors

The design system uses semantic color tokens — not raw palette values. Always use these:

Status Colors

With CSS Custom Properties

.my-component {
  color: var(--foreground);
  background: var(--background);
  border: 1px solid var(--border);
  border-radius: var(--radius-md);
}

.my-button {
  background: var(--primary);
  color: var(--primary-foreground);
}

With Tailwind CSS Utilities

<!-- Page layout -->
<div class="bg-background text-foreground min-h-screen">

  <!-- Card -->
  <div class="bg-card text-card-foreground rounded-md border border-border p-4">
    <h2 class="text-lg font-semibold">Title</h2>
    <p class="text-muted-foreground text-sm">Description</p>
  </div>

  <!-- Button -->
  <button class="bg-primary text-primary-foreground rounded-md px-4 py-2">
    Click me
  </button>

  <!-- Destructive action -->
  <button class="bg-destructive text-destructive-foreground rounded-md px-4 py-2">
    Delete
  </button>
</div>

Typography

Use font-display with text size and weight utilities for headings:

Font families: font-sans (Inter), font-serif (Georgia), font-mono (Geist Mono), font-display (Poppins)

Self-hosted fonts

The preset ships self-hosted @font-face declarations and woff2 files for the three brand fonts, so they render for end users without the font being installed locally and without any CDN request. Importing @brightlocal/tokens/tailwind-preset.css is all that's required — no Google Fonts <link>, no manual @font-face.

Bundled weights (latin subset, normal style, font-display: swap):

These cover every weight the design system uses through its shifted font-weight scale (font-normal → 300, font-medium → 400, font-semibold → 500, font-bold → 600, font-extrabold → 700). Rare extremes (100/200/800/900), italics, and non-latin subsets are intentionally omitted to keep the payload small; they fall back to the nearest shipped weight. font-serif uses the system Georgia stack and is not self-hosted.

The woff2 files are emitted as assets by your bundler (Vite, Next.js, etc.) and lazy-loaded per weight — a consumer only downloads the weights it actually renders. Fonts are licensed under the SIL Open Font License 1.1 (see the *-LICENSE.txt files shipped in fonts/).

Border Radius

AI Usage Rules

See AI_USAGE.md for the full AI usage guide, including semantic token reference, common mistakes, and setup instructions.

Key rules:

1. Never hardcode colors — always use semantic tokens or their Tailwind utility equivalents
2. Use bg-background text-foreground as the page baseline
3. Prefer semantic tokens over palette tokens — use bg-primary not bg-blue-600
4. Dark mode uses .dark class — tokens switch automatically, no manual dark: variants needed
5. Import the preset — a single @import "@brightlocal/tokens/tailwind-preset.css" provides everything

Development

This package is part of the BrightLocal Design System monorepo. Tokens are generated from Tokens Studio definitions in src/core-tokens/tokens-studio/.

Build pipeline: Tokens Studio JSON → Style Dictionary → CSS variables → Tailwind v4 preset

# Build all tokens (from packages/tokens/)
pnpm build:tokens

# Full build (tokens + copy to dist + tokens.json)
pnpm build

# From monorepo root
pnpm --filter @brightlocal/tokens build

Repository

GitHub Repository

License

Private package — BrightLocal internal use only.