blackcanyontickets/reactrebuild0825/NARDO_GREY_THEME_GUIDE.md

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

--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

--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

--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

--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

// 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

// 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

// 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

// 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

// 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

// 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.