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.

This page is generated from the source repository’s README and ROADMAP on every build. Edit the source repository, not this file.

README

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

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.

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

npm version CI License Node

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

Roadmap

Spectre Tokens Roadmap

@phcdevworks/spectre-tokens is the authoritative contract layer for token meaning across the Spectre system. It owns token definitions, semantic token contracts, modes and themes, and the generated outputs consumed by downstream packages. Its job is to keep token meaning stable, enforceable, and safe to consume — not to model component structure or framework behavior.

1. Phase 1 — Contract Foundation — Delivered

All contract foundation work is complete as of v2.5.0. The package is mature at the contract layer.

What is in place

  • tokens/ is the single source of truth. Token loading is deterministic and fails hard on duplicate path ownership.
  • contract.manifest.json is the machine-readable contract authority for public namespaces, required outputs, protected semantic groups, and change classification rules.
  • A 16-gate npm run check validation chain covers: build, manifest, structure, locked color, contrast, regression, docs, exports, CSS, Tailwind, consumer smoke, integration, ecosystem, classification, deprecation, dist sync, and lint. All gates must pass before merge.
  • Runtime JS, generated TypeScript, CSS variables, and Tailwind exports are validated for parity against the declared contract.
  • README.md and TOKEN_CONTRACT.md are validated against the manifest — documentation drift fails the check gate.
  • Contract-impacting changes require explicit classification (additive, semantic change, breaking) in CHANGELOG.md [Unreleased] before merge.
  • A downstream smoke and integration fixture validates runtime token import, CSS import, Tailwind preset usage, semantic token usage, mode-aware usage, namespace collision checks, and component-style fixture patterns.
  • CI runs the full validation chain on Node 22 and 24 for every push and pull request.
  • A multi-agent team (Claude Code, Codex, Copilot, Jules) operates with documented authority boundaries, PR creation requirements, and CodeRabbit review integration.

What will not change

  • tokens/ remains the only source of truth. No hand-editing generated files.
  • The 16-gate chain is the release standard. No gate is optional.
  • Protected semantic color families (success, warning, danger, CTA/brand-action) require explicit Bradley Potts approval to change.
  • This package does not own component structure, framework behavior, or adapter concerns.

2. Phase 2 — Mature Contract Operations — Delivered

All Phase 2 work is complete. The contract is hardened against real downstream consumption, release steps are automated, design tooling is wired in, and the deprecation lifecycle is formally enforced.

P0: Downstream Integration Hardening — Delivered

  • Integration fixture in example/integration-fixture/ exercises nav, alert, and badge component styles against the surface, text, accessibility, and component.badge namespaces the way a downstream UI library would.
  • Tailwind preset composition validated against a downstream config with its own theme extensions.
  • CSS variable namespace collision checks confirm no --sp-* shadowing risk.
  • Integration constraints documented as explicit contract rules in TOKEN_CONTRACT.md.

P1: Versioning Automation — Delivered

  • scripts/propose-version.ts reads the Contract change type: line from CHANGELOG.md [Unreleased] and proposes the correct semver bump: additive → minor, semantic change → minor, breaking → major.
  • Wired into the release procedure in CLAUDE.md and CODEX.md as step 1. Bradley Potts retains final version authority.

P2: Design Tool Synchronization — Delivered

  • scripts/build-dtcg.ts generates dist/tokens.dtcg.json in W3C DTCG format (no external dependency). Tokens Studio and Style Dictionary v4 both consume DTCG natively. 546 tokens across all public namespaces with inferred $type, $value, and $description.
  • Wired into npm run build via build:design. check:dist automatically catches stale output. check:manifest validates the file exists and contains valid DTCG tokens.
  • CONTRIBUTING.md documents the Tokens Studio setup and sync workflow.
  • contract.manifest.json declares the design output with required top-level keys.

P3: Deprecation Policy — Delivered

  • Deprecation lifecycle (active → deprecated → removed) defined in TOKEN_CONTRACT.md.
  • deprecated marker added to the token source schema via metadata.deprecated with since, replacedBy, and removeIn fields.
  • scripts/check-deprecation.ts warns on deprecated tokens and fails when a token has passed its removeIn version. Wired into npm run check.
  • Deprecation notice format documented in TOKEN_CONTRACT.md and CHANGELOG.md convention.

