flyer-crawler.projectium.com/docs/development/DESIGN_TOKENS.md

# Design Tokens

This document defines the design tokens used throughout the Flyer Crawler application, including color palettes, usage guidelines, and semantic mappings.

## Color Palette

### Brand Colors

The Flyer Crawler brand uses a **teal** color palette that evokes freshness, value, and the grocery shopping experience.

| Token                 | Value     | Tailwind | RGB           | Usage                                    |
| --------------------- | --------- | -------- | ------------- | ---------------------------------------- |
| `brand-primary`       | `#0d9488` | teal-600 | 13, 148, 136  | Main brand color, primary call-to-action |
| `brand-secondary`     | `#14b8a6` | teal-500 | 20, 184, 166  | Supporting actions, primary buttons      |
| `brand-light`         | `#ccfbf1` | teal-100 | 204, 251, 241 | Backgrounds, highlights (light mode)     |
| `brand-dark`          | `#115e59` | teal-800 | 17, 94, 89    | Hover states, backgrounds (dark mode)    |
| `brand-primary-light` | `#99f6e4` | teal-200 | 153, 246, 228 | Subtle backgrounds, light accents        |
| `brand-primary-dark`  | `#134e4a` | teal-900 | 19, 78, 74    | Deep backgrounds, strong emphasis (dark) |

### Color Usage Examples

```jsx
// Primary color for icons and emphasis
<TagIcon className="text-brand-primary" />

// Secondary color for primary action buttons
<button className="bg-brand-secondary hover:bg-brand-dark">
  Add to List
</button>

// Light backgrounds for selected/highlighted items
<div className="bg-brand-light dark:bg-brand-dark/30">
  Selected Flyer
</div>

// Focus rings on form inputs
<input className="focus:ring-brand-primary focus:border-brand-primary" />
```

## Semantic Color Mappings

### Primary (`brand-primary`)

**Purpose**: Main brand color for visual identity and key interactive elements

**Use Cases**:

- Icons representing key features (shopping cart, tags, deals)
- Hover states on links and interactive text
- Focus indicators on form elements
- Progress bars and loading indicators
- Selected state indicators

**Example Usage**:

```jsx
className = 'text-brand-primary hover:text-brand-dark';
```

### Secondary (`brand-secondary`)

**Purpose**: Supporting actions and primary buttons that drive user engagement

**Use Cases**:

- Primary action buttons (Add, Submit, Save)
- Call-to-action elements that require user attention
- Active state for toggles and switches

**Example Usage**:

```jsx
className = 'bg-brand-secondary hover:bg-brand-dark';
```

### Light (`brand-light`)

**Purpose**: Subtle backgrounds and highlights in light mode

**Use Cases**:

- Selected item backgrounds
- Highlighted sections
- Drag-and-drop target areas
- Subtle emphasis backgrounds

**Example Usage**:

```jsx
className = 'bg-brand-light dark:bg-brand-dark/20';
```

### Dark (`brand-dark`)

**Purpose**: Hover states and backgrounds in dark mode

**Use Cases**:

- Button hover states
- Dark mode backgrounds for highlighted sections
- Strong emphasis in dark theme

**Example Usage**:

```jsx
className = 'hover:bg-brand-dark dark:bg-brand-dark/30';
```

## Dark Mode Variants

All brand colors have dark mode variants defined using Tailwind's `dark:` prefix.

### Dark Mode Mapping Table

| Light Mode Class        | Dark Mode Class               | Purpose                              |
| ----------------------- | ----------------------------- | ------------------------------------ |
| `text-brand-primary`    | `dark:text-brand-light`       | Text readability on dark backgrounds |
| `bg-brand-light`        | `dark:bg-brand-dark/20`       | Subtle backgrounds                   |
| `bg-brand-primary`      | `dark:bg-brand-primary`       | Brand color maintained in both modes |
| `hover:text-brand-dark` | `dark:hover:text-brand-light` | Interactive text hover               |
| `border-brand-primary`  | `dark:border-brand-primary`   | Borders maintained in both modes     |

### Dark Mode Best Practices

1. **Contrast**: Ensure sufficient contrast (WCAG AA: 4.5:1 for text, 3:1 for UI)
2. **Consistency**: Use `brand-primary` for icons in both modes (it works well on both backgrounds)
3. **Backgrounds**: Use lighter opacity variants for dark mode backgrounds (e.g., `/20`, `/30`)
4. **Text**: Swap `brand-dark` ↔ `brand-light` for text elements between modes

## Accessibility

### Color Contrast Ratios

All color combinations meet WCAG 2.1 Level AA standards:

| Foreground      | Background        | Contrast Ratio | Pass Level |
| --------------- | ----------------- | -------------- | ---------- |
| `brand-primary` | white             | 4.51:1         | AA         |
| `brand-dark`    | white             | 7.82:1         | AAA        |
| white           | `brand-primary`   | 4.51:1         | AA         |
| white           | `brand-secondary` | 3.98:1         | AA Large   |
| white           | `brand-dark`      | 7.82:1         | AAA        |
| `brand-light`   | `brand-dark`      | 13.4:1         | AAA        |

### Focus Indicators

All interactive elements MUST have visible focus indicators using `focus:ring-2`:

```jsx
className = 'focus:ring-2 focus:ring-brand-primary focus:ring-offset-2';
```

### Color Blindness Considerations

The teal color palette is accessible for most forms of color blindness:

- **Deuteranopia** (green-weak): Teal appears as blue/cyan
- **Protanopia** (red-weak): Teal appears as blue
- **Tritanopia** (blue-weak): Teal appears as green

The brand colors are always used alongside text labels and icons, never relying solely on color to convey information.

## Implementation Notes

### Tailwind Config

Brand colors are defined in `tailwind.config.js`:

```javascript
theme: {
  extend: {
    colors: {
      brand: {
        primary: '#0d9488',
        secondary: '#14b8a6',
        light: '#ccfbf1',
        dark: '#115e59',
        'primary-light': '#99f6e4',
        'primary-dark': '#134e4a',
      },
    },
  },
}
```

### Usage in Components

Import and use brand colors with Tailwind utility classes:

```jsx
// Text colors
<span className="text-brand-primary dark:text-brand-light">Price</span>

// Background colors
<div className="bg-brand-secondary hover:bg-brand-dark">Button</div>

// Border colors
<div className="border-2 border-brand-primary">Card</div>

// Opacity variants
<div className="bg-brand-light/50 dark:bg-brand-dark/20">Overlay</div>
```

## Future Considerations

### Potential Extensions

- **Success**: Consider adding semantic success color (green) for completed actions
- **Warning**: Consider adding semantic warning color (amber) for alerts
- **Error**: Consider adding semantic error color (red) for errors (already using red-\* palette)

### Color Palette Expansion

If the brand evolves, consider these complementary colors:

- **Accent**: Warm coral/orange for limited-time deals
- **Neutral**: Gray scale for backgrounds and borders (already using Tailwind's gray palette)

## References

- [Tailwind CSS Color Palette](https://tailwindcss.com/docs/customizing-colors)
- [WCAG 2.1 Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)