# scripts/

Build and validation tooling for the ASK design tokens.

| Script | Command | What it does |
|---|---|---|
| [`validate-tokens.mjs`](./validate-tokens.mjs) | `pnpm run tokens:validate` | Validates `design-tokens/tokens.json` against the DTCG shape (color → hex, dimension → px, alias → resolves, etc.). |
| [`check-tokens.mjs`](./check-tokens.mjs)       | `pnpm run tokens:check`    | **Drift guard.** Verifies every hex defined in `tokens.json` appears in the curated `globals.css` / `tailwind.preset.ts` / `theme.ts` / `tokens-studio.json`. Fails CI if any consumer is out of sync. |
| [`build-tokens.mjs`](./build-tokens.mjs)       | `pnpm run tokens:build`    | Generates `dist/` consumer artifacts via Style Dictionary — CSS variables, SCSS map, JS/TS module, flat & nested JSON. **Does not overwrite the curated shadcn/storybook files** (those are hand-maintained for human readability). |

## Why the curated files aren't auto-generated

Style Dictionary is great, but it can't preserve:

- The shadcn HSL-channel convention (`354 78% 52%` without the `hsl()` wrapper).
- Human comments grouping tokens by semantic intent.
- The `.dark` overrides that diverge from the light defaults in non-mechanical ways.

So `globals.css` and `tailwind.preset.ts` are **curated**. `check-tokens.mjs` keeps them honest: if you change a hex in `tokens.json` without updating the CSS, CI fails with a precise list of what's missing.

## CI integration

`tokens-build.yml` runs in the GitHub Actions workflow:

1. Install deps.
2. Run `pnpm run tokens:build`.
3. `git diff --quiet` — fail if anything in the working tree changed (drift between source and committed `dist/`).

`ci.yml` additionally runs `tokens:validate` and `tokens:check` on every PR.

## Local workflow

```bash
# Edit design-tokens/tokens.json
$EDITOR design-tokens/tokens.json

# Validate the JSON shape is still DTCG-correct
pnpm run tokens:validate

# Update the curated consumer files by hand to match
$EDITOR design-tokens/shadcn/globals.css

# Verify nothing drifted
pnpm run tokens:check

# Regenerate the dist/ outputs for downstream consumers
pnpm run tokens:build
```