@phcdevworks/spectre-tokens 2.5.0 → 2.7.0

package/README.md

@@ -1,32 +1,40 @@
 # @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)
-[![License](https://img.shields.io/github/license/phcdevworks/spectre-tokens)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@phcdevworks/spectre-tokens)](https://www.npmjs.com/package/@phcdevworks/spectre-tokens)
+[![CI](https://github.com/phcdevworks/spectre-tokens/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/phcdevworks/spectre-tokens/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/@phcdevworks/spectre-tokens)](LICENSE)
+[![Node](https://img.shields.io/node/v/@phcdevworks/spectre-tokens)](https://nodejs.org)
 
-`@phcdevworks/spectre-tokens` is the design-token package of the Spectre system
-for downstream Spectre packages and compatible applications.
+`@phcdevworks/spectre-tokens` is the design-token package of the Spectre system.
+It provides a complete, UI-ready token surface for downstream Spectre packages
+and compatible applications.
 
 Maintained by PHCDevworks, it defines the visual language, semantic roles, and
-token contracts consumed downstream. It keeps visual meaning centralized in
-token data while downstream UI packages define structure and adapter packages
-translate those contracts for specific frameworks and runtimes.
-
-[Contributing](CONTRIBUTING.md) | [Changelog](CHANGELOG.md) |
-[Token Contract](TOKEN_CONTRACT.md) | [Roadmap](ROADMAP.md) |
-[Security Policy](SECURITY.md)
-
-## Key capabilities
-
-- 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
+token contracts that downstream consumers can rely on without filling gaps with
+raw palette values or local token inventions. Downstream UI packages define
+structure; adapter packages translate Spectre contracts for specific frameworks
+and runtimes.
+
+[Contributing](CONTRIBUTING.md) | [Code of Conduct](CODE_OF_CONDUCT.md) |
+[Changelog](CHANGELOG.md) | [Token Contract](TOKEN_CONTRACT.md) |
+[Roadmap](ROADMAP.md) | [Security Policy](SECURITY.md)
+
+## Source of truth
+
+`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 +48,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 +118,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.
+
+### Semantic namespaces (prefer for all UI work)
+
+| 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],
+}
+```
 
-### Source of truth
+Do not use `colors` as a substitute for semantic tokens in normal UI surfaces.
 
-- 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.
+## Consumer usage
 
 ### JavaScript and TypeScript tokens
 
@@ -164,34 +230,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 +298,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 +347,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 +420,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.