docs: update Tokens Studio pipeline documentation (#5167)

* docs: update Tokens Studio pipeline documentation

* docs: drop note about claude reviews on workflow PRs

* docs: add generated-output README and legacy-guide pointer

Author: pomfrida

documentation/agent-instructions/TOKENS_STUDIO.md

@@ -50,7 +50,7 @@ The CLI is `@tokens-studio/studio-cli` (binary name `studio`), installed as a **
 ```
 
 - The `ref` can reference a `branch`, a `release`, or a `tag` — pin to a release for reproducible builds.
-- Pull formats are `raw` (default), `dtcg`, and `css`. **There is no TypeScript pull format** — pull raw/DTCG JSON and generate TS locally, as the existing Style Dictionary build does for `build/ts/*`.
+- Pull formats are `raw` (default), `dtcg`, and `css`. **There is no TypeScript pull or export format** — TS modules are generated locally by `packages/eds-tokens/scripts/generate-ts-tokens.mjs` (see § The release pipeline below).
 - `studio config show` displays the config; `studio config remove <alias>` (alias `rm`) removes a source from `.studio.json`. It does **not** delete already-pulled token files — clean those up manually.
 - `.studio.json` is meant to be committed for team consistency.
 
@@ -69,7 +69,14 @@ The CLI is `@tokens-studio/studio-cli` (binary name `studio`), installed as a **
 | `studio exports run <name-or-id> --out <dir>`     | Run a saved export configuration and write the output                                                                                                                                                                                                                 |
 | `studio exports delete <name-or-id>`              | Delete a saved export configuration (`--force` skips the confirmation prompt) — **destructive, remote**                                                                                                                                                               |
 
-Export formats on the platform: CSS Variables, DTCG JSON, Raw JSON, and Figma Variables. Aliases: `studio pull` = `tokens pull`, `studio login`/`logout` = `auth login`/`logout`, `studio init` = `config init`. Global flags everywhere: `--json`, `--verbose`, `--host`.
+Export formats on the platform: `css`, `scss`, `dtcg`, `figma`, `swift`, `android`, `compose`. Aliases: `studio pull` = `tokens pull`, `studio login`/`logout` = `auth login`/`logout`, `studio init` = `config init`. Global flags everywhere: `--json`, `--verbose`, `--host`.
+
+### Export gotchas (hard-won, July 2026)
+
+- **Only the CSS export evaluates the platform's colour formulas** (`set_chroma(set_lightness(...))`) into concrete values. The DTCG export keeps raw `{alias}` references and unevaluated formulas — it is a structural interchange format, NOT "resolved tokens". Plan any downstream generation accordingly.
+- **Reference export configurations by ID, not name, in anything automated.** A rename in the Studio UI silently breaks name-based `studio exports run` — this happened when `EDS` was renamed to `EDS-CSS` and would have failed the next release run.
+- **`naming.prefix` (css config) must not include a trailing separator.** The schema example says `'ds-'`, but the CLI appends the casing separator itself: `eds-` produces `--eds--token` (double dash); use `eds`.
+- **The `dtcg` format is config-less** — `exports schema --format dtcg` returns 404 and there are no templates. Create it with just `--format dtcg --name <name>`; it inherits the project's dimension/theme-group setup.
 
 ## Safety rubric
 
@@ -79,6 +86,15 @@ Classify every command before running it:
 - **Edits or overwrites local files (fine in a clean git tree, mention it):** `tokens pull` without `--dry-run`, `exports run`/`exports preview --out`, `config init/add/remove` (edit `.studio.json` only).
 - **Mutates remote state or credentials — always ask the user first:** `exports create/update/duplicate/delete`, `auth logout` (revokes and deletes stored credentials), and any push-like or write-scoped command that appears in future CLI versions. Remember the shortcut aliases (`studio logout` = `auth logout`) count too. When in doubt, treat a command as remote-mutating until `--help` proves otherwise.
 
+## The release pipeline
+
+`.github/workflows/tokens_studio_release.yaml` runs on every Tokens Studio release and opens/updates an automated PR (branch `tokens-studio-release`) with the full token state:
+
+1. **Trigger:** the outbound **CI Trigger** in Studio (Integrations → CI Triggers, `eds-tokens-release`) sends a `repository_dispatch` event (type `tokens-release`) to this repo on `release.created`. It can be fired manually with its **Test** button.
+2. **Auth:** the workflow authenticates back to Studio via GitHub OIDC against the inbound **CI Integration** (Integrations → CI Integration (Inbound); subject pattern `repo:equinor/design-system:ref:refs/heads/main`, read-only). The outbound trigger and the inbound integration are **separate configs** — a 403 `No matching CI integration found` from `studio ... --ci` means the *inbound* integration is missing or misconfigured, no matter how healthy the trigger looks.
+3. **Steps:** `studio tokens pull` (raw token sets → `src/tokens/<alias>/`), `studio exports run` for the two saved configurations — `EDS-CSS` (css) and `EDS-DTCG` (dtcg), referenced by ID — into `src/tokens/css/` and `src/tokens/dtcg/`, then `pnpm run generate:ts-tokens` which combines DTCG structure with evaluated CSS values into TS modules in `src/tokens/ts/` (see the script header in `packages/eds-tokens/scripts/generate-ts-tokens.mjs` for the mechanics, including CSS Color 4 gamut mapping).
+4. **Output:** all three directories are committed to the release PR. They are **generated — never edit them by hand**, and they are not yet wired into the package `exports` map.
+
 ## Staying current
 
 The CLI and platform are young and move fast (v0.1.x as of the snapshot below). **Never answer Tokens Studio questions from memory alone.** In order of authority:
@@ -105,4 +121,4 @@ studio
 └── flags       --host --json --no-color --verbose
 ```
 
-Known state in this repo at snapshot time: CLI installed as a devDependency of `packages/eds-tokens` and approved in `onlyBuiltDependencies`. `.studio.json` lives in `packages/eds-tokens` and is pulled in CI by `.github/workflows/tokens_studio_release.yaml`, triggered by the Tokens Studio CI integration (`repository_dispatch`, event type `tokens-release`) on every platform release. CI auth is OIDC (`id-token: write` + `--ci`) — no service token stored.
+Known state in this repo at snapshot time: CLI installed as a devDependency of `packages/eds-tokens` and approved in `onlyBuiltDependencies`. `.studio.json` lives in `packages/eds-tokens` (single source alias `eds-test-3`, project `4952a007-699a-4124-a043-124e80cc28d6`, branch `main`, format raw — the test-phase alias/output is due a production-shaped rename). Two saved export configurations on the project: `EDS-CSS` (css, id `39d37416-632b-4f04-b49b-cfaec63e3baa`, prefix `eds`, split layout, density base comfortable) and `EDS-DTCG` (dtcg, id `019463d4-9bef-4e37-9425-6de80eec87c8`). CI auth is OIDC (`id-token: write` + `--ci`) — no service token stored. See § The release pipeline for the workflow chain.

documentation/how-to/TOKEN_SYSTEM_GUIDE.md

@@ -1,5 +1,10 @@
 # Token System Guide
 
+> **Note:** A new Tokens Studio-based pipeline is being phased in — see
+> [`documentation/agent-instructions/TOKENS_STUDIO.md`](../agent-instructions/TOKENS_STUDIO.md).
+> This guide covers the **legacy pipeline** (Figma REST sync + Style Dictionary),
+> which still owns everything the `@equinor/eds-tokens` package publishes.
+
 This guide provides a comprehensive walkthrough of the <abbr title="Equinor Design System">EDS</abbr> token system – from Figma setup through syncing, building, and implementation. It covers the complete token lifecycle and serves as documentation for working with design tokens in the EDS.
 
 ## Table of Contents

packages/eds-tokens/CLAUDE.md

@@ -2,6 +2,10 @@
 
 Design tokens package — CSS variables, JSON, and JS/TS outputs consumed by EDS components and product teams.
 
+## Two pipelines coexist
+
+The **legacy pipeline** below (Figma REST sync + Style Dictionary) still owns everything the package *publishes* (`build/`, the `exports` map). The **new Tokens Studio pipeline** writes generated output to `src/tokens/{<alias>,css,dtcg,ts}` via `.github/workflows/tokens_studio_release.yaml` — those directories are **generated, never edit them by hand**, and are not yet wired into the `exports` map. The TS modules are produced by `pnpm run generate:ts-tokens` (`scripts/generate-ts-tokens.mjs` — DTCG export for structure + CSS export for evaluated values; the script header documents the mechanics). Canonical pipeline doc: [`documentation/agent-instructions/TOKENS_STUDIO.md`](../../documentation/agent-instructions/TOKENS_STUDIO.md).
+
 ## Build Pipeline (3 steps)
 
 ```

packages/eds-tokens/src/tokens/README.md

@@ -0,0 +1,19 @@
+# Generated token output — do not edit
+
+Everything in this directory is written by the Tokens Studio release
+workflow (`.github/workflows/tokens_studio_release.yaml`) and committed
+through its automated pull requests. **Never edit these files by hand** —
+the next release run regenerates them and silently overwrites manual
+changes. Fix token values in Tokens Studio instead.
+
+| Directory  | Content                                | Produced by                                     |
+| ---------- | -------------------------------------- | ----------------------------------------------- |
+| `<alias>/` | Raw token sets (JSON, with `{alias}`s) | `studio tokens pull` (sources in `.studio.json`) |
+| `css/`     | CSS custom properties                  | `studio exports run` (EDS-CSS configuration)    |
+| `dtcg/`    | DTCG interchange JSON                  | `studio exports run` (EDS-DTCG configuration)   |
+| `ts/`      | TypeScript modules                     | `pnpm run generate:ts-tokens` (combines `dtcg/` + `css/`) |
+
+None of this is wired into the package `exports` map yet — the published
+artifacts still come from the legacy Style Dictionary build in `build/`.
+
+Pipeline documentation: [`documentation/agent-instructions/TOKENS_STUDIO.md`](../../../../documentation/agent-instructions/TOKENS_STUDIO.md).