@phcdevworks/spectre-ui-astro

Astro integration layer for the Spectre design system.

> 📋 View Roadmap | 🤝 Contributing Guide | 📝 Changelog

Overview

@phcdevworks/spectre-ui-astro is the official Astro adapter for the Spectre design system.

This package provides ergonomic Astro components (, , , , ) that wrap @phcdevworks/spectre-ui's design system. This package is a thin integration layer that consumes Spectre UI recipes and classes without duplicating styling logic.

- ✅ Uses Spectre UI's .sp-* classes and recipes internally
- ✅ Does not reimplement design logic
- ✅ Provides fully typed components with discriminated unions
- ✅ SSR-safe and framework-agnostic (pure Astro components)
- ✅ Consumes all styling from @phcdevworks/spectre-ui

$3

- ✅ Provides Astro component wrappers for Spectre UI
- ✅ Uses canonical recipes from @phcdevworks/spectre-ui
- ✅ Follows Astro SSR constraints (no client-side JavaScript unless specified)
- ✅ Exports type-safe component interfaces
- ✅ Provides a stable foundation for Spectre-powered Astro applications

$3

- ❌ Does not define or override design values
- ❌ Does not reimplement CSS or styling logic
- ❌ Does not run token generation at runtime
- ❌ Does not provide client-side JavaScript frameworks
- ❌ Does not manage CSS bundling (consumers import from @phcdevworks/spectre-ui)

This separation is intentional and enforced.

Installation

``bash
npm install @phcdevworks/spectre-ui-astro @phcdevworks/spectre-ui
`

Usage

$3

Import Spectre UI's CSS in your Astro layout:

`astro
---
// src/layouts/Layout.astro
import "@phcdevworks/spectre-ui/index.css";
---
`

$3

`astro
---
import "@phcdevworks/spectre-ui/index.css";
import {
SpBadge,
SpButton,
SpCard,
SpIconBox,
SpInput,
} from "@phcdevworks/spectre-ui-astro";
---


Get Started


label="Email"
type="email"
name="email"
placeholder="Enter your email"
required
/>
`

Components

$3

`astro
Primary CTA
Secondary
Low-emphasis
Destructive
`

All variants support full state coverage: disabled, loading, and sizes (sm, md, lg).

Polymorphic rendering:

`astro

Submit Form


Learn More


Non-interactive
`

Full props:

- variant: "primary" | "secondary" | "ghost" | "success" | "danger" (default: "primary")
- size: "sm" | "md" | "lg" (default: "md")
- as: "button" | "a" | "span" (default: "button")
- type: "button" | "submit" | "reset" (when as="button")
- href, target: string (when as="a")
- disabled, loading, fullWidth, iconOnly: boolean
- class: string (additional CSS classes)

$3

`astro



`

Full props:

- state: "default" | "error" | "success" | "disabled" (default: "default")
- type: "text" | "email" | "password" | "number" | "tel" | "url" | "search" | "date" | "time" | "datetime-local" (default: "text")
- label, errorMessage, helperText: string
- id: string (auto-generated if not provided)
- name, value, placeholder: string
- required, disabled, readonly: boolean
- class: string (additional CSS classes)
- Standard input attributes: min, max, step, pattern, maxlength, minlength

$3

`astro
Default shadow
Bordered
Transparent
`

Semantic HTML:

`astro



Article Title

- variant: "elevated" | "flat" | "outline" | "ghost" (default: "elevated")
- as: "div" | "section" | "article" (default: "div")
- class: string (additional CSS classes)

$3

`astro
Primary
Success
Warning
Danger
`

Full props:

- variant: "primary" | "success" | "warning" | "danger" (default: "primary")
- size: "sm" | "md" | "lg" (default: "md")
- class: string (additional CSS classes)

$3

`astro







`

Full props:

- variant: "primary" | "success" | "warning" | "danger" | "info" (default: "primary")
- size: "sm" | "md" | "lg" (default: "md")
- as: "div" | "span" (default: "span")
- class: string (additional CSS classes)

TypeScript Support

Type definitions are bundled automatically:

`typescript
import type {
BadgeVariant,
BadgeSize,
ButtonVariant,
ButtonSize,
CardVariant,
IconBoxVariant,
IconBoxSize,
InputState,
InputSize,
} from "@phcdevworks/spectre-ui-astro";
`

CSS Import

Spectre UI provides a single bundled CSS file that includes all necessary styles:

`astro
---
import "@phcdevworks/spectre-ui/index.css";
---
`

Alternatively, you can use the exported constant:

`astro
---
import { SPECTRE_UI_CSS } from "@phcdevworks/spectre-ui-astro";
---

`

This single import includes tokens, base styles, components, and utilities - everything needed for Spectre UI Astro components to work correctly.

Design Principles

1. Single source of truth – All design lives in @phcdevworks/spectre-ui
2. No CSS duplication – This package never defines .sp-* styles
3. Adapter, not framework – Thin by design
4. Type-safe ergonomics – Every component exports strict TypeScript types for confident usage
5. SSR-safe – All components work with Astro's server-side rendering

Part of the Spectre Suite

- Spectre Tokens – Design-token foundation
- Spectre UI – Core styling layer
- Spectre Blocks – WordPress block library
- Spectre Astro – Astro integration (this package)
- Spectre 11ty – Eleventy integration

For the project's future direction, see the Roadmap.

Contributing

Issues and pull requests are welcome. If you are proposing component or type changes, update src/` and include regenerated builds.

For detailed contribution guidelines, see CONTRIBUTING.md.

License

MIT © PHCDevworks — See LICENSE for details.

---

❤️ Support Spectre

If Spectre UI Astro helps your workflow, consider sponsoring:

- GitHub Sponsors
- Buy Me a Coffee