# Global Gala Email Design System & Component Inventory

**Version:** 2.0 (Atomic Design)
**Last Updated:** 2025-10-15
**Status:** In Development
**Methodology:** Atomic Design (Atoms → Molecules → Organisms → Templates → Pages)

---

## 🎨 Design Principles

### Alignment with Frontend Brand
The email system must match the frontend design tokens from `/showprima-frontend/apps/admin/src/lib/design-tokens.ts`:

- **Professional & Clean**: Stripe-inspired aesthetic
- **Consistent Branding**: Match frontend color palette exactly
- **Email-Safe**: No gradients, limited CSS, inline styles only
- **Accessible**: WCAG AA contrast ratios, readable typography
- **Responsive**: Mobile-first, tested across email clients

### NO Emojis
**Policy:** Zero emojis in production emails. Use professional iconography and clear typography instead.

---

## 🧬 Atomic Design Methodology for Emails

### Why Atomic Design for Email?
- **Reusability**: Build once, use everywhere
- **Consistency**: All emails share same design language
- **Maintainability**: Update atoms → cascades to all emails
- **Email-Safe**: Each level validated for email client compatibility

### Component Hierarchy

```
┌─────────────────────────────────────────────────┐
│ ATOMS (Design Tokens)                           │
│ ├─ Colors ($colors array)                       │
│ ├─ Typography (font-size, weight, line-height) │
│ ├─ Spacing (margins, padding)                   │
│ └─ Basic HTML elements (inline styled)          │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ MOLECULES (Simple Components)                   │
│ ├─ Button (atom styles + <a> tag)              │
│ ├─ Link (atom styles + color + underline)      │
│ ├─ Info Row (label + value)                    │
│ ├─ List Item (bullet + text)                   │
│ └─ Badge (background + text + padding)         │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ ORGANISMS (Complex Components)                  │
│ ├─ Alert Box (molecules assembled)             │
│ ├─ Card (container + molecules)                │
│ ├─ Section (background + molecules)            │
│ ├─ Table (multiple info rows)                  │
│ └─ Header/Footer (branding + molecules)        │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ TEMPLATES (Page Layouts)                        │
│ ├─ Base Layout (structure)                     │
│ ├─ Transaction Template (order/payment)        │
│ ├─ Notification Template (alerts/updates)      │
│ └─ Authentication Template (login/password)    │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│ PAGES (Specific Emails)                         │
│ ├─ welcome.blade.php                            │
│ ├─ password-reset.blade.php                     │
│ ├─ payment-confirmation.blade.php              │
│ └─ ... (11 total emails)                        │
└─────────────────────────────────────────────────┘
```

### Email Client Compatibility at Each Level
- **Atoms**: 100% inline styles, no CSS classes
- **Molecules**: Table-based layout where needed
- **Organisms**: Tested across Gmail, Outlook, Apple Mail
- **Templates**: MSO conditionals for Outlook
- **Pages**: Final validation in Litmus/Email on Acid

---

## 🎨 Color System

### Current Email Colors (DEPRECATED - DO NOT USE)
❌ **Old system to be removed:**
```php
'obsidian' => '#1a1a1a',
'bronze' => '#be8c3c',
'pearl' => '#fbfbfa',
'ash' => '#eeede9',
'saffron' => '#eb9425',
'jade' => '#35ab6b',
'carnelian' => '#c94630',
```

### ✅ New Email Color System (Frontend-Aligned)

Based on frontend `tailwind.config.js` and `design-tokens.ts`:

