# Generating Tokens

The CSS files are generated from raw Figma/Supernova token JSON files using Style Dictionary, then extended with a shadcn compatibility layer.

## Running the generator

```bash
nx run @mindvalley/css:generate
```

This produces two files:

- `packages/css/dist/mindvalley.css` — Mindvalley brand
- `packages/css/dist/b2b.css` — B2B brand

## Source files

| Source | Location |
| --- | --- |
| Token JSON (from Supernova) | `tokens/brands/{brand}/*.json` |
| Style Dictionary config | `src/style-dictionary/` |
| shadcn theme CSS | `src/themes/{brand}-shadcn.css` |

The generator reads the following token files per brand (when present): `color.json`, `space.json`, `border-radius.json`, `blur.json`, `shadow.json`, `dimension.json`, `size.json`, and `gradient.json`.

The following source files are present in `tokens/brands/{brand}/` but intentionally **not** emitted as CSS:

- `font-family.json`, `font-size.json`, `font-weight.json`, `line-height.json`, `letter-spacing.json`, `paragraph-spacing.json` — typography is owned by the Tailwind plugin (`src/tailwind/*`), not raw CSS variables
- `typography.json` — composite token, not consumable as CSS variables
- `string.json` — Figma display labels, not styling

`dimension.json` contains a `typography.list-spacing.*` subcategory; this is filtered out so no `--typography-*` variables leak into the dimension block.

Token JSON files are generated by [Supernova.io](https://supernova.io) from Figma and should not be edited manually.

## Nx caching

The `generate` target is configured with Nx caching in `project.json`:

- **Inputs**: source files (`default`), upstream dependencies (`^production`), token JSON (`{projectRoot}/tokens/**/*`), and theme CSS (`{projectRoot}/src/themes/**/*`)
- **Outputs**: `{projectRoot}/dist`

If none of the inputs have changed, Nx will skip regeneration and use the cached output.

## Generated output structure

Each CSS file contains the color base/theme layers, followed by single-variant blocks for every other token type, then the shadcn layer. The non-color blocks are appended in this order:

1. Space — `--card-padding-*`, `--component-spacing-*`, `--grid-margin-*`, `--layout-gutter-*`, `--section-gutter-*`
2. Border radius — `--rounded-*`
3. Blur — `--blur-*`
4. Shadow — `--shadow-*`
5. Dimension — `--breakpoints-*`, `--dimension-*`, `--overlay-*`, `--spacing-*`
6. Size — `--breakpoint-*`, `--container-*`, `--device-*`
7. Gradient — `--gradient-*` / `--gradients-*`

Non-color tokens only emit their `base` variant (the `desktop`/`tablet`/`mobile`/`light` variants in the source JSON are duplicates).

Gradient tokens with unresolved Style Dictionary references in the source data are silently dropped — see [Token Pipeline](token-pipeline.md#gradient-handling).

The color layer follows the original three-layer design:

### 1. Base layer — raw color scales

CSS custom properties for numbered color scales. Values are identical in `:root` and `.dark`.

```css
:root {
  /* Colors */
  --blue-600: #005cff;
  --grey-100: #f9f9f9;
  --purple-600: #7a12d4;
  /* ... */
}

.dark {
  /* Same values repeated */
  --blue-600: #005cff;
  --grey-100: #f9f9f9;
  /* ... */
}
```

### 2. Theme layer — semantic tokens

Semantic tokens that reference base-layer variables via `var()`. Values differ between `:root` and `.dark`.

```css
:root {
  /* Backgrounds */
  --bg-primary: var(--grey-100);
  --surface: var(--white);

  /* Content */
  --content-primary: var(--grey-700);

  /* Stroke */
  --border-border-light: var(--black-8-a_1);
}

.dark {
  /* Backgrounds */
  --bg-primary: var(--grey-650);
  --surface: var(--grey-700);

  /* Content */
  --content-primary: var(--white);

  /* Stroke */
  --border-border-light: var(--white-12-a_1);
}
```

### 3. shadcn layer — component framework variables

Appended from `src/themes/{brand}-shadcn.css`. Maps semantic tokens to shadcn/ui CSS variable conventions. See [shadcn Mapping](shadcn-mapping.md).

```css
:root {
  --background: var(--bg-primary);
  --foreground: var(--content-primary);
  --primary: var(--purple-600);
  /* ... */
}

.dark {
  --primary: var(--purple-400);
  /* ... */
}
```

## Script location

The generate script is at `packages/css/scripts/generate.ts`. It:

1. Instantiates Style Dictionary with custom transforms, filters, and format from `src/style-dictionary/`
2. Processes each brand sequentially, writing base + theme layers to `dist/`
3. Appends the static shadcn theme CSS from `src/themes/{brand}-shadcn.css`