npm package: @nuvia/tokens
Description: Design tokens and CSS variables for the Nuvia Design System. This package provides the foundational styling layer for Tailwind CSS v4.
Latest version: 1.6.0

# @nuvia/tokens

Design tokens and CSS variables for the Nuvia Design System. This package provides the foundational styling layer for Tailwind CSS v4.

## Installation

```bash
pnpm add @nuvia/tokens
```

## Usage

### Full Design System (Recommended)

If you're using `@nuvia/components`, you don't need to install this package separately—it's included automatically:

```css
@import "tailwindcss";
@import "@nuvia/components/styles/globals.css";
```

### Tokens Only (Without Components)

For apps that only need design tokens without React components:

```css
/* globals.css */
@import "tailwindcss";
@import "@nuvia/tokens/styles/globals.css";

@config "./tailwind.config.ts";
```

## Framework Setup

### Vite

```bash
pnpm add -D @tailwindcss/vite
```

```typescript
// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [tailwindcss()],
});
```

### Next.js / PostCSS

```bash
pnpm add -D @tailwindcss/postcss
```

```javascript
// postcss.config.mjs
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
export default config;
```

## What's Included

### Tailwind v4 Theme Registration

The CSS file includes `@theme inline` which registers all design tokens as Tailwind utilities:

```css
@theme inline {
  --color-background: hsl(var(--background));
  --color-primary: hsl(var(--primary));
  --color-muted: hsl(var(--muted));
  /* ... all semantic colors */
}
```

This enables classes like `bg-muted`, `text-primary`, `border-accent` to work automatically.

### CSS Variables

All design tokens are available as CSS variables in both light and dark themes:

```css
:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 4%;
  --primary: 228 45% 55%;
  /* ... */
}

.dark {
  --background: 240 10% 4%;
  --foreground: 0 0% 98%;
  /* ... */
}
```

### Dark Mode Support

Includes the Tailwind v4 dark mode variant:

```css
@custom-variant dark (&:is(.dark *));
```

### Utility Classes

Pre-built utility classes:

- `.flex-center`, `.flex-center-col`, `.flex-center-row`
- Typography tokens: `.token-font-heading-1` through `.token-font-minimum`
- Gradients: `.nuvia-gradient-1`, `.nuvia-gradient-2`, `.marketing-gradient`
- Fade gradients: `.fade-in-gradient-to-t/b/r/l`

## JavaScript Tokens

Access color values programmatically:

```typescript
import { colors } from "@nuvia/tokens";

console.log(colors.zafiro[500]); // "228 45% 55%"
console.log(colors.lumen[400]);  // "153 100% 45%"
```

## Color Palette

### Brand Colors

| Name | Description | Shades |
|------|-------------|--------|
| **Zafiro** | Primary brand blue | 100-800 |
| **Madrugada** | Secondary purple-blue | 100-800 |
| **Nimbus** | Neutral accent | 200-600 |
| **Indigo** | Accent blue | 100-800 |
| **Lumen** | Success/positive green | 100-800 |
| **Lilas** | Purple accent | 100-800 |
| **Magenta** | Marketing pink | 100-800 |
| **Magma** | Warning orange | 100-800 |

### Support Colors

| Name | Description | Shades |
|------|-------------|--------|
| **Light** | Neutral light tones | 100-700 |
| **Dark** | Neutral dark tones | 100-700 |
| **Error** | Destructive red | 100-700 |

## Theming

Toggle themes by adding/removing the `dark` class on `<html>`:

```javascript
// Enable dark mode
document.documentElement.classList.add("dark");

// Enable light mode  
document.documentElement.classList.remove("dark");

// Toggle
document.documentElement.classList.toggle("dark");
```

## Using with @nuvia/tailwind-config

For the complete Tailwind configuration including plugins and extended theme:

```bash
pnpm add @nuvia/tailwind-config
```

See [@nuvia/tailwind-config README](../tailwind-config/README.md) for setup.