@phcdevworks/spectre-ui

@phcdevworks/spectre-ui is the implementation layer between @phcdevworks/spectre-tokens and downstream adapters or 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.

Contributing | Changelog | Security Policy

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

Installation

npm install @phcdevworks/spectre-ui

Quick start

CSS import

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 { spectreTokens } from '@phcdevworks/spectre-tokens'

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

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 })

What this package owns

• 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

Golden rule: consume tokens, do not redefine them.

What this package does not own

• 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.

Package exports / API surface

Root package

Exports CSS path constants and class recipes, including:

• spectreStyles
• getButtonClasses
• getBadgeClasses
• getCardClasses
• getInputClasses
• getIconBoxClasses
• getPricingCardClasses
• getTestimonialClasses
• getRatingClasses

Recipes also export their related TypeScript option and variant types.

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

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
• Adapters and apps consume @phcdevworks/spectre-ui instead of re-implementing its styling layer

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

Development

Install dependencies, then run the package checks:

npm run build
npm test

Key source areas:

• src/styles/ for source CSS
• src/recipes/ for class recipes
• src/tailwind/ for Tailwind helpers
• tests/ for contract and regression coverage

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 build and npm test before opening a pull request

See CONTRIBUTING.md for the full workflow.

License

MIT © PHCDevworks. See LICENSE.