A hauntingly beautiful design system that merges gothic horror aesthetics with cutting-edge user experience design. PhantomUI creates an ethereal, atmospheric interface through translucent ghost elements, supernatural animations, shadowy depth effects, and eerie micro-interactions while maintaining full usability and accessibility.

• 🎨 Comprehensive Design Token System - Eight phantom colors, five shadow levels, and five animation primitives
• 👻 Gothic Horror Components - 17 production-ready components with supernatural aesthetics
• ✨ GPU-Accelerated Animations - Smooth 60fps animations using Framer Motion
• 🌫️ Canvas-Based Particle Effects - Performant fog, spirits, and atmospheric effects
• ♿ WCAG AA Accessible - Full keyboard navigation, ARIA labels, and screen reader support
• 📱 Fully Responsive - Works seamlessly across all device sizes
• 🎭 Demo Application - Grimoire Dashboard showcasing all components
• 🔧 TypeScript First - Complete type safety and IntelliSense support
• ⚡ Optimized Performance - Code splitting, lazy loading, and Intersection Observer

# Clone the repository
git clone https://github.com/HectorTa1989/phantomui.git
cd phantomui

# Install dependencies
npm install

# Start the demo application
npm run dev

The demo will be available at http://localhost:5173

# Install the core package (when published to npm)
npm install @phantomui/core

import { GhostlyButton, SpectralCard, PhantomModal } from '@phantomui/core';
import '@phantomui/core/dist/style.css';

function App() {
  return (
    <SpectralCard hoverable>
      <h2>Welcome to the Spirit Realm</h2>
      <GhostlyButton variant="primary">
        Enter the Darkness
      </GhostlyButton>
    </SpectralCard>
  );
}

phantomui/
├── packages/
│   ├── core/                    # Design system components library
│   │   ├── src/
│   │   │   ├── tokens/         # Design tokens (colors, shadows, typography)
│   │   │   ├── components/     # UI components
│   │   │   ├── animations/     # Animation primitives and utilities
│   │   │   ├── particles/      # Particle system
│   │   │   └── index.ts        # Public API
│   │   └── package.json
│   └── demo/                    # Grimoire Dashboard demo application
│       ├── src/
│       │   ├── pages/          # Application pages
│       │   ├── components/     # Demo-specific components
│       │   └── App.tsx
│       └── package.json
├── .kiro/                       # Kiro AI configuration
│   ├── specs/                   # Feature specifications
│   ├── hooks/                   # Automation hooks
│   └── steering/                # Code quality patterns
└── package.json                 # Monorepo root

PhantomUI includes 17 production-ready components:

• GhostlyButton - Translucent buttons with ripple effects and supernatural hover states
• CursedInput - Input fields with animated candle flames and validation states
• ShadowDropdown - Dropdowns that unfold from darkness with glowing items
• PhantomModal - Modals that materialize from fog with animated backdrops

• SpectralCard - Glassmorphism cards with fog particle effects
• GraveyardTable - Data tables with tombstone-styled rows and spirit animations
• SoulProgressBar - Progress bars with flowing ethereal energy
• HauntedToast - Notification toasts that dissolve into particles

• CandelabraSpinner - Three flickering candles loading indicator
• PageTransition - Veil transitions with ghostly figures

• GhostCursorTrail - Ethereal trail following the cursor
• CandlelightFlicker - Dynamic candlelight simulation
• BreathingContainer - Subtle breathing animation for containers
• DynamicShadow - Uncanny valley shadow effects
• SpiritOrbs - Floating orbs with organic movement

• CandleFlame - Reusable animated flame component
• ParticleSystem - Canvas-based particle effects engine
• ToastProvider - Context provider for toast notifications

• Framework: React 18 with TypeScript
• Build Tool: Vite for fast development and optimized builds
• Animation: Framer Motion for declarative animations
• Styling: TailwindCSS + CSS custom properties
• Particle Effects: Canvas API with simplex-noise for organic movement
• Routing: React Router for multi-page demo
• Testing: Vitest for unit tests, fast-check for property-based tests
• Type Safety: TypeScript with strict mode enabled

• Component API Documentation - Detailed API reference for all components
• Design Tokens - Colors, typography, shadows, and animations
• Accessibility Guidelines - WCAG compliance and best practices
• Performance Optimization - Tips for optimal performance
• Kiro Usage Guide - How this project was built with Kiro AI

The Grimoire Dashboard is a fully functional paranormal investigation agency dashboard that showcases all PhantomUI components:

• Home/Dashboard - Activity feed, spectral map, and team avatars
• Investigation Reports - Data table with search and filters
• Equipment Tracker - Card grid with battery progress bars
• Settings - Form with various input controls
• Dark Archive - Document viewer with page flip animation

# Install dependencies
npm install

# Start demo in development mode
npm run dev

# Build all packages
npm run build

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch --workspace=packages/core

# Lint code
npm run lint

PhantomUI is built with accessibility as a core principle:

• ✅ WCAG AA compliant (4.5:1 contrast ratios)
• ✅ Full keyboard navigation support
• ✅ ARIA labels and roles for screen readers
• ✅ Visible focus indicators with ethereal glow
• ✅ Respects prefers-reduced-motion media query
• ✅ Semantic HTML structure

All components are optimized for 60fps performance:

• GPU-accelerated animations (transform and opacity only)
• Canvas API with requestAnimationFrame for particle effects
• Intersection Observer to pause animations when not visible
• Code splitting and lazy loading
• Object pooling for particle systems
• CSS containment for layout optimization

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Required features: CSS backdrop-filter, Canvas API, CSS custom properties, Intersection Observer, requestAnimationFrame

https://youtu.be/R_5Mx9Gq3h4

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

MIT License - see LICENSE file for details

Built with Kiro AI - An AI-powered development assistant that helped create this entire design system through spec-driven development.

• 📧 Email: support@phantomui.dev
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

"Where shadows dance and spirits whisper, PhantomUI brings the supernatural to your fingertips." 👻