```php
$colors = [
    // --- NEUTRALS (Stripe-inspired cool grays) ---
    'white' => '#ffffff',           // Pure white backgrounds
    'neutral-50' => '#fafbfc',      // Light backgrounds, cards
    'neutral-100' => '#f6f8fa',     // Subtle backgrounds
    'neutral-200' => '#e3e8ee',     // Borders
    'neutral-300' => '#d1d9e0',     // Disabled borders
    'neutral-500' => '#697386',     // Secondary text, labels
    'neutral-600' => '#525f7f',     // Body text (subtle)
    'neutral-700' => '#3c4257',     // Body text (default)
    'neutral-800' => '#2e3445',     // Headings
    'neutral-900' => '#1a1f36',     // High contrast text

    // --- PRIMARY BRAND (Blue) ---
    'primary-400' => '#36a9f7',     // Light brand accent
    'primary-500' => '#0d8ce8',     // Main brand color
    'primary-600' => '#0070c6',     // Hover/active state
    'primary-700' => '#0059a1',     // Dark brand

    // --- SEMANTIC COLORS ---
    'success-50' => '#f0fdf5',      // Success background
    'success-500' => '#22c55e',     // Success primary
    'success-600' => '#16a34a',     // Success hover

    'warning-50' => '#fefce8',      // Warning background
    'warning-500' => '#eab308',     // Warning primary
    'warning-600' => '#ca8a04',     // Warning hover

    'error-50' => '#fef2f2',        // Error background
    'error-500' => '#ef4444',       // Error primary
    'error-600' => '#dc2626',       // Error hover

    'info-50' => '#eff6ff',         // Info background
    'info-500' => '#3b82f6',        // Info primary
    'info-600' => '#2563eb',        // Info hover

    // --- BACKGROUNDS ---
    'bg-body' => '#f6f8fa',         // Email body background
    'bg-card' => '#ffffff',         // Card/container background
    'bg-section' => '#fafbfc',      // Section background (subtle)

    // --- BORDERS ---
    'border-light' => '#e3e8ee',    // Standard borders
    'border-card' => '#e6ebf1',     // Card borders
];
```

---

## 📝 Typography System

### Font Stack
```css
font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
```

### Font Sizes (Frontend-aligned)
```php
// Hierarchy follows design-tokens.ts
'text-xs' => '11px',      // 0.6875rem - Fine print, labels
'text-sm' => '12px',      // 0.75rem - Secondary info
'text-base' => '14px',    // 0.875rem - Body text (DEFAULT)
'text-md' => '14px',      // 0.875rem - Body text
'text-lg' => '16px',      // 1rem - Lead paragraphs
'text-xl' => '18px',      // 1.125rem - Subheadings
'text-2xl' => '20px',     // 1.25rem - Section headers
'text-3xl' => '24px',     // 1.5rem - Page headers
'text-4xl' => '32px',     // 2rem - Hero text
```

### Font Weights
```php
'font-normal' => '400',     // Body text
'font-medium' => '500',     // Emphasis, labels
'font-semibold' => '600',   // Buttons, strong emphasis
'font-bold' => '700',       // Headings
```

### Line Heights
```php
'leading-tight' => '1.25',  // Headings
'leading-normal' => '1.5',  // Body text
'leading-relaxed' => '1.75', // Comfortable reading
```

### Letter Spacing
```php
'tracking-tight' => '-0.02em',  // Large headings
'tracking-normal' => '0',       // Body text
'tracking-wide' => '0.02em',    // Small caps, labels
```

---

## ⚛️ ATOMS - Design Tokens & Basic Elements

### Definition
Atoms are the fundamental building blocks. They cannot be broken down further without losing their meaning. In email systems, atoms are:
- **Design tokens** (colors, typography, spacing)
- **Single HTML elements** with inline styles

### File Structure
```
resources/views/emails/atoms/
├── _colors.blade.php         # Color token definitions
├── typography.blade.php       # H1, H2, H3, P, Small
└── spacing.blade.php          # Spacer component
```

