# Phoenix Nexus Design System

## Overview

The unified design system for Sankofa's Phoenix Nexus Cloud, ensuring consistent identity and experience across all three layers (Public Marketing, Portals, Documentation).

---

## Color System

### Primary Colors

**Phoenix Fire** (`#FF4500`)
- Primary brand color
- Used for CTAs, highlights, active states
- CSS variable: `--phoenix-fire`

**Sankofa Gold** (`#FFD700`)
- Secondary brand color
- Used for accents, premium features
- CSS variable: `--sankofa-gold`

**Sovereignty Purple** (`#6A0DAD`)
- Trust and compliance
- Used for security, enterprise features
- CSS variable: `--sovereignty-purple`

### Neutral Colors

**Studio Black** (`#0A0A0A`)
- Primary background
- CSS variable: `--studio-black`

**Studio Dark** (`#1A1A1A`)
- Secondary background
- CSS variable: `--studio-dark`

**Studio Medium** (`#2A2A2A`)
- Borders, dividers
- CSS variable: `--studio-medium`

### Status Colors

- **Success**: `#00FF88` (green)
- **Warning**: `#FFB800` (yellow)
- **Error**: `#FF0040` (red)
- **Info**: `#00B8FF` (blue)

---

## Typography

### Font Families

- **Sans**: Inter (via Next.js font optimization)
- **Mono**: System monospace

### Scale

- **Display**: 5xl, 4xl, 3xl (hero sections)
- **Heading**: 2xl, xl, lg (section headers)
- **Body**: base, sm (content)
- **Caption**: xs (metadata, labels)

---

## Components

### Buttons

**Variants**:
- `phoenix` - Primary action (Phoenix Fire)
- `outline` - Secondary action
- `ghost` - Tertiary action
- `destructive` - Destructive action

**Sizes**:
- `lg` - Large (hero CTAs)
- `default` - Standard
- `sm` - Small (compact spaces)

### Cards

Consistent card styling across all layers:
- Border: `border-studio-medium`
- Background: `bg-studio-black` or `bg-studio-dark`
- Hover: `hover:border-phoenix-fire/50`

### Forms

- Input fields with consistent styling
- Labels with proper spacing
- Error states with red accents
- Success states with green accents

---

## Spacing System

Using Tailwind's spacing scale:
- `xs`: 4px
- `sm`: 8px
- `md`: 16px
- `lg`: 24px
- `xl`: 32px
- `2xl`: 48px
- `3xl`: 64px

---

## Responsive Breakpoints

- **Mobile**: < 640px
- **Tablet**: 640px - 1024px
- **Desktop**: > 1024px

---

## Accessibility

### WCAG Compliance

- ✅ Semantic HTML
- ✅ ARIA labels where needed
- ✅ Keyboard navigation
- ✅ Focus indicators
- ✅ Color contrast ratios
- ✅ Screen reader support

### Best Practices

- Use `lang="en"` on `<html>`
- Provide `<title>` elements
- Use proper heading hierarchy
- Include alt text for images
- Ensure touch targets are at least 44x44px

---

## Animation

### Transitions

- Standard: `transition-colors`
- Duration: 200-300ms
- Easing: `ease-in-out`

### Loading States

- Spinner: `animate-spin`
- Pulse: `animate-pulse`
- Fade: `animate-fade-in`

---

## Usage Guidelines

### Public Marketing Site

- Use Phoenix Fire for primary CTAs
- Use Sankofa Gold for premium features
- Maintain high contrast for readability
- Focus on conversion and trust

### Portals

- Use Studio Dark backgrounds
- Phoenix Fire for active states
- Clear visual hierarchy for tasks
- Consistent navigation patterns

### Documentation

- Clean, readable typography
- Code blocks with proper syntax highlighting
- Clear section navigation
- Search-first UX

---

## Implementation

All components are in `src/components/ui/` using shadcn/ui as the base, customized with Phoenix Nexus colors and styling.

---

**Last Updated**: Current
**Version**: 1.0