3. Phase 3 — Validation Integrity — Delivered

The validation layer is hardened. Unit tests cover pure utilities and all critical validators are tested on negative paths.

What was delivered

  • vitest installed and wired. npm test runs the unit suite alongside the check gate.
  • tests/token-utils.test.ts — 15 assertions across flattenTokenTree, getTokenSourceFiles, and loadMergedTokens.
  • tests/propose-version.test.ts — computeVersionBump and extractClassification extracted and tested; 10 assertions.
  • tests/check-contrast.test.ts — computeContrast exported; 5 assertions confirming failing pairs < 4.5 and passing pairs ≥ 4.5.
  • tests/check-locked.test.ts — stableStringify exported; 7 assertions covering mutated values, added/removed keys, and type handling.
  • tests/check-regression.test.ts — findWrappedEntry exported from contract-utils.ts; 10 assertions covering missing paths and wrapped-entry detection.

4. Phase 4 — Token Surface Completion

P0: Correctness Fixes — Delivered

  • colors.focus.primary, colors.focus.error, colors.focus.info replaced with palette references — no more hardcoded hex.
  • focusVisible added to buttons.danger and buttons.success, matching all other button variants.

P1: Interactive UI Semantic Tokens — Delivered

  • link namespace published: default, hover, active, visited.
  • Interactive surface states published: surface.hover, surface.selected, surface.active with mode-aware variants.
  • Semantic divider published: surface.divider with mode-aware variants.

P2: Component Token Expansion — Delivered

spectre-ui Phase 4 recipes and spectre-ui-astro Phase 4 were gated on these five groups. They are now published in the token contract.

  • component.nav — bg, text, link, linkHover, linkActive, border.
  • component.modal — bg, shadow, border, overlay.
  • component.toast — success, warning, danger, info variants each with bg, text, border, icon.
  • component.tooltip — bg, text, border.
  • component.dropdown — bg, border, item.default, item.hover, item.active, item.text.

P3: Motion and Surface Polish — Delivered

  • Reduced-motion variants shipped in 2.9.0.
  • surface.hero resolved: retained in the surface namespace, documented with explicit hero/marketing-only usage constraints.
  • surface.alternate renamed to surface.subtle (--sp-surface-subtle). Breaking change, logged.

5. Phase 5 — CSS Generation Bug: Dropped Semantic Variables — Delivered

generateCssVariables in src/css.ts built dist/index.css from a hand-maintained semanticEntries array, not by iterating the full tokens object. link.* and surface.hover/selected/active/divider existed in tokens/semantic-roles.json and in the compiled tokens export, but had no corresponding entries in semanticEntries, so they were silently omitted from dist/index.css in every release through 3.0.0.

  • --sp-link-default/hover/active/visited and --sp-surface-hover/selected/active/divider now emit correctly in dist/index.css (light and dark blocks).
  • tests/css-semantic-coverage.test.ts asserts every top-level key under tokens.link and tokens.modes.default.surface has a matching CSS variable in generateCssVariables output, guarding against recurrence.
  • Published in 3.1.0, unblocking spectre-ui Phase 3 P2 (Link, interactive surface states, Divider styling).

6. Phase 4 P4 — Layout Width Scale — Delivered

Real downstream need: spectre-ui Phase 4d (app shell layout — Sidebar recipe, Container maxWidth prose variant) needed fixed-width values that did not exist anywhere in the published token object. Confirmed by reading the live package directly — layout only had section, stack (gap only), and container (paddingInline + one fixed maxWidth).

  • layout.sidebar.width added as a single fixed value (16rem), matching the existing container.maxWidth precedent rather than introducing a multi-step scale.
  • layout.container.maxWidthProse (65ch) added as a sibling key to the existing container.maxWidth, keeping that contract non-breaking.
  • Published in 3.1.0, unblocking spectre-ui Phase 4d.

7. Phase 7 — Form-Field Component Token Groups — Delivered

