✨ Feat: modernize CSS architecture

[ZhenShuo2021]

Closes #2679
Closes #2766

Caution

This is a large PR with breaking changes.

This PR modernizes the theme's CSS architecture and aligns it with the current Tailwind ecosystem. The goal is not only to clean up technical debt, but also to make customization more intuitive and ensure the final CSS output remains predictable and consistent.

If accepted, perhaps we could include this PR in the beta release.

Benefits

For general users

• Color schemes can now be previewed directly in IDEs.
• Better alignment with the Tailwind ecosystem, allowing the use of widely available Tailwind color palette tools.
• Support modern color spaces such as OKLCH and other arbitrary color formats.

For advanced users

• Supports Hugo's css.TailwindCSS pipeline to automate Tailwind class generation.
  • Supports @apply syntax in custom.css ([Feature]: Enable Tailwind @apply in custom.css to define reusable user classes #2679)!
  • No tricky build commands required.
  • Cleaner package.json management.
  • No need to maintain a separate main.css, components/*.css, or tailwind.config.js solely for Tailwind customization.

For CSS output

• Ensures Tailwind compiles correct and consistent CSS output.

  Example:

  .bg-neutral\/25 {
  /* it previously builds nested rgba color, and not using fallback for color-mix */
  -  background-color: color-mix(in srgb, rgba(rgba(var(--color-neutral), 1), 1) 25%, transparent);
  +  background-color: var(--color-neutral);
  
  -  @supports (color: color-mix(in lab, red, red)) { background-color: color-mix(in oklab, rgba(var(--color-neutral), 1) 25%, transparent);
  +  @supports (color: color-mix(in lab, red, red)) { background-color: color-mix(in oklab, var(--color-neutral) 25%, transparent);
    }
  }

• Resolves multiple long-standing issues where CSS rules were generated but not actually effective.

What This PR Actually Changes

Color Variables

The most significant change is that color scheme variables now store actual color values instead of raw RGB numbers.

:root {
-  --color-neutral: 255, 255, 255;
+  --clr-neutral: rgb(255, 255, 255);
}

By supporting full color values rather than raw RGB numbers, colors can now be previewed directly within IDEs. This also enables support for the OKLCH color space, allowing more intuitive, perceptual color adjustments that are not possible with traditional RGB color space.

This update further streamlines integration with Tailwind colors and simplifies migration to the standard 11-level color scale (e.g., defining --clr-XXX-950). Moving away from the previous non-standard 10-level system allows users to adopt advanced tooling such as tints.dev.

The 11-level system also improves contrast depth, addressing the issue where the previous darkest level (900) lacked sufficient contrast, as noted in #2630.

Removal of tailwind.config.js

Tailwind v4 moves configuration into CSS rather than JavaScript. This PR removes tailwind.config.js and replaces it with config.css.

New head Directory

Head-related partials are now organized under a dedicated head directory.

A new css.html is introduced so advanced users can override it and use css.TailwindCSS for live class generation if needed.

No migration is required, as existing extend points extend-head.html and favicons.html remain unchanged.

New tailwind Directory

The previous mixture of Tailwind CSS and plain CSS often caused confusion for both users and contributors. A dedicated tailwind directory has been introduced to clearly isolate Tailwind-specific files and make the structure easier to understand and maintain.

Miscellaneous

• uid.html now generates identical hashes for identical content.

Migration

Custom Color Scheme

If using a custom color scheme, update variables as follows:

:root {
- --color-neutral: 255, 255, 255;
+ --clr-neutral: rgb(255, 255, 255);
}

This can be processed efficiently in VS Code using regex find and replace: replace color(-\w+-*\d*): (\d+, \d+, \d+) with clr$1: rgb($2).

Optional Adjustments:

• Color Space Conversion: Using a converter such as ColorSrc is recommended when migrating from RGB to OKLCH. Simply paste the updated CSS file, and the tool will handle the conversion.
• New Color Levels: Consider defining --clr-XXX-950 for the three base colors to complete the 11-level scale.

Custom CSS

If colors are referenced in custom.css, update the syntax to remove the redundant rgb() wrapper:

.foo {
-  color: rgb(var(--color-neutral));
+  color: var(--clr-neutral);
}

Custom Tailwind Build

If managing a custom Tailwind configuration, update the command from:

node ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit

to:

node ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -i ./themes/blowfish/assets/css/tailwind/main.css -o ./assets/css/tailwind/compiled.css

Notes on css.TailwindCSS

To enable css.TailwindCSS, add the required settings as described in the documentation, and replace the existing resource handling in css.html with:

{{/* Replace the following block: */}}
{{/* 
{{ $cssResources = $cssResources | append (resources.Get "css/compiled/main.css") }} 
{{ with resources.Get "css/custom.css" }}
  {{ $cssResources = $cssResources | append . }}
{{ end }}
*/}}

{{/* With this Hugo Tailwind implementation: */}}
{{ with (templates.Defer (dict "key" "global")) }}
  {{ partial "inline/TailwindCSS" . }}
{{ end }}


{{ define "_partials/inline/TailwindCSS" }}
  {{ with resources.Get "css/main.css" }}
    {{ $opts := dict "minify" (not hugo.IsDevelopment) }}
    {{ with . | css.TailwindCSS $opts }}
      {{ if hugo.IsDevelopment }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" />
      {{ else }}
        {{ with . | fingerprint }}
          <link
            rel="stylesheet"
            href="{{ .RelPermalink }}"
            integrity="{{ .Data.Integrity }}"
            crossorigin="anonymous" />
        {{ end }}
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

Finally, manage the packages in the project root with npm install @tailwindcss/cli @tailwindcss/typography @tailwindcss/forms tailwind-scrollbar tailwindcss.

css.TailwindCSS is not supported out-of-the-box due to Hugo's implementation differs from a standard Tailwind setup, providing official support would introduce significant maintenance overhead and potential issues. This remains an opt-in path for advanced use cases.

[netlify]

✅ Deploy Preview for snazzy-dango-efb2ec ready!

Name	Link
🔨 Latest commit	d08d571
🔍 Latest deploy log	https://app.netlify.com/projects/snazzy-dango-efb2ec/deploys/69a0d5ce172cd300089f9bbe
😎 Deploy Preview	https://deploy-preview-2819--snazzy-dango-efb2ec.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.