@phcdevworks/spectre-ui

@phcdevworks/spectre-ui is the styling contract package of the Spectre system. It translates Spectre design tokens into CSS bundles, Tailwind theme configuration, and class recipe functions for downstream adapters and apps.

Maintained by PHCDevworks. It sits between @phcdevworks/spectre-tokens and the framework-specific adapter and component packages, so no downstream repo needs to hand-roll CSS, Tailwind config, or hardcode design values to consume Spectre's visual language.

Repository Snapshot

| Field | Value | |-------|-------| | Project team | project-design | | Repository role | Spectre L2 CSS, Tailwind, and recipe contract | | Package/artifact | @phcdevworks/spectre-ui | | Current version/status | 2.9.0 |

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-ui is Layer 2 of the Spectre design suite. It turns @phcdevworks/spectre-tokens into reusable CSS bundles, Tailwind tooling, and type-safe class recipes for downstream adapters and apps.

For: adapter authors and app developers who need a stable, token-driven styling contract without re-implementing class logic themselves.

Not for: authoring design tokens (that belongs in @phcdevworks/spectre-tokens) or building framework-specific components (that belongs in adapter packages such as @phcdevworks/spectre-ui-astro).

Contributing | Code of Conduct | Changelog | Roadmap | Security Policy

Source of truth

@phcdevworks/spectre-tokens is the source of truth for visual values and semantic meaning. ui-contract.manifest.json is the machine-readable contract authority for this package's public styling surface.

| Layer | Path | Rule | | --------------------- | ----------------------------------------------- | -------------------------------------------------------------- | | Token authority | Published @phcdevworks/spectre-tokens package | Design values and semantic meaning start there | | UI contract authority | ui-contract.manifest.json | Governs public recipes, CSS entry points, and Tailwind exports | | Source CSS | src/styles/ | Token-backed CSS classes and bundle entry points | | Source recipes | src/recipes/ | Framework-agnostic class string APIs | | Tailwind helpers | src/tailwind/ | Tailwind theme and preset integration | | Generated dist | dist/ | Never edit directly — regenerated by npm run build |

After any contract-facing source change: run npm run check to validate the full UI contract.

Architecture

| Layer | Package or consumer | Responsibility | Relationship to this package | | ----- | ---------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------- | | 1 | @phcdevworks/spectre-tokens | Defines design values and semantic token meaning | Upstream source of truth | | 2 | @phcdevworks/spectre-ui | Translates tokens into CSS bundles, Tailwind helpers, and class recipes | This package | | 3 | Adapters and apps, such as @phcdevworks/spectre-ui-astro | Deliver Spectre through framework-native ergonomics | Downstream consumers |

@phcdevworks/spectre-components is a separate component package that can wrap this styling contract in Lit web components. This package owns Layer 2 only: it does not deliver components and it does not define tokens.

Key capabilities

• Ships precompiled CSS: index.css, base.css, components.css, and utilities.css
• Provides Tailwind theme and preset helpers built from Spectre tokens
• Exports type-safe class recipes for shared UI patterns
• Keeps CSS classes and recipe APIs aligned
• Gives adapters and apps a stable styling contract instead of re-implementing classes
• Enforces a zero-hex approach so visual values stay tied to @phcdevworks/spectre-tokens

What this package owns

• Token-backed CSS class contracts in src/styles/
• Precompiled CSS bundles for root, base, components, and utilities
• Framework-agnostic class recipe functions in src/recipes/
• Tailwind preset and theme helpers in src/tailwind/
• Contract validation that keeps CSS, recipes, exports, and docs aligned

This package is the correct place to define reusable styling structure on top of Spectre tokens.

What this package does not own

• Design token values or semantic visual meaning. Those belong in @phcdevworks/spectre-tokens.
• Framework components, templates, hooks, or runtime behavior. Those belong in adapter packages.
• App-level layout, routing, data fetching, or product-specific composition.
• Local redefinition of token meaning. Downstream consumers should consume the token contract rather than recreate it.

Installation

npm install @phcdevworks/spectre-ui

Quick start

Vanilla HTML — CSS classes only

No framework needed. Import the CSS and use the sp-* classes directly:

<!doctype html>
<html>
  <head>
    <link
      rel="stylesheet"
      href="node_modules/@phcdevworks/spectre-ui/dist/index.css"
    />
  </head>
  <body>
    <button class="sp-btn sp-btn--primary sp-btn--md">Save</button>
    <button class="sp-btn sp-btn--ghost sp-btn--md">Cancel</button>
    <span class="sp-badge sp-badge--success sp-badge--sm">Published</span>

    <div class="sp-card sp-card--elevated">
      <p>Card content</p>
    </div>

    <div class="sp-input-wrapper">
      <label class="sp-label">Email</label>
      <input class="sp-input sp-input--md" type="email" />
    </div>
  </body>
