@neuravision/construct 2.0.2 → 2.1.1

package/tokens/README.md

@@ -1,179 +1,183 @@
 # Construct Design Tokens
 
-Design tokens are the single source of truth for all design decisions in the Construct Design System. They provide consistent values for colors, typography, spacing, and more across all applications.
+Construct tokens are the source of truth for reusable visual decisions. The pipeline validates and resolves three layers into CSS custom properties plus JSON, JavaScript, and TypeScript exports.
 
-## Design Direction
+## Three-layer architecture
 
-- **Enterprise-grade**: Clean, professional, high-trust aesthetic
-- **Ocean primary**: Deep, authoritative blue for key actions
-- **Teal accent**: Modern, clear accent for highlights
-- **Slate neutrals**: Versatile grays for typography and surfaces
+| Layer | Source | Responsibility | Example |
+| --- | --- | --- | --- |
+| Primitive | `primitives.json` | Raw, context-free scales | `space.4`, `color.orange.500` |
+| Semantic | `semantic.*.json` | Theme-aware purpose | `color.background.canvas`, `color.focus.ring` |
+| Component | `components.json` | Stable component decisions | `button.height`, `control.borderFocus` |
 
-## Files
-
-- **`primitives.json`**: Raw values (color palettes, typography scale, spacing, radius, shadows, layout)
-- **`semantic.light.json`**: Semantic mappings for light theme (brand, text, background, state colors)
-- **`semantic.dark.json`**: Dark theme overrides (color + theme metadata)
-- **`semantic.high-contrast.json`**: High-contrast theme overrides (color + theme metadata)
-- **`tokens.css`**: Generated CSS Custom Properties (ready for import)
-- **`tokens.json`**: Generated, resolved token values with units (for tooling)
-- **`tokens.js`**: Generated JavaScript module for runtime imports
-- **`tokens.ts`**: Generated TypeScript definitions and typed exports
+References flow down the architecture: semantic tokens can reference primitives; component tokens can reference semantic tokens or primitives. A lower layer must never reference a higher layer.
 
-## Two-Tier Token System
+```jsonc
+// Primitive
+{ "space": { "4": 8 } }
 
-### Primitives
-Raw design values that form the foundation:
+// Semantic
+{ "color": { "background": { "canvas": "{color.stone.50}" } } }
 
-```json
-{
-  "color": {
-    "ocean": {
-      "700": "#174C5D"
-    }
-  },
-  "space": {
-    "4": 8
-  }
-}
+// Component
+{ "button": { "height": "{size.controlHeight.md}" } }
 ```
 
-### Semantic
-Contextual tokens that reference primitives:
+The generated CSS names follow the same distinction:
 
-```json
-{
-  "color": {
-    "brand": {
-      "primary": "{color.ocean.700}"
-    }
-  }
-}
+```css
+--space-4: 8px;
+--color-bg-canvas: var(--color-stone-50);
+--component-button-height: var(--control-height-md);
 ```
 
-This approach means:
-- **Primitives** rarely change (your color palette)
-- **Semantic** tokens can be remapped for themes without touching primitives
-- Consistency is enforced automatically
+## Files
 
-## Usage
+### Authored sources
 
-### CSS
+- `primitives.json`
+- `semantic.light.json`
+- `semantic.dark.json`
+- `semantic.high-contrast.json`
+- `components.json`
 
-Import the generated CSS file:
+### Generated outputs
 
-```css
-@import "@neuravision/construct/tokens/tokens.css";
+- `tokens.css` — primitive, semantic, component, built-in theme, and system-preference custom properties
+- `tokens.json` — resolved values and metadata for tooling
+- `tokens.js` — runtime ESM exports
+- `tokens.ts` — typed, literal-preserving TypeScript exports
 
-body {
-  font-family: var(--font-family-body);
-  color: var(--color-text-primary);
-  background: var(--color-bg-canvas);
-}
+Never hand-edit generated outputs. Change source JSON and run `npm run build`.
 
-.button {
-  background: var(--color-brand-primary);
-  padding: var(--space-4) var(--space-6);
-  border-radius: var(--radius-control);
-}
-```
+### Schemas
 
