@phcdevworks/spectre-ui 0.2.2 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @phcdevworks/spectre-ui
 
-Framework-agnostic styling layer that powers Spectre Blocks, Spectre Astro, Spectre 11ty, and every Spectre integration.
+Cross-platform UI built on Spectre Tokens. A Tailwind-powered design system that turns the tokens into consistent CSS utilities, component classes and design recipes for WordPress blocks, Astro components, 11ty templates and other modern web apps.
 
 > 🤝 **[Contributing Guide](CONTRIBUTING.md)** | 📝 **[Changelog](CHANGELOG.md)**
 
@@ -43,11 +43,14 @@ import "@phcdevworks/spectre-ui/index.css";
 
 ### 2. Tailwind integration
 
-Spectre ships an opinionated Tailwind preset that mirrors the design tokens exactly.
+Spectre ships utilities to create Tailwind presets that mirror the design tokens exactly.
 
 ```ts
 // tailwind.config.ts
-import { spectrePreset } from "@phcdevworks/spectre-ui";
+import { createSpectreTailwindPreset } from "@phcdevworks/spectre-ui/tailwind";
+import { spectreTokens } from "@phcdevworks/spectre-tokens";
+
+const spectrePreset = createSpectreTailwindPreset({ tokens: spectreTokens });
 
 export default {
   content: ["./src/**/*.{js,ts,jsx,tsx,astro}"],
@@ -61,10 +64,8 @@ Works with Tailwind 3.x and 4.x through the classic config API.
 
 ```ts
 // tailwind.config.ts
-import {
-  createSpectreTailwindPreset,
-  spectreTokens,
-} from "@phcdevworks/spectre-ui";
+import { createSpectreTailwindPreset } from "@phcdevworks/spectre-ui/tailwind";
+import { spectreTokens } from "@phcdevworks/spectre-tokens";
 
 const customPreset = createSpectreTailwindPreset({
   tokens: spectreTokens,
@@ -87,10 +88,8 @@ export default {
 
 ```ts
 // tailwind.config.ts
-import {
-  createSpectreTailwindTheme,
-  spectreTokens,
-} from "@phcdevworks/spectre-ui";
+import { createSpectreTailwindTheme } from "@phcdevworks/spectre-ui/tailwind";
+import { spectreTokens } from "@phcdevworks/spectre-tokens";
 
 const { theme } = createSpectreTailwindTheme({
   tokens: spectreTokens,
@@ -317,16 +316,105 @@ import {
 
 Designers update tokens in `@phcdevworks/spectre-tokens`. Engineering evolves recipes, presets, and CSS in this package.
 
+## Testing
+
+The package includes automated tests to ensure recipe correctness, CSS contract integrity, and token-first design compliance:
+
+```bash
+npm test
+```
+
+Tests validate recipe output, CSS selector coverage, and guard against token drift (undefined variables, fallback values, raw color literals). All tests run via Vitest.
+
 ## Build & Release
 
 ```bash
 npm run build
 ```
 
-`tsup` compiles the TypeScript library (ESM, CJS, `.d.ts`) and copies CSS files to `dist/`. Because `dist/` is generated, releases are reproducible from `src/`.
+The build process consists of two steps:
+
+1. **TypeScript & CSS Copy (via tsup):**
+
+- Compiles the TypeScript source to ESM, CJS, and type definitions in `dist/`.
+- Copies raw CSS files (`base.css`, `components.css`, `utilities.css`) from `src/styles/` to `dist/`.
+
+2. **CSS Bundling (via PostCSS):**
+
+- Processes `src/styles/index.css` with PostCSS (including imports and plugins) and outputs the bundled CSS as `dist/index.css`.
+
+The `npm run build` script runs both steps in sequence:
+
+```bash
+tsup --config tsup.config.ts && npm run build:css
+```
+
+This ensures all JavaScript, type definitions, and CSS bundles are up to date in `dist/` for publishing.
 
 For release history and version notes, see the **[Changelog](CHANGELOG.md)**.
 
+## Spectre Design Philosophy
+
+Spectre is a **specification-driven design system** built on three strict layers:
+
+### 1. @phcdevworks/spectre-tokens (Foundation)
+
+**Purpose**: Single source of truth for design values (colors, surfaces, text roles, space, radii, shadows, etc.)
+
+**Exports**: CSS variables (`--sp-*`), TypeScript token object, Tailwind-compatible theme mappings
+
+**Rules**:
+
+- Tokens define semantic meaning, not UI behavior
+- UI must never invent new colors or values
+- Designers own `tokens/*.json`; engineers maintain `src/` transforms
+- Contrast targets and accessibility constraints are encoded at the token level
+
+**Status**: v0.1.0 released with stable semantic roles (`surface.*`, `text.*`, `component.*`) and considered correct/locked
+
+### 2. @phcdevworks/spectre-ui (Framework-Agnostic UI Layer)
+
+**Purpose**: Converts tokens into real CSS and class recipes
+
+**Ships**:
+
+- `index.css` (canonical CSS bundle: tokens + base + components + utilities)
+- `base.css` (resets + globals)
+- `components.css` (`.sp-btn`, `.sp-card`, `.sp-input`, etc.)
+- `utilities.css` (`.sp-stack`, `.sp-container`, etc.)
+- Type-safe recipes: `getButtonClasses`, `getCardClasses`, `getInputClasses`
+
+**Rules**:
+
+- UI must consume tokens, not redefine design values
+- Literal values in CSS are fallbacks only
+- Every CSS selector has a matching recipe where applicable
+- Tailwind preset is optional and non-authoritative
+
+**Status**: v0.4.0 released with refactored component styles and enhanced CSS variable system
+
+### 3. Framework Adapters (WordPress, Astro, 11ty)
+
+**Purpose**: Thin adapter layer around spectre-ui; automatically syncs and enqueues the Spectre UI CSS bundle
+
+**Rules**:
+
+- Adapters never define styles, never duplicate CSS, never load tokens directly
+- Adapters only synchronize and load CSS
+- All design values come from tokens, all CSS comes from spectre-ui
+
+**Status**: WordPress and Astro adapters at v0.1.0 with frontend and editor integration
+
+### Golden Rule (Non-Negotiable)
+
+**Tokens define meaning. UI defines structure. Adapters only translate.**
+
+Frameworks never invent CSS or design values—they only load what spectre-ui provides.
+
+- If it's a design token → belongs in `@phcdevworks/spectre-tokens`
+- If it's a CSS class or style → belongs in `@phcdevworks/spectre-ui`
+- If it's framework integration (hooks, blocks, components) → belongs in the adapter
+
 ## Design Principles
 
 1. **Single source of truth** – All Spectre products consume these styles and recipes.
@@ -341,8 +429,6 @@ Type definitions are bundled automatically:
 
 ```ts
 import type {
-  SpectreTokens,
-  SpectreTailwindTheme,
   ButtonVariant,
   ButtonSize,
   InputState,
@@ -358,6 +444,14 @@ import type {
   BadgeRecipeOptions,
   IconBoxRecipeOptions,
 } from "@phcdevworks/spectre-ui";
+
+import type {
+  SpectreTailwindTheme,
+  CreateSpectreTailwindThemeOptions,
+  CreateSpectreTailwindPresetOptions,
+} from "@phcdevworks/spectre-ui/tailwind";
+
+import type { SpectreTokens } from "@phcdevworks/spectre-tokens";
 ```
 
 ## Part of the Spectre Suite