HugoBlox-kit/modules/blox/assets/css/README.md

Hugo Blox Tailwind CSS v4 Color System

Architecture Overview

This system leverages Tailwind CSS v4's automatic utility generation to provide a comprehensive color system with minimal code.

How It Works

1. Theme Configuration (config/theme.css)

   • Colors defined in @theme block automatically generate ALL utilities
   • Includes standard Tailwind colors: gray, slate, zinc, neutral, stone
   • Includes themeable colors: primary, secondary

2. Theme Files (themes/*.css)

   • Small files that override --color-primary-* and --color-secondary-* variables
   • Users switch themes by loading different theme CSS files
   • No utilities redefined - just color values changed

3. Custom Utilities (color-utilities.css)

   • Only 42 lines vs previous 1,228 lines!
   • Contains only custom colors not auto-generated (like hb-dark)

Available Colors

Standard Colors (always available):

• gray-* - Neutral grays
• slate-* - Cool grays
• zinc-* - True grays
• neutral-* - Pure grays
• stone-* - Warm grays

Themeable Colors (vary by theme):

• primary-* - Main theme color
• secondary-* - Accent theme color

Custom Colors:

• hb-dark - Hugo Blox brand dark color

Auto-Generated Utilities

For every color defined in @theme, Tailwind automatically creates:

• Background: bg-{color}-{shade}
• Text: text-{color}-{shade}
• Border: border-{color}-{shade}
• Hover: hover:bg-{color}-{shade}, hover:text-{color}-{shade}
• Dark mode: dark:bg-{color}-{shade}, dark:text-{color}-{shade}
• Gradients: from-{color}-{shade}, to-{color}-{shade}
• Focus rings: focus:ring-{color}-{shade}
• All other Tailwind color variants

Shades Available

All colors include 11 shades: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950

Usage Examples

<!-- Standard colors (always available) -->
<div class="bg-gray-100 dark:bg-gray-800">...</div>
<div class="text-slate-700 hover:text-slate-900">...</div>

<!-- Themeable colors (change with theme) -->
<div class="bg-primary-500 hover:bg-primary-600">...</div>
<div class="bg-gradient-to-r from-primary-600 to-secondary-600">...</div>

<!-- Custom colors -->
<div class="bg-hb-dark text-white">...</div>

Benefits

1. Dramatically Reduced File Size: 1,228 lines → 42 lines (97% reduction!)
2. Automatic Generation: No manual utility definitions needed
3. Maintainable: Add new colors just by defining them in @theme
4. Consistent: All Tailwind variants automatically available
5. Themeable: Easy theme switching via CSS variable overrides

Adding New Colors

To add a new color scale:

1. Define in config/theme.css:

   --color-brand-500: 59 130 246;
   --color-brand-600: 37 99 235;
   /* etc. */
   

2. Tailwind automatically generates all utilities:

   • bg-brand-500, text-brand-600, hover:bg-brand-500, etc.

No manual utility definitions required!