Astro integration layer for the Spectre design system.
npm install @phcdevworks/spectre-ui-astroAstro integration layer for the Spectre design system.
> 📋 View Roadmap | 🤝 Contributing Guide | 📝 Changelog
@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
- ✅ 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
- ❌ 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.
``bash`
npm install @phcdevworks/spectre-ui-astro @phcdevworks/spectre-ui
Import Spectre UI's CSS in your Astro layout:
`astro`
---
// src/layouts/Layout.astro
import "@phcdevworks/spectre-ui/index.css";
---
`astro
---
import "@phcdevworks/spectre-ui/index.css";
import {
SpBadge,
SpButton,
SpCard,
SpIconBox,
SpInput,
} from "@phcdevworks/spectre-ui-astro";
---
Get Started
Card content goes here.
Card Title
type="email"
name="email"
placeholder="Enter your email"
required
/>
`
`astro`
All variants support full state coverage: disabled, loading, and sizes (sm, md, lg).
Polymorphic rendering:
`astro
`
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: booleanclass
- : string (additional CSS classes)
`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: stringid
- : string (auto-generated if not provided)name
- , value, placeholder: stringrequired
- , disabled, readonly: booleanclass
- : string (additional CSS classes)min
- Standard input attributes: , max, step, pattern, maxlength, minlength
`astro`
Semantic HTML:
` Article content.astro`
Article Title
Full props:
- variant: "elevated" | "flat" | "outline" | "ghost" (default: "elevated")as
- : "div" | "section" | "article" (default: "div")class
- : string (additional CSS classes)
`astro`
Full props:
- variant: "primary" | "success" | "warning" | "danger" (default: "primary")size
- : "sm" | "md" | "lg" (default: "md")class
- : string (additional CSS classes)
`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)
Type definitions are bundled automatically:
`typescript`
import type {
BadgeVariant,
BadgeSize,
ButtonVariant,
ButtonSize,
CardVariant,
IconBoxVariant,
IconBoxSize,
InputState,
InputSize,
} from "@phcdevworks/spectre-ui-astro";
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.
1. Single source of truth – All design lives in @phcdevworks/spectre-ui.sp-*
2. No CSS duplication – This package never defines 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
- 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.
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.
MIT © PHCDevworks — See LICENSE for details.
---
If Spectre UI Astro helps your workflow, consider sponsoring: