Spectre Base

WordPress theme delivery layer for the Spectre design system — Vite, TypeScript, Tailwind CSS 4, and a complete template hierarchy.

@phcdevworks/spectre-base (current version 1.0.0) is the WordPress theme delivery layer of the Spectre system. It brings Spectre Tokens, Spectre UI, and Spectre Components into WordPress through a Vite build pipeline, a TypeScript client entrypoint, and Tailwind CSS 4.

It is for teams building custom WordPress themes that need modern frontend assets without moving design-system ownership into PHP templates.

Source of truth

spectre-theme/ is the deployable WordPress theme directory. src/ is the build source. Everything in spectre-theme/dist/ is generated — never edit it directly.

Layer	Path	Rule
Theme JS entry	`src/js/main.ts`	Registers Spectre web components
Theme CSS entry	`src/styles/main.css`	Shell styles using `var(--sp-*)` only
WordPress theme	`spectre-theme/`	Template hierarchy, asset loading, Gutenberg config
Gutenberg tokens	`spectre-theme/theme.json`	All values must come from `var(--sp-*)`
Build output	`spectre-theme/dist/`	Never edit directly — regenerated by `npm run build`

Key capabilities

Ships a deployable WordPress theme directory in spectre-theme/
Builds theme-owned CSS and JavaScript through Vite and TypeScript
Switches between the Vite dev server in development and hashed assets in production (reads dist/.vite/manifest.json)
Consumes Spectre tokens, Spectre UI, and Spectre web components without redefining their contracts
Keeps PHP templates focused on WordPress structure and data delivery
Supports child themes for per-client branding via scaffolding (npm run create:child)

Design system guardrail

The CMS delivers; the design system defines. This theme is the delivery layer, not a second design system. WordPress owns template structure and data delivery; Spectre packages own visual meaning, styling contracts, and components.

Use var(--sp-*) tokens for all CSS values — never hardcode hex, RGB, rem, or px
Use <sp-button>, <sp-input>, and other <sp-*> components for controls
Keep PHP templates structural — semantic shell classes and WordPress functions only

Installation

Prerequisites: Node.js ^22.12.0 || >=24.0.0, npm 11.14.1, PHP 8.2, and ripgrep (required for the drift-check validation step).

npm install

Quick start

Start the Vite dev server:
```
npm run dev
```

Symlink the theme into your local WordPress install:

ln -s /path/to/spectre-base/spectre-theme /path/to/wordpress/wp-content/themes/spectre-theme

Set WordPress to development mode so the theme loads from the Vite dev server instead of spectre-theme/dist/:
```
define('WP_ENVIRONMENT_TYPE', 'development');
```
Build production assets when ready to deploy:
```
npm run build
npm run check:assets
```

Using as a starter

Fork or clone this repository to start a new Spectre-backed WordPress site. Minimum changes for a new site:

Update package.json — set name and version.
Update the theme header in spectre-theme/style.css — Theme Name, Theme URI, Author, Author URI, Description, and Text Domain.
Update spectre-theme/readme.txt to match.
Run npm install.
Symlink the theme and set WP_ENVIRONMENT_TYPE (see Quick start above).
Customize shell styles in src/styles/main.css using var(--sp-*) tokens only.
Register social icons via the spectre_base_footer_social_icons filter.
Build: npm run build && npm run check:assets.

Child themes

Agencies build client sites as WordPress child themes of spectre-base, inheriting the build pipeline, templates, and token contract while keeping client-specific branding isolated. Scaffold a new child theme:

npm run create:child -- <client-name>

This creates spectre-child-<client-name>/ with a style.css, functions.php, and minimal theme.json that inherits the full parent token set and is ready for brand-specific var(--sp-*) overrides.

Deployment

Development — symlink spectre-theme/ into WordPress and set WP_ENVIRONMENT_TYPE=development. Assets stream from the Vite dev server with HMR.

Production — run npm run build, then copy or ZIP the entire spectre-theme/ directory (including dist/) to wp-content/themes/spectre-theme/ on the server:

npm run check
zip -r spectre-theme.zip spectre-theme/

The dist/ directory must be present in the ZIP. It is generated by the build and is not committed to the repository.

What this package owns

The Vite build configuration for theme assets
The TypeScript entrypoint in src/js/main.ts
The CSS entrypoint in src/styles/main.css
The WordPress theme files in spectre-theme/, including asset loading in functions.php
The compiled output for theme-owned assets in spectre-theme/dist/

What this package does not own

Design token definitions — those belong to Spectre Tokens
Reusable UI component contracts and recipes — those belong to Spectre UI and Spectre Components
WordPress core installation, plugin management, or hosting concerns
Application state architecture beyond the theme entrypoint

When to use this package

You are building a WordPress site and need Spectre tokens, UI, and web components delivered through a theme
You want a Vite + TypeScript build pipeline for theme-owned assets without owning the design system itself
You need hot module replacement in development and hashed production assets without writing the plumbing yourself

When not to use this package

You want to define design tokens, color scales, typography, or component contracts — those belong in Spectre Tokens, Spectre UI, and Spectre Components
You need a WordPress plugin — plugin logic belongs in a separate plugin repository such as spectre-icons
You are building a non-WordPress frontend — this package is WordPress-specific

Relationship to the rest of Spectre

Package	Owns
Spectre Tokens	Design values, semantic token meaning, and token contracts
Spectre UI	CSS, utilities, Tailwind helpers, and type-safe class recipes
Spectre Components	Lit web component behavior and API
Spectre Base	WordPress theme delivery and Vite build pipeline

The theme consumes Spectre output — it does not redefine it.

For the full template hierarchy, shell class reference, PHP hook API, CSS custom property namespace, child theme patterns, and Spectre Icons integration, see the Spectre Base reference.