# @duo/tokens

Canonical design tokens for the Duo Design System.

## Install (published package)

The scope publishes to the **HRMTS** Azure Artifacts npm feed. In the consuming repo (or your user `~/.npmrc`), point the `@duo` scope at the registry and authenticate (Azure DevOps PAT with **Packaging → Read**, or `npm login` against that registry):

```ini
@duo:registry=https://pkgs.dev.azure.com/talentechdev/_packaging/HRMTS/npm/registry/
always-auth=true
```

Then install the version you need (initial releases start at `0.x`; check the feed or `npm view @duo/tokens version`):

```bash
pnpm add @duo/tokens
# or: npm install @duo/tokens
```

## Use in applications

Subpath exports from `package.json`:

| Subpath | Use case |
|--------|----------|
| `@duo/tokens` | JS/TS: flat map of scalar tokens (`duoTokens`, default export). |
| `@duo/tokens/css` | **Recommended for web:** single stylesheet defining `:root` CSS variables (`--duo-…`). |
| `@duo/tokens/scss` | SCSS variables (`$duo-color-gray-50`, …). |
| `@duo/tokens/json` | Resolved nested JSON bundle for tooling or runtime import. |
| `@duo/tokens/figma` | DTCG-shaped JSON for **Figma Variables → import from JSON**. |

**CSS (Vite, webpack, etc.):**

```ts
import "@duo/tokens/css";
```

Use tokens as `var(--duo-color-blue-900)` (names match generated `--duo-*` in `tokens.css`).

**SCSS:**

```scss
@use "@duo/tokens/scss" as *;
// e.g. color: $duo-color-blue-500;
```

**JS / TS:**

```ts
import { duoTokens } from "@duo/tokens";
// duoTokens["blue500"], semantic keys, spacing keys, etc.
```

**With `@duo/styles` or `@duo/ui`:** load tokens **first** so `var(--duo-…)` resolves, then styles/components (see [`@duo/styles` README](../styles/README.md)).

More detail on release and registry: [docs/token-pipeline.md](../../docs/token-pipeline.md).

## Source of truth

- **Base (product):** `src/base/base.json` and `src/base/color-primitives.json` (W3C/DTCG; semantic tree under a `duo` root).
- **Satellites:** `src/<id>/tokens.json` with JSON root **`duo-<id>`** (example: `src/email/tokens.json` → `duo-email`). Any number of folders is supported; each builds to `dist/<id>/`. Satellites may reference base tokens (e.g. `{color.surface}`).

See `src/README.md` for the source contract and supported token types.

Targets are assembled in `scripts/build-targets.mjs` via `getTokenBuilds()` (base + every `src/*/tokens.json` except `base/`). You should not need to change `build-tokens.mjs` or `validate-tokens.mjs` when adding `src/mobile/`, etc.

Do not use folder names `css`, `scss`, `json`, or `figma` — those names are reserved for base bundle exports.

## Outputs

Every target emits the same files under **`dist/<targetId>/`** (`dist/base/`, `dist/email/`, …). The base bundle uses `--duo-*` CSS variables; satellites use `--duo-<id>-*`.

| Import | Resolves to |
| ------ | ------------ |
| `@duo/tokens` | `dist/base/index.js` (`duoTokens`) |
| `@duo/tokens/css` | `dist/base/tokens.css` |
| `@duo/tokens/json` | `dist/base/tokens.json` |
| `@duo/tokens/figma` | `dist/base/figma-tokens.json` |
| `@duo/tokens/base`, `@duo/tokens/base/css`, … | same as the rows above (pattern exports) |
| `@duo/tokens/<id>` | `dist/<id>/index.js` (satellite id, e.g. `email`) |
| `@duo/tokens/<id>/css` | `dist/<id>/tokens.css` |

Satellite default export: `duo` + PascalCase(`<id>`) + `Tokens` (e.g. `duoEmailTokens`).

## Commands

```bash
pnpm --filter @duo/tokens build
pnpm --filter @duo/tokens validate
```

## Figma

Use `@duo/tokens/figma` or `@duo/tokens/email/figma` after a build. Sources use DTCG `$value` / `$type` tokens, alias references, and composite tokens where applicable; Figma bundles preserve nested structure for **Variables from JSON**.