@phcdevworks/spectre-ui 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -6,18 +6,73 @@ reflects package releases published to npm.
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-06-03
+
+Release Title: Tag Variant Expansion and Token Alignment
+
+### Added
+
+- **Tag Variants**: Expanded Tag recipe with `primary`, `secondary`, `success`,
+  `warning`, `danger`, `info`, `neutral`, `accent`, `cta`, and `ghost` variants
+  for full parity with Badge and Button components. CSS selectors backed by
+  token roles only.
+- **Dark Mode Fixtures**: Added dark mode verification fixtures under `examples/`
+  for Alert, Avatar, and Tag recipes.
+
+### Changed
+
+- **Token Alignment**: Updated `@phcdevworks/spectre-tokens` dependency to
+  `^2.7.0`.
+- **CI**: Promoted Node 24.x to the primary CI matrix target; Node 22.x
+  retained for one more cycle.
+- **Documentation**: Added Recipe Composition section to `CONTRIBUTING.md`
+  covering how adapters compose multiple recipe helpers, contract guarantees
+  (pure function, deterministic output, no side effects), and non-guarantees
+  (CSS specificity interactions, class ordering).
+
+## [1.6.0] - 2026-05-22
+
+Release Title: Contract Expansion and Governance Hardening
+
+### Added
+
+- **Component Variants**: Added `cta` variant support for `Badge` and
+  `IconBox`, `fullWidth` structural support for `IconBox`, and structural
+  `elevated`, `flat`, `outline`, and `ghost` variants for `Testimonial`.
+- **Input Recipes**: Added wrapper, label, helper-text, and error-message class
+  helpers so adapters can reuse the full input sub-element contract.
+- **Contract Governance**: Added Claude, Codex, Copilot, and Jules agent
+  guidance, PR template requirements, maintenance instructions, release
+  readiness prompts, and CodeRabbit configuration for review hygiene.
+- **Validation Shortcut**: Added `npm run check` as the canonical local and CI
+  validation gate.
+
 ### Changed
 
-- Clarified Spectre layer documentation so the UI package remains Layer 2,
-  `@phcdevworks/spectre-components` is the Layer 3 web-component package, and
-  framework adapters such as `@phcdevworks/spectre-ui-astro` remain downstream
-  delivery packages.
-- Added root Copilot support guidance to match the Spectre AI instruction
-  structure used by `@phcdevworks/spectre-tokens`.
-- Corrected README automation wording so Jules' bounded maintenance commit
-  authority matches `JULES.md`.
-- Removed a stale `.agents/jules.md` reference from shared agent guidance.
-- Updated shared agent guidance to reference the root Copilot support file.
+- **Token Alignment**: Updated the package to consume
+  `@phcdevworks/spectre-tokens` `^2.6.0` and refreshed dependency metadata.
+- **Runtime Contract**: Raised the Node.js requirement to `^22.13.0` or
+  `>=24.0.0`, documented npm `>=10.0.0`, and updated CI to validate on Node
+  22.x and 24.x.
+- **Validation Tooling**: Migrated build and validation scripts from `.mjs` to
+  TypeScript entry points executed with `node --experimental-strip-types`.
+- **Package Metadata**: Repositioned the package description and keywords
+  around Layer 2 CSS bundles, Tailwind tooling, and class recipes; included
+  `CHANGELOG.md` in the published package files.
+- **Documentation**: Expanded README, contributing, roadmap, TODO, and agent
+  guidance around the Spectre layer model, framework boundaries, contract
+  validation, package exports, and release-readiness workflows.
+
+### Fixed
+
+- **State Parity**: Improved Badge, Card, IconBox, PricingCard, and Testimonial
+  recipe/CSS parity for forced hover, focus, active, disabled, loading, and
+  structural state coverage.
+- **Selector Coverage**: Added testimonial attribute-selector support and
+  refreshed contract tests, export snapshots, and manifest entries for the new
+  public recipe helpers and variants.
+- **Docs Drift**: Corrected README badges, package links, Node/npm guidance,
+  Jules automation wording, and stale agent-reference paths.
 
 ## [1.5.0] - 2026-05-04
 

package/README.md

@@ -1,9 +1,9 @@
 # @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)
