@phcdevworks/spectre-tokens

Repository Snapshot

Field	Value
Project team	project-design
Repository role	Spectre L1 design-token contract
Package/artifact	@phcdevworks/spectre-tokens
Current version/status	3.3.1

Standard Workflow

1. Read AGENTS.md, then the agent-specific guide for the task.
2. Check TODO.md and ROADMAP.md for current scope.
3. Make the smallest repo-local change that satisfies the task.
4. Run npm run check when validation is required or practical.
5. Update docs and CHANGELOG.md only when behavior, public contracts, or release-relevant metadata changed.

Documentation Map

Guide	Path
Agent rules	AGENTS.md
Claude Code	CLAUDE.md
Codex	CODEX.md
Copilot	COPILOT.md
Jules	JULES.md
Roadmap	ROADMAP.md
Todo	TODO.md
Changelog	CHANGELOG.md
Security	SECURITY.md

@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 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 | Code of Conduct | Changelog | Token Contract | Roadmap | Security Policy

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

• 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
• Theme and mode definitions used by downstream consumers

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.
• Framework-specific delivery. Adapter packages translate Spectre contracts for specific frameworks and runtimes.
• 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.

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.
• 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

npm install @phcdevworks/spectre-tokens

Quick start

CSS import

Import the generated CSS variables:

@import '@phcdevworks/spectre-tokens/index.css';

Token usage

Load the token object in JavaScript or TypeScript:

import tokens from '@phcdevworks/spectre-tokens'

const card = {
  background: tokens.surface.page,
  color: tokens.text.onPage.default,
  maxWidth: tokens.layout.container.maxWidthProse,
  padding: tokens.space['16'],
  borderRadius: tokens.radii.md
}

Tailwind preset usage

Use the generated Tailwind preset when you want the package to populate theme values from the token contract:

// tailwind.config.ts
import { tailwindPreset } from '@phcdevworks/spectre-tokens'

export default {
  presets: [tailwindPreset]
}

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, 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

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.

// 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

Use the runtime token object when a consumer needs token values directly in code.

import tokens from '@phcdevworks/spectre-tokens'

const card = {
  background: tokens.surface.card,
  color: tokens.text.onSurface.default,
  borderColor: tokens.component.iconBox.border,
  maxWidth: tokens.layout.container.maxWidthProse,
  padding: tokens.space['16']
}

Use named exports when you need generated helpers or Tailwind integration:

import tokens, {
  generateCssVariables,
  tailwindPreset,
  tailwindTheme
} from '@phcdevworks/spectre-tokens'

const css = generateCssVariables(tokens)

Generated CSS variables

Import index.css when a downstream package or app wants the generated Spectre CSS variable contract.

@import '@phcdevworks/spectre-tokens/index.css';

.card {
  background: var(--sp-surface-card);
  color: var(--sp-text-on-surface-default);
  max-width: var(--sp-layout-container-max-width-prose);
}

.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.

import { tailwindPreset } from '@phcdevworks/spectre-tokens'

export default {
  presets: [tailwindPreset]
}

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.

export function ArticleShell() {
  return (
    <main className="mx-auto max-w-prose">
      <aside className="w-sidebar" />
    </main>
  )
}

Token model

The generated token object includes these namespaces:

• colors
• space
• layout
• radii
• typography
• font
• shadows
• breakpoints
• zIndex
• transitions
• animations
• opacity
• aspectRatios
• icons
• border
• accessibility
• buttons
• forms
• link
• surface
• text
• component
• modes

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.

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

contract.manifest.json is the machine-readable contract authority for this package.

It defines:

• public namespaces
• required output surfaces for JavaScript, CSS, and Tailwind
• protected semantic groups

Every contract-facing surface in this repository must match that manifest. Validation fails fast on token overwrite across files, undocumented namespaces, output drift, and README mismatch with the contract authority.

Themes and modes

The package includes mode-aware semantic tokens under modes, with default and dark mode definitions in the generated output.

Use semantic mode-aware values when the consumer needs light/dark or mode-specific behavior without branching on raw palette values.

import tokens from '@phcdevworks/spectre-tokens'

const darkPage = tokens.modes.dark.surface.page
const darkText = tokens.modes.dark.text.onPage.default

Guidance:

• Prefer semantic tokens for theme-aware UI.
• Prefer modes when a consumer explicitly needs mode-specific values.
• 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:

• the meaning of surface, text, component, buttons, forms, or modes
• protected semantic groups such as success, warning, danger, or CTA / brand-action semantics
• public namespace shape that this package already exports

Downstream packages may:

• compose UI structure on top of this contract
• map these tokens into framework-specific delivery
• use raw palette values when the usage is intentionally non-semantic

Upgrade expectations for consumers

Consumers should treat this package as a SemVer-governed contract.

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

If a downstream package depends on specific token paths or semantic meaning:

• read CHANGELOG.md for contract change classification
• 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

@phcdevworks/spectre-tokens exports:

• default / tokens
• tailwindTheme
• tailwindPreset
• generateCssVariables
• TypeScript types including SpectreTokens, TailwindTheme, SpectreModeTokens, and SpectreModeName

Example:

import tokens, {
  generateCssVariables,
  tailwindPreset,
  tailwindTheme
} from '@phcdevworks/spectre-tokens'

const css = generateCssVariables(tokens, {
  selector: ':root',
  prefix: 'sp'
})

CSS entry point

• @phcdevworks/spectre-tokens/index.css

Relationship to the rest of Spectre

Spectre keeps responsibilities separate:

• @phcdevworks/spectre-tokens defines visual language, semantic roles, and token contracts
• @phcdevworks/spectre-ui turns those contracts into reusable CSS, Tailwind 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

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
• do not redefine Spectre semantic contracts locally

Development

Install dependencies, then run the package verification flow:

npm install
npm run check

This project expects Node.js ^22.12.0 || >=24.0.0 and npm 11.17.0.

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 15 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

• 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 for full agent governance and boundary rules.

Contributing

PHCDevworks maintains this package as part of the Spectre system.

When contributing:

• treat tokens/ as the source of truth
• keep generated outputs derived from source data
• avoid breaking token contracts without an intentional major-version change
• run npm run build to regenerate outputs when sources change
• run npm run check as the full validation gate before opening a pull request
• do not modify locked semantic color families without explicit approval
• keep README.md, generated outputs, and contract.manifest.json aligned

See CONTRIBUTING.md for the full workflow.

License

MIT © PHCDevworks. See LICENSE.