-### Themes
+The published `schemas/` directory contains JSON Schema contracts for primitives, semantics, components, and product themes. `schemas/examples/theme.example.json` is a neutral custom-theme input suitable for editor validation and CI examples.
 
-Construct ships with light (default), dark, and high-contrast themes. The generated CSS includes theme overrides and system preference fallbacks.
+## CSS usage
 
-```html
-<html data-theme="dark">
-  ...
-</html>
-```
-
-Available values:
-- `light` (default)
-- `dark`
-- `high-contrast`
-
-If no `data-theme` is set, the system preferences are respected:
-- `prefers-color-scheme: dark` → dark theme
-- `prefers-contrast: more` → high-contrast theme
+```css
+@import '@neuravision/construct/tokens/tokens.css';
 
-### TypeScript/JavaScript
+.product-panel {
+  color: var(--color-text-primary);
+  background: var(--color-bg-surface);
+  padding: var(--space-6);
+  border-radius: var(--radius-card);
+}
+```
 
-Import the generated token module:
+Use semantic tokens in product CSS. Use component tokens when adapting the documented contract of that component. Primitive tokens are appropriate for scale-based values without product meaning, not as a shortcut around semantic intent.
+
+## JavaScript and TypeScript
+
+```ts
+import {
+  componentThemes,
+  components,
+  cssVars,
+  semantic,
+  semanticThemes,
+  tokenMetadata,
+  tokens,
+} from '@neuravision/construct/tokens';
+
+console.log(tokenMetadata.layers); // ['primitives', 'semantic', 'components']
+console.log(semantic.color.brand.primary); // resolved light-theme value
+console.log(components.button.height); // resolved component value
+console.log(cssVars.components.button.height); // var(--component-button-height)
+console.log(semanticThemes.dark.color.background.canvas);
+console.log(componentThemes.highContrast.metric.background);
+console.log(tokens.metadata.themes);
+```
 
-```typescript
-import { tokens, cssVars } from '@neuravision/construct/tokens/tokens';
+`tokens` contains `metadata`, `primitives`, `semantic`, `components`, `semanticThemes`, `componentThemes`, and `cssVars`. Named exports provide the same maps for tree-shakeable tooling.
 
-// Use resolved values
-console.log(tokens.semantic.color.brand.primary); // "#174C5D"
+## Built-in themes
 
-// Or use CSS variable references
-console.log(cssVars.semantic.color.brand.primary); // "var(--color-brand-primary)"
+Construct ships `light`, `dark`, and `high-contrast` scopes:
 
-// Access full theme maps
-console.log(tokens.semanticThemes.dark.color.background.canvas);
+```html
+<html data-theme="dark">…</html>
 ```
 
-## Building Tokens
+Themes can also be nested on containers. Every explicit theme scope declares the complete semantic and component contract, so light inside dark, high-contrast inside light, and custom themes inside any parent do not leak inherited values.
 
-The build script generates CSS, JSON, JavaScript, and TypeScript outputs from the source token files.
+With no explicit `data-theme`, root-level `prefers-color-scheme: dark` and `prefers-contrast: more` preferences apply automatically.
 
-### Run Build
+## Custom product themes
 
-From repository root:
-```bash
-node design/scripts/build-tokens.mjs
-```
+A custom theme extends one built-in theme and overrides only known semantic and/or component paths.
 
-From `design/` directory:
-```bash
-npm run build
+```json
+{
+  "$schema": "./node_modules/@neuravision/construct/schemas/theme.schema.json",
+  "name": "acme",
+  "extends": "light",
+  "semantic": {
+    "color": {
+      "brand": {
+        "primary": "{color.ocean.700}",
+        "primaryHover": "{color.ocean.800}",
+        "primaryActive": "{color.ocean.900}"
+      }
+    }
+  },
+  "components": {
+    "button": {
+      "radius": "{radius.pill}"
+    }
+  },
+  "contrast": [
+    {
+      "name": "button label",
+      "foreground": "components.button.color",
+      "background": "components.button.background",
+      "minRatio": 4.5
+    }
+  ]
+}
 ```
 
-### Check if Up-to-Date (CI)
-
-Verify outputs match sources without rebuilding:
+Compile it from the consuming project:
 
 ```bash
-npm run check
+npx construct-theme \
+  --theme ./acme.theme.json \
+  --out-dir ./src/generated/construct-theme
 ```
 
