@phcdevworks/spectre-tokens 3.5.0 → 4.1.0

package/README.md

@@ -1,14 +1,14 @@
 # @phcdevworks/spectre-tokens
 
-`@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.
+`@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](https://go.phcdev.co). It defines the visual
-language, semantic roles, and 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.
+language, semantic roles, and 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.
 
 ## Repository Snapshot
 
@@ -17,7 +17,7 @@ translate Spectre contracts for specific frameworks and runtimes.
 | Project team           | `project-design`                 |
 | Repository role        | Spectre L1 design-token contract |
 | Package/artifact       | `@phcdevworks/spectre-tokens`    |
-| Current version/status | 3.5.0                            |
+| Current version/status | 4.1.0                            |
 
 ## Standard Workflow
 
@@ -30,17 +30,18 @@ translate Spectre contracts for specific frameworks and runtimes.
 
 ## Documentation Map
 
-| Guide       | Path                         |
-| ----------- | ---------------------------- |
-| Agent rules | [AGENTS.md](AGENTS.md)       |
-| Claude Code | [CLAUDE.md](CLAUDE.md)       |
-| Codex       | [CODEX.md](CODEX.md)         |
-| Copilot     | [COPILOT.md](COPILOT.md)     |
-| Jules       | [JULES.md](JULES.md)         |
-| Roadmap     | [ROADMAP.md](ROADMAP.md)     |
-| Todo        | [TODO.md](TODO.md)           |
-| Changelog   | [CHANGELOG.md](CHANGELOG.md) |
-| Security    | [SECURITY.md](SECURITY.md)   |
+| Guide           | Path                                     |
+| --------------- | ---------------------------------------- |
+| Agent rules     | [AGENTS.md](AGENTS.md)                   |
+| Claude Code     | [CLAUDE.md](CLAUDE.md)                   |
+| Codex           | [CODEX.md](CODEX.md)                     |
+| Copilot         | [COPILOT.md](COPILOT.md)                 |
+| Jules           | [JULES.md](JULES.md)                     |
+| Roadmap         | [ROADMAP.md](ROADMAP.md)                 |
+| Todo            | [TODO.md](TODO.md)                       |
+| Token reference | [TOKEN_REFERENCE.md](TOKEN_REFERENCE.md) |
+| Changelog       | [CHANGELOG.md](CHANGELOG.md)             |
+| Security        | [SECURITY.md](SECURITY.md)               |
 
 [![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)
@@ -61,7 +62,7 @@ and runtimes.
 [Changelog](CHANGELOG.md) | [Token Contract](TOKEN_CONTRACT.md) |
 [Roadmap](ROADMAP.md) | [Security Policy](SECURITY.md)
 
-## Source of truth
+## 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
@@ -78,17 +79,16 @@ validated against them.
 After any source change: run `npm run build` to regenerate outputs, then
 `npm run check` to validate the full contract.
 
-## What this package owns
+## What This Package Owns
 
 - Visual language expressed as token data in `tokens/`
 - Semantic roles and token contracts consumed downstream
-- Generated token outputs for JavaScript, TypeScript, CSS variables, and
-  Tailwind theme exports
+- Generated token outputs for JavaScript, TypeScript, CSS variables, and DTCG
 - Theme and mode definitions used by downstream consumers
 
 This package is the correct place to define token meaning.
 
-## What this package does not own
+## What This Package Does Not Own
 
 - Component structure or composition. That belongs in downstream UI packages
   such as
@@ -100,17 +100,17 @@ This package is the correct place to define token meaning.
 - 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
+## 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 need design token values in JavaScript, TypeScript, CSS variables, or DTCG
+  format.
 - 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
+## When Not To Use This Package
 
 - You need UI components or component structure — use
   [`@phcdevworks/spectre-ui`](https://github.com/phcdevworks/spectre-ui).
@@ -126,7 +126,7 @@ This package is the correct place to define token meaning.
 npm install @phcdevworks/spectre-tokens
 ```
 
-## Quick start
+## Quick Start
 
 ### CSS import
 
@@ -152,21 +152,7 @@ const card = {
 }
 ```
 
-### Tailwind preset usage
-
-Use the generated Tailwind preset when you want the package to populate theme
-values from the token contract:
-
-```ts
-// tailwind.config.ts
-import { tailwindPreset } from '@phcdevworks/spectre-tokens'
-
-export default {
-  presets: [tailwindPreset]
-}
-```
-
-## Semantic tokens vs raw palette tokens
+## 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
@@ -174,15 +160,15 @@ mode-aware styling.
 
 ### Semantic namespaces (prefer for all UI work)
 
-| Namespace   | What it expresses                                                                                                       |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Namespace   | What it expresses                                                                                                           |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `surface`   | Background roles: page, card, input, overlay, subtle, hero (gradient, hero sections only), hover, selected, active, divider |
-| `text`      | Foreground roles: default, muted, subtle, meta, on-surface, on-page                                                     |
-| `component` | Role-specific tokens for icon boxes, badges, ratings, testimonials, pricing cards, nav, modal, toast, tooltip, dropdown |
-| `buttons`   | Button state tokens: default, hover, active, disabled, CTA                                                              |
-| `forms`     | Form state tokens: default, focused, error, disabled                                                                    |
-| `link`      | Inline link color roles: default, hover, active, visited                                                                |
-| `modes`     | Mode-aware overrides under `modes.default` and `modes.dark`                                                             |
+| `text`      | Foreground roles: default, muted, subtle, meta, on-surface, on-page                                                         |
+| `component` | Role-specific tokens for icon boxes, badges, ratings, testimonials, pricing cards, nav, modal, toast, tooltip, dropdown     |
+| `buttons`   | Button state tokens: default, hover, active, disabled, CTA                                                                  |
+| `forms`     | Form state tokens: default, focused, error, disabled                                                                        |
+| `link`      | Inline link color roles: default, hover, active, visited                                                                    |
+| `modes`     | Mode-aware overrides under `modes.default` and `modes.dark`                                                                 |
 
 ```ts
 import tokens from '@phcdevworks/spectre-tokens'
@@ -216,7 +202,7 @@ const chart = {
 
 Do not use `colors` as a substitute for semantic tokens in normal UI surfaces.
 
-## Consumer usage
+## Consumer Usage
 
 ### JavaScript and TypeScript tokens
 
@@ -235,14 +221,10 @@ const card = {
 }
 ```
 
-Use named exports when you need generated helpers or Tailwind integration:
+Use named exports when you need generated helpers:
 
 ```ts
-import tokens, {
-  generateCssVariables,
-  tailwindPreset,
-  tailwindTheme
-} from '@phcdevworks/spectre-tokens'
+import tokens, { generateCssVariables } from '@phcdevworks/spectre-tokens'
 
 const css = generateCssVariables(tokens)
 ```
@@ -264,41 +246,33 @@ CSS variable contract.
 .app-shell {
   width: var(--sp-layout-sidebar-width);
 }
-```
-
-The CSS entry point is intended for consumers that want the token contract as
-variables rather than reading values in JavaScript.
-
-### Tailwind preset
 
-Use the Tailwind preset when a consumer wants Tailwind theme values derived from
-the same token contract.
-
-```ts
-import { tailwindPreset } from '@phcdevworks/spectre-tokens'
+h1 {
+  font-family: var(--sp-heading-h1-family);
+  font-size: var(--sp-heading-h1-size);
+  line-height: var(--sp-heading-h1-line-height);
+  font-weight: var(--sp-heading-h1-weight);
+  letter-spacing: var(--sp-heading-h1-letter-spacing);
+}
 
-export default {
-  presets: [tailwindPreset]
+body {
+  font-family: var(--sp-body-family);
+  font-size: var(--sp-body-size);
+  line-height: var(--sp-body-line-height);
+  font-weight: var(--sp-body-weight);
+  letter-spacing: var(--sp-body-letter-spacing);
 }
 ```
 
-Use `tailwindTheme` directly only when a consumer needs the generated theme
-object outside the preset shape.
-
-The generated Tailwind theme includes the layout width mappings
-`maxWidth.container`, `maxWidth.prose`, and `width.sidebar`, derived from
-`layout.container.maxWidth`, `layout.container.maxWidthProse`, and
-`layout.sidebar.width`.
+The CSS entry point is intended for consumers that want the token contract as
+variables rather than reading values in JavaScript.
 
-```tsx
-export function ArticleShell() {
-  return (
-    <main className="mx-auto max-w-prose">
-      <aside className="w-sidebar" />
-    </main>
-  )
-}
-```
+`typography.heading.{h1..h6}` and `typography.body` are semantic role tokens —
+each a complete
+`{ fontFamily, fontSize, lineHeight, fontWeight, letterSpacing }` object
+referencing `typography.scale.*` and `typography.families.*` — so downstream
+consumers get a heading/body contract instead of hand-picking a raw
+`typography.scale` step per heading level.
 
 ### Token model
 
@@ -332,12 +306,15 @@ The exported runtime token object is a flattened string-based tree generated
 from `tokens/`. Source-only wrapper fields such as `value` and `metadata` are
 internal generation details and are not part of the public package contract.
 
+See [TOKEN_REFERENCE.md](TOKEN_REFERENCE.md) for the exhaustive, generated
+list of every token path, resolved value, and usage note.
+
 The `layout` namespace includes section, stack, and container spacing tokens,
 plus fixed layout width tokens for common consumer shells:
 `layout.container.maxWidth`, `layout.container.maxWidthProse`, and
 `layout.sidebar.width`.
 
-## Public contract guarantees
+## Public Contract Guarantees
 
 `contract.manifest.json` is the machine-readable contract authority for this
 package.
@@ -345,7 +322,7 @@ package.
 It defines:
 
 - public namespaces
-- required output surfaces for JavaScript, CSS, and Tailwind
+- required output surfaces for JavaScript, CSS, and DTCG
 - protected semantic groups
 
 Every contract-facing surface in this repository must match that manifest.
@@ -374,7 +351,7 @@ Guidance:
 - Do not invent local light/dark token contracts when this package already
   provides the semantic path.
 
-## Protected token families
+## 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
@@ -391,7 +368,7 @@ AI agents — apparent visual improvements still require human sign-off.
 recorded baseline. An intentional change requires updating the baseline as part
 of an approved, classified release.
 
-## Downstream boundaries
+## Downstream Boundaries
 
 Downstream packages should never redefine locally:
 
@@ -406,7 +383,7 @@ Downstream packages may:
 - map these tokens into framework-specific delivery
 - use raw palette values when the usage is intentionally non-semantic
 
-## Upgrade expectations for consumers
+## Upgrade Expectations For Consumers
 
 Consumers should treat this package as a SemVer-governed contract.
 
@@ -415,7 +392,7 @@ Practical guidance:
 - additive token paths are intended to be safe for existing consumers
 - semantic shifts may keep the same path but still affect visual meaning
 - renames and removals are breaking
-- generated JS, TS, CSS, and Tailwind outputs are expected to stay aligned
+- generated JS, TS, CSS, and DTCG outputs are expected to stay aligned
 
 If a downstream package depends on specific token paths or semantic meaning:
 
@@ -436,27 +413,21 @@ with a `Contract change type:` line before release.
 
 Renames and removals are always breaking regardless of perceived scope.
 
-## Package exports / API surface
+## Package Exports / API Surface
 
 ### Root package
 
 `@phcdevworks/spectre-tokens` exports:
 
 - `default` / `tokens`
-- `tailwindTheme`
-- `tailwindPreset`
 - `generateCssVariables`
-- TypeScript types including `SpectreTokens`, `TailwindTheme`,
-  `SpectreModeTokens`, and `SpectreModeName`
+- TypeScript types including `SpectreTokens`, `SpectreModeTokens`, and
+  `SpectreModeName`
 
 Example:
 
 ```ts
-import tokens, {
-  generateCssVariables,
-  tailwindPreset,
-  tailwindTheme
-} from '@phcdevworks/spectre-tokens'
+import tokens, { generateCssVariables } from '@phcdevworks/spectre-tokens'
 
 const css = generateCssVariables(tokens, {
   selector: ':root',
@@ -468,27 +439,26 @@ const css = generateCssVariables(tokens, {
 
 - `@phcdevworks/spectre-tokens/index.css`
 
-## Relationship to the rest of Spectre
+## Relationship To The Rest Of Spectre
 
 Spectre keeps responsibilities separate:
 
 - [`@phcdevworks/spectre-tokens`](https://github.com/phcdevworks/spectre-tokens)
   defines visual language, semantic roles, and token contracts
 - [`@phcdevworks/spectre-ui`](https://github.com/phcdevworks/spectre-ui) turns
-  those contracts into reusable CSS, Tailwind tooling, and shared styling
+  those contracts into reusable CSS, utility tooling, and shared styling
   behavior
 - Adapter packages translate Spectre contracts for framework-specific delivery
 
 That separation keeps token meaning centralized while letting the package system
 expand by responsibility.
 
-## Consumer checklist
+## Consumer Checklist
 
 For downstream packages and compatible apps:
 
 - import tokens from the package root when you need runtime values
 - import `index.css` when you need generated CSS variables
-- use `tailwindPreset` when you need Tailwind theme integration
 - prefer semantic namespaces for UI behavior
 - use raw palette values only when fixed palette access is intentional
 - treat `tokens/` as source of truth and generated outputs as derived
@@ -503,14 +473,14 @@ npm install
 npm run check
 ```
 
-This project expects Node.js `^22.12.0 || >=24.0.0` and npm `11.17.0`.
+This project expects Node.js `^22.12.0 || >=24.0.0` and npm `12.0.1`.
 
 ### 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 16 steps must pass before commit  |
+| `npm run check`          | Full validation gate — every step 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 |
@@ -544,17 +514,17 @@ treated as downstream UI primitives.
 | `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
+## 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.
+repository. Codex handles releases and production stabilization, including
+cutting tagged releases and GitHub Releases. Jules handles small automated fixes
+and generated-output sync. GitHub Copilot provides development support.
+
+All AI agents with repository access (Claude Code, Codex, Copilot, Jules) have
+commit, push, and tag authority in this repository. Publishing to npm remains
+Bradley Potts's sole authority. See [AGENTS.md](AGENTS.md) for the full
+commit-policy and release-authority grant.
 
 **Protected from automated change:** locked color families (`success`,
 `warning`, `danger`, CTA/brand-action), `contract.manifest.json`, and