Cross-repo audit found sp-checkbox, sp-fieldset, sp-label, sp-radio, sp-select, and sp-textarea shipped in spectre-components with no backing component.* token group here and no recipe in spectre-ui — the same gating pattern Phase 4 P2 used for Nav/Toast/Tooltip/Dropdown/Modal.

  • component.checkbox and component.radio — bg, border, checkedBg, checkedBorder, text, disabledBg, disabledBorder.
  • component.select — bg, border, text, placeholderText, disabledBg, disabledBorder, focusBorder.
  • component.textarea — bg, border, text, placeholder, disabledBg, disabledBorder, focusBorder.
  • component.fieldset — border, legendText.
  • component.label — text, disabledText, requiredIndicatorText.
  • Published in 3.2.0, unblocking the corresponding spectre-ui form-field recipes (getCheckboxClasses, getRadioClasses, getSelectClasses, getTextareaClasses, getFieldsetClasses, getLabelClasses).

8. Phase 8 — Select/Textarea Invalid and Success State Roles — Delivered

spectre-ui audited component.select/component.textarea while adding size/fullWidth/pill options and found both groups missing invalid/success color roles, unlike component.input’s existing error/success border-bg pairs — blocking spectre-ui Phase 5 P0.

  • Added borderInvalid/bgInvalid and borderSuccess/bgSuccess to component.select and component.textarea, mirroring forms.invalid/ forms.valid. Published in 3.3.0.
  • 3.3.0’s new fields never reached generated CSS/types due to a hand-maintained field-mapping array bug in src/css.ts (same class as the 3.1.0 Phase 5 fix). Generalizing the regression test to cover all of tokens.component.* also surfaced two more pre-existing instances: component.badge’s *BgHover fields, and component.testimonial/ component.pricingCard/component.rating being entirely absent from CSS generation. All fixed and published in 3.3.1 — spectre-ui must depend on ^3.3.1, not ^3.3.0.

9. Explicitly Out of Scope

  • Component structure or composition — belongs in @phcdevworks/spectre-ui.
  • Framework-specific token delivery — belongs in adapter packages.
  • UI primitives or component anatomy — example/ is illustrative only.
  • Local consumer reinterpretation of Spectre token meaning.
  • Anything that moves styling, component anatomy, or adapter concerns into this repo.
  1. Phase 1 — done.
  2. Phase 2 — done.
  3. Phase 3 — done.
  4. Phase 4 P0 — done.
  5. Phase 4 P1 — done.
  6. Phase 4 P2 — done. Component token expansion unblocked spectre-ui Phase 4 and spectre-ui-astro Phase 4.
  7. Phase 4 P3 — done. surface.hero/surface.alternate resolved.
  8. Phase 5 — done, published in 3.1.0. link.* and surface.hover/selected/active/divider now emit correctly in dist/index.css, unblocking spectre-ui Phase 3 P2.
  9. Phase 4 P4 — done, published in 3.1.0. Added layout.sidebar.width and layout.container.maxWidthProse, unblocking spectre-ui Phase 4d.
  10. Phase 7 — done, published in 3.2.0. Added component.checkbox, component.radio, component.select, component.textarea, component.fieldset, and component.label, unblocking the corresponding spectre-ui form-field recipes.
  11. Phase 8 — done, published in 3.3.0. Added borderInvalid, bgInvalid, borderSuccess, and bgSuccess to component.select and component.textarea, mirroring forms.invalid/forms.valid. Unblocks spectre-ui Phase 5 P0’s deferred invalid/success options on getSelectClasses/getTextareaClasses — adoption still pending there.
  12. 3.3.1 fix (ready, pending release) — 3.3.0’s new select/textarea fields never reached generated CSS/types due to a hand-maintained field-mapping array bug in src/css.ts (same class as the 3.1.0 Phase 5 fix). Generalizing the regression test to cover all of tokens.component.* also surfaced two more pre-existing instances of the same bug: component.badge’s *BgHover fields, and component.testimonial/component.pricingCard/component.rating being entirely absent from CSS generation. All fixed; full npm run check gate and vitest run pass clean. spectre-ui should depend on ^3.3.1, not ^3.3.0, once published.