Skip to main content

Color Usage Guide - Design Patterns

Color Philosophy​

Our theme system provides 6 semantic colors that work together as a cohesive palette. Each color has a specific purpose and recommended pairings for optimal readability and visual hierarchy.

Color Roles & Pairings​

1. Primary Color (--primary)​

Role: Main brand color, primary CTAs, key UI elements Intensity: Medium-dark (60-70% brightness) Best for: Buttons, headers, active states, key highlights

Recommended Pairings:

// Primary buttons - use white text for contrast
<button className="bg-primary text-white hover:bg-secondary hover:text-white">
  Primary Action
</button>

// Primary text (for links, labels)
<a className="text-primary hover:text-secondary">Click here</a>

// Primary borders
<div className="border-2 border-primary bg-white text-text-dark">
  Highlighted Card
</div>

2. Secondary Color (--secondary)​

Role: Secondary actions, hover states, accents Intensity: Medium (lighter than primary) Best for: Hover states, secondary buttons, supporting UI elements

Recommended Pairings:

// Secondary buttons
<button className="bg-secondary text-white hover:bg-primary hover:text-white">
  Secondary Action
</button>

// As hover state for primary
<button className="bg-primary text-white hover:bg-secondary">
  Action
</button>

// Secondary text
<span className="text-secondary">Supporting text</span>

3. Tertiary Color (--tertiary)​

Role: Muted elements, disabled states, subtle backgrounds Intensity: Light (70-80% brightness) Best for: Disabled buttons, muted badges, subtle containers

Recommended Pairings:

// Tertiary buttons (low emphasis actions)
<button className="bg-tertiary text-text-dark hover:bg-secondary hover:text-white">
  Cancel
</button>

// Disabled state
<button disabled className="bg-tertiary text-gray-400 cursor-not-allowed">
  Disabled
</button>

// Muted badges
<span className="bg-tertiary text-text-dark px-2 py-1 rounded">
  Draft
</span>

4. Light Color (--light)​

Role: Borders, dividers, very subtle backgrounds Intensity: Very light (85-90% brightness) Best for: Borders, dividers, hover backgrounds, badges

Recommended Pairings:

// Borders and dividers
<div className="border border-light">Content</div>
<hr className="border-light" />

// Light hover states
<div className="hover:bg-light transition">
  <span className="text-text-dark">Hover me</span>
</div>

// Subtle badges
<span className="bg-light text-text-dark border border-light px-2 py-1 rounded">
  Tag
</span>

5. Background Color (--background)​

Role: Page backgrounds, card backgrounds, subtle fills Intensity: Very light (90-95% brightness) Best for: Page backgrounds, card backgrounds, section backgrounds

Recommended Pairings:

// Page/section backgrounds
<div className="bg-background min-h-screen">
  <div className="text-text-dark">Content</div>
</div>

// Card backgrounds
<div className="bg-background border border-light rounded-lg p-6">
  <h2 className="text-text-dark">Card Title</h2>
</div>

// Alternating row colors
<tr className="bg-background hover:bg-light">
  <td className="text-text-dark">Row content</td>
</tr>

6. Text Dark Color (--text-dark)​

Role: Main body text, headings, dark text content Intensity: Very dark (15-25% brightness) Best for: All text on light backgrounds

Recommended Pairings:

// Body text (use on light backgrounds)
<p className="text-text-dark">
  This is the main body text color
</p>

// Headings
<h1 className="text-text-dark text-2xl font-bold">Heading</h1>

// Text on light/background colors
<div className="bg-background">
  <p className="text-text-dark">Text content</p>
</div>

<div className="bg-light">
  <p className="text-text-dark">Text content</p>
</div>

Complete Button Patterns​

Primary Button (Highest Emphasis)​

<button className="bg-primary text-white hover:bg-secondary hover:text-white transition">
  Primary Action
</button>

Secondary Button (Medium Emphasis)​

<button className="bg-secondary text-white hover:bg-primary hover:text-white transition">
  Secondary Action
</button>

Tertiary Button (Low Emphasis)​

<button className="bg-tertiary text-text-dark hover:bg-secondary hover:text-white transition">
  Tertiary Action
</button>

Ghost/Outline Button​

<button className="bg-transparent border-2 border-primary text-primary hover:bg-primary hover:text-white transition">
  Outline Button
</button>

Text Button (Lowest Emphasis)​

<button className="bg-transparent text-primary hover:text-secondary hover:underline">
  Text Link Button
</button>

Danger/Destructive Button​

<button className="bg-red-600 text-white hover:bg-red-700 transition">
  Delete
</button>

Note: For destructive actions, use Tailwind's red colors, not theme colors

Text Color Patterns​

On Dark Backgrounds (primary, secondary)​

<div className="bg-primary">
  <p className="text-white">Always use white text</p>
</div>

<div className="bg-secondary">
  <p className="text-white">Always use white text</p>
</div>

On Light Backgrounds (tertiary, light, background)​

<div className="bg-tertiary">
  <p className="text-text-dark">Use text-dark for readability</p>
</div>

<div className="bg-light">
  <p className="text-text-dark">Use text-dark for readability</p>
</div>

<div className="bg-background">
  <p className="text-text-dark">Use text-dark for readability</p>
</div>

<div className="bg-white">
  <p className="text-text-dark">Use text-dark for readability</p>
</div>

Colored Text on Light Backgrounds​