-[![License](https://img.shields.io/github/license/phcdevworks/spectre-ui)](LICENSE)
+[![CI](https://github.com/phcdevworks/spectre-ui/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/phcdevworks/spectre-ui/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/@phcdevworks/spectre-ui)](LICENSE)
+[![Node](https://img.shields.io/node/v/@phcdevworks/spectre-ui)](https://nodejs.org)
 
 `@phcdevworks/spectre-ui` is **Layer 2 of the Spectre design suite**. It turns
 [`@phcdevworks/spectre-tokens`](https://github.com/phcdevworks/spectre-tokens)
@@ -17,7 +17,8 @@ styling contract without re-implementing class logic themselves.
 `@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) |
+[Contributing](CONTRIBUTING.md) | [Code of Conduct](CODE_OF_CONDUCT.md) |
+[Changelog](CHANGELOG.md) | [Roadmap](ROADMAP.md) |
 [Security Policy](SECURITY.md)
 
 ## Source of truth
@@ -40,37 +41,15 @@ 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
-└─────────────────────────────┘
-```
+| 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 |
 
-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.
+`@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
 
@@ -251,6 +230,10 @@ All options are optional and fall back to sensible defaults.
 | 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` | — |
 
 Each recipe family also exports sub-element helpers for its structural parts
 (labels, wrappers, sub-containers, text elements). See the full list below.
@@ -270,6 +253,8 @@ Root constants:
 
 Root recipe functions:
 
+- `getAlertClasses`
+- `getAvatarClasses`
 - `getBadgeClasses`
 - `getButtonClasses`
 - `getCardClasses`
@@ -277,6 +262,8 @@ Root recipe functions:
 - `getInputClasses`
 - `getPricingCardClasses`
 - `getRatingClasses`
+- `getSpinnerClasses`
+- `getTagClasses`
 - `getTestimonialClasses`
 
 Root recipe helper functions:

package/dist/base.css

@@ -144,10 +144,14 @@
   --sp-layout-container-max-width: 72rem;
   --sp-border-width-base: 1px;
   --sp-border-width-thick: 2px;
+  --sp-border-style-none: none;
+  --sp-border-style-solid: solid;
   --sp-radius-none: 0;
   --sp-radius-sm: 2px;
   --sp-radius-md: 4px;
   --sp-radius-lg: 8px;
+  --sp-radius-xl: 12px;
+  --sp-radius-2xl: 16px;
   --sp-radius-pill: 999px;
   --sp-font-family-sans: system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
   --sp-font-family-serif: 'Times New Roman', Times, serif;
@@ -183,34 +187,21 @@
   --sp-font-6xl-line-height: 5rem;
   --sp-font-6xl-weight: 900;
   --sp-font-xs-letter-spacing: 0.02em;
-  --sp-text-on-page-default: #141b24;
-  --sp-text-on-page-muted: #4b576a;
-  --sp-text-on-page-subtle: #657287;
-  --sp-text-on-page-meta: #657287;
-  --sp-text-on-surface-default: #141b24;
-  --sp-text-on-surface-muted: #4b576a;
-  --sp-text-on-surface-subtle: #657287;
-  --sp-text-on-surface-meta: #657287;
-  --sp-badge-neutral-bg: #eef1f6;
-  --sp-badge-neutral-text: #374253;
-  --sp-badge-info-bg: #e0f2fe;
-  --sp-badge-info-text: #075985;
-  --sp-badge-success-bg: #dcfce7;
-  --sp-badge-success-text: #166534;
-  --sp-badge-warning-bg: #fff1c2;
-  --sp-badge-warning-text: #8f5200;
-  --sp-badge-danger-bg: #fee2e2;
-  --sp-badge-danger-text: #991b1b;
-  --sp-icon-box-bg: #ffffff;
-  --sp-icon-box-border: #d9dfeb;
-  --sp-icon-box-icon-default: #0369a1;
-  --sp-icon-box-icon-success: #16a34a;
-  --sp-icon-box-icon-warning: #d48806;
-  --sp-icon-box-icon-danger: #dc2626;
+  --sp-font-sm-letter-spacing: 0em;
+  --sp-font-md-letter-spacing: 0em;
+  --sp-font-lg-letter-spacing: 0em;
+  --sp-font-xl-letter-spacing: 0em;
+  --sp-font-2xl-letter-spacing: 0em;
+  --sp-font-3xl-letter-spacing: 0em;
+  --sp-font-4xl-letter-spacing: 0em;
+  --sp-font-5xl-letter-spacing: 0em;
+  --sp-font-6xl-letter-spacing: 0em;
   --sp-shadow-none: none;
   --sp-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.06);
   --sp-shadow-md: 0 2px 6px -1px rgba(0, 0, 0, 0.08);
   --sp-shadow-lg: 0 6px 16px -4px rgba(0, 0, 0, 0.12);
+  --sp-shadow-xl: 0 12px 24px -6px rgba(0, 0, 0, 0.15);
+  --sp-shadow-2xl: 0 20px 48px -12px rgba(0, 0, 0, 0.20);
   --sp-breakpoint-sm: 640px;
   --sp-breakpoint-md: 768px;
   --sp-breakpoint-lg: 1024px;
@@ -224,20 +215,26 @@
   --sp-z-index-modal: 1400;
   --sp-z-index-popover: 1500;
   --sp-z-index-tooltip: 1600;
+  --sp-z-index-toast: 1700;
   --sp-duration-instant: 75ms;
   --sp-duration-fast: 150ms;
   --sp-duration-base: 200ms;
+  --sp-duration-relaxed: 250ms;
   --sp-duration-moderate: 300ms;
   --sp-duration-slow: 500ms;
   --sp-duration-slower: 700ms;
+  --sp-duration-long: 1000ms;
+  --sp-duration-slowest: 1200ms;
   --sp-easing-linear: linear;
   --sp-easing-in: cubic-bezier(0.4, 0, 1, 1);
   --sp-easing-out: cubic-bezier(0, 0, 0.2, 1);
   --sp-easing-inout: cubic-bezier(0.4, 0, 0.2, 1);
   --sp-easing-spring: cubic-bezier(0.4, 0, 0.2, 1);
+  --sp-easing-overshoot: cubic-bezier(0.34, 1.56, 0.64, 1);
   --sp-opacity-disabled: 0.38;
   --sp-opacity-hover: 0.92;
   --sp-opacity-active: 0.84;
+  --sp-opacity-loading: 0.6;
   --sp-opacity-focus: 1;
   --sp-opacity-overlay: 0.5;
   --sp-opacity-tooltip: 0.95;
@@ -369,7 +366,7 @@
   --sp-button-text-default: #eef1f6;
   --sp-button-text-on-primary: #ffffff;
   --sp-badge-neutral-bg: #374253;
-  --sp-badge-neutral-text: #eef1f6;
+  --sp-badge-neutral-text: #f7f8fb;
   --sp-badge-info-bg: #0c4a6e;
   --sp-badge-info-text: #e0f2fe;
   --sp-badge-success-bg: #166534;