@nebulaai/lumina-ui/DESIGN_SYSTEM.md

Enterprise-grade glass morphism UI components with neural-inspired design system

# Lumina UI Design System

A premium glass morphism design system for React applications.

## Design Philosophy

Lumina UI embraces the beauty of light, transparency, and depth. Our design system is built on three core principles:

1. **Luminous Clarity** - Clean, readable interfaces with purposeful transparency
2. **Elegant Depth** - Layered glass effects that create visual hierarchy
3. **Smooth Interactions** - Fluid animations and tactile feedback

## Visual Language

### Glass Morphism
Our signature aesthetic combines:
- Translucent backgrounds with backdrop blur
- Subtle border highlights
- Layered depth with shadows
- Luminous glow effects

### Color Palette
- **Primary**: Deep navy with glass variants
- **Secondary**: Soft grays with transparency
- **Accent**: Bright blues and purples for highlights
- **Glass**: White/black overlays with varying opacity

### Typography
- **Headings**: Bold, high contrast for clarity through glass
- **Body**: Readable weights optimized for translucent backgrounds
- **UI Text**: Carefully spaced for glass interface elements

## Component Architecture

### Base Components
All components inherit from base glass styles:
```css
.glass {
  @apply bg-white/10 backdrop-blur-md border border-white/20;
}
```

### Interaction States
- **Hover**: Increased opacity and subtle elevation
- **Active**: Reduced elevation and scale
- **Focus**: Glow rings and border enhancement
- **Disabled**: Reduced opacity and blocked interactions

### Animation Principles
- **Duration**: 200ms for micro-interactions, 300ms for transitions
- **Easing**: Smooth curves that feel natural
- **Physics**: Elevation and scale changes that respect momentum

## Layout System

### Spacing Scale
Based on 4px grid system:
- **Tight**: 12px (3 units) - Component internal spacing
- **Standard**: 16px (4 units) - Element spacing
- **Section**: 24px (6 units) - Section spacing
- **Generous**: 32px (8 units) - Major layout spacing

### Glass Panel Structure
- **Sidebar**: 320px width with rounded-right corners
- **Main Content**: Fluid with max-width constraints
- **Modals**: Centered with backdrop blur overlay
- **Cards**: 16px border radius with hover elevation

## Accessibility

### Glass Considerations
- High contrast text over translucent backgrounds
- Alternative solid backgrounds for reduced motion
- Keyboard navigation with visible focus states
- Screen reader optimized markup

### Interactive Elements
- Minimum 44px touch targets
- Clear focus indicators
- Descriptive ARIA labels
- Semantic HTML structure

## Usage Guidelines

### Do's
✅ Layer glass elements for depth
✅ Use consistent border radius (12px-16px)
✅ Apply hover states for interactive elements
✅ Maintain high contrast for text readability

### Don'ts
❌ Overuse transparency (maintain hierarchy)
❌ Stack too many glass layers
❌ Use low contrast text on glass
❌ Ignore reduced motion preferences

## Implementation

### Required Setup
1. Include Tailwind CSS with our custom config
2. Import base glass styles
3. Configure backdrop-blur support
4. Add CSS custom properties for theming

### Example Usage
```tsx
import { Button, Card } from '@nebulaai/lumina-ui'

<Card className="lumina-card">
  <Button variant="glass" className="hover-elevate">
    Glass Button
  </Button>
</Card>
```

## Browser Support

- **Modern Browsers**: Full glass morphism support
- **Safari**: Optimized backdrop-blur performance
- **Firefox**: Fallback solid backgrounds
- **Chrome**: Hardware accelerated effects

## Performance

- GPU-accelerated transforms and filters
- Minimal DOM manipulation
- Optimized CSS for mobile devices
- Reduced motion alternatives