### 1. Colors (Design Token Atom)
**File:** `emails/atoms/_colors.blade.php`
```php
@php
// Frontend-aligned color system
$colors = [
    // Neutrals (Stripe-inspired)
    'white' => '#ffffff',
    'neutral-50' => '#fafbfc',
    'neutral-100' => '#f6f8fa',
    'neutral-200' => '#e3e8ee',
    'neutral-500' => '#697386',
    'neutral-700' => '#3c4257',
    'neutral-900' => '#1a1f36',

    // Primary brand
    'primary-500' => '#0d8ce8',
    'primary-600' => '#0070c6',

    // Semantic colors
    'success-50' => '#f0fdf5',
    'success-500' => '#22c55e',
    'warning-50' => '#fefce8',
    'warning-500' => '#eab308',
    'error-50' => '#fef2f2',
    'error-500' => '#ef4444',
    'info-50' => '#eff6ff',
    'info-500' => '#3b82f6',
];
@endphp
```

### 2. Typography Atoms
**Email-safe implementation with inline styles:**

#### H1 Component (`emails/atoms/h1.blade.php`)
```blade
<h1 style="
    margin: 0 0 20px;
    color: {{ $colors['neutral-900'] ?? '#1a1f36' }};
    font-size: 28px;
    font-weight: 600;
    letter-spacing: -0.02em;
    line-height: 1.25;
    font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
">
    {{ $slot }}
</h1>
```

#### H2 Component (`emails/atoms/h2.blade.php`)
```blade
<h2 style="
    margin: 0 0 16px;
    color: {{ $colors['neutral-800'] ?? '#2e3445' }};
    font-size: 20px;
    font-weight: 600;
    letter-spacing: -0.01em;
    line-height: 1.3;
    font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
">
    {{ $slot }}
</h2>
```

#### H3 Component (`emails/atoms/h3.blade.php`)
```blade
<h3 style="
    margin: 0 0 12px;
    color: {{ $colors['neutral-800'] ?? '#2e3445' }};
    font-size: 16px;
    font-weight: 600;
    line-height: 1.4;
    font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
">
    {{ $slot }}
</h3>
```

#### Body Text Component (`emails/atoms/text.blade.php`)
```blade
<p style="
    margin: 0 0 16px;
    color: {{ $colors['neutral-700'] ?? '#3c4257' }};
    font-size: 14px;
    font-weight: 400;
    line-height: 1.5;
    font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
">
    {{ $slot }}
</p>
```

#### Small Text Component (`emails/atoms/small.blade.php`)
```blade
<p style="
    margin: 0 0 12px;
    color: {{ $colors['neutral-500'] ?? '#697386' }};
    font-size: 12px;
    font-weight: 400;
    line-height: 1.5;
    font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
">
    {{ $slot }}
</p>
```

### 3. Spacer Atom (`emails/atoms/spacer.blade.php`)
```blade
<div style="height: {{ $height ?? '20px' }};"></div>
```

**Usage:** `@include('emails.atoms.spacer', ['height' => '40px'])`

---

## 🧩 MOLECULES - Simple Components

### Definition
Molecules are groups of atoms functioning together as a unit. They are relatively simple but serve a clear purpose.

### File Structure
```
resources/views/emails/molecules/
├── button.blade.php           # CTA button
├── link.blade.php             # Text link
├── info-row.blade.php         # Label: Value pair
├── badge.blade.php            # Status badge
└── list-item.blade.php        # Single list item
```

### 1. Button Molecule (`emails/molecules/button.blade.php`)
**Email-safe with table-based structure:**

```blade
@php
$variant = $variant ?? 'primary';
$size = $size ?? 'medium';

// Variant colors
$variantStyles = [
    'primary' => [
        'bg' => $colors['primary-500'] ?? '#0d8ce8',
        'text' => '#ffffff',
    ],
    'secondary' => [
        'bg' => $colors['neutral-700'] ?? '#3c4257',
        'text' => '#ffffff',
    ],
    'success' => [
        'bg' => $colors['success-500'] ?? '#22c55e',
        'text' => '#ffffff',
    ],
    'danger' => [
        'bg' => $colors['error-500'] ?? '#ef4444',
        'text' => '#ffffff',
    ],
];

// Size padding
$sizeStyles = [
    'small' => 'padding: 8px 16px; font-size: 12px;',
    'medium' => 'padding: 12px 24px; font-size: 14px;',
    'large' => 'padding: 14px 32px; font-size: 16px;',
];

$bg = $variantStyles[$variant]['bg'];
$text = $variantStyles[$variant]['text'];
$padding = $sizeStyles[$size];
@endphp

<!--[if mso]>
<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="{{ $href }}" style="height:40px;v-text-anchor:middle;width:200px;" arcsize="10%" stroke="f" fillcolor="{{ $bg }}">
<w:anchorlock/>
<center>
<![endif]-->
<a href="{{ $href }}" style="
    {{ $padding }}
    background-color: {{ $bg }};
    color: {{ $text }} !important;
    font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    font-weight: 600;
    text-decoration: none;
    border-radius: 6px;
    display: inline-block;
    text-align: center;
    line-height: 1.5;
">
    {{ $slot }}
</a>
<!--[if mso]>
</center>
</v:roundrect>
<![endif]-->
```

