Blowfish Theme Bug Report: Tailwind v4 Gradient Incompatibility

Summary

Blowfish v2.93.0's color scheme format (comma-separated RGB triplets) is incompatible with Tailwind CSS v4's native gradient utilities, causing gradients to render as transparent instead of displaying the intended colors.

Environment

• Blowfish Version: v2.93.0
• Hugo Version: v0.155.2+extended
• Tailwind CSS Version: v4.1.17 (via @tailwindcss/cli v4.1.17)
• Color Scheme: fire (but affects all Blowfish schemes)
• Browser: All modern browsers

Steps to Reproduce

1. Set up a Hugo site with Blowfish v2.93.0 theme
2. Configure to use Tailwind v4 (as Blowfish v2.93.0 does by default)
3. Set colorScheme = "fire" in params.toml
4. Create a custom shortcode or component using Tailwind v4 gradient utilities:

   <div class="bg-gradient-to-r from-primary-400 to-primary-600">
     <h3 class="text-white">Gradient Header</h3>
   </div>

5. Build and view the site

Expected Behavior

The gradient should render with colors from orange-400 to orange-600 (based on the fire color scheme).

Actual Behavior

The gradient renders as transparent - no colors are visible. The text becomes unreadable against certain backgrounds.

Root Cause Analysis

Blowfish's Color Format (Tailwind v3 Pattern)

Blowfish defines colors in assets/css/schemes/fire.css as comma-separated RGB triplets:

:root {
  --color-primary-400: 251, 146, 60;
  --color-primary-600: 234, 88, 12;
  /* ... */
}

This format was designed for Tailwind v3, where you would use:

background: rgba(var(--color-primary-400), 1);

Tailwind v4's Gradient System

Tailwind v4 defines gradients using CSS @property with strict type validation:

@property --tw-gradient-from {
  syntax: "<color>";
  inherits: false;
}

When Tailwind v4's .from-primary-400 utility is applied, it generates:

.from-primary-400 {
  --tw-gradient-from: var(--color-primary-400);
}

The Incompatibility

1. --tw-gradient-from receives the value 251, 146, 60 (bare RGB channels)
2. This violates the syntax: "<color>" requirement
3. The browser invalidates the @property value
4. The gradient falls back to transparent

Note: In practice, Tailwind v4 won't generate from-* utilities for colors defined in plain :root (only for colors in @theme).
The above describes what would happen if someone attempted to migrate Blowfish's colors to @theme to enable gradient utilities - they would still fail due to the comma-separated format incompatibility.

This issue doesn't occur with standard Tailwind colors because they're defined as full color values:

--color-orange-400: oklch(74.68% 0.167 45.24); /* Valid color */

Current Workaround

Users must define custom gradient utilities that wrap Blowfish's RGB channels:

@layer utilities {
  .bg-gradient-to-r.from-primary-400.to-primary-600 {
    background: linear-gradient(
      to right,
      rgb(var(--color-primary-400)),
      rgb(var(--color-primary-600))
    );
  }
}

/* Also override with space-separated format for other utilities */
:root {
  --color-primary-400: 251 146 60; /* space-separated */
  --color-primary-600: 234 88 12;
}

This workaround has significant limitations:

• Must manually define every gradient combination
• Loses Tailwind's native gradient flexibility (arbitrary values, multiple stops, etc.)
• Requires maintaining duplicate color definitions
• Breaks the expectation that standard Tailwind utilities "just work"

Proposed Solutions

Option 1: Convert to Space-Separated RGB (Recommended)

Update all color scheme files to use space-separated RGB triplets instead of comma-separated:

Before:

:root {
  --color-primary-400: 251, 146, 60;
}

After:

:root {
  --color-primary-400: 251 146 60; /* space-separated */
}

Impact:

• ✅ Makes gradients work with Tailwind v4's native utilities
• ✅ Still compatible with existing rgb(var(--color-primary-400)) usage
• ✅ Enables other Tailwind v4 features that expect proper color values
• ⚠️ Breaking change: May affect custom user CSS that relies on comma-separated format

Option 2: Convert to Full Color Values (More Future-Proof)

Define colors as complete color values using modern CSS color functions:

:root {
  --color-primary-400: oklch(74.68% 0.167 45.24); /* or rgb(251 146 60) */
}

Impact:

• ✅ Fully compatible with Tailwind v4's color system
• ✅ Enables color-mix(), relative colors, and other modern CSS features
• ✅ Better browser optimization
• ⚠️ Breaking change: Requires updating all theme color usage patterns

Option 3: Hybrid Approach (Backwards Compatible)

Define colors in both formats:

:root {
  /* New format for Tailwind v4 utilities */
  --color-primary-400: rgb(251 146 60);

  /* Legacy format for backwards compatibility (different variable name) */
  --color-primary-400-channels: 251, 146, 60;
}

Impact:

• ✅ Maintains backwards compatibility
• ✅ Enables Tailwind v4 gradients
• ⚠️ Requires more complex migration path
• ⚠️ Increases maintenance burden

Affected Files

All color scheme files in assets/css/schemes/:

• avocado.css
• blowfish.css
• fire.css (currently using)
• ocean.css
• forest.css
• princess.css
• neon.css
• bloody.css
• terminal.css
• marvel.css
• noir.css
• garden.css
• winter.css
• congo.css
• slate.css
• gopher.css

Additional Context

Why This Matters

1. User Expectations: Tailwind v4 is advertised as the current version, and users expect standard utilities to work
2. Documentation Gap: Blowfish documentation doesn't warn about gradient incompatibility
3. Migration Path: Users migrating from other themes may encounter unexpected issues
4. Future Features: Other Tailwind v4 features may also be affected by this color format

Related Blowfish Changes

Blowfish v2.93.0 upgraded to Tailwind v4.1.17, but appears to use a hybrid approach:

• Uses Tailwind v4 CLI for building
• Retains Tailwind v3-style color definitions
• May have been tested primarily with non-gradient utilities

Community Impact

This affects:

• Any Blowfish user who wants to use custom gradients
• Developers creating custom shortcodes or components
• Users leveraging Tailwind v4's color features
• Future Tailwind v4 features that depend on proper color format

References

• Tailwind CSS v4 Migration Guide: https://tailwindcss.com/docs/v4-beta
• CSS @Property Spec: https://developer.mozilla.org/en-US/docs/Web/CSS/@property
• Blowfish v2.93.0 Release: https://github.com/nunocoracao/blowfish/releases/tag/v2.93.0
• User's Original Motivation: I wanted to create a custom shortcode where the header element had a gradient background using Blowfish theme colors to provide visual appeal and hierarchy on the landing page.

Reproduction Repository

The issue is straightforward to reproduce following the steps above. A minimal reproduction repository is not necessary as the problem occurs with any attempt to use Tailwind v4's gradient utilities with Blowfish's color scheme variables.

For Blowfish Maintainers

I'm happy to:

1. Submit a PR with the fix (if you confirm which solution you prefer)
2. Help test the changes across different color schemes
3. Update documentation to reflect the changes
4. Assist with migration guide for existing users

Thank you for maintaining this excellent Hugo theme!