@dataimago/tokens-neutral 0.1.0-alpha.6

package/README.md

@@ -0,0 +1,67 @@
+# @dataimago/tokens-neutral
+
+Neutral-identity design tokens — sensible defaults for externally-owned consumers (Level-3 user apps generated by `apps/template/` in `dataimago-ai`; future third-party Level-2 hubs).
+
+**Identity:** Noto Sans throughout (no Josefin Sans). Neutral palette (ink, stone, paper, functional only — no forest, copper, accent, or presentation-blue). Interactive accent role maps to a quiet ink-700/ink-200 by default; owners customize from there.
+
+**Non-identity tokens** (spacing, radius, motion, shadows, ethical thresholds) are read from `@dataimago/tokens` at build time and stay in lockstep — no duplication, no drift.
+
+## Install
+
+```sh
+pnpm add @dataimago/tokens-neutral
+```
+
+## Usage
+
+```css
+/* globals.css — import CSS custom properties */
+@import '@dataimago/tokens-neutral/css';
+```
+
+```js
+// Tailwind: pair with @dataimago/css-neutral preset
+module.exports = {
+  presets: [require('@dataimago/css-neutral/tailwind-preset')],
+  content: [/* your app */],
+};
+```
+
+```ts
+// JS/TS: typed runtime access
+import { color, font } from '@dataimago/tokens-neutral';
+```
+
+## When to use this vs `@dataimago/tokens`
+
+| Consumer | Use |
+|---|---|
+| `dataimago.ai` (Level-1 hub) | `@dataimago/tokens` (dataimago house identity) |
+| `dissertation.ai`, `sgpc.ai`, `rpkg.ai` (Level-2 hubs — dataimago-owned) | `@dataimago/tokens` (dataimago house identity) |
+| `apps/template/` (per-user Level-3 apps generated by the framework) | `@dataimago/tokens-neutral` |
+| Third-party Level-2 hubs (future) | `@dataimago/tokens-neutral` as the starting point; owner customizes |
+
+## Architectural notes
+
+This package implements **Variant A** of the two-tier identity pattern proposed during the iteration-3 scope-contraction amendment (2026-05-14):
+
+- **Variant A (current):** additive neutral sibling. `@dataimago/tokens` keeps the dataimago house identity; `@dataimago/tokens-neutral` ships sensible neutral defaults. Non-breaking.
+- **Variant B (iteration-4 target):** neutral-as-base. `@dataimago/tokens` would be refactored to ship the neutral foundation; the dataimago house identity would move into a new `@dataimago/dataimago-theme` overlay package. Breaking change; deferred until dissertation-ai (iteration-3 D.1+) validates the framework.
+
+See [`wiki/decisions/tokens-neutral-sibling.md`](../../wiki/decisions/tokens-neutral-sibling.md) for the full rationale + deprecation path.
+
+## Build
+
+```sh
+pnpm --filter @dataimago/tokens-neutral build
+```
+
+Emits:
+- `dist/tokens.css` — CSS custom properties (light + dark theme variants)
+- `dist/tokens.scss` — same, as SCSS
+- `dist/index.{mjs,cjs,d.ts}` — typed JS modules
+
+## Related
+
+- [`@dataimago/tokens`](../tokens) — dataimago house identity
+- [`@dataimago/css-neutral`](../css-neutral) — compiled CSS + Tailwind preset built from this package

package/dist/index.cjs

