@phcdevworks/spectre-ui 1.5.0 → 1.6.0

package/README.md

@@ -1,21 +1,77 @@
 # @phcdevworks/spectre-ui
 
+[![npm version](https://img.shields.io/npm/v/@phcdevworks/spectre-ui)](https://www.npmjs.com/package/@phcdevworks/spectre-ui)
+[![CI](https://github.com/phcdevworks/spectre-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/phcdevworks/spectre-ui/actions/workflows/ci.yml)
 [![GitHub issues](https://img.shields.io/github/issues/phcdevworks/spectre-ui)](https://github.com/phcdevworks/spectre-ui/issues)
-[![GitHub pull requests](https://img.shields.io/github/issues-pr/phcdevworks/spectre-ui)](https://github.com/phcdevworks/spectre-ui/pulls)
 [![License](https://img.shields.io/github/license/phcdevworks/spectre-ui)](LICENSE)
 
-`@phcdevworks/spectre-ui` is the implementation layer between
+`@phcdevworks/spectre-ui` is **Layer 2 of the Spectre design suite**. It turns
 [`@phcdevworks/spectre-tokens`](https://github.com/phcdevworks/spectre-tokens)
-and downstream adapters or apps.
+into reusable CSS bundles, Tailwind tooling, and type-safe class recipes for
+downstream adapters and apps.
 
-Maintained by PHCDevworks, it turns Spectre tokens into reusable CSS bundles,
-Tailwind tooling, and type-safe class recipes. It is framework-agnostic,
-token-driven, and follows a strict zero-hex policy so visual values do not drift
-locally.
+**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](CONTRIBUTING.md) | [Changelog](CHANGELOG.md) |
 [Security Policy](SECURITY.md)
 
+## 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
+
+```
+┌─────────────────────────────┐
+│  @phcdevworks/spectre-tokens │  Layer 1 — design values, semantic tokens
+│  (design source of truth)   │
+└──────────────┬──────────────┘
+               │ consumed by
+               ▼
+┌─────────────────────────────┐
+│  @phcdevworks/spectre-ui    │  Layer 2 — THIS PACKAGE
+│  CSS bundles, recipes,      │  translates tokens into structure
+│  Tailwind helpers           │
+└──────────────┬──────────────┘
+               │ consumed by
+               ▼
+┌─────────────────────────────┐
+│  @phcdevworks/spectre-      │  Layer 3 — canonical Lit web components
+│  components                 │  wraps CSS classes and recipes as
+│                             │  framework-agnostic custom elements
+└──────────────┬──────────────┘
+               │ alongside / consumed by
+               ▼
+┌─────────────────────────────┐
+│  Adapters and apps          │  Layer 4 — framework-specific delivery
+│  spectre-ui-astro, React,   │  binds Spectre contracts to native
+│  Vue, WordPress, etc.       │  framework ergonomics
+└─────────────────────────────┘
+```
+
+This package owns Layer 2 only. It does not deliver components and it does not
+define tokens. It translates tokens into a stable contract that adapters and
+apps consume.
+
 ## Key capabilities
 
 - Ships precompiled CSS: `index.css`, `base.css`, `components.css`, and
@@ -28,6 +84,27 @@ locally.
 - 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`](https://github.com/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
 
 ```bash
@@ -36,7 +113,34 @@ npm install @phcdevworks/spectre-ui
 
 ## Quick start
 
-### CSS import
+### Vanilla HTML — CSS classes only
+
+No framework needed. Import the CSS and use the `sp-*` classes directly:
+
+```html
+<!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:
 
@@ -87,31 +191,74 @@ const badge = getBadgeClasses({ variant: 'success', size: 'sm' })
 const pricingCard = getPricingCardClasses({ featured: true })
 ```
 
-## What this package owns
+## When to use this package
 
-- Token-driven CSS implementation
-- Precompiled CSS bundles and utility classes
-- Tailwind helpers and preset generation
-- Type-safe class recipes for shared UI contracts
-- Stable styling behavior consumed by downstream adapters and apps
+Use `@phcdevworks/spectre-ui` when you need:
 
-Golden rule: consume tokens, do not redefine them.
+- 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
 
-## What this package does not own
+## 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`](https://github.com/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.
 
-- Design values or semantic meaning That belongs to
-  `@phcdevworks/spectre-tokens`.
-- Framework-specific component delivery Adapters and apps consume
-  `@phcdevworks/spectre-ui`; they do not recreate its styling logic.
-- Local visual values outside the token contract Hardcoded hex, spacing, or
-  shadow values are drift unless clearly intentional and documented.
+## 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` |
+
+Each recipe family also exports sub-element helpers for its structural parts
+(labels, wrappers, sub-containers, text elements). See the full list below.
+
 ### Root package
 
-The root package exports CSS path constants plus the recipe functions re-exported
-from `src/recipes/index.ts`.
+The root package exports CSS path constants plus the recipe functions
+re-exported from `src/recipes/index.ts`.
 
 Root constants:
 
@@ -134,6 +281,10 @@ Root recipe functions:
 
 Root recipe helper functions:
 
+- `getInputErrorMessageClasses`
+- `getInputHelperTextClasses`
+- `getInputLabelClasses`
+- `getInputWrapperClasses`
 - `getPricingCardBadgeClasses`
 - `getPricingCardDescriptionClasses`
 - `getPricingCardPriceClasses`
@@ -164,6 +315,75 @@ state TypeScript types defined by those recipes.
 - `@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.
+
+## 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:
@@ -172,24 +392,79 @@ Spectre keeps responsibilities separate:
   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
+  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
 
-Install dependencies, then run the package verification flow:
+### Local setup
+
+```bash
+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 `npm@11.15.0`.
+
+### 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
 
-    npm run ci:verify
+**`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.
 
-Planning artifacts for contract hardening live in:
+**`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`.
 
-- [`ROADMAP.md`](ROADMAP.md)
-- [`TODO.md`](TODO.md)
+**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.
 
-Key source areas:
+**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
@@ -197,6 +472,9 @@ Key source areas:
 - `tests/` for contract and regression coverage
 - `examples/` for visual demos and verification fixtures
 
+Planning artifacts for contract hardening live in [ROADMAP.md](ROADMAP.md) and
+[TODO.md](TODO.md).
+
 ## Examples
 
 Use [`examples/examples.html`](examples/examples.html) as the visual index for
@@ -208,6 +486,34 @@ Available examples include:
 - `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:
+
+```bash
+npm run check
+```
+
+This runs: runtime check → lint → 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](AGENTS.md) for full agent governance and boundary rules.
+
 ## Contributing
 
 PHCDevworks maintains this package as part of the Spectre suite.
@@ -217,7 +523,7 @@ When contributing:
 - keep styling token-driven
 - keep recipe APIs and CSS classes in sync
 - avoid local visual values unless clearly intentional
-- run npm run ci:verify before opening a pull request
+- run `npm run check` before opening a pull request
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
 

package/dist/base.css

@@ -2,7 +2,7 @@
   --sp-surface-page: #f7f8fb;
   --sp-surface-card: #ffffff;
   --sp-surface-input: #ffffff;
-  --sp-surface-overlay: rgba(20, 27, 36, 0.6);
+  --sp-surface-overlay: rgba(0, 0, 0, 0.6);
   --sp-surface-alternate: #eef1f6;
   --sp-surface-hero: linear-gradient(135deg, #5b6ee1 0%, #6f3fd7 100%);
   --sp-text-on-page-default: #141b24;