npm package: @namp88/compass-tokens
Description: Design tokens for Compass design system - CSS custom properties
Author: namp88
Latest version: 1.0.15

# @namp88/compass-tokens

Design tokens for the Compass design system, exported from Figma and transformed into CSS custom properties.

## Installation

```bash
npm install @namp88/compass-tokens
```

## Quick Start

```html
<!-- 1. Include the tokens -->
<link rel="stylesheet" href="node_modules/@namp88/compass-tokens/dist/css/tokens.css">

<!-- 2. Set the theme on <html> -->
<html data-theme="light">
```

**Important:** You must set `data-theme` on `<html>` for semantic tokens (colors, backgrounds, borders) to apply.

## Fonts

The design system uses two fonts:

| Token | Font | Usage |
|-------|------|-------|
| `--gl-font-family-text` | **Inter** | Body text, UI elements |
| `--gl-font-family-heading` | **Poppins** | Headings |

### Option 1: Google Fonts (recommended)

Add to your `<head>`:

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Poppins:wght@500;600;700&display=swap" rel="stylesheet">
```

### Option 2: CSS @import

```css
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Poppins:wght@500;600;700&display=swap');
```

### Option 3: npm packages

```bash
npm install @fontsource/inter @fontsource/poppins
```

Then in your entry file:

```js
import '@fontsource/inter/400.css';
import '@fontsource/inter/500.css';
import '@fontsource/inter/600.css';
import '@fontsource/inter/700.css';
import '@fontsource/poppins/500.css';
import '@fontsource/poppins/600.css';
import '@fontsource/poppins/700.css';
```

### Using font tokens in CSS

```css
h1 {
  font-family: var(--gl-font-family-heading);   /* Poppins */
  font-size: var(--gl-heading-font-size-4xl);
  line-height: var(--gl-heading-line-height-4xl);
}

p {
  font-family: var(--gl-font-family-text);       /* Inter */
  font-size: var(--gl-text-font-size-md);
  line-height: var(--gl-text-line-height-md);
}
```

## Theming

All semantic tokens are scoped to `[data-theme="..."]` selectors. Primitive tokens (sizes, spacing, raw color palette) are available globally in `:root`.

### Available Themes

| Theme | Attribute | Description |
|-------|-----------|-------------|
| Light | `data-theme="light"` | Default light theme |
| Dark | `data-theme="dark"` | Dark theme |
| High Contrast | `data-theme="high-contrast"` | High contrast / accessibility |

### Usage

```html
<!-- Light -->
<html data-theme="light">

<!-- Dark -->
<html data-theme="dark">

<!-- High Contrast -->
<html data-theme="high-contrast">
```

### Switching themes with JavaScript

```js
// Set theme explicitly
document.documentElement.dataset.theme = 'dark';

// Reset to light
document.documentElement.dataset.theme = 'light';
```

### Auto-detect system preference

If you want to automatically match the user's OS theme:

```js
// On page load
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.dataset.theme = prefersDark ? 'dark' : 'light';

// Listen for changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
  document.documentElement.dataset.theme = e.matches ? 'dark' : 'light';
});
```

## File Structure

```
dist/css/
├── tokens.css              ← All-in-one (primitives + all themes)
├── index.css               ← Modular imports via @import
├── colors.css              ← Color palette primitives
├── primitives.css          ← Spacing, sizes, borders, shadows
├── typography.css          ← Font sizes, weights, line-heights
├── semantic/
│   ├── light.css           ← Light theme semantic tokens
│   ├── dark.css            ← Dark theme semantic tokens
│   └── high-contrast.css   ← High contrast semantic tokens
└── components/
    ├── button.css           ← Button size variants
    └── icon-size.css        ← Icon size variants
```

### Option 1: Single file (simplest)

```css
@import '@namp88/compass-tokens/dist/css/tokens.css';
```

### Option 2: Modular imports

```css
/* Only what you need */
@import '@namp88/compass-tokens/dist/css/colors.css';
@import '@namp88/compass-tokens/dist/css/primitives.css';
@import '@namp88/compass-tokens/dist/css/semantic/light.css';
@import '@namp88/compass-tokens/dist/css/semantic/dark.css';
```

### Option 3: Index file (all modular)

```css
@import '@namp88/compass-tokens/dist/css/index.css';
```

## Token Naming Convention

All tokens follow the `--gl-*` prefix pattern matching Figma's Code Syntax output:

```css
/* Primitives */
--gl-color-blue-500: #1f75cb;
--gl-space-xs: 10px;
--gl-border-radius-md: 8px;

/* Semantic (theme-dependent) */
--gl-color-border: var(--gl-color-neutral-200);        /* in light */
--gl-color-border: var(--gl-color-neutral-550);        /* in dark */
--gl-color-background: var(--gl-color-neutral-50);     /* in light */
--gl-color-background: var(--gl-color-neutral-900);    /* in dark */
```

### Using tokens in your CSS

```css
.card {
  background: var(--gl-color-background);
  border: var(--gl-border-width-md) solid var(--gl-color-border);
  border-radius: var(--gl-border-radius-md);
  padding: var(--gl-space-3xl);
}
```

## How It Works

```
Figma Variables
     │
     ▼
Figma Plugin (Compass v2 Publisher)
     │  Exports JSON with codeSyntax
     ▼
tokens/design-tokens.json
     │
     ▼
npm run transform:css
     │  Generates CSS custom properties
     ▼
dist/css/tokens.css
```

## Development

### Regenerate CSS from tokens

```bash
npm run transform:css
```

### Build (alias for transform)

```bash
npm run build
```

## Token Sources

Tokens are exported from the [Figma Foundations file](https://www.figma.com/design/kl0MBxTZwJQ1jY3EvYSflG/Foundations--Compass-) using the Compass v2 Publisher plugin.

Variable names in CSS directly match Figma's **Code Syntax (WEB)** output, so when you inspect a component in Figma Dev Mode, the CSS variable names are identical to what's in this package.

## License

MIT