-This command exits with a non-zero code if outputs are outdated, making it perfect for CI/CD pipelines.
-
-## Token Naming Conventions
+Import the generated token sheet after every Construct style entry. Foundations, the full component bundle, and standalone component entries each pull in the built-in tokens; loading the generated file last prevents those imports from overriding a custom root scope:
 
-### CSS Variables
+```css
+@import '@neuravision/construct/foundations.css';
+@import '@neuravision/construct/components/button.css';
+@import './generated/construct-theme/tokens.css';
+```
 
-Tokens are converted to kebab-case CSS variables:
+Product CSS that intentionally overrides Construct tokens belongs after the generated sheet.
 
-- Primitives: `--color-ocean-700`, `--space-4`, `--radius-md`
-- Semantic: `--color-brand-primary`, `--color-text-primary`, `--color-bg-canvas`
+Repeat `--theme` to include multiple product themes. Without `--out-dir`, the public CLI writes to `./construct-theme`. Use `--validate-only` in fast checks, `--check` to compare an existing output directory, and `--report-contrast` for a ratio report.
 
-### TypeScript
+The compiler rejects invalid schemas, unknown or missing paths, circular/missing references, duplicate names/selectors, unsafe or invalid scope selectors, structurally unsafe CSS literals, invalid typed color/length/weight/shadow values, and failing built-in or declared contrast pairs before it writes output. Custom selectors intentionally support one simple scope (`:root`, a class/id, or a `data-*` attribute selector) rather than arbitrary selector programs.
 
-Tokens are available as nested objects with camelCase properties:
+## Repository commands
 