**Usage:**
```blade
@component('emails.molecules.button', [
    'href' => 'https://example.com',
    'variant' => 'primary',
    'size' => 'medium',
    'colors' => $colors
])
    View Order
@endcomponent
```

### 2. Link Molecule (`emails/molecules/link.blade.php`)
```blade
<a href="{{ $href }}" style="
    color: {{ $colors['primary-600'] ?? '#0070c6' }};
    text-decoration: underline;
    font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
">
    {{ $slot }}
</a>
```

### 3. Info Row Molecule (`emails/molecules/info-row.blade.php`)
**Table-based for email compatibility:**

```blade
<table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin: 0; padding: 12px 0; border-bottom: 1px solid {{ $colors['neutral-200'] ?? '#e3e8ee' }};">
    <tr>
        <td style="
            font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            font-size: 14px;
            font-weight: 500;
            color: {{ $colors['neutral-600'] ?? '#525f7f' }};
            padding-right: 20px;
            vertical-align: top;
            width: 40%;
        ">
            {{ $label }}
        </td>
        <td style="
            font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            font-size: 14px;
            font-weight: 600;
            color: {{ $colors['neutral-900'] ?? '#1a1f36' }};
            vertical-align: top;
            text-align: right;
        ">
            {{ $value }}
        </td>
    </tr>
</table>
```

### 4. Badge Molecule (`emails/molecules/badge.blade.php`)
```blade
@php
$variant = $variant ?? 'neutral';
$badgeStyles = [
    'success' => ['bg' => $colors['success-50'] ?? '#f0fdf5', 'text' => $colors['success-600'] ?? '#16a34a'],
    'warning' => ['bg' => $colors['warning-50'] ?? '#fefce8', 'text' => $colors['warning-600'] ?? '#ca8a04'],
    'error' => ['bg' => $colors['error-50'] ?? '#fef2f2', 'text' => $colors['error-600'] ?? '#dc2626'],
    'info' => ['bg' => $colors['info-50'] ?? '#eff6ff', 'text' => $colors['info-600'] ?? '#2563eb'],
    'neutral' => ['bg' => $colors['neutral-100'] ?? '#f6f8fa', 'text' => $colors['neutral-700'] ?? '#3c4257'],
];
$style = $badgeStyles[$variant];
@endphp

<span style="
    display: inline-block;
    padding: 4px 12px;
    background-color: {{ $style['bg'] }};
    color: {{ $style['text'] }};
    font-size: 12px;
    font-weight: 600;
    border-radius: 12px;
    font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
">
    {{ $slot }}
</span>
```

---

## 🧬 ORGANISMS - Complex Components

### Definition
Organisms are relatively complex components composed of molecules and/or atoms. They form distinct sections of an interface.

### File Structure
```
resources/views/emails/organisms/
├── alert-box.blade.php        # Alert/notice box
├── card.blade.php             # Content card
├── section.blade.php          # Background section
├── table.blade.php            # Data table
├── header.blade.php           # Email header
└── footer.blade.php           # Email footer
```

