@swiftsolve/rove-tokens 1.1.0 → 1.2.0

package/DESIGN.md

@@ -64,7 +64,7 @@ Disabled controls use `--opacity-disabled`.
 ### Focus and motion
 
 - Keyboard focus is `outline: var(--focus-outline)` with `outline-offset: var(--focus-offset)`. Rows flush with a card's edge draw it inside instead, with `--focus-inset`.
-- Animate with `--ease-out` (or `--ease-in-out`) over `--duration-fast` or `--duration-normal`. A looping pulse uses `--ease-pulse`, which is symmetric, so it fades out and back in alike.
+- Animate with `--ease-out` (or `--ease-in-out`) over `--duration-fast` or `--duration-normal`. A panel resizing to its content springs, with `var(--duration-spring) var(--ease-spring)`: it arrives within `--duration-normal`, and its slight overshoot settles after. A looping pulse uses `--ease-pulse`, which is symmetric, so it fades out and back in alike.
 
 ### Icons
 
@@ -106,7 +106,7 @@ Names and uses, from Figma. The values are in `tokens.css`; Dark and Light diffe
 - **Layout:** `--rail-item-size` 38px (rail items), `--titlebar-height` 56px (title bar)
 - **Cards:** `--card-padding` `var(--spacing-14)` (card inset), `--card-header-padding-y` `var(--card-padding)`, `--card-header-padding-x` `var(--card-padding)`, `--card-header-min-height` 42px (compact card header), `--card-header-height` 44px (card header), `--card-body-padding` `var(--card-padding)`, `--row-padding-y` 8px (data row, above and below)
 - **Font weights:** `--weight-regular` 400, `--weight-medium` 500, `--weight-semibold` 600
-- **Motion:** `--duration-fast` 140ms (hovers, small changes), `--duration-normal` 220ms (panels, page changes)
+- **Motion:** `--duration-fast` 140ms (hovers, small changes), `--duration-normal` 220ms (panels, page changes), `--duration-spring` 450ms (a spring’s full run)
 
 ### Text styles
 
@@ -135,4 +135,4 @@ What Figma variables can't hold, from `src/code-tokens.json`.
 
 - **Shadows:** `--shadow-panel`, `--shadow-raised`, `--shadow-popover`
 - **Focus:** `--focus-outline`, `--focus-inset`
-- **Motion:** `--ease-out`, `--ease-in-out`, `--ease-pulse`
+- **Motion:** `--ease-out`, `--ease-in-out`, `--ease-pulse`, `--ease-spring`

package/README.md