// Primary text (links, emphasis)
<a className="text-primary hover:text-secondary">
  Link text
</a>

// Secondary text (labels, captions)
<span className="text-secondary">
  Supporting information
</span>

// Muted text (tertiary used sparingly)
<span className="text-tertiary">
  Less important text
</span>

// Main text (default)
<p className="text-text-dark">
  Body text
</p>

// Gray text (for meta info)
<span className="text-gray-500">
  Last updated 2 hours ago
</span>

Card Patterns​

Default Card​

<div className="bg-white border border-light rounded-lg p-6">
  <h3 className="text-text-dark text-lg font-semibold mb-2">Card Title</h3>
  <p className="text-text-dark mb-4">Card content goes here</p>
  <button className="bg-primary text-white hover:bg-secondary px-4 py-2 rounded">
    Action
  </button>
</div>

Highlighted Card​

<div className="bg-background border border-primary rounded-lg p-6">
  <h3 className="text-primary text-lg font-semibold mb-2">Featured</h3>
  <p className="text-text-dark mb-4">Important card content</p>
  <button className="bg-primary text-white hover:bg-secondary px-4 py-2 rounded">
    Learn More
  </button>
</div>

Subtle Card​

<div className="bg-background border border-light rounded-lg p-6">
  <h3 className="text-text-dark text-lg font-semibold mb-2">Card Title</h3>
  <p className="text-text-dark mb-4">Card content</p>
</div>

Badge Patterns​

Status Badges​

// Active/Success
<span className="bg-green-100 text-green-800 px-2 py-1 rounded-full text-xs font-medium">
  Active
</span>

// Warning
<span className="bg-yellow-100 text-yellow-800 px-2 py-1 rounded-full text-xs font-medium">
  Pending
</span>

// Error
<span className="bg-red-100 text-red-800 px-2 py-1 rounded-full text-xs font-medium">
  Failed
</span>

// Info (using theme colors)
<span className="bg-light text-primary px-2 py-1 rounded-full text-xs font-medium border border-primary">
  New
</span>

Tag Badges​

// Neutral tags
<span className="bg-light text-text-dark px-2 py-1 rounded text-xs border border-light">
  JavaScript
</span>

// Primary tags
<span className="bg-primary text-white px-2 py-1 rounded text-xs">
  Featured
</span>

Form Patterns​

Input Fields​

<input
  type="text"
  className="border border-light focus:border-primary focus:ring-2 focus:ring-primary/20 rounded px-3 py-2 text-text-dark bg-white"
  placeholder="Enter text"
/>

Labels​

<label className="text-text-dark font-medium mb-1 block">
  Field Label
</label>

Help Text​

<p className="text-gray-500 text-sm mt-1">
  This is help text
</p>

Error Messages​

<p className="text-red-600 text-sm mt-1">
  This field is required
</p>

Table Patterns​

Table Header​

<thead className="bg-primary text-white">
  <tr>
    <th className="px-4 py-3 text-left">Column 1</th>
    <th className="px-4 py-3 text-left">Column 2</th>
  </tr>
</thead>

Table Rows​

<tbody>
  <tr className="border-b border-light hover:bg-background transition">
    <td className="px-4 py-3 text-text-dark">Data 1</td>
    <td className="px-4 py-3 text-text-dark">Data 2</td>
  </tr>
  <tr className="border-b border-light hover:bg-background transition">
    <td className="px-4 py-3 text-text-dark">Data 1</td>
    <td className="px-4 py-3 text-text-dark">Data 2</td>
  </tr>
</tbody>

Alternating Rows​

<tbody>
  <tr className="bg-white hover:bg-background transition">
    <td className="px-4 py-3 text-text-dark">Row 1</td>
  </tr>
  <tr className="bg-background hover:bg-light transition">
    <td className="px-4 py-3 text-text-dark">Row 2</td>
  </tr>
</tbody>

Key Principles​

  1. Dark backgrounds (primary, secondary) → Always use white text
  2. Light backgrounds (tertiary, light, background, white) → Always use text-dark
  3. Buttons should specify both bg and text color for clarity
  4. Hover states should change both background AND text color consistently
  5. For destructive actions (delete, remove), use Tailwind's red colors, not theme colors
  6. For success states, use Tailwind's green colors
  7. For warnings, use Tailwind's yellow/amber colors
  8. For info, you can use theme colors (primary, secondary)

Common Mistakes to Avoid​

❌ DON'T: Use primary/secondary text on primary/secondary backgrounds

<div className="bg-primary text-primary">Can't read this!</div>

❌ DON'T: Forget to specify text color on themed backgrounds

<button className="bg-primary">Missing text color</button>

❌ DON'T: Mix theme colors randomly

<button className="bg-tertiary text-white">Bad contrast</button>

✅ DO: Use consistent, high-contrast pairings

<button className="bg-primary text-white hover:bg-secondary hover:text-white">
  Good contrast and consistency
</button>

✅ DO: Specify both background and text in transitions

<button className="bg-tertiary text-text-dark hover:bg-primary hover:text-white transition-all">
  Smooth transition
</button>

Testing Your Colors​

When creating UI with theme colors:

  1. Check contrast: Ensure text is always readable
  2. Test hover states: Make sure hover colors are distinct
  3. Try multiple themes: Switch between themes to ensure consistency
  4. Check dark mode: If applicable, test with dark backgrounds
  5. Use browser dev tools: Check color contrast ratios (aim for WCAG AA minimum: 4.5:1)