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

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

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:

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:

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:

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:

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:

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:

// 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
• WCAG 2.1 Contrast Guidelines
• WebAIM Contrast Checker