</html>

CSS import (bundler or framework)

Import the full stylesheet:

import '@phcdevworks/spectre-ui/index.css'

Or import the bundles separately:

import '@phcdevworks/spectre-ui/base.css'
import '@phcdevworks/spectre-ui/components.css'
import '@phcdevworks/spectre-ui/utilities.css'

Tailwind preset usage

Use Spectre tokens as the source of truth for your Tailwind theme:

// tailwind.config.ts
import type { Config } from 'tailwindcss'
import { createSpectreTailwindPreset } from '@phcdevworks/spectre-ui/tailwind'
import tokens from '@phcdevworks/spectre-tokens'

const config: Config = {
  content: ['./src/**/*.{ts,tsx,js,jsx,html}'],
  presets: [createSpectreTailwindPreset({ tokens })]
}

export default config

Class recipe usage

Class recipes are the stable styling API for adapters and apps. They return predictable class strings and keep behavior consistent across frameworks.

import {
  getBadgeClasses,
  getButtonClasses,
  getPricingCardClasses
} from '@phcdevworks/spectre-ui'

const cta = getButtonClasses({ variant: 'primary', size: 'lg' })
const badge = getBadgeClasses({ variant: 'success', size: 'sm' })
const pricingCard = getPricingCardClasses({ featured: true })

When to use this package

Use @phcdevworks/spectre-ui when you need:

• precompiled, token-backed CSS ready to drop into any framework
• a Tailwind preset or theme helper built from Spectre tokens
• stable, type-safe class recipes for shared UI patterns (buttons, badges, cards, inputs, etc.) that you want to remain consistent across frameworks
• a styling contract that is enforced through tests and CI rather than conventions alone

When not to use this package

Do not use @phcdevworks/spectre-ui when you need to:

• Define new design values — add them to @phcdevworks/spectre-tokens instead.
• Deliver framework components — use an adapter package such as @phcdevworks/spectre-ui-astro that wraps this package in framework-native components.
• Use raw Tailwind utilities without a shared recipe contract — import Tailwind directly and use the Spectre preset; you do not need this package's recipe layer if you are building one-off UI with utility classes.

What belongs here vs elsewhere