### 1. Alert Box Organism (`emails/organisms/alert-box.blade.php`)
```blade
@php
$variant = $variant ?? 'info';
$alertStyles = [
    'success' => ['bg' => $colors['success-50'] ?? '#f0fdf5', 'border' => $colors['success-500'] ?? '#22c55e', 'text' => $colors['success-600'] ?? '#16a34a'],
    'warning' => ['bg' => $colors['warning-50'] ?? '#fefce8', 'border' => $colors['warning-500'] ?? '#eab308', 'text' => $colors['warning-600'] ?? '#ca8a04'],
    'error' => ['bg' => $colors['error-50'] ?? '#fef2f2', 'border' => $colors['error-500'] ?? '#ef4444', 'text' => $colors['error-600'] ?? '#dc2626'],
    'info' => ['bg' => $colors['info-50'] ?? '#eff6ff', 'border' => $colors['info-500'] ?? '#3b82f6', 'text' => $colors['info-600'] ?? '#2563eb'],
];
$style = $alertStyles[$variant];
@endphp

<table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin: 20px 0;">
    <tr>
        <td style="
            background-color: {{ $style['bg'] }};
            border-left: 4px solid {{ $style['border'] }};
            padding: 20px;
            border-radius: 6px;
        ">
            @if(isset($title))
            <h3 style="
                margin: 0 0 10px;
                color: {{ $style['text'] }};
                font-size: 16px;
                font-weight: 600;
                font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            ">
                {{ $title }}
            </h3>
            @endif
            <div style="
                color: {{ $style['text'] }};
                font-size: 14px;
                line-height: 1.5;
                font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            ">
                {{ $slot }}
            </div>
        </td>
    </tr>
</table>
```

### 2. Card Organism (`emails/organisms/card.blade.php`)
```blade
<table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin: 20px 0;">
    <tr>
        <td style="
            background-color: {{ $colors['white'] ?? '#ffffff' }};
            border: 1px solid {{ $colors['neutral-200'] ?? '#e3e8ee' }};
            border-radius: 8px;
            padding: 24px;
        ">
            {{ $slot }}
        </td>
    </tr>
</table>
```

### 3. Section Organism (`emails/organisms/section.blade.php`)
```blade
@php
$background = $background ?? 'transparent';
$bgColors = [
    'neutral' => $colors['neutral-50'] ?? '#fafbfc',
    'white' => $colors['white'] ?? '#ffffff',
    'transparent' => 'transparent',
];
$bg = $bgColors[$background] ?? $background;
@endphp

<table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin: 20px 0;">
    <tr>
        <td style="
            background-color: {{ $bg }};
            padding: 20px;
            border-radius: 8px;
        ">
            {{ $slot }}
        </td>
    </tr>
</table>
```

---

## 📄 TEMPLATES - Page Layouts

### Definition
Templates are page-level structures that combine organisms into layouts. They define the overall structure without specific content.

### File Structure
```
resources/views/emails/templates/
├── base.blade.php             # Master layout (already exists)
├── transaction.blade.php      # Orders, payments, refunds
├── notification.blade.php     # Alerts, updates, status changes
└── authentication.blade.php   # Login, password, verification
```

---

## 📧 PAGES - Specific Email Implementations

### Definition
Pages are specific instances of templates with real content. These are the actual emails sent to customers.

### File Structure
```
resources/views/emails/pages/
├── welcome.blade.php
├── password-reset.blade.php
├── payment-confirmation.blade.php
└── ... (11 total emails)
```

---

## 📧 Email-Specific Patterns Found

### By Email Type:

#### **Welcome Email** (Simple)
- H1 heading
- Body paragraphs
- Section with background
- Unordered list
- Primary button
- Footer

#### **Password Reset** (Simple)
- H1 heading
- Body text
- Primary button
- Link display
- Warning box
- Expiry information

#### **Payment Confirmation** (Complex)
- Success badge/header
- Order details (info rows)
- Payment details (info rows)
- Event information
- Next steps section
- Download button

#### **Payment Failed** (Complex)
- Error badge/header
- Error details box
- Retry instructions
- Troubleshooting list
- Support information
- Retry button

