portfolio/docs/THEME-COLOR-GUIDE.md

Theme Color System Guide

This guide explains how to use the dynamic theme color system in this portfolio.

Overview

The portfolio uses Nuxt UI's CSS variable system to support multiple theme colors (green, blue, red, orange, etc.). All UI elements should adapt to the user-selected primary color.

CSS Variables

Available Variables

/* Light mode defaults */
--ui-color-primary-50   /* Very light tint - backgrounds */
--ui-color-primary-100  /* Light tint */
--ui-color-primary-200  /* Lighter shade - borders */
--ui-color-primary-300  /* Light shade */
--ui-color-primary-400  /* Medium-light shade - dark mode text */
--ui-color-primary-500  /* Main primary color */
--ui-color-primary-600  /* Medium-dark shade - hover states */
--ui-color-primary-700  /* Dark shade - text */
--ui-color-primary-800  /* Darker shade */
--ui-color-primary-900  /* Very dark shade */
--ui-color-primary-950  /* Darkest shade - dark mode backgrounds */

Usage Patterns

✅ Correct Usage

/* Using CSS variables */
.my-button {
  background: var(--ui-color-primary-500);
  color: white;
}

.my-button:hover {
  background: var(--ui-color-primary-600);
}

/* Using semantic Tailwind classes */
<div class="text-primary bg-primary border-primary">

/* Gradients with CSS variables */
.gradient-bg {
  background: linear-gradient(
    to right,
    var(--ui-color-primary-600),
    var(--ui-color-primary-500)
  );
}

/* Color mixing for transparency */
.subtle-bg {
  background: color-mix(in oklch, var(--ui-color-primary-50) 60%, transparent);
}

❌ Incorrect Usage

/* Never use hardcoded colors */
.my-button {
  background: #a855f7;  /* ❌ Stays purple forever */
}

/* Never use Tailwind color classes */
<div class="text-purple-500">  /* ❌ Doesn't respond to theme */
<div class="bg-violet-600">    /* ❌ Bypasses theme system */

Dark Mode Considerations

• Light mode: Use darker shades (500, 600, 700) for better contrast
• Dark mode: Use lighter shades (200, 300, 400) for better visibility
• Always test both modes when adding new styles

/* Example: Text color that works in both modes */
.my-text {
  color: var(--ui-color-primary-600);
}

.dark .my-text {
  color: var(--ui-color-primary-400);
}

Common Patterns

Buttons

/* Primary button */
.btn-primary {
  background: linear-gradient(to right, 
    var(--ui-color-primary-600), 
    var(--ui-color-primary-500)
  );
  box-shadow: 0 10px 15px -3px color-mix(
    in oklch, 
    var(--ui-color-primary-500) 30%, 
    transparent
  );
}

.btn-primary:hover {
  background: linear-gradient(to right, 
    var(--ui-color-primary-700), 
    var(--ui-color-primary-600)
  );
}

Cards with Hover Effects

.card {
  border: 1px solid var(--ui-color-primary-200);
  box-shadow: 0 10px 15px -3px color-mix(
    in oklch, 
    var(--ui-color-primary-500) 5%, 
    transparent
  );
}

.card:hover {
  border-color: var(--ui-color-primary-500);
  box-shadow: 0 20px 25px -5px color-mix(
    in oklch, 
    var(--ui-color-primary-500) 15%, 
    transparent
  );
}

Focus Rings

.interactive {
  --tw-ring-color: var(--ui-color-primary-500);
}

.dark .interactive {
  --tw-ring-color: var(--ui-color-primary-400);
}

Migration Checklist

When adding new components or styles:

1. ✅ Search for any purple/violet color references
2. ✅ Replace with appropriate primary color variable
3. ✅ Test with multiple primary colors (green, blue, red, orange)
4. ✅ Test in both light and dark modes
5. ✅ Verify hover/focus states use primary color
6. ✅ Check contrast ratios for accessibility (WCAG AA minimum)

Examples from Codebase

Scrollbar

:root {
  --scrollbar-thumb: var(--ui-color-primary-500);
  --scrollbar-thumb-hover: var(--ui-color-primary-600);
}

:root.dark {
  --scrollbar-thumb: var(--ui-color-primary-400);
  --scrollbar-thumb-hover: var(--ui-color-primary-300);
}

Chip Buttons (Social Icons)

.chip-button {
  --tw-ring-color: color-mix(in oklch, var(--ui-color-primary-200) 70%, transparent);
  background: linear-gradient(
    to bottom right,
    color-mix(in oklch, white 90%, transparent),
    color-mix(in oklch, var(--ui-color-primary-50) 50%, transparent)
  );
  color: var(--ui-color-primary-700);
}

Gradient Text

.gradient-text {
  background: linear-gradient(
    to right,
    var(--ui-color-primary-600),
    var(--ui-color-primary-500),
    var(--ui-color-primary-400)
  );
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
}

Troubleshooting

Issue: Colors not updating when theme changes

Solution: Make sure you're using CSS variables, not hardcoded colors or Tailwind color classes.

Issue: Poor contrast in dark mode

Solution: Use lighter shades (200-400) in dark mode instead of darker shades (600-800).

Issue: Gradients look wrong

Solution: Ensure all color stops in the gradient use primary color variables.

Resources

• Nuxt UI Color Documentation
• CSS color-mix() Documentation
• OKLCH Color Space