# Nardo Grey Theme System - Implementation Guide

## Overview

This theme system is built on Nardo Grey (#4B4B4B) as the foundational brand anchor, with emerald accents and semantic color tokens for maximum readability and visual hierarchy.

## Design Principles

### 1. Nardo Grey Foundation
- **Brand Anchor**: Nardo Grey (#4B4B4B) serves as the primary brand color
- **Not Overwhelming**: Used strategically for backgrounds and accents, never covering everything
- **Sophisticated**: Provides a premium, modern aesthetic without being harsh

### 2. High Contrast Text
- **Ivory Text**: #F5F5F2 instead of pure white for warmth
- **Muted Sand**: #D6D3C9 for secondary text 
- **WCAG AA Compliance**: All text combinations meet 4.5:1+ contrast ratios
- **No Washed Out Look**: Deliberate contrast choices prevent text from becoming unreadable

### 3. Emerald Accent System
- **Primary Emerald**: #2ECC71 for light mode, #58D68D for dark mode
- **Confident Color**: Breaks up grey monotony with vibrant, professional accent
- **Versatile**: Works for buttons, links, highlights, and focus states
- **Accessible**: Proper contrast ratios maintained across all usage

## Semantic Token System

### Background Colors
```css
--color-bg-primary: #FAFAFA (light) / #4B4B4B (dark)    /* Page backgrounds */
--color-bg-secondary: #F5F5F2 (light) / #3B3B3B (dark)  /* Card/section backgrounds */
--color-surface: rgba(255,255,255,0.85) (light) / rgba(75,75,75,0.85) (dark) /* Panels, widgets */
```

### Text Colors
```css
--color-text-primary: #1A1A1A (light) / #F5F5F2 (dark)     /* Main text */
--color-text-secondary: #4B4B4B (light) / #D6D3C9 (dark)   /* Muted text */
--color-text-tertiary: #6B6B6B (light) / #ABABAB (dark)    /* Subtle text */
--color-text-disabled: #ABABAB (light) / #6B6B6B (dark)    /* Disabled states */
```

### Accent Colors
```css
--color-accent: #2ECC71 (light) / #58D68D (dark)           /* Primary emerald */
--color-accent-hover: #27AE60 (light) / #85E6A3 (dark)     /* Hover states */
--color-accent-bg: rgba(46,204,113,0.1) (light) / rgba(88,214,141,0.15) (dark) /* Backgrounds */
--color-accent-border: rgba(46,204,113,0.3) (light) / rgba(88,214,141,0.4) (dark) /* Borders */
```

### Elevation System
```css
--color-elevated-1: rgba(255,255,255,0.9) (light) / rgba(75,75,75,0.6) (dark)   /* Subtle elevation */
--color-elevated-2: rgba(255,255,255,0.95) (light) / rgba(75,75,75,0.8) (dark)  /* Medium elevation */
--color-elevated-3: #FFFFFF (light) / #6B6B6B (dark)                           /* High elevation */
```

## Component Usage Patterns

### Buttons
```tsx
// Primary action - emerald accent
<Button variant="primary" size="md">Primary Action</Button>

// Secondary action - elevated surface with accent border
<Button variant="secondary" size="md">Secondary Action</Button>

// Accent background - light emerald
<Button variant="accent" size="md">Accent Action</Button>

// Minimal styling
<Button variant="ghost" size="md">Ghost Action</Button>
```

### Cards
```tsx
// Default card with subtle elevation
<Card variant="default" elevation="1">...</Card>

// Medium elevation for important content
<Card variant="elevated" elevation="2">...</Card>

// Clean surface for grouped content
<Card variant="surface" elevation="1">...</Card>

// Premium glassmorphism effect
<Card variant="glass" elevation="2">...</Card>
```

### Tailwind Utility Classes
```tsx
// Backgrounds
<div className="bg-primary">       {/* Page background */}
<div className="bg-secondary">     {/* Card background */}
<div className="bg-surface">       {/* Panel background */}

// Text
<p className="text-primary">       {/* Main text */}
<p className="text-secondary">     {/* Muted text */}
<p className="text-accent">        {/* Accent text */}

// Elevation
<div className="bg-elevated-1">    {/* Subtle elevation */}
<div className="bg-elevated-2">    {/* Medium elevation */}
<div className="bg-elevated-3">    {/* High elevation */}

// States
<div className="state-success">    {/* Success background + text */}
<div className="state-warning">    {/* Warning background + text */}
<div className="state-error">      {/* Error background + text */}
```

### Custom Utility Classes
```tsx
// Pre-built card styles
<div className="card">             {/* Default card with borders + shadow */}
<div className="card-elevated">    {/* Medium elevation card */}
<div className="card-raised">      {/* High elevation card */}

// Glass effects
<div className="glass">            {/* Glassmorphism with backdrop blur */}
<div className="glass-subtle">     {/* Lighter glass effect */}
<div className="glass-strong">     {/* Stronger glass effect */}

// Interactive elements
<button className="interactive">   {/* Hover effects + focus ring */}
```

## Visual Hierarchy Guidelines

### 1. Card Elevation
- **Level 1**: Basic content containers (elevation="1")
- **Level 2**: Important content, featured items (elevation="2") 
- **Level 3**: Modal dialogs, critical alerts (elevation="3")

### 2. Text Hierarchy
- **Primary**: Main headings, important content
- **Secondary**: Body text, descriptions
- **Tertiary**: Labels, metadata, timestamps
- **Disabled**: Inactive elements

### 3. Color Usage
- **Emerald Accent**: CTAs, links, active states, success indicators
- **Background Surfaces**: Content separation without overwhelming
- **Border Colors**: Subtle definition between elements

## Accessibility Features

### Focus Management
- **Emerald Focus Rings**: Clear visibility for keyboard navigation
- **2px Ring Width**: WCAG compliant focus indicators
- **Proper Offset**: Ring separated from element for clarity

### Contrast Ratios
- **Text on Light**: 4.5:1+ ratio for all text sizes
- **Text on Dark**: 4.5:1+ ratio for all text sizes  
- **Accent Combinations**: Verified across all background colors

### Color Blind Friendly
- **Emerald Choice**: Easily distinguishable from grey foundations
- **Multiple Indicators**: Never rely on color alone for meaning
- **Pattern + Color**: Use text, icons, or shapes alongside color

## Dark Mode Implementation

### Automatic Theme Switching
```tsx
// The system automatically adjusts based on:
// 1. User preference (localStorage)
// 2. System preference (prefers-color-scheme)
// 3. Class-based toggling (.dark)
```

### Key Dark Mode Changes
- **Background**: Nardo Grey becomes the primary background
- **Text**: Ivory and sand colors for warmth instead of stark white
- **Accent**: Lighter emerald (#58D68D) for proper contrast
- **Shadows**: Enhanced shadows for depth in dark environments
- **Glass Effects**: Adjusted opacity and blur for dark themes

## Browser Support

### CSS Custom Properties
- All modern browsers (IE11+ with polyfill)
- CSS variables cascade properly across theme changes
- Fallback values provided for critical properties

### Backdrop Blur
- Modern browsers with Webkit/Blink engines
- Graceful degradation to solid backgrounds
- Progressive enhancement approach

## Performance Considerations

### Token-Based System
- **CSS Variables**: Minimal runtime overhead
- **No JavaScript**: Theme switching via CSS class changes
- **Tree Shaking**: Unused utilities removed by Tailwind

### Optimization Tips
- Use semantic tokens instead of hardcoded values
- Leverage Tailwind's purge/scan functionality
- Minimize custom CSS in favor of utility classes

## Quick Reference

### Theme Colors (Light Mode)
- **Nardo Grey**: #4B4B4B
- **Page Background**: #FAFAFA (subtle off-white)
- **Card Background**: #F5F5F2 (warm ivory)
- **Primary Text**: #1A1A1A (near black)
- **Emerald Accent**: #2ECC71

### Theme Colors (Dark Mode)  
- **Nardo Grey**: #4B4B4B (primary background)
- **Card Background**: #3B3B3B (darker grey)
- **Primary Text**: #F5F5F2 (warm ivory)
- **Secondary Text**: #D6D3C9 (muted sand)
- **Emerald Accent**: #58D68D (lighter for contrast)

### Usage Examples
```tsx
// Dashboard card
<Card variant="elevated" elevation="2" className="p-lg">
  <h2 className="text-primary text-xl font-semibold mb-md">Revenue</h2>
  <p className="text-secondary text-sm mb-lg">Monthly performance</p>
  <Button variant="primary" size="sm">View Details</Button>
</Card>

// Navigation link
<a href="/events" className="text-secondary hover:text-accent transition-colors">
  Events
</a>

// Status indicator
<div className="state-success p-md rounded-lg">
  <span className="font-medium">Payment successful</span>
</div>
```

## Development Workflow

1. **Always use semantic tokens** instead of hardcoded colors
2. **Test in both light and dark modes** before committing
3. **Verify contrast ratios** for any new text/background combinations  
4. **Use pre-built card/button variants** when possible
5. **Follow the elevation system** for visual hierarchy
6. **Test keyboard navigation** to ensure focus visibility

This theme system provides a solid foundation for building sophisticated, accessible interfaces with the professional aesthetic of Nardo Grey and the vibrant confidence of emerald accents.