README

A modern TALL stack component library built with Tailwind CSS v4, Livewire 3, and Alpine.js.

Features

Modern Stack: Built on the TALL stack (Tailwind v4, Alpine.js, Laravel 12, Livewire 3)
Accessible: Full keyboard navigation, ARIA attributes, and semantic HTML
Themeable: Semantic color tokens with built-in light/dark mode support
Localized: i18n support for English, French, and Arabic
Composable: Highly flexible components using Blade slots and attributes
Testable: Designed with testing in mind using Pest v4

Installation

Quick Install (Recommended)

Install the package via Composer and run the install command:

composer require stratos/spire-ui
php artisan spire:install

The install command will:

✓ Detect your package manager (npm, pnpm, or yarn)
✓ Install JavaScript dependencies (Alpine.js, Tailwind CSS, polyfills, flag-icons)
✓ Build assets
✓ Optionally publish configuration
✓ Show you the next steps

Manual Installation

If you prefer to install dependencies manually:

composer require stratos/spire-ui
npm install && npm run build

Asset Setup

Import CSS in your resources/css/app.css:

@import 'tailwindcss';
@import '../../vendor/stratos/spire-ui/resources/css/index.css';

Import JavaScript in your resources/js/app.js:

import { initializeSpireUI } from '../../vendor/stratos/spire-ui/resources/js/index';

initializeSpireUI();

Build assets:

npm run build

Configuration (Optional)

Publish the configuration file to customize component defaults:

php artisan vendor:publish --tag=spire-ui-config

This will create config/spire-ui.php where you can customize:

Component prefix
Dark mode settings
Global component defaults (size, radius, placement)
Component-specific settings

Usage

Components will be available using the spire prefix:

<x-spire::button>Click me</x-spire::button>

Component Naming Convention

Spire UI uses folder-based components with dot notation:

Parent component: <x-spire::dropdown />
Child component: <x-spire::dropdown.item />

Theming

Spire UI uses semantic color tokens defined in vendor/stratos/spire-ui/resources/css/base/theme.css. All tokens support light/dark mode automatically.

Available Tokens

Primary: primary, primary-hover, primary-active, primary-foreground
Secondary: secondary, secondary-hover, secondary-active, secondary-foreground
Surfaces: body, surface, overlay (elevation hierarchy from base to top)
Text: text, text-muted, text-disabled
Borders: border, border-hover, border-focus
States: success, error, warning, info (each with -hover, -bg, -foreground variants)

Surface Elevation Hierarchy

Spire UI uses a three-layer elevation system that creates depth through color contrast:

Light Mode:

body - neutral-50 (subtle gray background)
surface - white (cards, panels appear elevated/lighter)
overlay - neutral-100 (modals, dialogs on top)

Dark Mode:

body - neutral-950 (darkest background)
surface - neutral-900 (cards, panels slightly lighter)
overlay - neutral-800 (modals, dialogs even lighter)

<!-- Page background -->
<body class="bg-body text-text">
    <!-- Elevated card -->
    <div class="bg-surface border border-border rounded-lg p-6">
        <h2>Card content appears elevated</h2>
    </div>

    <!-- Modal overlay (highest elevation) -->
    <div class="bg-overlay/95 backdrop-blur">
        <div class="bg-surface rounded-lg p-6">
            Modal content
        </div>
    </div>
</body>

Color System Architecture

Spire UI uses a three-layer color system:

Base Colors (7 colors): primary-base, secondary-base, neutral-base, success-base, error-base, warning-base, info-base
Shade Scale (50-950): Each base generates 11 shades using relative color syntax
Semantic Tokens: User-friendly names with automatic light/dark mode support

Foreground Colors

Each semantic color has an adaptive -foreground variant that ensures WCAG-compliant contrast:

<!-- Automatically adapts text color for optimal contrast -->
<button class="bg-primary text-primary-foreground">
    Click me
</button>

<div class="bg-success text-success-foreground p-4">
    Success message with perfect contrast
</div>

<span class="bg-error text-error-foreground px-2 py-1">
    Error badge
</span>

Usage Examples

<!-- Using semantic tokens -->
<button class="bg-primary hover:bg-primary-hover text-primary-foreground">
    Primary Button
</button>

<!-- Using specific shades -->
<div class="bg-primary-50 text-primary-900 dark:bg-primary-950 dark:text-primary-100">
    Custom styled element
</div>

<!-- State colors with foreground -->
<div class="bg-warning text-warning-foreground border border-warning rounded-md p-4">
    Warning message
</div>

Localization

Spire UI supports multiple languages out of the box. Set your application locale:

// config/app.php
'locale' => 'en', // or 'fr', 'ar'

Translation files are located in vendor/stratos/spire-ui/resources/lang/{locale}/spire-ui.php.

Contributing

Contributions are welcome! Please read our Contributing Guide and Code of Conduct before submitting pull requests.

License

MIT License

stratos / spire-ui

Maintainers

Details