@dataimago/tokens 0.1.0-alpha.4 → 0.1.0-alpha.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataimago/tokens",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.48",
   "description": "dataimago design tokens — canonical JSON sources plus generated TS/CSS artifacts",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,10 @@
     "./frequent": "./src/frequent.json",
     "./components": "./src/components.json",
     "./css": "./dist/tokens.css",
-    "./scss": "./dist/tokens.scss"
+    "./scss": "./dist/tokens.scss",
+    "./dtcg": "./dist/tokens.dtcg.json",
+    "./dtcg-w3c": "./dist/tokens.w3c.dtcg.json",
+    "./tokens-studio": "./dist/tokens.studio.json"
   },
   "files": [
     "src",

package/src/README.md

@@ -1,175 +1,59 @@
-# dataimago Design Tokens - Developer Guide
-
-## 🎯 Source of Truth Architecture
-
-This directory contains the **authoritative source** for all design decisions across the dataimago ecosystem. These JSON-based tokens serve as the foundation for:
-
-- **CSS Custom Properties**: Generated via idempotent build process
-- **Theme Support**: Automatic light/dark mode generation  
-- **Consumer Integration**: Distributed to all consumer repositories via git submodules
-- **Design Consistency**: Single definition → multiple output formats
-
-## 🔄 Idempotent Token Processing
-
-The token build system follows strict deterministic principles:
-
-- **✅ Stable Output**: Same tokens → identical CSS every time
-- **✅ No Timestamps**: Generated CSS excludes dynamic timestamps
-- **✅ Version Controlled**: Only source tokens are committed, generated files are build artifacts
-- **✅ Consumer Ready**: Generated assets integrate seamlessly into consumer repositories
-
-## Overview
-These tokens are processed into CSS custom properties that work across light and dark themes via our idempotent build system.
-
-## Token Structure
-
-### 🎨 **theme-colors.json** - Theme-Aware Colors
-Your carefully tuned light/dark color scheme:
-
-```json
-{
-  "color": {
-    "surface": {
-      "page": {
-        "light": "rgb(237, 237, 235)",  // Your warm light gray
-        "dark": "rgb(20, 20, 16)"       // Your warm dark background
-      }
-    },
-    "content": {
-      "primary": {
-        "light": "rgb(20, 20, 16)",             // Near Black text on light
-        "dark": "rgb(237, 237, 235)"    // Near white on dark
-      },
-      "secondary": {
-        "light": "#7c7c7c",             // Your tuned light gray
-        "dark": "#83838f"               // Your tuned dark gray
-      }
-    }
-  }
-}
-```
-
-### 🏃 **frequent.json** - High-Change Values
-Most commonly adjusted in DevTools:
-
-```json
-{
-  "spacing": {
-    "component": {
-      "padding": "1rem",    // Card/button internal spacing
-      "margin": "1.5rem",   // Between-component spacing
-      "gap": "0.75rem"      // Flex/grid gaps
-    }
-  },
-  "contrast": {
-    "readable": "...",      // Comfortable reading contrast
-    "medium": "...",        // Secondary information
-    "subtle": "..."         // De-emphasized text
-  }
-}
-```
-
-### 🎯 **effects.json** - Theme-Aware Effects
-Shadows and borders that adapt to themes:
-
-```json
-{
-  "shadow": {
-    "subtle": {
-      "light": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
-      "dark": "0 1px 2px 0 rgb(255 255 255 / 0.03)"
-    }
-  },
-  "border": {
-    "subtle": {
-      "light": "rgba(0, 0, 0, 0.1)",
-      "dark": "rgba(255, 255, 255, 0.1)"
-    }
-  }
-}
-```
-
-### 🧩 **components.json** - Component References
-Components reference semantic tokens:
-
-```json
-{
-  "card": {
-    "background": "surface.elevated",
-    "padding": "spacing.component.padding",
-    "shadow": "shadow.moderate"
-  }
-}
-```
+# dataimago Token Source Guide
 
-## DevTools → Token Workflow
+This directory is the source tree for `@dataimago/tokens`. The package build turns these JSON files into CSS variables, SCSS maps, typed JS modules, and an additive DTCG-style export.
 
-### Common Adjustments:
+## Distribution
 
-| **DevTools Change** | **Edit This Token** | **CSS Variable Generated** |
-|---------------------|--------------------|-----------------------------|
-| Card padding too tight | `frequent.json` → `spacing.component.padding` | `--spacing-component-padding` |
-| Text too light in dark | `theme-colors.json` → `content.secondary.dark` | `--color-content-secondary` |
-| Button needs more emphasis | `theme-colors.json` → `interactive.primary` | `--color-interactive-primary` |
-| Borders invisible | `effects.json` → `border.subtle.dark` | `--color-border-subtle` |
+Consumers receive tokens through public npm packages, not a production git submodule:
 
-### Quick Edit Workflow:
+- House identity: `@dataimago/tokens`, `@dataimago/css`, `@dataimago/ui`, `@dataimago/brand`
+- Neutral identity: `@dataimago/tokens-neutral`, `@dataimago/css-neutral`
 
-```bash
-# 1. Edit token JSON file
-edit ui/src/tokens/frequent.json
-
-# 2. Quick rebuild
-cd ui && npm run watch  # Auto-rebuilds on save
+The compatibility contract for this tightening iteration is strict: do not remove existing package names, package exports, token names, CSS custom properties, or required consumer import paths.
 
-# 3. Changes appear instantly in browser
-```
+## Source Files
 
-## Generated CSS Structure
+| File | Role | Emits CSS variables? | Schema-governed? |
+|---|---|---:|---:|
+| `colors.json` | Primitive color scales and functional colors | Yes | Yes |
+| `theme-colors.json` | Semantic light/dark color roles | Yes | Yes |
+| `typography.json` | Font families, sizes, weights, styles, features, line heights | Yes | Yes |
+| `spacing.json` | Spacing, radius, and layout scale | Yes | Yes |
+| `effects.json` | Theme-aware borders/shadows and motion tokens | Yes | Yes |
+| `frequent.json` | High-change reference values and metadata clusters | No | No |
+| `components.json` | Component-level aliases/reference manifest | No | No |
 
-The build system creates theme-aware CSS custom properties:
+`frequent.json` and `components.json` are intentionally treated as metadata/reference manifests in the current alpha line. Do not assume they emit CSS or normalize them opportunistically; any migration to canonical token shape needs to preserve existing exports and CSS variables.
 
-```css
-/* Theme-agnostic values */
-:root {
-  --color-brand-dataimago-primary: #3498DB;
-  --spacing-component-padding: 1rem;
-}
+## Build Outputs
 
-/* Light theme */
-:root, [data-bs-theme="light"] {
-  --color-surface-page: rgb(237, 237, 235);
-  --color-content-primary: #000000;
-}
+Run from the repo root:
 
-/* Dark theme */
-[data-bs-theme="dark"], @media (prefers-color-scheme: dark) {
-  --color-surface-page: rgb(20, 20, 16);
-  --color-content-primary: rgb(237, 237, 235);
-}
+```bash
+node packages/tokens/build.mjs
 ```
 
-## Token Naming Convention
+The build emits:
 
-**Pattern**: `category-purpose-variant`
+- `packages/tokens/dist/tokens.css`
+- `packages/tokens/dist/tokens.scss`
+- `packages/tokens/dist/index.mjs`
+- `packages/tokens/dist/index.cjs`
+- `packages/tokens/dist/index.d.ts`
+- `packages/tokens/dist/tokens.dtcg.json`
 
-- `--color-surface-page` = Color for surface/page level
-- `--color-content-primary` = Color for content/primary emphasis  
-- `--spacing-component-padding` = Spacing for component/padding use
-- `--shadow-moderate` = Shadow for moderate elevation
+Run the compatibility check after token changes:
 
-## Theme Philosophy
-
-- **Semantic naming** = Describes purpose, not appearance
-- **Your colors preserved** = Light/dark values from your tuned SCSS files
-- **DevTools friendly** = Easy to find the token you need to change
-- **Automatic theming** = Components work in both themes without extra code
+```bash
+node tools/check-css-vars.mjs
+```
 
-## Integration with Existing System
+The check compares generated CSS variable names against `packages/tokens/schema/css-vars.snapshot.json` and fails on removals. Additive variables are allowed.
 
-- **Quarto themes** continue working (website-light.scss, website-dark.scss)
-- **New tokens** complement existing system
-- **Backward compatible** = Old CSS still works during transition
-- **Build system** automatically distributes to all channels
+## Editing Rules
 
-Your carefully tuned color relationships are now systematized and ready for efficient DevTools-driven development! 🎯
+- Use canonical leaf shapes in CSS-emitting files: `{ "value": "..." }` or `{ "light": "...", "dark": "..." }`.
+- Use `_invariant` or another underscore-prefixed metadata key for group-level notes.
+- Never add a group-level `description` beside string-valued children in CSS-emitting files; that is the historical walker-bailout bug pattern.
+- Prefer semantic roles over primitive palette references in consumers.
+- Record threshold or role changes in `wiki/log.md`, and add or amend an ADR when the change alters durable design intent.

package/src/colors.json

@@ -40,7 +40,7 @@
       "paper": {
         "50":  { "value": "#fefdfb", "description": "Paper scale — lightest warm surface; renamed from cream — reserved for elevated cards/modals when warm tint is desired" },
         "100": { "value": "#fdf9f2", "description": "Paper scale — warm page-background option (legacy cream-100); not the primary surface in this iteration" },
-        "200": { "value": "#faf2e3", "description": "Paper scale — code-block and pull-quote background; warm tint reads as 'paper'" },
+        "200": { "value": "#faf2e3", "description": "Paper scale — pull-quote background; warm tint reads as 'paper' (code blocks and sunken surfaces moved to the card colour, 2026-11-02)" },
         "300": { "value": "#f5e8cf", "description": "Paper scale — call-out / emphasised panel background" },
         "400": { "value": "#edd9b3", "description": "Paper scale — muted warm accent" },
         "500": { "value": "#e0c088", "description": "Paper scale — strong warm accent; wheat" }
@@ -74,20 +74,20 @@
     },
     "functional": {
       "success": {
-        "value": "#27AE60",
-        "description": "Success states and positive actions"
+        "value": "#009E73",
+        "description": "Success hue (Okabe-Ito bluish-green, 2026-11-02; was Flat-UI #27AE60). For text use the mode-aware color.state.success"
       },
       "warning": {
-        "value": "#F39C12",
-        "description": "Warning states and caution"
+        "value": "#E69F00",
+        "description": "Warning hue (Okabe-Ito orange, 2026-11-02; was Flat-UI #F39C12). For text use the mode-aware color.state.warning"
       },
       "error": {
-        "value": "#E74C3C",
-        "description": "Error states and critical issues"
+        "value": "#ef5350",
+        "description": "Error hue (red, 2026-11-02; was Flat-UI #E74C3C). For text use the mode-aware color.state.error"
       },
       "info": {
         "value": "#3498DB",
-        "description": "Informational content"
+        "description": "Info hue (the slate accent). For text use the mode-aware color.state.info"
       }
     }
   }

package/src/dataviz.json

@@ -0,0 +1,136 @@
+{
+  "color": {
+    "dataviz": {
+      "okabe-ito": {
+        "orange": {
+          "value": "#E69F00",
+          "description": "Okabe-Ito orange (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "sky-blue": {
+          "value": "#56B4E9",
+          "description": "Okabe-Ito sky blue (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "bluish-green": {
+          "value": "#009E73",
+          "description": "Okabe-Ito bluish green (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "yellow": {
+          "value": "#F0E442",
+          "description": "Okabe-Ito yellow — 1.13:1 on the light page: never use it without a mark outline or a label (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "blue": {
+          "value": "#0072B2",
+          "description": "Okabe-Ito blue (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "vermillion": {
+          "value": "#D55E00",
+          "description": "Okabe-Ito vermillion (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "reddish-purple": {
+          "value": "#CC79A7",
+          "description": "Okabe-Ito reddish purple (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "black": {
+          "light": "#000000",
+          "dark": "#FDF9F2",
+          "description": "Okabe-Ito black (Okabe & Ito 2008). In dark mode it becomes content.primary.dark: #000000 is 1.14:1 on the dark page. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        }
+      },
+      "categorical": {
+        "1": {
+          "value": "#E69F00",
+          "description": "= okabe-ito.orange (slot 1, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "2": {
+          "value": "#56B4E9",
+          "description": "= okabe-ito.sky-blue (slot 2, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "3": {
+          "value": "#009E73",
+          "description": "= okabe-ito.bluish-green (slot 3, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "4": {
+          "value": "#F0E442",
+          "description": "= okabe-ito.yellow (slot 4, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "5": {
+          "value": "#0072B2",
+          "description": "= okabe-ito.blue (slot 5, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "6": {
+          "value": "#D55E00",
+          "description": "= okabe-ito.vermillion (slot 6, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "7": {
+          "value": "#CC79A7",
+          "description": "= okabe-ito.reddish-purple (slot 7, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "8": {
+          "light": "#000000",
+          "dark": "#FDF9F2",
+          "description": "= okabe-ito.black (slot 8, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        }
+      },
+      "uncertainty": {
+        "outer": {
+          "light": "#D6D6D6",
+          "dark": "#333333",
+          "description": "Outermost nested uncertainty band (gray 0.84 in the LIwLD PSTricks figures). The ramp is mirrored in dark mode so the innermost band stays the strongest. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        },
+        "union": {
+          "light": "#9E9E9E",
+          "dark": "#6B6B6B",
+          "description": "Union band (gray 0.62); mirrored in dark mode. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        },
+        "inner": {
+          "light": "#333333",
+          "dark": "#D6D6D6",
+          "description": "Innermost band (gray 0.20); mirrored in dark mode, where #333333 would be 1.46:1. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        }
+      },
+      "sgpc-bucket": {
+        "very-low": {
+          "value": "#D55E00",
+          "description": "= okabe-ito.vermillion. SGPc growth bucket 1 of 5 (very low) on the ordered scale very low → very high. Colour is never the only channel: pair it with a marker and the bucket letter code. Author decision 2026-11-01, matching the LIwLD paper's figures."
+        },
+        "low": {
+          "value": "#E69F00",
+          "description": "= okabe-ito.orange. SGPc growth bucket 2 of 5 (low) on the ordered scale very low → very high. Colour is never the only channel: pair it with a marker and the bucket letter code. Author decision 2026-11-01, matching the LIwLD paper's figures."
+        },
+        "typical": {
+          "value": "#56B4E9",
+          "description": "= okabe-ito.sky-blue. SGPc growth bucket 3 of 5 (typical) on the ordered scale very low → very high. Colour is never the only channel: pair it with a marker and the bucket letter code. Author decision 2026-11-01, matching the LIwLD paper's figures."
+        },
+        "high": {
+          "value": "#009E73",
+          "description": "= okabe-ito.bluish-green. SGPc growth bucket 4 of 5 (high) on the ordered scale very low → very high. Colour is never the only channel: pair it with a marker and the bucket letter code. Author decision 2026-11-01, matching the LIwLD paper's figures."
+        },
+        "very-high": {
+          "value": "#0072B2",
+          "description": "= okabe-ito.blue. SGPc growth bucket 5 of 5 (very high) on the ordered scale very low → very high. Colour is never the only channel: pair it with a marker and the bucket letter code. Author decision 2026-11-01, matching the LIwLD paper's figures."
+        }
+      },
+      "sgpc-role": {
+        "marginal": {
+          "value": "#0072B2",
+          "description": "= okabe-ito.blue. SGPc methodological role: what the separate margins (the score distributions) supply. 5.19:1 on white. A figure uses role colours or bucket colours, never both: this hue is also sgpc-bucket.very-high. Light-ground tints (marginal-pale 30 %, marginal-wash 12 %, mixes with white) ship in the TeX, JSON and R data-viz outputs only, and a tint is never the only channel: it sits with this stroke or a label. Maintainer decision 2026-11-09."
+        },
+        "linkage": {
+          "value": "#D55E00",
+          "description": "= okabe-ito.vermillion. SGPc methodological role: what linkage (the copula) supplies. 3.87:1 on white. A figure uses role colours or bucket colours, never both: this hue is also sgpc-bucket.very-low. Light-ground tints (linkage-pale 30 %, linkage-wash 12 %, mixes with white) ship in the TeX, JSON and R data-viz outputs only, and a tint is never the only channel: it sits with this stroke or a label. Maintainer decision 2026-11-09."
+        },
+        "kernel": {
+          "value": "#CC79A7",
+          "description": "= okabe-ito.reddish-purple. SGPc methodological role: the kernel-substitution term b_K. 3.06:1 on white, 2.86:1 on the light figure plate and 2.61:1 on the light page, so the kernel term always carries a second cue (a dash pattern or a label). Its light-ground tint (kernel-pale, 30 % mixed with white) ships in the TeX, JSON and R data-viz outputs only and is never the only channel. Maintainer decision 2026-11-09."
+        }
+      },
+      "map": {
+        "ocean": {
+          "light": "#808fa7",
+          "dark": "#042438",
+          "description": "Map-surface ground: the sea on the SGPc globe, behind land, absent countries and bucket-filled shapes. A muted slate blue on light surfaces and a deep blue on dark (maintainer 2026-10-22); not a palette step. The light value moved from #c9e1ec on 2026-11-01, when the Okabe-Ito sky-blue bucket blended into it: #808fa7 sits mid-way in lightness between the two blue buckets and is grey enough to read as sea. Gated by tools/dataviz-check.mjs against the five sgpc-bucket colours and the land neutrals (ink-200 land and ink-100 absent in light; ink-600 land and ink-700 absent in dark) at ΔE2000 ≥ 11.1 under normal vision and deutan, protan and tritan simulation, and the country outline (ink-600 light, ink-300 dark) at ≥ 3:1. Draw country borders in this colour, as gaps between shapes. The dark value moved from the apps' #14232c to #042438 on 2026-11-03 (maintainer): a slightly deeper sea keeps the quiet 'no data' countries (ink-700) distinct from it for protan readers (#14232c was ΔE 6.61 from them). Raised from the SGPc apps (2026-11-03)."
+        }
+      }
+    }
+  }
+}

package/src/effects.json

@@ -14,18 +14,50 @@
       "light": "0 10px 15px -3px rgb(20 20 16 / 0.1)",
       "dark": "0 10px 15px -3px rgb(237 237 235 / 0.4)",
       "description": "Strong elevation - modals, floating elements"
+    },
+    "figure-plate": {
+      "hover": {
+        "light": "0 10px 15px -3px rgb(20 20 16 / 0.1)",
+        "dark": "0 4px 12px rgb(0 0 0 / 0.5)",
+        "description": "Figure plate on hover. Light mode is the prominent shadow. Dark mode needs its own value: the plate stays light in dark mode, and prominent's light-ink glow (rgb(237 237 235 / 0.4)) would haze the dark page round a light plate, so a plain black shadow is used. Not mode-invariant."
+      },
+      "active": {
+        "light": "0 4px 6px -1px rgb(20 20 16 / 0.1)",
+        "dark": "0 2px 8px rgb(0 0 0 / 0.35)",
+        "description": "Figure plate while pressed. Light mode is the moderate shadow; dark mode is a plain black shadow for the same reason as figure-plate.hover. Not mode-invariant."
+      }
+    },
+    "lift": {
+      "light": "0 -8px 24px rgb(20 20 16 / 0.07)",
+      "dark": "0 -8px 24px rgb(0 0 0 / 0.30)",
+      "description": "Upward panel lift: a lower panel rising over the section above it, e.g. the landing's lower panel over the globe during the section wipe. Every other shadow here falls downward. Light is ink-900-ish at 0.07 (the apps wrote rgb(28 25 23), normalised to the house base rgb(20 20 16)); dark is plain black at 0.30 because a light-ink glow (as in shadow.prominent) would haze the dark page above the panel. The dark value is a controller call, not measured. Raised from the SGPc apps (2026-11-03)."
+    },
+    "sheet": {
+      "light": "0 -8px 24px rgb(0 0 0 / 0.18)",
+      "dark": "0 -8px 24px rgb(0 0 0 / 0.18)",
+      "description": "Upward shadow for a bottom sheet (the map details panel on a narrow screen). Plain black at 0.18 in both modes: a sheet is a physical layer over the page, so light and dark carry the same value. Raised from the SGPc apps (2026-11-03)."
+    },
+    "float": {
+      "light": "0 1px 2px rgb(20 20 16 / 0.06), 0 4px 14px rgb(20 20 16 / 0.08)",
+      "dark": "0 1px 2px rgb(0 0 0 / 0.40), 0 4px 14px rgb(0 0 0 / 0.35)",
+      "description": "Floating control: a small disc standing off the page, e.g. the landing's scroll chevron. Two layers, a tight contact shadow and a soft spread. Pair it with a hairline outline, because a shadow alone does not read in dark mode. Light is the apps' value normalised to rgb(20 20 16); dark is plain black, stronger (0.40 and 0.35) so the layers still read on a dark page, a controller call, not measured. Raised from the SGPc apps (2026-11-03)."
+    },
+    "print": {
+      "light": "0 1px 3px rgb(0 0 0 / 0.25)",
+      "dark": "0 1px 3px rgb(0 0 0 / 0.25)",
+      "description": "Paper drop shadow under a printed-paper object, e.g. the paper-cover thumbnail on color.surface.print. It depicts a physical object, so it is theme-invariant: the same in light and dark. Raised from the SGPc apps (2026-11-03)."
     }
   },
   "border": {
     "subtle": {
-      "light": "rgba(20, 20, 16, 0.1)",
-      "dark": "rgba(237, 237, 235, 0.1)",
-      "description": "Subtle borders - element separation"
+      "light": "rgba(20, 20, 16, 0.47)",
+      "dark": "rgba(237, 237, 235, 0.47)",
+      "description": "Subtle borders - element separation. THE ALPHA IS THE ROLE. Distinct from color.border.subtle: this family has its own base (20,20,16 / 237,237,235), so it needs a DIFFERENT alpha to render the same. 0.47 here matches 0.45 there at 3.07:1 on the worst surface; copying 0.45 would land at 2.90:1 and fail WCAG 1.4.11. Gated by tools/contrast-check.mjs."
     },
     "moderate": {
-      "light": "rgba(20, 20, 16, 0.15)",
-      "dark": "rgba(237, 237, 235, 0.15)",
-      "description": "Moderate borders - defined boundaries"
+      "light": "rgba(20, 20, 16, 0.63)",
+      "dark": "rgba(237, 237, 235, 0.63)",
+      "description": "Moderate borders - defined boundaries. 0.63 here matches color.border.moderate 0.60 in rendered contrast; see border.subtle on why the numbers differ between the two families."
     },
     "focus": {
       "light": "#3498DB",
@@ -50,5 +82,51 @@
       "value": "0.3s",
       "description": "Reserved for the dataimago wordmark / brand-mark transitions; do not borrow for general UI"
     }
+  },
+  "gradient": {
+    "video-poster": {
+      "value": "linear-gradient(135deg, #2b3a4a, #1f2a1f 60%, #3b2f1c)",
+      "description": "Video-poster placeholder, shown until a real poster frame exists: a slate-to-green-to-umber diagonal. It depicts a video frame, so it is theme-invariant (the same in light and dark). Its three stops (#2b3a4a, #1f2a1f, #3b2f1c) are a one-off and are NOT palette colours: do not reach for them elsewhere. A CSS gradient string has no clean DTCG mapping, so this token is in tokens.css and the JS exports only and is left out of the W3C DTCG and Tokens Studio exports (the legacy dist/tokens.dtcg.json still carries it). Raised from the SGPc apps (2026-11-03)."
+    }
+  },
+  "motion": {
+    "enter": {
+      "value": "200ms",
+      "description": "Something arrives: a page fade, tooltip in, chip in, view switch, drawer open, chart marks. Pair with motion.ease-out. Raised from the SGPc apps (2026-11-03), which named it --motion-enter. Within the 300ms motion-dignity ceiling; gated by tools/motion-lint.mjs."
+    },
+    "exit": {
+      "value": "120ms",
+      "description": "Something leaves: tooltip out, chip out, drawer close. Shorter than motion.enter, because leaving should not hold the reader. Pair with motion.ease-in; a component that unmounts in script holds the unmount for this long. Raised from the SGPc apps (2026-11-03), which named it --motion-exit."
+    },
+    "ease-out": {
+      "value": "cubic-bezier(0.25, 0.46, 0.45, 0.94)",
+      "description": "easeOutQuad, the curve foundations/design/motion-dignity.md names, for entrances: fast at the start, settling gently. Raised from the SGPc apps (2026-11-03), which named it --motion-ease-out."
+    },
+    "ease-in": {
+      "value": "cubic-bezier(0.55, 0.085, 0.68, 0.53)",
+      "description": "easeInQuad, for exits: starts gently and leaves quickly. The counterpart of motion.ease-out. Raised from the SGPc apps (2026-11-03), which named it --motion-ease-in."
+    },
+    "duration": {
+      "120": {
+        "value": "120ms",
+        "description": "Duration scale step, 120ms. Equal to motion.exit."
+      },
+      "160": {
+        "value": "160ms",
+        "description": "Duration scale step, 160ms: a hover on a small control, a sheet leaving."
+      },
+      "200": {
+        "value": "200ms",
+        "description": "Duration scale step, 200ms. Equal to motion.enter."
+      },
+      "250": {
+        "value": "250ms",
+        "description": "Duration scale step, 250ms: a sheet arriving, a grid-column change."
+      },
+      "300": {
+        "value": "300ms",
+        "description": "Duration scale step, 300ms: the motion-dignity ceiling. Nothing in the scale is longer, and the motion gate holds every motion.* value to it. A slow ambient entrance is not a token: a wait before an animation is a delay, not motion, and the animation itself stays at or under this step."
+      }
+    }
   }
-}
+}