@phcdevworks/spectre-tokens 2.5.0 → 2.6.0

package/README.md

@@ -1,8 +1,9 @@
 # @phcdevworks/spectre-tokens
 
-[![GitHub issues](https://img.shields.io/github/issues/phcdevworks/spectre-tokens)](https://github.com/phcdevworks/spectre-tokens/issues)
-[![GitHub pulls](https://img.shields.io/github/issues-pr/phcdevworks/spectre-tokens)](https://github.com/phcdevworks/spectre-tokens/pulls)
+[![npm version](https://img.shields.io/npm/v/@phcdevworks/spectre-tokens)](https://www.npmjs.com/package/@phcdevworks/spectre-tokens)
+[![CI](https://img.shields.io/github/actions/workflow/status/phcdevworks/spectre-tokens/ci.yml?branch=main&label=CI)](https://github.com/phcdevworks/spectre-tokens/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/phcdevworks/spectre-tokens)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%5E22.12.0%20%7C%7C%20%3E%3D24.0.0-brightgreen)](https://nodejs.org)
 
 `@phcdevworks/spectre-tokens` is the design-token package of the Spectre system
 for downstream Spectre packages and compatible applications.
@@ -16,17 +17,22 @@ translate those contracts for specific frameworks and runtimes.
 [Token Contract](TOKEN_CONTRACT.md) | [Roadmap](ROADMAP.md) |
 [Security Policy](SECURITY.md)
 
-## Key capabilities
+## Source of truth
 
-- Uses `tokens/` as the source of truth for design-token data
-- Generates JavaScript, TypeScript, CSS, and Tailwind theme exports from shared
-  token sources
-- Defines semantic token contracts for surfaces, text, components, buttons,
-  forms, and modes
-- Exposes primitives and semantic roles for downstream packages and compatible
-  applications
-- Keeps visual meaning centralized so downstream consumers do not redefine token
-  contracts
+`tokens/` is the source of truth. `contract.manifest.json` is the
+machine-readable contract authority. Everything else is derived from them or
+validated against them.
+
+| Layer | Path | Rule |
+|---|---|---|
+| Source token data | `tokens/*.json` | All token value changes start here — never anywhere else |
+| Contract authority | `contract.manifest.json` | Governs public namespaces and required output surfaces |
+| Public entry points | `src/index.ts` · `src/types.ts` · `src/css.ts` | Contract-authority files — changes require changelog classification |
+| Generated TypeScript | `src/generated/tokens.ts` | **Never edit directly** — regenerated by `npm run build` |
+| Generated dist | `dist/` | **Never edit directly** — regenerated by `npm run build` |
+
+After any source change: run `npm run build` to regenerate outputs, then
+`npm run check` to validate the full contract.
 
 ## What this package owns
 
@@ -40,14 +46,30 @@ This package is the correct place to define token meaning.
 
 ## What this package does not own
 
-- Component structure or composition That belongs in downstream UI packages such
-  as [`@phcdevworks/spectre-ui`](https://github.com/phcdevworks/spectre-ui).
-- Framework-specific delivery Adapter packages translate Spectre contracts for
+- Component structure or composition. That belongs in downstream UI packages
+  such as
+  [`@phcdevworks/spectre-ui`](https://github.com/phcdevworks/spectre-ui).
+- Framework-specific delivery. Adapter packages translate Spectre contracts for
   specific frameworks and runtimes.
-- Local redefinition of token meaning Downstream consumers should consume these
+- Local redefinition of token meaning. Downstream consumers should consume these
   contracts rather than recreate them independently.
-- Example app architecture The `example/` directory documents token usage; it is
-  not the contract source and should not become a downstream UI layer.
+- Example app architecture. The `example/` directory documents token usage; it
+  is not the contract source and should not become a downstream UI layer.
+
+## When to use this package
+
+- You are building a Spectre ecosystem package and need the visual language contract.
+- You need design token values in JavaScript, TypeScript, CSS variables, or a Tailwind theme.
+- You want a single source of truth for semantic roles: `surface`, `text`, `component`, `buttons`, `forms`, `modes`.
+- You are consuming tokens as named values, not inventing new token meaning.
+
+## When not to use this package
+
+- You need UI components or component structure — use
+  [`@phcdevworks/spectre-ui`](https://github.com/phcdevworks/spectre-ui).
+- You need framework-specific component delivery — use the appropriate adapter package.
+- You want to define your own token meaning or override Spectre semantics locally —
+  this package is the authority; downstream consumers should consume, not redefine.
 
 ## Installation
 
@@ -94,14 +116,56 @@ export default {
 }
 ```
 
-## Consumer usage
+## Semantic tokens vs raw palette tokens
+
+Semantic tokens express UI meaning. Raw palette tokens expose the fixed color
+ramp. Always prefer semantic tokens for UI surfaces, text, buttons, forms, and
+mode-aware styling.
 
-### Source of truth
+### Semantic namespaces (prefer for all UI work)
 
-- Change token data in `tokens/`.
-- Treat generated outputs as derived artifacts.
-- Treat `contract.manifest.json` as the machine-readable contract authority for
-  public namespaces and required outputs.
+| Namespace | What it expresses |
+|---|---|
+| `surface` | Background roles: page, card, overlay, sidebar |
+| `text` | Foreground roles: default, muted, subtle, meta, on-surface, on-page |
+| `component` | Role-specific tokens for icon boxes, badges, ratings, testimonials, pricing cards |
+| `buttons` | Button state tokens: default, hover, active, disabled, CTA |
+| `forms` | Form state tokens: default, focused, error, disabled |
+| `modes` | Mode-aware overrides under `modes.default` and `modes.dark` |
+
+```ts
+import tokens from '@phcdevworks/spectre-tokens'
+
+// Semantic — always prefer this for UI
+const card = {
+  background: tokens.surface.card,
+  color: tokens.text.onSurface.default,
+}
+
+// Mode-aware semantic
+const dark = {
+  background: tokens.modes.dark.surface.page,
+  color: tokens.modes.dark.text.onPage.default,
+}
+```
+
+### Raw palette (use sparingly)
+
+The `colors` namespace exposes the raw palette ramp. Use it only when fixed
+color access is intentional — data visualization, compatibility layers, or
+tooling that inspects palette data directly.
+
+```ts
+// Raw palette — only when fixed color access is deliberate
+const chart = {
+  series1: tokens.colors.brand[500],
+  series2: tokens.colors.neutral[300],
+}
+```
+
+Do not use `colors` as a substitute for semantic tokens in normal UI surfaces.
+
+## Consumer usage
 
 ### JavaScript and TypeScript tokens
 
@@ -164,34 +228,6 @@ export default {
 Use `tailwindTheme` directly only when a consumer needs the generated theme
 object outside the preset shape.
 
-### Semantic tokens first
-
-Prefer semantic namespaces for downstream UI work:
-
-- `surface`
-- `text`
-- `component`
-- `buttons`
-- `forms`
-- `modes`
-
-These namespaces are the main consumer-facing contract because they express UI
-meaning rather than raw color selection.
-
-### When raw palette access is acceptable
-
-Raw palette access through `colors` is acceptable when a consumer deliberately
-needs fixed palette values.
-
-Typical cases:
-
-- data visualization or non-semantic decorative use
-- compatibility layers that need a specific raw ramp
-- tooling that inspects or serializes palette data directly
-
-Raw palette access should not replace semantic token usage for normal UI
-surfaces, text, buttons, forms, or mode-aware styling.
-
 ### Token model
 
 The generated token object includes these namespaces:
@@ -260,6 +296,23 @@ Guidance:
 - Do not invent local light/dark token contracts when this package already
   provides the semantic path.
 
+## Protected token families
+
+The following semantic groups are locked. Their values must not change without
+explicit approval from Bradley Potts. This applies to all contributors and all
+AI agents — apparent visual improvements still require human sign-off.
+
+| Protected group | Backed by | Guarded by |
+|---|---|---|
+| `success` | `colors.success` palette | `check:locked` + `check:contrast` |
+| `warning` | `colors.warning` palette | `check:locked` + `check:contrast` |
+| `danger` semantic roles | `colors.error` palette | `check:locked` + `check:contrast` |
+| CTA / primary action / brand-action | `colors.brand` + `buttons.cta` | `check:locked` + `check:contrast` |
+
+`check:locked` fails immediately if any protected value changes from the
+recorded baseline. An intentional change requires updating the baseline as part
+of an approved, classified release.
+
 ## Downstream boundaries
 
 Downstream packages should never redefine locally:
@@ -292,6 +345,19 @@ If a downstream package depends on specific token paths or semantic meaning:
 - read `TOKEN_CONTRACT.md` for contract rules
 - prefer documented public namespaces over undocumented internal assumptions
 
+### Change classification
+
+Every contract-affecting change is classified in `CHANGELOG.md [Unreleased]`
+with a `Contract change type:` line before release.
+
+| Classification | When to use | Examples |
+|---|---|---|
+| `additive` | New tokens, new paths, new CSS variables — existing consumers unaffected | Adding a namespace, adding a token inside an existing family |
+| `semantic change` | Path stays the same but meaning, intent, or visual output shifts | Adjusting the role of an existing surface or text token |
+| `breaking` | Existing consumers may need code changes | Renaming a token path, removing a namespace, changing mode names |
+
+Renames and removals are always breaking regardless of perceived scope.
+
 ## Package exports / API surface
 
 ### Root package
@@ -352,30 +418,71 @@ For downstream packages and compatible apps:
 
 ## Development
 
-Regenerate package outputs:
+Install dependencies, then run the package verification flow:
 
 ```bash
-npm run build
+npm install
+npm run check
 ```
 
-Run the full validation and release gate:
+This project expects Node.js `^22.12.0 || >=24.0.0` and npm `11.14.1`.
 
-```bash
-npm run check
-```
+### Common commands
+
+| Command | What it does |
+|---|---|
+| `npm run build` | Regenerate all outputs — run after any token source change |
+| `npm run check` | Full validation gate — all 14 steps must pass before commit |
+| `npm run lint` | Run ESLint against all source files |
+| `npm run format` | Apply Prettier formatting to all files |
+| `npm run generate` | Regenerate `src/generated/tokens.ts` from token sources only |
+| `npm run check:manifest` | Validate public namespaces against `contract.manifest.json` |
+| `npm run check:docs` | Validate README and TOKEN_CONTRACT headings against manifest |
+| `npm run check:locked` | Confirm protected color families are unchanged |
+| `npm run check:contrast` | Confirm all paired tokens meet WCAG AA |
+| `npm run check:dist` | Confirm `dist/` artifacts are in sync with source |
 
-Key source areas:
+### Key source areas
 
-- `tokens/` for source token data
-- `src/generated/` for generated token output
-- `src/` for package entry points, CSS generation, and types
-- `scripts/` for build and validation scripts
-- `example/` for usage examples
+- `tokens/` — source token data (source of truth)
+- `src/` — package entry points, CSS generation, and public types
+- `src/generated/` — auto-generated output (do not edit directly)
+- `scripts/` — build and validation scripts
+- `example/` — usage examples and smoke consumer
 
 The files in `example/` are illustrative token demos only. They help explain the
 token contract, but they are not the package contract itself and should not be
 treated as downstream UI primitives.
 
+## Troubleshooting
+
+| Failure | Cause | Fix |
+|---|---|---|
+| `check:regression` fails | A token value changed vs the recorded baseline | Revert the unintended change, or update the baseline if the change was intentional |
+| `check:locked` fails | A protected color family was modified | Revert unless Bradley Potts has explicitly approved the change |
+| `check:contrast` fails | A text/background token pair does not meet WCAG AA | Adjust the token value or the `metadata.pair` reference in the source JSON |
+| `check:dist` fails | Generated dist is out of sync | Run `npm run build` then re-run `npm run check` |
+| `check:manifest` fails | A namespace exists in outputs but is not declared in `contract.manifest.json` | Add the namespace to the manifest or remove it from the source |
+| `check:docs` fails | README or TOKEN_CONTRACT.md has drifted from the manifest | Update the doc to match the current contract |
+| `check:classification` fails | A contract-authority file changed without a classification entry | Add `Contract change type: additive`, `semantic change`, or `breaking` to `CHANGELOG.md [Unreleased]` |
+
+## AI and automation boundaries
+
+Claude Code (`claude-sonnet-4-6`) is the primary development agent for this
+repository. Codex handles releases and production stabilization. Jules handles
+small automated fixes and generated-output sync. GitHub Copilot provides
+development support.
+
+Claude Code does not create git commits. All Claude Code changes are prepared
+and validated, then handed off to Bradley Potts for human review and commit.
+Jules commits bounded automated maintenance tasks autonomously when all
+validation gates pass.
+
+**Protected from automated change:** locked color families (`success`,
+`warning`, `danger`, CTA/brand-action), `contract.manifest.json`, and
+`src/generated/tokens.ts`. See [AGENTS.md](AGENTS.md) for full agent
+governance and boundary rules.
+
 ## Contributing
 
 PHCDevworks maintains this package as part of the Spectre system.

package/dist/index.cjs

@@ -206,7 +206,7 @@ var coreTokens = {
         "page": "{colors.neutral.50}",
         "card": "{colors.white}",
         "input": "{colors.white}",
-        "overlay": "{colors.neutral.900} / 0.6",
+        "overlay": "{colors.black} / 0.6",
         "alternate": "{colors.neutral.100}",
         "hero": "linear-gradient(135deg, {colors.indigo.500} 0%, {colors.violet.600} 100%)"
       },
@@ -628,7 +628,7 @@ var coreTokens = {
     "page": "{colors.neutral.50}",
     "card": "{colors.white}",
     "input": "{colors.white}",
-    "overlay": "{colors.neutral.900} / 0.6"
+    "overlay": "{colors.black} / 0.6"
   },
   "text": {
     "onPage": {
@@ -850,6 +850,23 @@ var resolveValue = (tokens2, value) => {
   str = str.replace(opacityRegex, (match, hex, opacity) => hexToRgba(hex, opacity));
   return str;
 };
+var resolveSemanticValue = (value, tokens2) => {
+  if (typeof value === "string" || typeof value === "number") {
+    return resolveValue(tokens2, value);
+  }
+  if (value && typeof value === "object" && "value" in value) {
+    return resolveValue(tokens2, value.value);
+  }
+  return void 0;
+};
+var getPath = (source, path) => path.reduce((acc, key) => acc && typeof acc === "object" ? acc[key] : void 0, source);
+var pickSemantic = (tokens2, ...candidates) => {
+  for (const candidate of candidates) {
+    const resolved = resolveSemanticValue(candidate, tokens2);
+    if (resolved !== void 0) return resolved;
+  }
+  return void 0;
+};
 var createCssVariableMap = (tokens2, options = {}) => {
   const prefix = options.prefix ?? DEFAULT_PREFIX;
   const map = {};
@@ -998,23 +1015,6 @@ var createCssVariableMap = (tokens2, options = {}) => {
   }
   return map;
 };
-var resolveSemanticValue = (value, tokens2) => {
-  if (typeof value === "string" || typeof value === "number") {
-    return resolveValue(tokens2, value);
-  }
-  if (value && typeof value === "object" && "value" in value) {
-    return resolveValue(tokens2, value.value);
-  }
-  return void 0;
-};
-var getPath = (source, path) => path.reduce((acc, key) => acc && typeof acc === "object" ? acc[key] : void 0, source);
-var pickSemantic = (tokens2, ...candidates) => {
-  for (const candidate of candidates) {
-    const resolved = resolveSemanticValue(candidate, tokens2);
-    if (resolved !== void 0) return resolved;
-  }
-  return void 0;
-};
 var generateCssVariables = (tokens2, options = {}) => {
   const selector = options.selector ?? DEFAULT_SELECTOR;
   const prefix = options.prefix ?? DEFAULT_PREFIX;