#### **Chargeback Notification** (Very Complex)
- Status-based header (conditional coloring)
- Alert badge (multi-state)
- Chargeback details (info rows)
- Order information (info rows)
- Technical details (code blocks)
- Action required section (conditional)
- Evidence submission instructions

#### **Ticket Reassigned** (Complex)
- Info header
- Seat comparison display (before/after)
- Reason box
- Order information
- Warning box (multi-point)
- Attachment notice
- Action button
- Step-by-step instructions

---

## 🎯 Priority Components to Build

### Phase 1: Foundation (Build First)
1. **Typography components** (H1, H2, H3, Body, Small)
2. **Button component** (all variants)
3. **Alert box component** (all semantic colors)
4. **Info row component** (key-value display)

### Phase 2: Content Structure
5. **Card component**
6. **Section component** (with background variants)
7. **Divider component**
8. **List components** (ol/ul)

### Phase 3: Advanced
9. **Table component**
10. **Status badge component**
11. **Timeline component**
12. **Code block component**

---

## ✅ Email Client Compatibility Rules

### Safe CSS Properties (Use These)
- `margin`, `padding`
- `font-size`, `font-weight`, `font-family`
- `color`, `background-color`
- `border`, `border-radius` (limited support)
- `text-align`, `line-height`
- `width`, `max-width`

### Unsafe CSS (AVOID)
- ❌ **Gradients** (`linear-gradient`, `radial-gradient`) - Poor support
- ❌ **Flexbox/Grid** - Not supported in Outlook
- ❌ **Transforms/Animations** - Stripped by most clients
- ❌ **External stylesheets** - Must use inline styles
- ❌ **CSS variables** - Limited support

### Best Practices
- ✅ Use tables for layout (email clients expect this)
- ✅ Inline all styles
- ✅ Set explicit widths
- ✅ Use `mso` conditional comments for Outlook
- ✅ Test in Litmus/Email on Acid before production

---

## 🚀 Implementation Strategy

### Step 1: Update Color System
- Replace deprecated colors in `base.blade.php`
- Create new color palette aligned with frontend

### Step 2: Build Core Components
- Typography components (H1-H3, Body, Small)
- Button component (all variants)
- Alert box component

### Step 3: Migrate Welcome Email
- Polish as reference implementation
- Document usage patterns

### Step 4: Migrate Remaining Emails
- Use Welcome as template
- Follow component-driven approach
- Maintain consistency

---

## 📏 Component Specifications (Detailed)

### Button Component
```php
// Variants
'primary'   => Primary brand blue (#0d8ce8)
'secondary' => Neutral gray (#525f7f)
'success'   => Success green (#22c55e)
'danger'    => Error red (#ef4444)
'ghost'     => Transparent with border

// Sizes
'small'  => padding: 8px 16px, font-size: 12px
'medium' => padding: 12px 24px, font-size: 14px (default)
'large'  => padding: 14px 32px, font-size: 16px

// States
- Default
- Hover (darker shade)
- Disabled (opacity 0.5)
```

### Alert Box Component
```php
// Variants
'success' => Green background (#f0fdf5), green border (#22c55e)
'warning' => Yellow background (#fefce8), yellow border (#eab308)
'error'   => Red background (#fef2f2), red border (#ef4444)
'info'    => Blue background (#eff6ff), blue border (#3b82f6)

// Structure
- Icon/emoji (optional)
- Title (H3, semibold)
- Body text
- Bordered left accent (4px)
```

### Info Row Component
```php
// Structure
<div class="info-row">
  <span class="label">Order Number:</span>
  <span class="value">#12345</span>
</div>

// Styling
- Label: 500 weight, neutral-600 color
- Value: 600 weight, neutral-900 color
- Bottom border (except last)
- Responsive: stack on mobile
```

---

## 📋 Content Guidelines

### Voice & Tone
- **Professional**: Clear, concise, respectful
- **Helpful**: Action-oriented, supportive
- **Transparent**: Honest about status and next steps
- **Empathetic**: Acknowledge customer concerns

