Use @layer components instead of @layer utilities for custom component styles in Tailwind template

[martijn10kb]

Summary

In the Spina Tailwind CSS configuration template (application.tailwind.css.tt), custom component styles (such as .btn, .form-input, and .modal-window) were defined under @layer utilities. This PR shifts them into @layer components to align with CSS Cascade Layers and standard Tailwind design principles.

The Problem

By wrapping custom component styles under @layer utilities, these classes are registered at the same priority level as standard utility classes.

Under Tailwind v4 (and v3), CSS Cascade Layers are defined as:

@layer theme, base, components, utilities;

Since layers defined last have the highest priority, utility classes (utilities layer) are designed to override component styles (components layer).

When styles like .modal-window are placed in the @layer utilities block, their custom declarations (like a default max-width: var(--container-lg);) run at utility priority. Because they are declared physically after Tailwind's own compiled utility classes, they override the utility classes. This meant that applying a utility class like <div class="modal-window max-w-xs"> would fail to change the width because .modal-window would take priority. Developers were forced to write manual CSS overrides or use !important to force utility overrides to work.

The Solution

By changing the layer wrapper from @layer utilities to @layer components inside the template:

@layer utilities {
@layer components {
  /* Buttons */
  .btn {

We correctly register these classes within the components layer.

Now, Tailwind's cascade priority natively ensures that any utility class (such as max-w-xs, bg-red-500, etc.) applied on a custom component will always override the component's default style as intended by design, without requiring any manual CSS workarounds.