# @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
```bash
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
```bash
npm install @brightlocal/tokens tailwindcss@^4.1.18
```
### 2. Import the preset in your main CSS file
```css
/* 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
### 3. Enable dark mode
Add the `.dark` class to your root element:
```html
...
...
```
### 4. Use with `@brightlocal/ui-components`
```tsx
import { Button } from "@brightlocal/ui-components/button";
// Components automatically use the semantic tokens from the preset
```
## Usage
### Core Tokens (CSS Variables)
Import individual token CSS files for granular control:
```css
@import "@brightlocal/tokens/core-tokens/colors.css";
@import "@brightlocal/tokens/core-tokens/spacing.css";
@import "@brightlocal/tokens/core-tokens/typography.css";
```
### Tailwind CSS Presets
```css
/* 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) |
| `@brightlocal/tokens/tailwind-preset-lab.css` | Experimental Tailwind CSS 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
```css
.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
```html
```
### 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)
### 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](./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](https://tokens.studio/) definitions in `src/core-tokens/tokens-studio/`.
Build pipeline: Tokens Studio JSON → Style Dictionary → CSS variables → Tailwind v4 preset
```bash
# 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](https://github.com/BrightLocal/design-system/tree/main/packages/tokens)
## License
Private package — BrightLocal internal use only.