| What | Where it lives | | ------------------------------------------------ | ------------------------------------------ | | Semantic color values, spacing scale, type scale | @phcdevworks/spectre-tokens | | Token-to-CSS variable mapping | here — src/styles/ | | Precompiled CSS bundles | here — built to dist/*.css | | Class recipe functions (input → class string) | here — src/recipes/ | | Tailwind preset and theme helpers | here — src/tailwind/ | | Astro, React, Vue, Lit, Svelte components | Adapter packages (e.g. spectre-ui-astro) | | WordPress shortcodes or PHP templates | A WordPress adapter package | | App-level layout, routing, or data fetching | Consuming apps | | New design decisions (new colors, new spacing) | @phcdevworks/spectre-tokens |

Golden rule: this package consumes tokens and exposes class contracts. It does not define tokens and it does not deliver framework components.

Package exports / API surface

Recipe quick reference

All recipe functions accept a plain options object and return a class string. All options are optional and fall back to sensible defaults.

| Recipe | Function | Variants | Sizes | Common boolean flags | | ----------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------- | | Button | getButtonClasses | primary secondary ghost danger success cta accent | sm md lg | disabled loading fullWidth pill iconOnly | | Badge | getBadgeClasses | primary secondary success warning danger neutral info ghost accent cta | sm md lg | interactive disabled loading fullWidth | | Card | getCardClasses | elevated flat outline ghost | — | interactive padded fullHeight disabled loading | | Input | getInputClasses | — | sm md lg | disabled loading fullWidth pill | | Input state | getInputClasses | state: default error success disabled loading | — | — | | IconBox | getIconBoxClasses | primary secondary success warning danger info neutral ghost accent cta | sm md lg | interactive disabled loading pill fullWidth | | PricingCard | getPricingCardClasses | — | — | featured interactive disabled loading fullHeight | | Rating | getRatingClasses | — | sm md lg | interactive disabled loading pill fullWidth | | Testimonial | getTestimonialClasses | elevated flat outline ghost | — | interactive disabled loading fullHeight | | Alert | getAlertClasses | info success warning danger neutral | sm md lg | dismissed | | Avatar | getAvatarClasses | — | sm md lg xl | shape: circle square | | Tag | getTagClasses | default primary secondary success warning danger info neutral accent cta outline ghost | sm md lg | dismissible selected disabled loading interactive fullWidth | | Spinner | getSpinnerClasses | — | sm md lg | — | | Nav | getNavClasses | — | — | bordered sticky fullWidth align: start\|center\|end | | Toast | getToastClasses | info success warning danger | — | dismissed fullWidth | | Tooltip | getTooltipClasses | placement: top bottom left right | — | visible | | Dropdown | getDropdownClasses | menu placement: bottom-start bottom-end top-start top-end | — | fullWidth, item: active disabled | | Modal | getModalClasses | — | — | open fullWidth | | Container | getContainerClasses | maxWidth: prose | — | — | | Stack | getStackClasses | direction: vertical horizontal, basis: sidebar, align: center stretch | — | — | | Section | getSectionClasses | — | — | — | | Grid | getGridClasses | columns: 1 2 3 4 6 12 | gap: sm md lg | — | | Sidebar | getSidebarClasses | — | — | bordered | | Footer | getFooterClasses | — | — | bordered fullWidth | | Checkbox | getCheckboxClasses | — | — | checked disabled | | Radio | getRadioClasses | — | — | checked disabled | | Select | getSelectClasses | size: sm md lg, state: default invalid success | — | fullWidth pill disabled focused loading | | Textarea | getTextareaClasses | size: sm md lg, state: default invalid success | — | fullWidth pill disabled focused loading | | Fieldset | getFieldsetClasses | — | — | disabled | | Label | getLabelClasses | — | — | disabled required |

Each recipe family also exports sub-element helpers for its structural parts (labels, wrappers, sub-containers, text elements). See the full list below.

Semantic utility classes (no recipe wrapper)

These primitives are intentionally plain CSS classes in src/styles/utilities.css with no recipe function — there is no variant or size axis to validate, so a recipe wrapper would add indirection without a type-safety benefit. Apply the class name directly.

| Class | Tokens | Usage | | ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------- | | .sp-link | --sp-link-default --sp-link-hover --sp-link-active --sp-link-visited | Inline text links (<a>). | | .sp-surface--hover | --sp-surface-hover | Clickable list items, menu items, table rows on hover. | | .sp-surface--selected | --sp-surface-selected | Selected list items, menu items, table rows. | | .sp-surface--active | --sp-surface-active | Pressed/active state for clickable surfaces. | | .sp-divider | --sp-surface-divider | <hr>, section separators, table borders. |

Root package

The root package exports CSS path constants plus the recipe functions re-exported from src/recipes/index.ts.

Root constants:

• spectreStyles
• spectreBaseStylesPath
• spectreComponentsStylesPath
• spectreIndexStylesPath
• spectreUtilitiesStylesPath

Root recipe functions:

• getAlertClasses
• getAvatarClasses
• getBadgeClasses
• getButtonClasses
• getCardClasses
• getCheckboxClasses
• getContainerClasses
• getDropdownClasses
• getFieldsetClasses
• getFooterClasses
• getGridClasses
• getIconBoxClasses
• getInputClasses
• getLabelClasses
• getModalClasses
• getNavClasses
• getPricingCardClasses
• getRadioClasses
• getRatingClasses
• getSectionClasses
• getSelectClasses
• getSidebarClasses
• getSpinnerClasses
• getStackClasses
• getTagClasses
• getTestimonialClasses
• getTextareaClasses
• getToastClasses
• getTooltipClasses

Root recipe helper functions:

• getDropdownItemClasses
• getDropdownMenuClasses
• getFieldsetLegendClasses
• getInputErrorMessageClasses
• getInputHelperTextClasses
• getInputLabelClasses
• getInputWrapperClasses
• getModalOverlayClasses
• getNavLinkClasses
• getNavLinksClasses
• getPricingCardBadgeClasses
• getPricingCardDescriptionClasses
• getPricingCardPriceClasses
• getPricingCardPriceContainerClasses
• getRatingStarClasses
• getRatingStarsClasses
• getRatingTextClasses
• getSidebarBackdropClasses
• getSidebarGroupClasses
• getSidebarGroupSummaryClasses
• getSidebarHeaderClasses
• getSidebarLinkClasses
• getSidebarToggleClasses
• getTestimonialAuthorClasses
• getTestimonialAuthorInfoClasses
• getTestimonialAuthorNameClasses
• getTestimonialAuthorTitleClasses
• getTestimonialQuoteClasses
• getToastIconClasses

The root package also re-exports the related recipe option, variant, size, and state TypeScript types defined by those recipes.

Tailwind entry point

@phcdevworks/spectre-ui/tailwind exports:

• createSpectreTailwindPreset
• createSpectreTailwindTheme

CSS entry points

• @phcdevworks/spectre-ui/index.css
• @phcdevworks/spectre-ui/base.css
• @phcdevworks/spectre-ui/components.css
• @phcdevworks/spectre-ui/utilities.css

Public contract guarantees

ui-contract.manifest.json defines the public styling contract for this package.

It covers:

• CSS entry points
• root package constants and recipe function exports
• Tailwind subpath exports
• recipe families, variants, sizes, and public states

Every contract-facing surface must match that manifest. Validation fails when README documentation omits manifest-declared exports, when export snapshots drift, when Tailwind artifacts drift, or when CSS contract coverage no longer matches the declared surface.

Sidebar interactive-state contract

getSidebarClasses is the first recipe family with an interactive-state CSS contract. Below breakpoints.md (768px), .sp-sidebar renders off-canvas (transform: translateX(-100%)). This package owns only the CSS reaction to that state — it does not own toggle behavior, click handlers, or open/closed state management.

Consumers (typically a framework adapter) toggle the sidebar by setting a data-sidebar-open="true" attribute on an ancestor element wrapping .sp-sidebar and .sp-sidebar-backdrop (from getSidebarBackdropClasses):

• [data-sidebar-open="true"] .sp-sidebar slides the sidebar into view (transform: translateX(0)).
• [data-sidebar-open="true"] .sp-sidebar-backdrop shows the backdrop overlay (display: block).
• Above breakpoints.md, the sidebar docks inline and the backdrop is always hidden, regardless of the data-sidebar-open value.

A consumer-rendered toggle button that opens/closes the sidebar must carry getSidebarToggleClasses(). .sp-sidebar-toggle stacks above .sp-sidebar-backdrop (--sp-component-sidebar-toggle-z-index, above --sp-component-sidebar-backdrop-z-index) so the backdrop never intercepts clicks meant for the toggle once the sidebar is open. The class also supplies the token-backed button layout, color, hover, and focus-visible treatment; adapters only supply the control markup and behavior.

Adapters own the hamburger/toggle control, click handling, and SSR-safe initial closed state.

Above breakpoints.md, .sp-sidebar stretches to height: 100% so a short link list matches the height of a taller sibling content column when docked inline in a Stack row (see align: 'stretch' on getStackClasses).

getSidebarLinkClasses accepts a level option ('parent' | 'child', default 'parent') for nested link indentation — e.g. a package name with "Overview" / "Reference" links beneath it. getSidebarHeaderClasses styles a section label (e.g. "Tokens", "UI", "Guides") as a muted eyebrow, visually distinct from .sp-sidebar__link.

For collapsible navigation sections, apply getSidebarGroupClasses() to a native details element and getSidebarGroupSummaryClasses() to its summary. The CSS removes the browser marker, styles the summary as an interactive section label, and rotates a consumer-provided .sp-sidebar__group-icon when the group is open. Wrap the nested links in .sp-sidebar__group-content for the standard bottom spacing. Open/closed behavior remains native to details; this package returns class strings and does not render markup.

Downstream boundaries

Downstream packages should never redefine locally:

• Spectre design token meaning
• CSS class semantics already provided by this package
• recipe option names, variants, sizes, or states
• package CSS entry point behavior
• Tailwind helper export names

Downstream packages may:

• compose application UI with the exported classes
• wrap recipe functions in framework-specific adapters
• import CSS entry points directly in applications or adapter packages
• extend app-specific layout around Spectre contracts

Upgrade expectations for consumers

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

Practical guidance:

• additive recipes, variants, states, and helpers are intended to be safe for existing consumers
• semantic shifts may keep the same class or option name but still affect visual output
• renames, removals, and behavior changes to existing classes or options are breaking
• generated JS, TypeScript declarations, CSS bundles, Tailwind exports, README docs, and ui-contract.manifest.json are expected to stay aligned

If a downstream package depends on a class, recipe option, CSS entry point, or Tailwind helper:

• read CHANGELOG.md for contract change classification
• prefer documented public exports over internal paths
• run consuming app validation after package upgrades

Change classification

Contract-affecting changes should be classified in CHANGELOG.md [Unreleased] before release.

| Classification | When to use | Examples | | ----------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- | | additive | New public styling surface that does not break existing consumers | Adding a recipe helper, variant, state, or CSS entry point | | semantic change | Public name remains but behavior or visual meaning shifts | Adjusting an existing class or recipe option to map to different token intent | | breaking | Existing consumers may need code changes | Renaming or removing a class, option, export, or CSS entry point |

Renames and removals are always breaking regardless of perceived scope.

Relationship to the rest of Spectre

Spectre keeps responsibilities separate:

• @phcdevworks/spectre-tokens defines design values and semantic meaning
• @phcdevworks/spectre-ui turns those tokens into reusable CSS, Tailwind tooling, and type-safe class recipes
• @phcdevworks/spectre-components turns those styling contracts into framework-agnostic Lit web components
• Adapters and apps consume @phcdevworks/spectre-ui instead of re-implementing its styling layer, or wrap Spectre component contracts for a specific runtime

That separation keeps recipe behavior consistent across frameworks and reduces implementation drift.

Consumer checklist

For downstream packages and compatible apps:

• import @phcdevworks/spectre-ui/index.css for the full styling contract
• import split CSS entry points only when the consumer needs bundle-level control
• use recipe functions when framework adapters need stable class strings
• use @phcdevworks/spectre-ui/tailwind for Tailwind theme integration
• consume tokens from @phcdevworks/spectre-tokens instead of inventing visual values locally
• treat dist/ as generated package output, not an authoring surface
• do not add framework runtime logic to this package

Development

Local setup

git clone https://github.com/phcdevworks/spectre-ui.git
cd spectre-ui
nvm use          # picks up .nvmrc (Node 22.22.2)
npm install
npm run ci:verify

This project requires Node.js ^22.13.0 || >=24.0.0 and npm >=10.0.0. The checked-in package manager is [email protected].

Common commands

| Command | What it does | | ---------------------------------- | -------------------------------------------------------- | | npm run check | Full validation gate — run before every PR | | npm run ci:verify | Underlying verification sequence used by npm run check | | npm test | Build then run the contract and regression test suite | | npm run build | Emit TypeScript and CSS artifacts to dist/ | | npm run lint | ESLint with TypeScript-aware config | | npm run validate:exports | Verify root export surface against snapshot | | npm run validate:exports:update | Update the export snapshot after adding a public export | | npm run validate:tailwind | Verify Tailwind exports and emitted subpath artifacts | | npm run validate:tailwind:update | Update the Tailwind export snapshot | | npm run validate:tokens | Check for token drift against latest published release |

Troubleshooting

validate:runtime fails — you are on the wrong Node version. Run nvm use to switch to the version in .nvmrc, or install Node 22 or 24.

validate:tokens fails with a network error — the check requires outbound npm registry access. In a restricted environment, run the other validators individually; this step is the only network-dependent one in ci:verify.

Tests pass but the build shows stale output — npm test rebuilds automatically via the pretest hook. If you ran vitest directly, run npm run build first.

Lint fails locally but passes in CI — confirm you are on the same Node version as CI (Node 22.x or 24.x). ESLint plugin resolution can differ across runtimes.

Export snapshot out of date — run npm run validate:exports:update after adding a public export, then commit the updated scripts/export-snapshot.json.

Key source areas

• src/styles/ for source CSS
• src/recipes/ for class recipes
• src/tailwind/ for Tailwind helpers
• tests/ for contract and regression coverage
• examples/ for visual demos and verification fixtures

Planning artifacts for contract hardening live in ROADMAP.md and TODO.md.

All scoped roadmap phases through Phase 5 are delivered — there is no open implementation phase right now. New recipe or CSS work opens only when a downstream adapter surfaces a real integration gap, or when @phcdevworks/spectre-tokens publishes a new token group this package should consume. This package synchronizes only against published npm releases, not in-progress upstream work.

Examples

Use examples/examples.html as the visual index for the package demos.

Available examples include:

• vanilla.html for the broad component showcase
• showroom.html for a richer marketing-style composition
• verification.html and focused verification fixtures for regression checks

Validation

Run the full validation gate before any pull request:

npm run check

This runs: runtime check → lint → changelog validation → export validation → README validation → token drift check → build → Tailwind contract → CSS contract → tests. All steps must pass.

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 token sync passes. GitHub Copilot provides development support.

Claude Code, Codex, and Copilot do not create git commits by default. Jules may commit only bounded automated maintenance when the JULES.md scope and validation gates pass. Release decisions, tags, and publishing remain with Bradley Potts.

Protected from automated change: CSS contracts, recipe public API surface, and the zero-hex policy (no hardcoded color/spacing values). See AGENTS.md for full agent governance and boundary rules.

Contributing

PHCDevworks maintains this package as part of the Spectre suite.

When contributing:

• keep styling token-driven
• keep recipe APIs and CSS classes in sync
• avoid local visual values unless clearly intentional
• run npm run check before opening a pull request

See CONTRIBUTING.md for the full workflow.

License

MIT © PHCDevworks. See LICENSE.