-```typescript
-tokens.primitives.color.ocean[700]
-tokens.semantic.color.brand.primary
-cssVars.semantic.color.brand.primary
+```bash
+npm run build            # generate tokens and standalone component entries
+npm run tokens:validate  # schema, references, theme shape, contrast
+npm run tokens:test      # positive and negative pipeline contracts
+npm run check            # all non-mutating package contracts
 ```
 
-## Brand Guidance
+## Font families
 
-- **Primary**: Use for key actions, primary buttons, and main navigation
-- **Accent**: Use sparingly for highlights, special emphasis, and interactive elements
-- **Backgrounds**: Prefer `surface` and `muted` for large content areas
-- **Text**: Use `primary` for body text, `secondary` for less important text, `muted` for hints
+Token output includes resilient local/system fallback stacks. Foundations make no network request. See [Font loading and self-hosting](../docs/fonts.md) for the optional hosted preset and self-hosting pattern.
 
 ## Versioning
 
-Tokens follow Semantic Versioning:
-
-- **MAJOR**: Removing/renaming tokens or changing existing token values
-- **MINOR**: Adding new tokens, scales, or semantic aliases
-- **PATCH**: Documentation, build scripts, internal changes (no token value changes)
-
----
+- **Major:** remove/rename a token or change a public token's meaning.
+- **Minor:** add a token, layer capability, or backward-compatible theme feature.
+- **Patch:** fix generation or validation without changing the documented output contract.
 
-**Construct** - Build accessible design constructs
+Value changes are evaluated by consumer impact. A contrast correction may require a minor release even when names remain stable because it changes rendered product color.

package/tokens/components.json

@@ -0,0 +1,54 @@
+{
+  "button": {
+    "background": "{color.brand.primary}",
+    "backgroundHover": "{color.brand.primaryHover}",
+    "backgroundActive": "{color.brand.primaryActive}",
+    "border": "{color.brand.primary}",
+    "color": "{color.text.onPrimary}",
+    "height": "{size.controlHeight.md}",
+    "paddingX": "{space.6}",
+    "fontSize": "{font.size.sm}",
+    "lineHeight": "{font.lineHeight.sm}",
+    "fontWeight": "{font.weight.semibold}",
+    "radius": "{radius.control}",
+    "gap": "{space.3}",
+    "loadingSpinnerSize": "{size.icon.md}"
+  },
+  "control": {
+    "background": "{color.background.elevated}",
+    "backgroundHover": "{color.background.surface}",
+    "backgroundDisabled": "{color.background.muted}",
+    "border": "{color.border.default}",
+    "borderHover": "{color.border.strong}",
+    "borderFocus": "{color.focus.ring}",
+    "text": "{color.text.primary}",
+    "placeholder": "{color.text.muted}",
+    "radius": "{radius.control}"
+  },
+  "card": {
+    "background": "{color.background.elevated}",
+    "border": "{color.border.subtle}",
+    "radius": "{radius.card}",
+    "padding": "{space.6}",
+    "shadow": "{shadow.card}",
+    "shadowHover": "{shadow.dropdown}"
+  },
+  "status": {
+    "gap": "{space.2}",
+    "fontSize": "{font.size.sm}",
+    "iconSize": "{size.icon.sm}"
+  },
+  "metric": {
+    "background": "{color.background.elevated}",
+    "border": "{color.border.subtle}",
+    "radius": "{radius.card}",
+    "padding": "{space.6}",
+    "valueFontSize": "{font.size.2xl}",
+    "labelFontSize": "{font.size.sm}"
+  },
+  "meter": {
+    "height": "{space.3}",
+    "radius": "{radius.pill}",
+    "track": "{color.background.muted}"
+  }
+}

package/tokens/primitives.json

@@ -0,0 +1,268 @@
+{
+  "color": {
+    "stone": {
+      "0": "#FFFFFF",
+      "50": "#FAFAF8",
+      "100": "#F1F0EB",
+      "200": "#E4E2DB",
+      "300": "#D3D0C7",
+      "400": "#B4AFA1",
+      "500": "#8E887A",
+      "600": "#66604E",
+      "700": "#4B473E",
+      "800": "#353128",
+      "900": "#211E18",
+      "950": "#16130F"
+    },
+    "orange": {
+      "50": "#FFF1EA",
+      "100": "#FFDFCE",
+      "200": "#FFBE9C",
+      "300": "#FF9462",
+      "400": "#FB6E2E",
+      "500": "#F4581C",
+      "600": "#DD4A0F",
+      "700": "#B23C0C",
+      "800": "#882D09",
+      "900": "#5C1E06"
+    },
+    "ocean": {
+      "50": "#EAF1FB",
+      "100": "#CFE0F4",
+      "200": "#A6C6EA",
+      "300": "#76A6DC",
+      "400": "#4584CC",
+      "500": "#2A68B5",
+      "600": "#1F5BA6",
+      "700": "#184780",
+      "800": "#123356",
+      "900": "#0C2238"
+    },
+    "teal": {
+      "50": "#E7F7F6",
+      "100": "#C5ECEA",
+      "200": "#93DAD6",
+      "300": "#63C7C1",
+      "400": "#35B2AA",
+      "500": "#1C9891",
+      "600": "#167B76",
+      "700": "#115F5C",
+      "800": "#0D4744",
+      "900": "#0A3533"
+    },
+    "amber": {
+      "50": "#FBF3D6",
+      "100": "#F6E3A6",
+      "200": "#EDC85F",
+      "300": "#DFAB1F",
+      "400": "#C8930A",
+      "500": "#A87A00",
+      "600": "#876200",
+      "700": "#694B00",
+      "800": "#4B3500",
+      "900": "#2F2100"
+    },
+    "red": {
+      "50": "#FCE9ED",
+      "100": "#F7C6CF",
+      "200": "#EF98A8",
+      "300": "#E4647C",
+      "400": "#D43B57",
+      "500": "#BE1F3D",
+      "600": "#9C1631",
+      "700": "#771025",
+      "800": "#530B19",
+      "900": "#330610"
+    },
+    "green": {
+      "50": "#E8F6EF",
+      "100": "#C7EAD9",
+      "200": "#9EDCC0",
+      "300": "#70CBA3",
+      "400": "#48B988",
+      "500": "#2EA070",
+      "600": "#237F59",
+      "700": "#1B6145",
+      "800": "#134533",
+      "900": "#0C2E22"
+    },
+    "purple": {
+      "50": "#F4EFFA",
+      "100": "#E5D7F4",
+      "200": "#C9B0E6",
+      "300": "#A988D6",
+      "400": "#8961C2",
+      "500": "#6F45A8",
+      "600": "#5A3789",
+      "700": "#432868",
+      "800": "#2D1A48",
+      "900": "#1A0F2C"
+    },
+    "pink": {
+      "50": "#FBEEF3",
+      "100": "#F5CDDC",
+      "200": "#EA9CB7",
+      "300": "#DD6F92",
+      "400": "#CD4671",
+      "500": "#B22F58",
+      "600": "#8E2244",
+      "700": "#6A1932",
+      "800": "#461020",
+      "900": "#29080F"
+    }
+  },
+  "font": {
+    "family": {
+      "brand": "Lato",
+      "text": "Lato",
+      "mono": "JetBrains Mono"
+    },
+    "weight": {
+      "regular": 400,
+      "medium": 500,
+      "semibold": 600,
+      "bold": 700,
+      "extrabold": 800
+    },
+    "size": {
+      "2xs": 10,
+      "xs": 12,
+      "sm": 14,
+      "md": 16,
+      "lg": 18,
+      "xl": 20,
+      "2xl": 24,
+      "3xl": 28,
+      "4xl": 32,
+      "5xl": 40,
+      "6xl": 48
+    },
+    "lineHeight": {
+      "2xs": 14,
+      "xs": 16,
+      "sm": 20,
+      "md": 24,
+      "lg": 28,
+      "xl": 32,
+      "2xl": 36,
+      "3xl": 40,
+      "4xl": 44,
+      "5xl": 52,
+      "6xl": 60
+    },
+    "letterSpacing": {
+      "tight": -0.3,
+      "normal": 0,
+      "wide": 0.3
+    }
+  },
+  "space": {
+    "0": 0,
+    "1": 2,
+    "2": 4,
+    "3": 6,
+    "4": 8,
+    "5": 12,
+    "6": 16,
+    "7": 20,
+    "8": 24,
+    "9": 32,
+    "10": 40,
+    "11": 48,
+    "12": 64,
+    "13": 80
+  },
+  "radius": {
+    "xs": 2,
+    "sm": 4,
+    "md": 8,
+    "lg": 12,
+    "xl": 16,
+    "2xl": 24,
+    "round": 999
+  },
+  "border": {
+    "width": {
+      "thin": 1,
+      "medium": 2,
+      "thick": 3
+    }
+  },
+  "opacity": {
+    "muted": 0.7,
+    "disabled": 0.5,
+    "overlay": 0.6
+  },
+  "size": {
+    "controlHeight": {
+      "xs": 28,
+      "sm": 32,
+      "md": 40,
+      "lg": 48,
+      "calendarDay": 36
+    },
+    "icon": {
+      "sm": 16,
+      "md": 20,
+      "lg": 24,
+      "xl": 32
+    }
+  },
+  "layout": {
+    "container": {
+      "sm": 640,
+      "md": 960,
+      "lg": 1200,
+      "xl": 1440
+    },
+    "gutter": {
+      "sm": 16,
+      "md": 24,
+      "lg": 32
+    },
+    "gridGap": {
+      "sm": 16,
+      "md": 24,
+      "lg": 32
+    },
+    "navbar": {
+      "height": 56
+    }
+  },
+  "shadow": {
+    "xs": "0 1px 2px rgba(28, 20, 10, 0.07)",
+    "sm": "0 2px 6px rgba(28, 20, 10, 0.09)",
+    "md": "0 8px 20px rgba(28, 20, 10, 0.11)",
+    "lg": "0 16px 36px rgba(28, 20, 10, 0.13)",
+    "xl": "0 24px 56px rgba(28, 20, 10, 0.17)"
+  },
+  "motion": {
+    "duration": {
+      "fast": 120,
+      "normal": 200,
+      "slow": 280,
+      "xslow": 400
+    },
+    "easing": {
+      "standard": "cubic-bezier(0.2, 0, 0, 1)",
+      "decelerate": "cubic-bezier(0, 0, 0, 1)",
+      "accelerate": "cubic-bezier(0.3, 0, 1, 1)"
+    }
+  },
+  "zIndex": {
+    "base": 0,
+    "dropdown": 1000,
+    "sticky": 1100,
+    "overlay": 1200,
+    "modal": 1300,
+    "toast": 1400,
+    "tooltip": 1500
+  },
+  "breakpoint": {
+    "xs": 360,
+    "sm": 600,
+    "md": 900,
+    "lg": 1200,
+    "xl": 1536
+  }
+}