Skip to content

THEME_COLORS_DOCUMENTATION.md

Latest commit

 

History

History
258 lines (193 loc) · 7.03 KB

THEME_COLORS_DOCUMENTATION.md

File metadata and controls

258 lines (193 loc) · 7.03 KB

Theme-Aware Text Colors Implementation

Overview

This document explains the theme-aware text color system that has been implemented in the DevPath-Web application. Text colors now automatically adjust based on the current theme (light/dark mode) without requiring component-level theme detection.

Features Added

1. New CSS Variables in globals.css

The following CSS variables have been added to support theme-aware text colors:

Light Mode (Default)

--text-primary: #0f172a;      /* Dark slate for main text */
--text-secondary: #64748b;    /* Medium slate for secondary text */
--text-muted: #94a3b8;        /* Light slate for muted text */
--text-light: #f1f5f9;        /* Light color for text on dark backgrounds */
--text-dark: #0f172a;         /* Dark color for text on light backgrounds */

Dark Mode (.dark class)

--text-primary: #ffffff;      /* White for main text */
--text-secondary: #94a3b8;    /* Slate for secondary text */
--text-muted: #64748b;        /* Darker slate for muted text */
--text-light: #e2e8f0;        /* Light color for text */
--text-dark: #ffffff;         /* White for dark theme */

2. Utility Classes in globals.css

New utility classes for easy theme-aware styling:

.text-primary-theme      /* Main text color with transition */
.text-secondary-theme    /* Secondary text color with transition */
.text-muted-theme       /* Muted text color with transition */
.text-light-theme       /* Light text color with transition */
.text-dark-theme        /* Dark text color with transition */

/* Theme-aware alternatives for specific grays */
.theme-aware-gray       /* Gray text that becomes lighter in dark mode */
.theme-aware-black      /* Black text that becomes white in dark mode */
.theme-aware-light-gray /* Light gray text */
.theme-aware-subtle-gray /* Subtle gray text */
.theme-aware-dark-gray  /* Dark gray text */

3. Updated Components

The following components have been updated to use theme-aware colors:

  • Hero.tsx - Already using var(--text-secondary)
  • Sponsors.module.css - Updated text color
  • Resources.module.css - Updated hover state colors
  • CodingNews.module.css - Updated multiple text colors
  • RepoModal.module.css - Updated all text colors
  • InteractiveSteps.module.css - Updated text colors
  • page.module.css - Uses light/dark mode detection

Usage Guide

In CSS Modules

Use CSS variables for text colors:

.myComponent {
  color: var(--text-primary);        /* Main text */
}

.myComponent p {
  color: var(--text-secondary);      /* Secondary text */
}

.myComponent .helper {
  color: var(--text-muted);          /* Muted/disabled text */
}

In JSX Components

Use Tailwind classes (already configured):

{/* Using Tailwind's default theme colors */}
<h1 className="text-foreground">Main heading</h1>
<p className="text-muted-foreground">Helper text</p>

{/* Or use utility classes from globals.css */}
<div className="text-primary-theme">
  This text adjusts automatically
</div>

In Inline Styles

Import and use the theme helper:

import { useThemeColors } from '@/lib/theme';

function MyComponent() {
  const { textPrimary, textSecondary } = useThemeColors();
  
  return (
    <>
      <p style={{ color: textPrimary }}>Main text</p>
      <p style={{ color: textSecondary }}>Secondary text</p>
    </>
  );
}

Best Practices

✅ Do's

  1. Use CSS variables for static colors:

    color: var(--text-primary);

  2. Use Tailwind classes when possible:

    className="text-foreground"
className="text-muted-foreground"

  3. Add smooth transitions:

    color: var(--text-primary);
transition: color var(--transition-fast);

  4. Use appropriate text colors for hierarchy:

    • Main content: --text-primary
    • Secondary info: --text-secondary
    • Disabled/hint text: --text-muted

❌ Don'ts

  1. Avoid hardcoded color values:

    /* ❌ BAD */
color: #000000;
color: #ffffff;
color: #666666;

  2. Don't mix theme approaches:

    /* ❌ BAD */
.myClass {
  color: white;  /* Will be invisible in light mode */
}

  3. Don't forget transitions:

    /* ❌ Jarring color change */
color: var(--text-primary);
/* without transition */

/* ✅ Smooth transition */
color: var(--text-primary);
transition: color var(--transition-fast);

Color Reference

Text Colors

Variable Light Mode Dark Mode Use Case
--text-primary #0f172a #ffffff Main headings and body text
--text-secondary #64748b #94a3b8 Secondary information, captions
--text-muted #94a3b8 #64748b Disabled, placeholder, helper text
--text-light #f1f5f9 #e2e8f0 Text on dark backgrounds
--text-dark #0f172a #ffffff Text on light backgrounds

Accent Colors (Fixed across themes)

  • --accent-cyan: #00d4ff
  • --accent-purple: #9d4edd
  • --accent-pink: #ff006e
  • --accent-green: #00ff88
  • --accent-orange: #ff6b35

Migration Guide

If you're updating existing components:

  1. Find hardcoded text colors:

    grep -r "color: #" src/components --include="*.module.css"

  2. Replace with variables:

    /* Before */
color: #475569;

/* After */
color: var(--text-secondary);

  3. Add transitions:

    color: var(--text-secondary);
transition: color var(--transition-fast);

Testing

To verify theme-aware colors are working:

  1. Open the app in light mode (default)
  2. Observe text colors match the light mode palette
  3. Switch to dark mode
  4. Observe text colors smoothly transition to dark mode palette
  5. Check that all text remains readable in both modes

Troubleshooting

Text is invisible in one theme

Problem: Text color is hardcoded as white or black Solution: Replace with var(--text-primary) or appropriate variable

Colors don't transition smoothly

Problem: Missing transition property Solution: Add transition: color var(--transition-fast);

Colors not updating when theme changes

Problem: Inline styles or wrong variable names Solution: Use CSS variables instead of inline styles, verify variable names

Files Modified

  • src/app/globals.css - Added new CSS variables and utility classes
  • src/components/home/Sponsors.module.css - Updated to use theme variables
  • src/components/home/Resources.module.css - Updated hover colors
  • src/components/home/CodingNews.module.css - Updated text colors
  • src/components/source-code/RepoModal.module.css - Updated all text colors
  • src/components/source-code/InteractiveSteps.module.css - Updated text colors
  • src/lib/theme.ts - Created theme utility file

Future Enhancements

  1. Create React hook for theme detection: useTheme()
  2. Add theme transition animations
  3. Create Storybook stories for theme testing
  4. Add accessibility contrast ratio validation
  5. Create theme designer tool for custom color schemes