@dataimago/tokens 0.1.0-alpha.1 → 0.1.0-alpha.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataimago/tokens",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.12",
   "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

@@ -13,37 +13,63 @@
         "800": { "value": "#1c1917", "description": "Ink scale — surfaces in dark mode" },
         "900": { "value": "#0c0a09", "description": "Ink scale — near-black; primary dark surface and text color" }
       },
-      "cream": {
-        "50":  { "value": "#fefdfb", "description": "Cream scale — lightest warm surface" },
-        "100": { "value": "#fdf9f2", "description": "Cream scale — canonical page background (light mode)" },
-        "200": { "value": "#faf2e3", "description": "Cream scale — slightly richer surface tint" },
-        "300": { "value": "#f5e8cf", "description": "Cream scale — pull-quote background, subtle panels" },
-        "400": { "value": "#edd9b3", "description": "Cream scale — muted warm accent" },
-        "500": { "value": "#e0c088", "description": "Cream scale — strong warm accent; wheat" }
+      "stone": {
+        "50":  { "value": "#f7f7f6", "description": "Stone scale — lightest cool-neutral surface; cards/modals one step above page" },
+        "100": { "value": "#ededeb", "description": "Stone scale — canonical page background (light mode); matches Paper_1 presentation surface" },
+        "200": { "value": "#dcdcda", "description": "Stone scale — borders, dividers; matches presentation-theme.scss --color-border" },
+        "300": { "value": "#c1c1bf", "description": "Stone scale — pressed border / disabled chrome" },
+        "400": { "value": "#a0a0a0", "description": "Stone scale — disabled text, muted icons" },
+        "500": { "value": "#7c7c7c", "description": "Stone scale — secondary text; matches presentation-theme.scss --color-secondary" },
+        "600": { "value": "#5e5e5c", "description": "Stone scale — caption / metadata text on light surfaces" },
+        "700": { "value": "#424240", "description": "Stone scale — primary text on cream/paper surfaces" },
+        "800": { "value": "#292927", "description": "Stone scale — high-contrast headings on light surfaces" },
+        "900": { "value": "#14140f", "description": "Stone scale — body text on light surfaces; matches presentation-theme.scss $body-color rgb(20,20,16)" }
+      },
+      "forest": {
+        "50":  { "value": "#f0f1ed", "description": "Forest scale — pale wash; subtle backdrop for forest-coded panels" },
+        "100": { "value": "#dde0d4", "description": "Forest scale — light hover-background tint for ghost buttons on light surfaces" },
+        "200": { "value": "#bdc4ad", "description": "Forest scale — soft accent panels" },
+        "300": { "value": "#98a384", "description": "Forest scale — interactive primary (dark mode); lighter for visibility on dark surfaces" },
+        "400": { "value": "#7e8a6b", "description": "Forest scale — interactive hover (dark mode); steps toward canonical" },
+        "500": { "value": "#5e6749", "description": "Forest scale — mid-step; charts and decorative emphasis" },
+        "600": { "value": "#4d5640", "description": "Forest scale — between mid and canonical" },
+        "700": { "value": "#434739", "description": "Forest scale — canonical interactive primary (light mode); 7.75:1 on stone-100, white text 9.0:1 — passes WCAG AAA" },
+        "800": { "value": "#363a2e", "description": "Forest scale — interactive hover (light mode); slightly darker than canonical" },
+        "900": { "value": "#1f2218", "description": "Forest scale — pressed/active state and deep emphasis" }
+      },
+      "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'" },
+        "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" }
       },
       "copper": {
         "50":  { "value": "#fdf4ee", "description": "Copper scale — warm tint wash" },
         "100": { "value": "#fbe5d1", "description": "Copper scale — soft copper backdrop" },
         "200": { "value": "#f6c79c", "description": "Copper scale — muted copper accent" },
-        "300": { "value": "#f0a467", "description": "Copper scale — interactive primary on dark mode" },
-        "400": { "value": "#ea8441", "description": "Copper scale — hover on dark mode" },
-        "500": { "value": "#d46820", "description": "Copper scale — canonical interactive primary (light mode)" },
-        "600": { "value": "#b55017", "description": "Copper scale — hover on light mode" },
+        "300": { "value": "#f0a467", "description": "Copper scale — historical interactive primary on dark mode (now superseded by forest)" },
+        "400": { "value": "#ea8441", "description": "Copper scale — historical hover on dark mode" },
+        "500": { "value": "#d46820", "description": "Copper scale — historical interactive primary (light mode); kept for callouts and chart accents" },
+        "600": { "value": "#b55017", "description": "Copper scale — historical hover on light mode" },
         "700": { "value": "#913d15", "description": "Copper scale — active/pressed state" },
         "800": { "value": "#753318", "description": "Copper scale — on dark surfaces" },
         "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" },
-        "500": { "value": "#3498DB", "description": "Presentation-blue scale — Flat-UI peter-river; reserved presentation accent (distinct from functional.info)" },
+        "500": { "value": "#3498DB", "description": "Presentation-blue scale — Flat-UI peter-river; reserved presentation accent. NOT for body text or button backgrounds (fails WCAG AA on stone-100). Decorative use only: borders, chart series, slide accents." },
         "600": { "value": "#2980B9", "description": "Presentation-blue scale — Flat-UI belize-hole; hover/emphasized on presentation accent" },
-        "700": { "value": "#1f618d", "description": "Presentation-blue scale — pressed/deep emphasis on presentation accent" }
+        "700": { "value": "#1f618d", "description": "Presentation-blue scale — pressed/deep emphasis on presentation accent; passes AA on stone-100 for text use" }
       }
     },
     "functional": {

package/src/effects.json

@@ -34,10 +34,21 @@
     }
   },
   "transition": {
-    "quick": "0.15s ease",
-    "standard": "0.25s ease-in-out",
-    "smooth": "0.35s ease",
-    "logo": "0.3s",
-    "description": "Animation durations - consistent timing"
+    "quick": {
+      "value": "0.15s ease",
+      "description": "Snap-fast micro-interactions — hover lifts, focus rings, immediate-feedback affordances"
+    },
+    "standard": {
+      "value": "0.25s ease-in-out",
+      "description": "Default for most state changes — toggles, button states, card hovers"
+    },
+    "smooth": {
+      "value": "0.35s ease",
+      "description": "Theme transitions, navbar collapse/expand, layout shifts that should feel deliberate"
+    },
+    "logo": {
+      "value": "0.3s",
+      "description": "Reserved for the dataimago wordmark / brand-mark transitions; do not borrow for general UI"
+    }
   }
 }