### Writing Standards
- Use active voice
- Keep sentences short (< 20 words)
- One idea per paragraph
- Use bullet points for lists
- Highlight important information

### Subject Line Format
```
[Status] [Action] - [Context]

Examples:
✓ "Password Reset Request - Expires in 1 Hour"
✓ "Payment Confirmed - Order #12345"
✓ "Action Required: Chargeback Dispute - Due Oct 20"
```

---

## 🧪 Testing Checklist

### Email Clients to Test
- [ ] Gmail (Desktop & Mobile)
- [ ] Apple Mail (iOS & macOS)
- [ ] Outlook (Windows, Mac, Office 365)
- [ ] Yahoo Mail
- [ ] Outlook.com
- [ ] Samsung Mail

### Viewport Sizes
- [ ] Desktop (600px+ width)
- [ ] Tablet (480-600px)
- [ ] Mobile (320-480px)

### Accessibility
- [ ] Color contrast ratios (WCAG AA)
- [ ] Alt text for images
- [ ] Semantic HTML structure
- [ ] Screen reader compatibility

---

---

## 🚀 Implementation Roadmap

### Phase 1: Build Atomic Foundation (2-3 hours)

**Step 1.1: Create Atom Components**
```bash
mkdir -p resources/views/emails/atoms
mkdir -p resources/views/emails/molecules
mkdir -p resources/views/emails/organisms
```

**Files to create:**
- `atoms/_colors.blade.php` - Color token definitions
- `atoms/h1.blade.php` - H1 heading atom
- `atoms/h2.blade.php` - H2 heading atom
- `atoms/h3.blade.php` - H3 heading atom
- `atoms/text.blade.php` - Body text atom
- `atoms/small.blade.php` - Small text atom
- `atoms/spacer.blade.php` - Vertical spacer atom

**Step 1.2: Create Molecule Components**
- `molecules/button.blade.php` - Button with MSO conditionals
- `molecules/link.blade.php` - Text link
- `molecules/info-row.blade.php` - Table-based key-value row
- `molecules/badge.blade.php` - Status badge

**Step 1.3: Create Organism Components**
- `organisms/alert-box.blade.php` - Alert/notice box
- `organisms/card.blade.php` - Content card
- `organisms/section.blade.php` - Background section

**Step 1.4: Test Components**
- Create test email using all components
- Validate in email preview system
- Test in Gmail, Outlook (desktop), Apple Mail

---

### Phase 2: Polish Welcome Email (1 hour)

**Step 2.1: Refactor Welcome Email**
- Update to use new Atomic components
- Replace deprecated colors with frontend-aligned palette
- Ensure all inline styles are email-safe
- Remove any remaining gradients or flexbox

**Step 2.2: Document Usage**
- Add code examples to styleguide
- Document common patterns
- Create troubleshooting guide

---

### Phase 3: Migrate Remaining Emails (3-4 hours)

**Simple Emails** (30 mins each):
1. Password Reset
2. Password Changed
3. Order Verification

**Medium Emails** (45 mins each):
4. Order Cancellation
5. Ticket Blocked

**Complex Emails** (1 hour each):
6. Payment Confirmation
7. Payment Failed
8. Refund Processed
9. Chargeback Notification
10. Ticket Reassigned

---

### Phase 4: Email Client Testing (2 hours)

**Test Matrix:**
- [ ] Gmail Desktop (Chrome, Safari, Firefox)
- [ ] Gmail Mobile (iOS, Android)
- [ ] Apple Mail (macOS, iOS)
- [ ] Outlook 2016/2019 (Windows)
- [ ] Outlook for Mac
- [ ] Outlook.com (Web)
- [ ] Yahoo Mail
- [ ] Samsung Mail

