@brightlocal/tokens

v1.0.0

Published

3 days ago

BrightLocal Design System tokens

Downloads

1,005

0High
0Medium
0Low

@brightlocal/tokens

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

Compatibility

| Dependency | Version | |---|---| | Tailwind CSS | ^4.1.18 (v4 required) | | CSS Import Syntax | @import / @theme (Tailwind v4 CSS-first config) | | Build Systems | Vite, Next.js, PostCSS — any bundler with CSS @import support |

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

| Export Path | Description | |---|---| | @brightlocal/tokens/tailwind-preset.css | Main Tailwind CSS v4 preset (includes all tokens and self-hosted fonts) | | @brightlocal/tokens/tailwind-preset-lab.css | Experimental Tailwind CSS preset | | @brightlocal/tokens/fonts.css | Standalone @font-face rules for Inter, Poppins, Geist Mono (already included by the preset) | | @brightlocal/tokens/core-tokens/colors.css | Color design tokens (CSS variables) | | @brightlocal/tokens/core-tokens/spacing.css | Border radius, shadow, breakpoint, and container tokens | | @brightlocal/tokens/core-tokens/typography.css | Typography tokens (fonts, sizes, weights) | | @brightlocal/tokens/tokens.json | Machine-readable token reference for AI tools and MCP servers (not for runtime code — read-only reference) |

Token Reference

Semantic Colors

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

| Token (CSS) | Tailwind Utility | Purpose | |---|---|---| | var(--background) | bg-background | Page/app background | | var(--foreground) | text-foreground | Default text color | | var(--primary) | bg-primary, text-primary | Primary brand/action color | | var(--primary-foreground) | text-primary-foreground | Text on primary backgrounds | | var(--secondary) | bg-secondary | Secondary actions | | var(--secondary-foreground) | text-secondary-foreground | Text on secondary backgrounds | | var(--muted) | bg-muted | Muted/subtle backgrounds | | var(--muted-foreground) | text-muted-foreground | Muted/subtle text | | var(--accent) | bg-accent | Accent/highlight backgrounds | | var(--accent-foreground) | text-accent-foreground | Text on accent backgrounds | | var(--destructive) | bg-destructive, text-destructive | Error/danger states | | var(--destructive-foreground) | text-destructive-foreground | Text on destructive backgrounds | | var(--border) | border-border | Default border color | | var(--input) | border-input | Input field borders | | var(--outline) | shadow-default | Focus ring color (used via shadow utility) | | var(--card) | bg-card | Card backgrounds | | var(--card-foreground) | text-card-foreground | Text on card backgrounds | | var(--card-border) | border-card-border | Card border color | | var(--popover) | bg-popover | Popover/dropdown backgrounds | | var(--popover-foreground) | text-popover-foreground | Text on popover backgrounds | | var(--link) | text-link | Link color | | var(--link-visited) | text-link-visited | Visited link color |

Status Colors

| Token (CSS) | Tailwind Utility | Purpose | |---|---|---| | var(--success-background) | bg-success-background | Success notification background | | var(--success-foreground) | text-success-foreground | Success text | | var(--info-background) | bg-info-background | Info notification background | | var(--info-foreground) | text-info-foreground | Info text | | var(--warning-background) | bg-warning-background | Warning notification background | | var(--warning-foreground) | text-warning-foreground | Warning text |

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:

| Heading | Classes | Size | |---|---|---| | XL | font-display text-5xl font-medium | 48px | | LG | font-display text-4xl font-medium | 36px | | MD | font-display text-3xl font-medium | 30px | | SM | font-display text-2xl font-medium | 24px |

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):

| Family | Utility | Weights shipped | |---|---|---| | Inter | font-sans | 300, 400, 500, 600, 700 | | Poppins | font-display | 400, 500, 600, 700 | | Geist Mono | font-mono | 300, 400 |

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

| Tailwind Utility | Value | |---|---| | rounded-none | 0px | | rounded-xs | 2px | | rounded-sm | 6px | | rounded-md | 8px | | rounded-lg | 10px | | rounded-xl | 14px | | rounded-2xl | 16px | | rounded-3xl | 24px | | rounded-4xl | 32px | | rounded-full | 9999px |

AI Usage Rules

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

Key rules:

Never hardcode colors — always use semantic tokens or their Tailwind utility equivalents
Use bg-background text-foreground as the page baseline
Prefer semantic tokens over palette tokens — use bg-primary not bg-blue-600
Dark mode uses .dark class — tokens switch automatically, no manual dark: variants needed
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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@brightlocal/tokens

Compatibility

Installation

Quick Start (Golden Path)

1. Install the package

2. Import the preset in your main CSS file

3. Enable dark mode

4. Use with @brightlocal/ui-components

Usage

Core Tokens (CSS Variables)

Tailwind CSS Presets

Available Exports

Token Reference

Semantic Colors

Status Colors

With CSS Custom Properties

With Tailwind CSS Utilities

Typography

Self-hosted fonts

Border Radius

AI Usage Rules

Development

Repository

License

4. Use with `@brightlocal/ui-components`