Color System Documentation
Color System Documentation
Overview
The color system uses CSS custom properties (variables) defined in src/styles/global.css
as the single source of truth. All colors cascade from these root definitions.
Architecture
1. Base Color Definitions
Located in src/styles/global.css
:
:root {
/* Core parameters */
--hue: 0deg; /* Base hue (0 = neutral) */
--saturation: 0%; /* Color intensity (0% = grayscale) */
--bg-brightness: 100%; /* Background brightness (100% = white) */
--fg-brightness: 10%; /* Text brightness (10% = near black) */
}
2. Color Scale Generation
The system generates a 19-step opacity scale from the base foreground color:
--theme-color-900: hsl(var(--theme-fg) / 1.0); /* 100% opacity */
--theme-color-850: hsl(var(--theme-fg) / 0.9675); /* 96.75% opacity */
--theme-color-800: hsl(var(--theme-fg) / 0.935); /* 93.5% opacity */
/* ... continues to ... */
--theme-color-50: hsl(var(--theme-fg) / 0.0225); /* 2.25% opacity */
3. Semantic Color Tokens
/* Backgrounds */
--theme-bg: 0deg 0% 100%; /* Pure white #ffffff */
--theme-special-lightest: 0deg 0% 99%; /* Near white #fcfcfc */
--theme-special-lighter: 0deg 0% 97%; /* Light gray #f7f7f7 */
--theme-special-light: 0deg 0% 95%; /* Gray #f2f2f2 */
/* Text */
--theme-text: hsl(30deg 2% 10%); /* Subtle warm black #1a1918 */
--theme-accent-base: 0deg 0% 15%; /* Near black #262626 */
--theme-lightest: 0deg 0% 45%; /* Medium gray #737373 */
--theme-lighter: 0deg 0% 35%; /* Dark gray #595959 */
--theme-light: 0deg 0% 30%; /* Darker gray #4d4d4d */
/* Links & Accents */
--theme-link: 220deg 35% 40%; /* Sophisticated blue #365880 */
--theme-quote: hsl(40deg 5% 35%); /* Warm quote color */
Current Implementation (Refined Neutrals)
Light Mode
- Background: Pure white (#ffffff) for maximum clarity
- Text: Subtle warm black (hsl(30deg 2% 10%)) - adds warmth without being noticeable
- Grays: Pure neutral scale (0% saturation) for versatility
Dark Mode
:root[data-theme="dark"] {
--bg-brightness: 8%; /* Very dark #141414 */
--fg-brightness: 90%; /* Bright text #e6e6e6 */
/* Warm tints for comfort */
--bg-hue: 40deg;
--bg-saturation: 5%; /* Subtle warmth */
/* Enhanced opacity for readability */
--theme-text: hsl(40deg 5% 88% / 0.90);
}
Usage Patterns
Text Hierarchy
/* Primary text */
color: var(--theme-text);
/* Secondary text */
color: var(--theme-lighter);
/* Tertiary text */
color: var(--theme-lightest);
/* Disabled/subtle */
color: var(--theme-color-400);
Backgrounds
/* Main background */
background: var(--theme-bg);
/* Card/elevated surface */
background: var(--theme-special-lightest);
/* Hover state */
background: var(--theme-special-lighter);
/* Active/pressed */
background: var(--theme-special-light);
Borders
/* Strong border */
border-color: var(--theme-color-200);
/* Default border */
border-color: var(--theme-color-150);
/* Subtle border */
border-color: var(--theme-color-100);
/* Faint border */
border-color: var(--theme-color-75);
Tailwind Integration
The color system is integrated with Tailwind through custom color definitions:
// tailwind.config.ts
colors: {
bgColor: "hsl(var(--theme-bg) / <alpha-value>)",
textColor: "hsl(var(--theme-text) / <alpha-value>)",
accent: {
base: "hsl(var(--theme-accent-base) / <alpha-value>)",
one: "hsl(var(--theme-accent-one) / <alpha-value>)",
two: "hsl(var(--theme-accent-two) / <alpha-value>)",
},
// Opacity scale
color: {
900: "hsl(var(--theme-color-900) / <alpha-value>)",
800: "hsl(var(--theme-color-800) / <alpha-value>)",
// ... etc
}
}
Using in HTML
<!-- Text colors -->
<p class="text-textColor">Primary text</p>
<p class="text-light">Secondary text</p>
<p class="text-lighter">Tertiary text</p>
<!-- Backgrounds -->
<div class="bg-bgColor">Main background</div>
<div class="bg-special-light">Card background</div>
<!-- Borders -->
<div class="border border-color-150">Default border</div>
<div class="border-2 border-color-200">Strong border</div>
Micro-Contrast Adjustments
The system includes specific adjustments for different text sizes:
Light Mode
/* Headers need slightly lighter color for optical balance */
h1, h2 { color: hsl(0deg 0% 12%); }
h3, h4, h5, h6 { color: hsl(0deg 0% 15%); }
/* Small text needs higher contrast */
.text-sm, .caption { color: hsl(0deg 0% 30%); }
Dark Mode
/* Headers brighter than body */
h1, h2 { color: hsl(40deg 5% 92%); }
/* Small text muted for hierarchy */
.text-sm { color: hsl(40deg 5% 75%); }
Special States
Selection Colors
::selection {
background: hsl(220deg 40% 92%); /* Light blue */
color: hsl(0deg 0% 10%);
}
/* Dark mode */
:root[data-theme="dark"] ::selection {
background: hsl(220deg 30% 25%);
color: hsl(0deg 0% 95%);
}
Focus States
:focus {
outline: 1.5px solid hsl(220deg 35% 40%);
outline-offset: 3px;
}
/* Dark mode */
:root[data-theme="dark"] :focus {
outline-color: hsl(220deg 25% 70%);
}
Code Syntax Highlighting
/* Inline code */
--code-inline-bg: var(--theme-color-100);
/* Code blocks */
--code-bg: var(--theme-special);
--code-title-bg: var(--theme-color-200);
--code-line-highlight: hsl(40deg 10% 0% / 0.04);
Making Changes
To adjust the entire color system:
- Change base parameters in
:root
- All derived colors update automatically
- Test in both light and dark modes
To add warmth:
:root {
--hue: 30deg; /* Warm hue */
--saturation: 2%; /* Subtle warmth */
}
To increase contrast:
:root {
--fg-brightness: 5%; /* Darker text */
}
Accessibility
The color system maintains WCAG AAA compliance:
- Normal text: 16.5:1 contrast ratio
- Large text: Exceeds requirements
- UI elements: Minimum 3:1 contrast
Performance
- Single source of truth reduces CSS size
- CSS variables enable runtime theming
- No JavaScript required for theme switching
- Efficient cascade minimizes overrides
Debug Helpers
Add to any element to visualize the color scale:
<div class="bg-color-900">900 - Full opacity</div>
<div class="bg-color-800">800 - 93.5% opacity</div>
<div class="bg-color-700">700 - 87% opacity</div>
<!-- etc... -->
This color system provides a sophisticated, maintainable foundation for the entire design system while ensuring excellent readability and visual harmony.