@@ -12,6 +12,7 @@ Tokens for Rove, straight from the Rove Design System in Figma.
 [![Slideshow](https://img.shields.io/github/actions/workflow/status/swiftsolve/rove-tokens/presentation.yml?label=slideshow&labelColor=17181b)](https://github.com/swiftsolve/rove-tokens/actions/workflows/presentation.yml)
 [![Version](https://img.shields.io/github/package-json/v/swiftsolve/rove-tokens?label=version&labelColor=17181b&color=5b8cff)](https://github.com/swiftsolve/rove-tokens/tags)
 [![Figma](https://img.shields.io/badge/Figma-source_of_truth-5b8cff?logo=figma&logoColor=white&labelColor=17181b)](https://www.figma.com/design/NoICIoyhWNOya9tOnNfEhH/Rove-Design-System)
+
 [![DTCG](https://img.shields.io/badge/DTCG-2025.10-5b8cff?labelColor=17181b)](https://www.designtokens.org/tr/2025.10/format/)
 [![Style Dictionary](https://img.shields.io/badge/Style_Dictionary-5-5b8cff?labelColor=17181b)](https://styledictionary.com/)
 [![WCAG](https://img.shields.io/badge/WCAG_2.2-AA-5b8cff?labelColor=17181b)](#-contrast)
@@ -23,22 +24,57 @@ Tokens for Rove, straight from the Rove Design System in Figma.
 [📐 DESIGN.md](DESIGN.md)  · 
 [💡 Rationale](docs/rationale.md)
 
+[📖 Tokens Storybook](https://rove.swiftsolve.net/storybook/tokens/)  · 
+[🧱 Components Storybook](https://rove.swiftsolve.net/storybook/)
+
 </div>
 
 ---
 
-Figma is the source of truth; this package turns its variables and text styles into DTCG token files, and those into CSS with [Style Dictionary](https://styledictionary.com/).
+Figma is the source of truth. A [Figma plugin](figma-plugin/) exports its variables and text styles, and this package turns them into DTCG token files, and those into CSS with [Style Dictionary](https://styledictionary.com/).
 
 > [!TIP]
 > **Building Rove UI?** [`DESIGN.md`](DESIGN.md) says which token to use for what, with every value. It ships in the package, so coding agents in Rove can read it from `node_modules/@swiftsolve/rove-tokens/DESIGN.md`.
 
+## ⚙️ How it works
+
+```mermaid
+%%{init: {"themeCSS": ".cluster-label { translate: 236px 0; }", "theme": "base", "themeVariables": {"fontFamily": "Inter, -apple-system, Segoe UI, Helvetica, Arial, sans-serif", "fontSize": "14px", "primaryColor": "#151618", "primaryTextColor": "#eeeeef", "primaryBorderColor": "#2b2c2f", "lineColor": "#8e8f93", "clusterBkg": "#0b0b0c", "clusterBorder": "#3a69d5", "titleColor": "#5b8cff", "dropShadow": "none"}}}%%
+flowchart TD
+  figma("<b>Figma file</b><br/>variables, styles"):::source
+  exports("<b>src/figma/*.json</b><br/>Figma plugin"):::file
+  code("<b>src/code‑tokens.json</b><br/>shadows, easings"):::file
+  slides("<b>Slideshow</b><br/>npm run present"):::ship
+
+  subgraph build ["npm run build"]
+    dtcg("<b>tokens/</b><br/>figma‑to‑dtcg.mjs"):::file
+    css("<b>tokens.css</b><br/>Style Dictionary"):::file
+    textCss("<b>text-styles.css</b><br/>dtcg‑to‑text‑styles.mjs"):::file
+    design("<b>DESIGN.md</b><br/>token‑reference.mjs"):::file
+  end
+
+  pkg("<b>npm package</b><br/>for Rove"):::ship
+  storybook("<b>Storybook</b><br/>both themes"):::ship
+
+  figma --> exports & slides
+  exports & code --> dtcg
+  dtcg --> css & textCss & design
+  build --> pkg & storybook
+
+  classDef source fill:#3a69d5,stroke:#5b8cff,color:#ffffff
+  classDef file fill:#151618,stroke:#2b2c2f,color:#eeeeef
+  classDef ship fill:#20263a,stroke:#5b8cff,color:#eeeeef
+```
+
+Under each file is what writes it: a script in `scripts/tokens/`, [Style Dictionary](https://styledictionary.com/) (run by `dtcg-to-css.mjs`), or the Figma plugin, which exports the file's variables and text styles. [What's where](#️-whats-where) has the details.
+
 ## 📦 Use
 
 ```bash
 npm install @swiftsolve/rove-tokens
 ```
 
-The package ships `tokens.css`, `text-styles.css` and `tokens/` built. You can also install straight from a version tag (`github:swiftsolve/rove-tokens#v1.0.0`); then npm builds them on install, which needs Node 22 (see `.nvmrc`).
+The package ships `tokens.css`, `text-styles.css` and `tokens/` built. You can also install straight from a version tag (`github:swiftsolve/rove-tokens#v1.1.0`); then npm builds them on install, which needs Node 22 (see `.nvmrc`).
 
 ```css
 @import '@swiftsolve/rove-tokens/tokens.css';
@@ -47,6 +83,8 @@ The package ships `tokens.css`, `text-styles.css` and `tokens/` built. You can a
 
 Dark values sit on `:root`, Light values on `:root.theme-light`. CSS names follow the Figma names: `bg/base` is `--bg-base`, `spacing/12` is `--spacing-12`.
 
+Every colour lives once in the Palette collection (`neutral/850`, `blue/450`; higher numbers are darker; a see-through shade adds `-a` and its opacity, `neutral/850-a10`), and the Color tokens point at it. The Palette isn't in `tokens.css`: a token that points at a shade gets the shade's value there. Figma-only collections (Icon tone, Capability level) and variables without a code syntax aren't in `tokens.css` either.
+
 Each Figma text style becomes four tokens: `--type-<style>-size`, `-weight`, `-line-height` (a unitless ratio) and `-letter-spacing` (in `em`). `Number/Display` gives `--type-number-display-size` and so on. A size bound to a variable comes through as that variable (`var(--font-size-3xl)`).
 
 `text-styles.css` applies a style whole: `.type-heading-large` sets the font family and all four, plus the text case (Overline is uppercase). The classes set no colour and sit in `@layer components`, so Tailwind utilities on the same element still win.
@@ -71,19 +109,34 @@ The colours meet [WCAG 2.2](https://www.w3.org/TR/WCAG22/) level AA in both them
 
 ## 📖 Storybook
 
-**Rove Tokens** is a Storybook of every token in both themes: colour, palette, type, spacing, radius, effects, motion and layout.
+Two Storybooks are hosted on rove.swiftsolve.net:
+
+- [**Rove Tokens**](https://rove.swiftsolve.net/storybook/tokens/): every token in both themes (colour, palette, type, spacing, radius, effects, motion and layout), built from this repo's `main`.
+- [**Rove Components**](https://rove.swiftsolve.net/storybook/): the Rove app's UI library, built from the tokens.
+
+To run Rove Tokens locally:
 
 ```bash
 npm run storybook
 ```
 
-It opens on <http://localhost:6007>; the Theme menu in the toolbar switches Dark and Light. The pages read the DTCG files in `tokens/` and are styled with `tokens.css`, so a new build shows up without editing them. `npm run build:storybook` writes a static copy to `storybook-static/`.
+It opens on <http://localhost:6007>; the Theme menu in the toolbar switches Dark and Light. The pages read the DTCG files in `tokens/` and are styled with `tokens.css`, so a new build shows up without editing them.
+
+## 🛠️ Scripts
+
+| Script | What it does |
+| --- | --- |
+| `npm run build` | Figma export → DTCG → `tokens.css`, `text-styles.css` and the `DESIGN.md` reference. `npm install` and `npm publish` run it too. |
+| `npm run storybook` | The Rove Tokens Storybook on port 6007 |
+| `npm run build:storybook` | A static copy of it in `storybook-static/` |
+| `npm run present` | Builds, then exports the Figma file's pages to the slideshow in `presentation/`. Needs `FIGMA_TOKEN` in `.env.local`. |
+| `npm run present:publish` | Pushes that slideshow to GitHub Pages |
 
 ## 🔄 Update the tokens
 
 1. Change the variables or text styles in Figma.
 2. Export them to `src/figma/variables.json` and `src/figma/text-styles.json`, either with the plugin in `figma-plugin/` (Figma desktop: Plugins → Development → Import plugin from manifest; then **Export**) or by asking Claude to export them through the Figma connection.
-3. Run `npm run build` (Node 22) and check `tokens.css`. It writes the DTCG files, then generates `tokens.css` from them with Style Dictionary and `text-styles.css` from the text styles, then rewrites the token reference at the end of `DESIGN.md`. The build stops if a variable's code syntax doesn't match its name, or a DTCG reference doesn't resolve.
+3. Run `npm run build` (Node 22) and check `tokens.css`. The build stops if a variable's code syntax doesn't match its name, or a DTCG reference doesn't resolve.
 4. Commit the change.
 
 ## 🚀 Release
@@ -105,24 +158,42 @@ It opens on <http://localhost:6007>; the Theme menu in the toolbar switches Dark
 
 ## 🗂️ What's where
 
+**From Figma**
+
 | Path | What |
 | --- | --- |
 | `src/figma/variables.json` | Raw Figma export. Every variable with a Web code syntax becomes that CSS variable. |
 | `src/figma/text-styles.json` | Raw export of the local text styles: font, size, weight, line height, letter spacing, text case (when set) and the variables bound to them. Each style becomes a `--type-*` group. |
-| `figma-plugin/` | The Figma plugin that writes the two exports. |
+| `figma-plugin/` | Rove Tokens Export, the Figma plugin that writes the two exports: every local variable by collection and mode, aliases kept, in the variables panel's order, and every local text style with the variables bound to it. It previews both files, then downloads them; it has no network access. |
 | `src/code-tokens.json` | What Figma variables can't hold: font stacks for the font-family variables, shadows, easing curves and the CSS expressions built on variables (`--focus-outline`). `{figma/name}` pulls a Figma value in per theme. |
-| `DESIGN.md` | How to build Rove UI with the tokens. The rules at the top are written by hand; the token reference below the marker line is generated by the build. |
+
+**Build**
+
+| Path | What |
+| --- | --- |
 | `scripts/tokens/build.mjs` | `npm run build`: runs the steps below and writes `tokens.css` and `text-styles.css` at the package root, where the import paths point. |
-| `scripts/tokens/dtcg.mjs` | Figma export → the DTCG files in `tokens/`, checking that every reference resolves in both themes. |
-| `scripts/tokens/css.mjs` | DTCG files → `tokens.css`, with Style Dictionary and a `rove/css` format: Dark on `:root`, what differs in Light on `:root.theme-light`, each text style as four `--type-*` variables (letter spacing included). |
-| `scripts/tokens/text-styles.mjs` | DTCG text styles → `text-styles.css`: a `.type-<style>` class per style that reads its `--type-*` variables. |
-| `scripts/tokens/design.mjs` | Figma export and `tokens.css` → the token reference in `DESIGN.md`: every token by name and Figma description, with values for the scales (spacing, radius, type, opacity) but not the colours, so nobody copies a hex. |
-| `scripts/presentation/export.mjs` | `npm run present`: exports the Figma file's pages to `presentation/index.html`, a slideshow styled with the tokens. Needs `FIGMA_TOKEN` (a Figma personal access token, `file_content:read`) in `.env.local`. |
-| `scripts/presentation/open.mjs` | `npm run present:open`: opens the exported presentation in your browser. |
-| `.storybook/` | The Rove Tokens Storybook's config, and the Inter and Questrial files it serves. |
+| `scripts/tokens/figma-to-dtcg.mjs` | Figma export → the DTCG files in `tokens/`, checking that every reference resolves in both themes. |
+| `scripts/tokens/dtcg-to-css.mjs` | DTCG files → `tokens.css`, with Style Dictionary and a `rove/css` format: Dark on `:root`, what differs in Light on `:root.theme-light`, each text style as four `--type-*` variables (letter spacing included). |
+| `scripts/tokens/dtcg-to-text-styles.mjs` | DTCG text styles → `text-styles.css`: a `.type-<style>` class per style that reads its `--type-*` variables. |
+| `scripts/tokens/token-reference.mjs` | Figma export and `tokens.css` → the token reference in `DESIGN.md`: every token by name and Figma description, with values for the scales (spacing, radius, type, opacity) but not the colours, so nobody copies a hex. |
+| `DESIGN.md` | How to build Rove UI with the tokens. The rules at the top are written by hand; the token reference below the marker line is generated by the build. |
+
+**Storybook and slideshow**
+
+| Path | What |
+| --- | --- |
+| `.storybook/` | The Rove Tokens Storybook's config, and the Inter, Questrial and Geist Mono files it bundles. |
 | `stories/` | Its pages, one file per sidebar group. `tokens.js` reads the DTCG files. |
+| `scripts/presentation/export.mjs` | `npm run present`: exports the Figma file's pages to `presentation/index.html`, a slideshow styled with the tokens. Needs `FIGMA_TOKEN` (a Figma personal access token, `file_content:read`) in `.env.local`. |
 | `scripts/presentation/publish.mjs` | `npm run present:publish`: pushes the exported presentation to the `gh-pages` branch, which GitHub Pages serves at <https://swiftsolve.github.io/rove-tokens/>. Each publish replaces the last. |
-| `.github/workflows/presentation.yml` | Runs the export and publish on every `v*` tag, or by hand. Needs the `FIGMA_TOKEN` repository secret. |
-| `docs/rationale.md` | Why the values are what they are (contrast targets, theme choices). |
 
-Every colour lives once in the Palette collection (`neutral/850`, `blue/450`; higher numbers are darker; a see-through shade adds `-a` and its opacity, `neutral/850-a10`), and the Color tokens point at it. The Palette isn't in `tokens.css`: a token that points at a shade gets the shade's value there. Figma-only collections (Icon tone, Capability level) and variables without a code syntax aren't in `tokens.css` either.
+**Workflows and docs**
+
+A release tag is the `v1.2.0`-style git tag that `npm version` creates and `git push --follow-tags` pushes (see [Release](#-release)).
+
+| Path | What |
+| --- | --- |
+| `.github/workflows/build.yml` | On each release tag, builds the tokens and checks `DESIGN.md` was rebuilt and committed. Run it by hand from Actions to check `main`. |
+| `.github/workflows/publish.yml` | On each release tag, publishes that version to npm with trusted publishing, so the repo holds no npm token. |
+| `.github/workflows/presentation.yml` | On each release tag, or by hand from Actions, exports the slideshow from Figma and publishes it. Needs the `FIGMA_TOKEN` repository secret. |
+| `docs/rationale.md` | Why the values are what they are (contrast targets, theme choices). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftsolve/rove-tokens",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Rove's design tokens, exported from the Rove Design System in Figma, as CSS and DTCG.",
   "type": "module",
   "license": "UNLICENSED",
@@ -24,7 +24,6 @@
   "scripts": {
     "build": "node scripts/tokens/build.mjs",
     "present": "npm run build && node scripts/presentation/export.mjs",
-    "present:open": "node scripts/presentation/open.mjs",
     "present:publish": "node scripts/presentation/publish.mjs",
     "prepare": "npm run build",
     "storybook": "storybook dev -p 6007",

package/src/code-tokens.json

@@ -14,6 +14,7 @@
 
     "--ease-out": "cubic-bezier(0.16, 1, 0.3, 1)",
     "--ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
-    "--ease-pulse": "cubic-bezier(0.42, 0, 0.58, 1)"
+    "--ease-pulse": "cubic-bezier(0.42, 0, 0.58, 1)",
+    "--ease-spring": "linear(0, 0.1896, 0.4943, 0.7351, 0.8834, 0.9602, 0.9936, 1.0046, 1.0062, 1.0047, 1.0028, 1.0014, 1.0006, 1, 1)"
   }
 }

package/src/figma/variables.json

@@ -2072,6 +2072,16 @@
       "values": {
         "Value": 220
       }
+    },
+    {
+      "name": "duration/spring",
+      "collection": "Motion",
+      "type": "FLOAT",
+      "code": "var(--duration-spring)",
+      "description": "A spring’s full run",
+      "values": {
+        "Value": 450
+      }
     }
   ]
 }

package/text-styles.css

@@ -1,4 +1,4 @@
-/* @swiftsolve/rove-tokens 1.1.0. Generated from Figma by scripts/tokens/build.mjs; do not edit. */
+/* @swiftsolve/rove-tokens 1.2.0. Generated from Figma by scripts/tokens/build.mjs; do not edit. */
 
 @layer components {
   /* Page titles, the wordmark. */

package/tokens/motion.tokens.json

@@ -15,6 +15,14 @@
         "unit": "ms"
       },
       "$description": "Panels, page changes"
+    },
+    "spring": {
+      "$type": "duration",
+      "$value": {
+        "value": 450,
+        "unit": "ms"
+      },
+      "$description": "A spring’s full run"
     }
   }
 }

package/tokens.css

@@ -1,4 +1,4 @@
-/* @swiftsolve/rove-tokens 1.1.0. Generated from Figma by scripts/tokens/build.mjs; do not edit. */
+/* @swiftsolve/rove-tokens 1.2.0. Generated from Figma by scripts/tokens/build.mjs; do not edit. */
 :root {
   /* Color */
   --bg-base: #0b0b0c; /* Backdrop */
@@ -98,6 +98,7 @@
   /* Motion */
   --duration-fast: 140ms; /* Hovers, small changes */
   --duration-normal: 220ms; /* Panels, page changes */
+  --duration-spring: 450ms; /* A spring’s full run */
 
   /* Code-only */
   --shadow-panel: 0 1px 2px rgba(0, 0, 0, 0.22), 0 4px 12px rgba(0, 0, 0, 0.1);
@@ -108,6 +109,7 @@
   --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
   --ease-pulse: cubic-bezier(0.42, 0, 0.58, 1);
   --focus-inset: calc(-1 * var(--focus-ring-width));
+  --ease-spring: linear(0, 0.1896, 0.4943, 0.7351, 0.8834, 0.9602, 0.9936, 1.0046, 1.0062, 1.0047, 1.0028, 1.0014, 1.0006, 1, 1);
 
   /* Type styles */
   --type-heading-large-size: var(--font-size-2xl);