@@ -0,0 +1,439 @@
+// Auto-generated by packages/tokens-neutral/build.mjs — do not edit.
+const tokens = {
+  "color": {
+    "surface": {
+      "page": {
+        "light": "#ededeb",
+        "dark": "#141410",
+        "description": "Main page background — stone-100 (light) / stone-900 (dark)"
+      },
+      "page-scrolled": {
+        "light": "#ededeb",
+        "dark": "#141410",
+        "description": "Page background when navbar shrinks — matches page"
+      },
+      "elevated": {
+        "light": "#f7f7f6",
+        "dark": "#1c1917",
+        "description": "Cards, modals, dropdowns — one step above page (stone-50 / ink-800)"
+      },
+      "sunken": {
+        "light": "#faf2e3",
+        "dark": "#0c0a09",
+        "description": "Input fields, code blocks — below page level (paper-200 light / ink-900 dark)"
+      },
+      "navbar": {
+        "light": "#ededeb",
+        "dark": "#141410",
+        "description": "Navbar background — matches page in both themes"
+      },
+      "navbar-scrolled": {
+        "light": "#ededeb",
+        "dark": "#141410",
+        "description": "Navbar when scrolled/shrunk — matches page-scrolled"
+      },
+      "code": {
+        "light": "#faf2e3",
+        "dark": "#1c1917",
+        "description": "Code block and inline code background"
+      }
+    },
+    "border": {
+      "subtle": {
+        "light": "rgba(12, 10, 9, 0.08)",
+        "dark": "rgba(253, 249, 242, 0.08)",
+        "description": "Subtle borders — element separation"
+      },
+      "moderate": {
+        "light": "rgba(12, 10, 9, 0.15)",
+        "dark": "rgba(253, 249, 242, 0.15)",
+        "description": "Moderate borders — defined boundaries"
+      },
+      "strong": {
+        "light": "rgba(12, 10, 9, 0.25)",
+        "dark": "rgba(253, 249, 242, 0.25)",
+        "description": "Strong borders — prominent separation"
+      },
+      "card": {
+        "light": "rgba(12, 10, 9, 0.15)",
+        "dark": "rgba(253, 249, 242, 0.15)",
+        "description": "Card border color with transparency for subtle definition"
+      },
+      "code": {
+        "light": "#d6d3d1",
+        "dark": "#292524",
+        "description": "Code block border"
+      }
+    },
+    "content": {
+      "primary": {
+        "light": "#14140f",
+        "dark": "#fdf9f2",
+        "description": "Primary text — stone-900 on stone-100 (light) / paper-100 on dark surface"
+      },
+      "secondary": {
+        "light": "#7c7c7c",
+        "dark": "#a8a29e",
+        "description": "Secondary text — stone-500 (light) / ink-300 (dark)"
+      },
+      "muted": {
+        "light": "#78716c",
+        "dark": "#78716c",
+        "description": "Muted text — captions, meta info"
+      },
+      "inverse": {
+        "light": "#fdf9f2",
+        "dark": "#0c0a09",
+        "description": "Inverse text — for contrasting backgrounds"
+      }
+    },
+    "interactive": {
+      "primary": {
+        "light": "#292524",
+        "dark": "#d6d3d1",
+        "description": "Primary interactive — ink-700 on light (15:1 on stone-100, AAA) / ink-200 on dark (high contrast quiet voice). Neutral default; @dataimago/tokens uses forest-700/forest-300 for dataimago house identity. Owners customize by overriding."
+      },
+      "hover": {
+        "light": "#1c1917",
+        "dark": "#a8a29e",
+        "description": "Hover state — ink-800 on light (one step deeper) / ink-300 on dark"
+      },
+      "accent": {
+        "light": "#292524",
+        "dark": "#d6d3d1",
+        "description": "Accent — neutral default mirrors interactive.primary (ink-700 / ink-200). The neutral package intentionally ships without a brand-color accent role; consumers that want a sky-blue, copper, forest, or other distinctive accent override this token. @dataimago/tokens maps this role to mode-aware presentation-blue per iteration-2."
+      },
+      "focus": {
+        "light": "#292524",
+        "dark": "#d6d3d1",
+        "description": "Focus indicators — mirrors interactive.primary"
+      }
+    }
+  },
+  "spacing": {
+    "xs": {
+      "value": "0.25rem"
+    },
+    "sm": {
+      "value": "0.5rem"
+    },
+    "md": {
+      "value": "1rem"
+    },
+    "lg": {
+      "value": "1.5rem"
+    },
+    "xl": {
+      "value": "2rem"
+    },
+    "2xl": {
+      "value": "3rem"
+    },
+    "3xl": {
+      "value": "4rem"
+    }
+  },
+  "radius": {
+    "sm": {
+      "value": "0.25rem"
+    },
+    "md": {
+      "value": "0.5rem"
+    },
+    "lg": {
+      "value": "0.75rem"
+    },
+    "xl": {
+      "value": "1rem"
+    },
+    "full": {
+      "value": "9999px"
+    }
+  },
+  "contrast": {
+    "high": {
+      "light": "rgb(20, 20, 16)",
+      "dark": "rgb(237, 237, 235)",
+      "description": "Maximum contrast text - accessibility focus"
+    },
+    "readable": {
+      "light": "rgb(20, 20, 16)",
+      "dark": "rgb(237, 237, 235)",
+      "description": "Comfortable reading contrast - primary text"
+    },
+    "medium": {
+      "light": "#7c7c7c",
+      "dark": "#83838f",
+      "description": "Medium emphasis - secondary information"
+    },
+    "subtle": {
+      "light": "#7c7c7c",
+      "dark": "#83838f",
+      "description": "De-emphasized text - captions, meta info"
+    }
+  },
+  "shadow": {
+    "sm": {
+      "value": "0 1px 2px 0 rgb(0 0 0 / 0.05)"
+    },
+    "md": {
+      "value": "0 4px 6px -1px rgb(0 0 0 / 0.1)"
+    },
+    "lg": {
+      "value": "0 10px 15px -3px rgb(0 0 0 / 0.1)"
+    },
+    "xl": {
+      "value": "0 20px 25px -5px rgb(0 0 0 / 0.1)"
+    }
+  },
+  "border": {
+    "subtle": {
+      "light": "rgba(20, 20, 16, 0.1)",
+      "dark": "rgba(237, 237, 235, 0.1)",
+      "description": "Subtle borders - element separation"
+    },
+    "moderate": {
+      "light": "rgba(20, 20, 16, 0.15)",
+      "dark": "rgba(237, 237, 235, 0.15)",
+      "description": "Moderate borders - defined boundaries"
+    },
+    "focus": {
+      "light": "#3498DB",
+      "dark": "#4FC3F7",
+      "description": "Focus indicators - accessibility"
+    }
+  },
+  "transition": {
+    "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"
+    }
+  },
+  "card": {
+    "background": "surface.elevated",
+    "padding": "spacing.component.padding",
+    "radius": "radius.component",
+    "shadow": "shadow.moderate",
+    "border": "border.subtle",
+    "description": "Card component tokens - references semantic tokens"
+  },
+  "button": {
+    "padding-x": "spacing.component.padding",
+    "padding-y": "spacing.micro.normal",
+    "radius": "radius.component",
+    "font-weight": "typography.weight.medium",
+    "primary": {
+      "background": "interactive.primary",
+      "text": "content.inverse",
+      "hover": "interactive.hover"
+    },
+    "secondary": {
+      "background": "surface.elevated",
+      "text": "content.primary",
+      "hover": "surface.page"
+    }
+  },
+  "navbar": {
+    "background": "surface.navbar",
+    "background-scrolled": "surface.navbar-scrolled",
+    "text": "content.secondary",
+    "text-hover": "interactive.accent",
+    "transition": "transition.smooth"
+  },
+  "navigation": {
+    "item-spacing": "spacing.micro.loose",
+    "hover-background": {
+      "light": "rgba(20, 20, 16, 0.05)",
+      "dark": "rgba(237, 237, 235, 0.05)"
+    },
+    "active-background": {
+      "light": "rgba(20, 20, 16, 0.1)",
+      "dark": "rgba(237, 237, 235, 0.1)"
+    }
+  },
+  "font": {
+    "family": {
+      "sans": {
+        "value": "Noto Sans, Fira Sans, system-ui, sans-serif",
+        "description": "Primary sans-serif font - body text. Same as @dataimago/tokens (Noto Sans is neutral)."
+      },
+      "mono": {
+        "value": "JetBrains Mono, SF Mono, Monaco, Inconsolata, monospace",
+        "description": "Monospace font - code blocks and technical content. Same as @dataimago/tokens."
+      },
+      "display": {
+        "value": "var(--font-family-display-editorial)",
+        "description": "Alias of display-editorial. Preserved for naming-parity with @dataimago/tokens; consumers writing `var(--font-family-display)` get sensible neutral output."
+      },
+      "display-editorial": {
+        "value": "Noto Sans, system-ui, sans-serif",
+        "description": "Editorial display family — neutral default. @dataimago/tokens uses Josefin Sans here; @dataimago/tokens-neutral substitutes Noto Sans so externally-owned consumers (Level-3 user apps, third-party Level-2 hubs) ship without inheriting the dataimago house typographic identity. Owners may override by extending the Tailwind preset or redeclaring the CSS variable."
+      },
+      "display-documentation": {
+        "value": "Noto Sans, system-ui, sans-serif",
+        "description": "Documentation display family — Noto Sans. Identical to @dataimago/tokens (this family was already Noto Sans in the house package)."
+      },
+      "brand": {
+        "value": "Noto Sans, system-ui, sans-serif",
+        "description": "Brand font — neutral default. @dataimago/tokens uses Futura for the dataimago navbar wordmark; @dataimago/tokens-neutral substitutes Noto Sans. Owners customize by extending the Tailwind preset."
+      },
+      "math": {
+        "value": "Noto Sans Math, Noto Sans, system-ui, sans-serif",
+        "description": "Mathematical notation font — Noto Sans Math. Same as @dataimago/tokens (neutral by virtue of Noto's broad coverage)."
+      }
+    },
+    "size": {
+      "micro": {
+        "value": "0.75rem",
+        "description": "Micro text - captions, metadata"
+      },
+      "small": {
+        "value": "0.875rem",
+        "description": "Small text - secondary information"
+      },
+      "base": {
+        "value": "1rem",
+        "description": "Base text size - body content"
+      },
+      "readable": {
+        "value": "1.125rem",
+        "description": "Comfortable reading size - main content"
+      },
+      "emphasis": {
+        "value": "1.25rem",
+        "description": "Emphasized text - call-outs"
+      },
+      "heading-small": {
+        "value": "1.5rem",
+        "description": "Small headings - H4, H5"
+      },
+      "heading-medium": {
+        "value": "1.875rem",
+        "description": "Medium headings - H3"
+      },
+      "heading-large": {
+        "value": "2.25rem",
+        "description": "Large headings - H2"
+      },
+      "heading-xl": {
+        "value": "3rem",
+        "description": "Extra large headings - H1"
+      }
+    },
+    "weight": {
+      "extralight": {
+        "value": "200",
+        "description": "Extra-light weight — reserved for display-scale refinements (subtitles, oversized numerals)"
+      },
+      "light": {
+        "value": "300",
+        "description": "Light weight — minor headings (h4–h6), large display at small sizes"
+      },
+      "normal": {
+        "value": "400",
+        "description": "Normal text weight — body content"
+      },
+      "medium": {
+        "value": "500",
+        "description": "Medium weight — emphasis within text"
+      },
+      "semibold": {
+        "value": "600",
+        "description": "Semi-bold — subtitles, important text, default h1/h2 in the neutral stack"
+      },
+      "bold": {
+        "value": "700",
+        "description": "Bold — strong emphasis"
+      },
+      "heading": {
+        "_invariant": "Heading-weight cluster — neutral default uses semibold (600) for h1/h2 because Noto Sans's medium (500) feels light at hero scale where Josefin's medium has geometric character. Owners may override per-heading by extending the Tailwind preset.",
+        "h1": {
+          "value": "var(--font-weight-semibold)",
+          "description": "Heading h1 weight — semibold (600). Neutral default; @dataimago/tokens uses medium (500) tuned for Josefin Sans's geometric voice."
+        },
+        "h2": {
+          "value": "var(--font-weight-semibold)",
+          "description": "Heading h2 weight — semibold (600). Neutral default; @dataimago/tokens uses medium (500)."
+        },
+        "h3": {
+          "value": "var(--font-weight-medium)",
+          "description": "Heading h3 weight — medium (500). Same hierarchy logic as the house package; sized differentiation does the rest."
+        },
+        "h4": {
+          "value": "var(--font-weight-normal)",
+          "description": "Heading h4 weight — normal (400). Minor heading."
+        },
+        "h5": {
+          "value": "var(--font-weight-normal)",
+          "description": "Heading h5 weight — normal (400). Minor heading."
+        },
+        "h6": {
+          "value": "var(--font-weight-normal)",
+          "description": "Heading h6 weight — normal (400). Minor heading."
+        },
+        "subtitle": {
+          "value": "var(--font-weight-semibold)",
+          "description": "Subtitle weight — semibold (600)."
+        }
+      }
+    },
+    "style": {
+      "normal": {
+        "value": "normal",
+        "description": "Normal font style - upright text"
+      },
+      "italic": {
+        "value": "italic",
+        "description": "Italic style - sloped text with true italic glyphs"
+      },
+      "oblique": {
+        "value": "oblique",
+        "description": "Oblique style - sloped text without true italic design"
+      }
+    },
+    "lineHeight": {
+      "tight": {
+        "value": "1.25",
+        "description": "Tight line height - headings"
+      },
+      "normal": {
+        "value": "1.5",
+        "description": "Normal line height - body text"
+      },
+      "relaxed": {
+        "value": "1.625",
+        "description": "Relaxed line height - long-form content"
+      }
+    },
+    "feature-settings": {
+      "_invariant": "OpenType feature settings — neutral defaults. @dataimago/tokens applies lining figures (lnum) to display headings to correct Josefin Sans's old-style default figures; Noto Sans uses uniform-baseline figures natively, so the neutral package emits `normal` for both display and body.",
+      "display": {
+        "value": "\"normal\"",
+        "description": "Default figure style for display headings (neutral default). Noto Sans's native figures are uniform-baseline; no lnum override needed."
+      },
+      "body": {
+        "value": "\"normal\"",
+        "description": "Default figure style for body text (neutral default)."
+      }
+    }
+  }
+};
+module.exports = tokens;
+module.exports.default    = tokens;
+module.exports.color      = tokens.color;
+module.exports.font       = tokens.font;
+module.exports.spacing    = tokens.spacing;
+module.exports.radius     = tokens.radius;
+module.exports.shadow     = tokens.shadow;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+// Auto-generated by packages/tokens-neutral/build.mjs — do not edit.
+declare const tokens: {
+  color?: Record<string, any>;
+  font?: Record<string, any>;
+  spacing?: Record<string, any>;
+  radius?: Record<string, any>;
+  shadow?: Record<string, any>;
+  [key: string]: any;
+};
+export default tokens;
+export declare const color: typeof tokens.color;
+export declare const font: typeof tokens.font;
+export declare const spacing: typeof tokens.spacing;
+export declare const radius: typeof tokens.radius;
+export declare const shadow: typeof tokens.shadow;