@phcdevworks/spectre-tokens 2.0.0 → 2.1.0

package/README.md

@@ -1,20 +1,33 @@
 # @phcdevworks/spectre-tokens
 
-JSON-first design tokens that power Spectre UI, Spectre Blocks, Spectre Astro, Spectre 11ty, and every future Spectre surface.
+### **The DNA (Layer 1 of the Spectre 8-Layer Arsenal)**
 
-🤝 **[Contributing Guide](CONTRIBUTING.md)** | 📝 **[Changelog](CHANGELOG.md)** | 🎨 **[Token Examples](example/examples.md)**
+`@phcdevworks/spectre-tokens` is the Single Source of Truth for the entire Spectre ecosystem. It defines the visual language—colors, typography, space, and semantic roles—that all other layers consume.
 
-## Overview
+🤝 **[Contributing Guide](CONTRIBUTING.md)** | 📝 **[Changelog](CHANGELOG.md)** | 🏛️ **[Spectre Arsenal](https://github.com/phcdevworks)**
 
-`@phcdevworks/spectre-tokens` defines Spectre's visual language—colors, typography, space, radii, shadows, breakpoints, z-index scales, transitions, and CRO-focused interaction states. The package turns the raw JSON tokens in `tokens/` into multiple consumption modes (JS, TS, Tailwind, CSS variables) so teams can stay in sync regardless of framework.
+---
+
+## 🏗️ Core Architecture
+
+This package is the foundation. It follows a strict **JSON-First** policy—authoritative values live in `tokens/` and are transformed into multiple consumption modes (CSS, JS/TS, Tailwind).
+
+- 🧬 **Authoritative JSON**: Domain-specific token storage for better maintainability.
+- 🧪 **Type-Safe DNA**: 100% strict TypeScript interfaces derived directly from JSON.
+- 🌪️ **Multi-Format Output**: Generates CSS Variables, Tailwind Presets, and ESM/CJS exports.
+- ♿ **Accessibility First**: Encodes WCAG constraints (contrast, touch targets) at the token level.
+
+---
 
 **Single source of truth:** JSON is the source. Everything else is generated.
 
-- ✅ Centralized token definitions and semantic naming
-- ✅ JS/TS objects, Tailwind theme + preset, and CSS variable outputs
-- ✅ CRO-focused surfaces (buttons, forms, states) and accessibility-first tokens
-- ✅ Helpers for scoped CSS variable generation
-- ✅ Type-safe outputs with bundled `.d.ts` files
+- ✅ **Modular Architecture**: domain-specific token storage for better maintainability
+- ✅ **AI-Ready DNA**: Zero `any` types and 100% strict TypeScript build process
+- ✅ **Auto-Generated Typings**: Strictly-typed TS interfaces derived directly from JSON
+- ✅ **Multi-File Merging**: Type-safe merging of cross-domain token references
+- ✅ **JS/TS objects**, Tailwind theme + preset, and CSS variable outputs
+- ✅ **CRO-focused surfaces** (buttons, forms, states) and accessibility-first tokens
+- ✅ **Type-safe outputs** with bundled `.d.ts` files
 
 ## Installation
 
@@ -132,7 +145,7 @@ The `tokens` object includes:
 - `opacity`: Opacity scale (hover, active, disabled, focus, overlay, tooltip)
 - `borders`: Border color tokens
 - `surface`: Semantic surface backgrounds (page, card, input, overlay)
-- `text`: Semantic text colors (onPage, onSurface with default/muted/subtle/meta)
+- `text`: Semantic text colors (onPage, onSurface with default/muted/subtle/meta/**brand**)
 - `component`: Component-specific tokens (card, input, button, badge, iconBox)
 - `modes`: Theme mode definitions (default/light and dark)
 
@@ -429,6 +442,7 @@ For secondary/metadata text styling:
 ```ts
 tokens.text.onPage.meta; // Metadata text on page backgrounds
 tokens.text.onSurface.meta; // Metadata text on card/surface backgrounds
+tokens.text.onPage.brand; // Brand accent text on page canvas
 ```
 
 ```css
@@ -744,12 +758,12 @@ tokens.borders.input; // "#cbd5f5"
 
 | Folder     | Responsibility                                                                                                |
 | ---------- | ------------------------------------------------------------------------------------------------------------- |
-| `tokens/`  | Raw JSON token files owned by design (e.g. `core.json`, modes, component semantics).                          |
+| `tokens/`  | Raw JSON token files (modularized as `palette.json`, `typography.json`, `components.json`, etc.).             |
 | `src/`     | TypeScript source that turns JSON into reusable formats (JS/TS exports, Tailwind theme, CSS helpers).         |
-| `scripts/` | Build utilities. `build-css.js` consumes the compiled library and writes `dist/index.css`.                    |
+| `scripts/` | Build utilities and strictly-typed token merging engines.                                                     |
 | `dist/`    | Generated artifacts: `index.js`, `index.cjs`, `index.d.ts`, and `index.css`. Regenerated via `npm run build`. |
 
-Designers only touch the JSON under `tokens/`. Engineering evolves `src/` + `scripts/` when structure changes.
+Designers only touch the JSON under `tokens/`. Engineering evolves `src/` + `scripts/` when structure or transforms change.
 
 ## Build & Release
 
@@ -853,7 +867,7 @@ Spectre is a **specification-driven design system** built on three strict layers
 - Designers own `tokens/*.json`; engineers maintain `src/` transforms
 - Contrast targets and accessibility constraints are encoded at the token level
 
-**Status**: v0.1.0 released with stable semantic roles (`surface.*`, `text.*`, `component.*`) and considered correct/locked
+**Status**: v2.0.0 released. Transitioned to modular JSON storage and full AI-readiness.
 
 ### 2. @phcdevworks/spectre-ui (Framework-Agnostic UI Layer)
 
@@ -874,7 +888,7 @@ Spectre is a **specification-driven design system** built on three strict layers
 - Every CSS selector has a matching recipe where applicable
 - Tailwind preset is optional and non-authoritative
 
-**Status**: v0.1.0 released, hardened and aligned to tokens
+**Status**: v1.0.0 hardened and aligned to tokens. v2.0.0 compatibility ready.
 
 ### 3. Adapters (WordPress, Astro, etc.)
 
@@ -1420,7 +1434,7 @@ const customThemeCSS = generateCssVariables(tokens, {
 **Question:** Can I add my own theme modes beyond default/dark?
 
 **Answer:**
-Yes! Extend the `modes` object in your `core.json`:
+Yes! Extend the `modes` object in your `tokens/modes.json`:
 
 ```json
 {
@@ -1488,7 +1502,7 @@ Two approaches:
 Semantic tokens in `modes` use the `{ value: "..." }` format for metadata. The TypeScript library automatically resolves these:
 
 ```ts
-// In core.json: { "value": "#f8fafc" }
+// In tokens/*.json: { "value": "#f8fafc" }
 tokens.surface.page; // Returns "#f8fafc" (string)
 
 // The library handles resolution automatically
@@ -1506,15 +1520,18 @@ Issues and pull requests are welcome. If you are proposing token changes, update
 
 For detailed contribution guidelines, see **[CONTRIBUTING.md](CONTRIBUTING.md)**.
 
-## License
+---
 
-See **[LICENSE](LICENSE)** for details.
+## 🏛️ The Spectre Suite Hierarchy
 
----
+Spectre is built on a non-negotiable hierarchy to prevent style leakage and duplication:
+
+1.  **Layer 1: DNA (This Package)** – The source of truth for all design values.
+2.  **Layer 2: Blueprint (UI)** ([@phcdevworks/spectre-ui](https://github.com/phcdevworks/spectre-ui)) – Translates tokens into CSS structure and recipes.
+3.  **Layer 3: Adapters** (WordPress, Astro, etc.) – Thin bridges that map Layer 2 to specific frameworks.
 
-## ❤️ Support Spectre
+> **The Golden Rule**: Tokens define *meaning*. UI defines *structure*. Adapters define *delivery*.
+
+---
 
-If Spectre Tokens helps your workflow, consider sponsoring:
 
-- [GitHub Sponsors](https://github.com/sponsors/phcdevworks)
-- [Buy Me a Coffee](https://buymeacoffee.com/phcdevworks)

package/dist/index.cjs

@@ -229,6 +229,9 @@ var coreTokens = {
       },
       "textDisabled": {
         "value": "{colors.neutral.400}"
+      },
+      "focusRing": {
+        "value": "{colors.info.500} / 0.4"
       }
     },
     "secondary": {
@@ -258,6 +261,9 @@ var coreTokens = {
       },
       "borderDisabled": {
         "value": "{colors.neutral.200}"
+      },
+      "focusRing": {
+        "value": "{colors.info.500} / 0.4"
       }
     },
     "ghost": {
@@ -278,6 +284,9 @@ var coreTokens = {
       },
       "textDisabled": {
         "value": "{colors.neutral.400}"
+      },
+      "focusRing": {
+        "value": "{colors.info.500} / 0.4"
       }
     },
     "danger": {
@@ -301,6 +310,9 @@ var coreTokens = {
       },
       "textDisabled": {
         "value": "{colors.neutral.400}"
+      },
+      "focusRing": {
+        "value": "{colors.error.500} / 0.4"
       }
     },
     "success": {
@@ -324,6 +336,9 @@ var coreTokens = {
       },
       "textDisabled": {
         "value": "{colors.neutral.400}"
+      },
+      "focusRing": {
+        "value": "{colors.success.500} / 0.4"
       }
     },
     "cta": {
@@ -350,6 +365,9 @@ var coreTokens = {
       },
       "shadow": {
         "value": "0 4px 14px 0 {colors.warning.500} / 0.39"
+      },
+      "focusRing": {
+        "value": "{colors.warning.500} / 0.4"
       }
     },
     "accent": {
@@ -373,6 +391,9 @@ var coreTokens = {
       },
       "textDisabled": {
         "value": "{colors.neutral.400}"
+      },
+      "focusRing": {
+        "value": "{colors.accent.500} / 0.4"
       }
     }
   },
@@ -774,6 +795,9 @@ var coreTokens = {
               "pair": "modes.dark.component.badge.neutralText"
             }
           },
+          "neutralBgHover": {
+            "value": "{colors.neutral.600}"
+          },
           "neutralText": {
             "value": "{colors.neutral.100}",
             "metadata": {}
@@ -784,6 +808,9 @@ var coreTokens = {
               "pair": "modes.dark.component.badge.infoText"
             }
           },
+          "infoBgHover": {
+            "value": "{colors.info.700}"
+          },
           "infoText": {
             "value": "{colors.info.100}",
             "metadata": {}
@@ -794,6 +821,9 @@ var coreTokens = {
               "pair": "modes.dark.component.badge.successText"
             }
           },
+          "successBgHover": {
+            "value": "{colors.success.700}"
+          },
           "successText": {
             "value": "{colors.success.100}",
             "metadata": {}
@@ -804,6 +834,9 @@ var coreTokens = {
               "pair": "modes.dark.component.badge.warningText"
             }
           },
+          "warningBgHover": {
+            "value": "{colors.warning.700}"
+          },
           "warningText": {
             "value": "{colors.warning.100}",
             "metadata": {}
@@ -814,6 +847,9 @@ var coreTokens = {
               "pair": "modes.dark.component.badge.dangerText"
             }
           },
+          "dangerBgHover": {
+            "value": "{colors.error.700}"
+          },
           "dangerText": {
             "value": "{colors.error.100}",
             "metadata": {}
@@ -952,16 +988,16 @@ var coreTokens = {
       "900": "#0f172a"
     },
     "accent": {
-      "50": "#eff6ff",
-      "100": "#dbeafe",
+      "50": "#f5f3ff",
+      "100": "#ede9fe",
       "200": "#ddd6fe",
-      "300": "#93c5fd",
-      "400": "#60a5fa",
+      "300": "#c4b5fd",
+      "400": "#a78bfa",
       "500": "#8b5cf6",
       "600": "#7c3aed",
       "700": "#6d28d9",
-      "800": "#1e40af",
-      "900": "#1e3a8a"
+      "800": "#5b21b6",
+      "900": "#4c1d95"
     },
     "success": {
       "50": "#f0fdf4",
@@ -1169,6 +1205,12 @@ var coreTokens = {
     "card": "{colors.neutral.200}",
     "input": "{colors.neutral.300}"
   },
+  "border": {
+    "width": {
+      "base": "1px",
+      "thick": "2px"
+    }
+  },
   "surface": {
     "page": {
       "value": "{colors.neutral.50}",
@@ -1228,7 +1270,8 @@ var coreTokens = {
         "sm": "1rem",
         "md": "1.5rem",
         "lg": "2rem"
-      }
+      },
+      "maxWidth": "72rem"
     }
   },
   "font": {
@@ -1430,6 +1473,16 @@ var createCssVariableMap = (tokens2, options = {}) => {
         assign(toVariableName(prefix, "layout", "container", "padding-inline", key), value);
       });
     }
+    const container = layout.container;
+    if (container?.maxWidth) {
+      assign(toVariableName(prefix, "layout", "container", "max-width"), container.maxWidth);
+    }
+  }
+  const border = baseTokens.border;
+  if (border?.width) {
+    Object.entries(border.width).forEach(([key, value]) => {
+      assign(toVariableName(prefix, "border", "width", key), value);
+    });
   }
   Object.entries(baseTokens.radii).forEach(([key, value]) => {
     assign(toVariableName(prefix, "radius", key), value);
@@ -1808,7 +1861,7 @@ var createTailwindTheme = (source = tokens) => {
   return {
     colors,
     spacing: { ...source.space ?? {} },
-    borderRadius: { ...source.radii },
+    borderRadius: { ...source.radii ?? {} },
     fontFamily,
     fontSize,
     boxShadow: { ...source.shadows },
@@ -1816,7 +1869,14 @@ var createTailwindTheme = (source = tokens) => {
     zIndex: { ...source.zIndex },
     transitionDuration: { ...source.transitions.duration },
     transitionTimingFunction: { ...source.transitions.easing },
-    opacity: { ...source.opacity }
+    opacity: { ...source.opacity },
+    maxWidth: {
+      container: source.layout?.container?.maxWidth
+    },
+    borderWidth: {
+      DEFAULT: source.border?.width.base,
+      ...source.border?.width ?? {}
+    }
   };
 };
 var tailwindTheme = createTailwindTheme(tokens);