**Recommended Tools:**
- Litmus (https://litmus.com)
- Email on Acid (https://www.emailonacid.com)
- PutsMail (free preview tool)

---

## ✅ Email-Safe Checklist

For each component, validate:

### HTML Structure
- [ ] Tables used for layout (not divs/flexbox)
- [ ] All styles inline (no external CSS)
- [ ] Proper `cellpadding="0" cellspacing="0" border="0"` on tables
- [ ] Explicit widths set where needed
- [ ] Alt text on all images

### CSS Properties
- [ ] No gradients (use solid colors)
- [ ] No flexbox/grid (use tables)
- [ ] No transforms or animations
- [ ] No pseudo-elements (::before, ::after)
- [ ] Font fallback stacks provided

### Outlook Compatibility
- [ ] MSO conditionals for buttons
- [ ] VML for rounded corners (if needed)
- [ ] Tables for layout structure
- [ ] No negative margins

### Responsive Design
- [ ] Max-width set on container
- [ ] Font sizes readable on mobile (min 14px)
- [ ] Touch targets 44x44px minimum
- [ ] Single column layout for mobile

### Accessibility
- [ ] Color contrast ratios pass WCAG AA
- [ ] Semantic HTML structure
- [ ] Alt text descriptive
- [ ] Links clearly identifiable

---

## 📚 Component Usage Examples

### Example 1: Simple Welcome Email
```blade
@include('emails.atoms._colors')

@component('emails.templates.base', [
    'title' => 'Welcome to Global Gala',
    'previewText' => "Welcome aboard, {$userName}!",
    'colors' => $colors
])

@component('emails.atoms.h1', ['colors' => $colors])
    Welcome to Global Gala, {{ $userName }}
@endcomponent

@component('emails.atoms.text', ['colors' => $colors])
    Thank you for joining Global Gala, your premier destination for event ticketing.
@endcomponent

@component('emails.molecules.button', [
    'href' => $frontendUrl . '/events',
    'variant' => 'primary',
    'size' => 'medium',
    'colors' => $colors
])
    Explore Events
@endcomponent

@endcomponent
```

### Example 2: Transaction Email with Alert
```blade
@include('emails.atoms._colors')

@component('emails.templates.base', ['colors' => $colors])

@component('emails.organisms.alert-box', [
    'variant' => 'success',
    'title' => 'Payment Confirmed',
    'colors' => $colors
])
    Your payment of €18.61 has been processed successfully.
@endcomponent

@component('emails.organisms.card', ['colors' => $colors])
    @component('emails.atoms.h2', ['colors' => $colors])
        Order Details
    @endcomponent

    @component('emails.molecules.info-row', [
        'label' => 'Order Number',
        'value' => '#12345',
        'colors' => $colors
    ])
    @endcomponent

    @component('emails.molecules.info-row', [
        'label' => 'Total Amount',
        'value' => '€18.61',
        'colors' => $colors
    ])
    @endcomponent
@endcomponent

@endcomponent
```

---

## 🎨 Color Usage Guidelines

### When to Use Each Color

**Neutrals** (Primary usage):
- `neutral-900`: Main headings, important text
- `neutral-700`: Body text (default)
- `neutral-500`: Secondary text, labels
- `neutral-200`: Borders, dividers
- `neutral-50`: Subtle backgrounds

**Primary Brand** (Sparingly):
- `primary-500`: Main CTAs, links
- `primary-600`: Button hover states
- Use for 1-2 key actions per email maximum

**Semantic Colors** (Status communication):
- `success-*`: Confirmations, completed actions
- `warning-*`: Cautions, pending actions
- `error-*`: Problems, failures, urgent alerts
- `info-*`: General information, updates

**Anti-patterns (Don't):**
- ❌ Multiple bright colors competing for attention
- ❌ Color as the only indicator (accessibility issue)
- ❌ Overuse of semantic colors (dilutes meaning)
- ❌ Mixing old and new color systems

---

**Next Steps:**
1. ✅ Emojis removed from welcome email
2. ✅ Frontend styleguide reviewed
3. ✅ Component inventory completed with Atomic Design
4. ✅ Email-safe architecture documented
5. 🔨 **Ready to build Phase 1 components**