@dataimago/tokens-neutral 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,69 @@
+# @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
+- `dist/tokens.dtcg.json` — additive DTCG-style export for tools and agents
+- `dist/{spacing,effects,frequent,components}.json` — inherited non-identity token files copied from `@dataimago/tokens` so public subpath exports resolve from this package
+
+## Related
+
+- [`@dataimago/tokens`](../tokens) — dataimago house identity
+- [`@dataimago/css-neutral`](../css-neutral) — compiled CSS + Tailwind preset built from this package

package/dist/colors.json

@@ -0,0 +1,134 @@
+{
+  "color": {
+    "palette": {
+      "ink": {
+        "50": {
+          "value": "#f5f5f4",
+          "description": "Ink scale — warmest near-white"
+        },
+        "100": {
+          "value": "#e7e5e4",
+          "description": "Ink scale — subtle neutral surface tint"
+        },
+        "200": {
+          "value": "#d6d3d1",
+          "description": "Ink scale — borders, dividers on light surfaces"
+        },
+        "300": {
+          "value": "#a8a29e",
+          "description": "Ink scale — muted text on dark surfaces"
+        },
+        "400": {
+          "value": "#78716c",
+          "description": "Ink scale — secondary text on dark surfaces"
+        },
+        "500": {
+          "value": "#57534e",
+          "description": "Ink scale — secondary text on light surfaces"
+        },
+        "600": {
+          "value": "#44403c",
+          "description": "Ink scale — primary text on mid surfaces"
+        },
+        "700": {
+          "value": "#292524",
+          "description": "Ink scale — primary text, high contrast; neutral interactive primary"
+        },
+        "800": {
+          "value": "#1c1917",
+          "description": "Ink scale — surfaces in dark mode"
+        },
+        "900": {
+          "value": "#0c0a09",
+          "description": "Ink scale — near-black; primary dark surface and text color"
+        }
+      },
+      "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)"
+        },
+        "200": {
+          "value": "#dcdcda",
+          "description": "Stone scale — borders, dividers"
+        },
+        "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"
+        },
+        "600": {
+          "value": "#5e5e5c",
+          "description": "Stone scale — caption / metadata text on light surfaces"
+        },
+        "700": {
+          "value": "#424240",
+          "description": "Stone scale — primary text on light surfaces"
+        },
+        "800": {
+          "value": "#292927",
+          "description": "Stone scale — high-contrast headings on light surfaces"
+        },
+        "900": {
+          "value": "#14140f",
+          "description": "Stone scale — body text on light surfaces"
+        }
+      },
+      "paper": {
+        "50": {
+          "value": "#fefdfb",
+          "description": "Paper scale — lightest warm surface; elevated cards/modals when warm tint is desired"
+        },
+        "100": {
+          "value": "#fdf9f2",
+          "description": "Paper scale — warm page-background option"
+        },
+        "200": {
+          "value": "#faf2e3",
+          "description": "Paper scale — code-block and pull-quote background"
+        },
+        "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"
+        }
+      }
+    },
+    "functional": {
+      "success": {
+        "value": "#27AE60",
+        "description": "Success states and positive actions"
+      },
+      "warning": {
+        "value": "#F39C12",
+        "description": "Warning states and caution"
+      },
+      "error": {
+        "value": "#E74C3C",
+        "description": "Error states and critical issues"
+      },
+      "info": {
+        "value": "#3498DB",
+        "description": "Informational content"
+      }
+    }
+  }
+}

package/dist/components.json

@@ -0,0 +1,44 @@
+{
+  "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)"
+    }
+  }
+}

package/dist/effects.json

@@ -0,0 +1,54 @@
+{
+  "shadow": {
+    "subtle": {
+      "light": "0 1px 2px 0 rgb(20 20 16 / 0.05)",
+      "dark": "0 1px 2px 0 rgb(237 237 235 / 0.03)",
+      "description": "Subtle elevation - barely perceptible"
+    },
+    "moderate": {
+      "light": "0 4px 6px -1px rgb(20 20 16 / 0.1)",
+      "dark": "0 4px 6px -1px rgb(237 237 235 / 0.05)",
+      "description": "Moderate elevation - cards, dropdowns"
+    },
+    "prominent": {
+      "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"
+    }
+  },
+  "border": {
+    "subtle": {
+      "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.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",
+      "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"
+    }
+  }
+}

package/dist/frequent.json

@@ -0,0 +1,51 @@
+{
+  "spacing": {
+    "component": {
+      "padding": "1rem",
+      "margin": "1.5rem",
+      "gap": "0.75rem",
+      "description": "Most frequently adjusted spacing - component internals"
+    },
+    "layout": {
+      "section": "3rem",
+      "container": "2rem",
+      "comfortable": "1rem",
+      "description": "Layout-level spacing - between major elements"
+    },
+    "micro": {
+      "tight": "0.25rem",
+      "normal": "0.5rem",
+      "loose": "1rem",
+      "description": "Fine-tuning spacing - when things feel cramped or loose"
+    }
+  },
+  "radius": {
+    "component": "0.5rem",
+    "subtle": "0.25rem",
+    "prominent": "0.75rem",
+    "full": "9999px",
+    "description": "Border radius values - component rounding"
+  },
+  "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"
+    }
+  }
+}