@dataimago/tokens 0.1.0-alpha.3 → 0.1.0-alpha.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataimago/tokens",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.30",
   "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" }
@@ -58,10 +58,12 @@
         "900": { "value": "#612b16", "description": "Copper scale — deep foundation" }
       },
       "accent": {
-        "50":  { "value": "#fdf2f2", "description": "Accent scale — faint wash for emancipation-coded panels" },
-        "500": { "value": "#b54a27", "description": "Accent scale — canonical moral/emancipation accent" },
-        "600": { "value": "#9a3e20", "description": "Accent scale — hover on accent" },
-        "700": { "value": "#7d321a", "description": "Accent scale — pressed state" }
+        "50":  { "value": "#f0f8fc", "description": "Accent scale — pale wash for accent-tinted backgrounds (iteration-2; was #fdf2f2 emancipation-coded panels in iteration-1)" },
+        "300": { "value": "#3498DB", "description": "Accent scale — dark-mode canonical (5.41:1 on stone-900, AA). Sourced from presentation-blue-500 — Flat-UI peter-river. Iteration-2 introduces this stop to enable mode-aware role mapping; see wiki/decisions/iteration-2-blue-accent.md." },
+        "400": { "value": "#2980B9", "description": "Accent scale — dark-mode hover/emphasized variant (sourced from presentation-blue-600 — Flat-UI belize-hole)" },
+        "500": { "value": "#1f618d", "description": "Accent scale — light-mode canonical (5.68:1 on stone-100, AA; 6.66:1 white-on-color, AA). Sourced from presentation-blue-700. Iteration-2 sky-blue moral-weight; supersedes iteration-1's #b54a27 emancipation-copper-red. The scale-name is preserved (consumer-side text-accent-500 keeps working with the same mental model); only the value moved." },
+        "600": { "value": "#154d6f", "description": "Accent scale — light-mode hover (HSL-interpolated from accent-500: H≈205°, S+4, L−6)" },
+        "700": { "value": "#0f3a52", "description": "Accent scale — light-mode pressed/active (HSL-interpolated from accent-500: H≈205°, S+8, L−13)" }
       },
       "presentation-blue": {
         "50":  { "value": "#f0f8fc", "description": "Presentation-blue scale — pale wash for reveal.js callout backgrounds" },
@@ -72,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,115 @@
+{
+  "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."
+        }
+      }
+    }
+  }
+}

package/src/effects.json

@@ -18,14 +18,14 @@
   },
   "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",
@@ -51,4 +51,4 @@
       "description": "Reserved for the dataimago wordmark / brand-mark transitions; do not borrow for general UI"
     }
   }
-}
+}