Theming Guide

This application uses a globals.css-based theming system. All theme customizations should be made directly in the app/globals.css file.

Architecture

The theming system is built on CSS custom properties (variables) and supports:

Light/Dark mode switching via next-themes
Static theme definitions in globals.css
Tailwind CSS v4 integration with CSS variables

Theme Structure

Base Theme Variables

The application defines CSS variables in app/globals.css for both light and dark modes:

:root,
.light {
  --background: #ffffff;
  --foreground: #1a0f0d;
  --primary: #471d1e;
  --accent: #f5f5f4;
  --sidebar-background: #481d1e;
  /* ... other variables */
}
 
.dark {
  --background: #1a0f0d;
  --foreground: #ffffff;
  --primary: #ffffff;
  --accent: #332a28;
  --sidebar-background: #1a0f0d;
  /* ... other variables */
}

Variable Categories

Layout Colors
- --background - Main background color
- --foreground - Primary text color
- --card - Card background
- --border - Border color
Interactive Colors
- --primary - Primary button/link color
- --secondary - Secondary button color
- --accent - Accent/hover color
- --destructive - Error/danger color
- --success - Success color
Sidebar Colors
- --sidebar-background - Sidebar background
- --sidebar-foreground - Sidebar text
- --sidebar-accent - Sidebar hover state
Chart Colors
- --chart-1 through --chart-5 - Data visualization colors

Adding Custom Themes

To create a custom theme, add a new CSS class in globals.css:

.theme-custom {
  --background: #f5f8fa;
  --foreground: #1a2332;
  --primary: #0066cc;
  --accent: #e6f2ff;
  --sidebar-background: #0066cc;
  --sidebar-foreground: #ffffff;
  /* Override other variables as needed */
}

Then apply the theme class to the root element or specific components.

AI-Based Theme Updates

To update themes using AI, modify the CSS variables in app/globals.css:

Identify the theme section you want to modify (:root, .light, .dark, or custom theme classes)
Update the HEX values for the desired variables
Test the changes by applying the theme class
Ensure proper contrast ratios for accessibility

Example AI Prompts for Theme Changes

Design System Compliance:

Based on docs/THEMING.md, update the :root/.light and .dark theme sections in app/globals.css to comply with the Department of Veterans Affairs Web Design System. Use HEX format with proper contrast ratios: background #ffffff, foreground #212121, primary #0f2a44, accent #f1f8ff, sidebar background #0f2a44. Ensure 4.5:1 contrast for normal text and test in both light and dark modes. Apply theme class to root element.

Brand-Specific Theming:

Based on docs/THEMING.md, create a new .github-theme class in app/globals.css using HEX format and following all variable categories: background #ffffff, foreground #24292f, primary #0969da, accent #f6f8fa, sidebar background #f6f8fa. Include all layout, interactive, sidebar, and chart colors. Maintain sufficient contrast ratios and test in both light and dark modes before applying to components.

Accessibility-First Approach:

Based on docs/THEMING.md, add a new .high-contrast class in app/globals.css following the theming architecture. Use HEX format for all variable categories: background #000000, foreground #ffffff, primary #0099ff, accent #262626, sidebar background #0d0d0d. Ensure all combinations exceed 7:1 contrast ratio, include proper focus ring colors, and test accessibility for users with visual impairments. Apply class to root element when needed.

Color Guidelines

Use HEX color format for better readability and manipulation
Maintain sufficient contrast ratios (4.5:1 for normal text, 3:1 for large text)
Test themes in both light and dark modes
Consider accessibility for users with visual impairments

Tailwind Integration

The theme variables are automatically available in Tailwind CSS classes:

<div className="bg-background text-foreground">
  <button className="bg-primary text-primary-foreground">Primary Button</button>
</div>

Theming Guide

On this page