Organização do CSS personalizado com camadas

When mixing Tailwind utility classes with custom CSS, specificity conflicts can emerge. A custom CSS rule like .btn { color: red; } might override a Tailwind utility text-blue-500 due to source order, even though you intended the utility to win. Tailwind's @layer directive solves this by giving you explicit control over where in the CSS cascade your custom styles are inserted.

Tailwind organizes all generated CSS into three ordered layers: base comes first and contains element-level resets and defaults. components comes second and is designed for multi-utility class abstractions. utilities comes last and contains all single-purpose utility classes. This order ensures utilities always win over component styles, which always win over base styles — a predictable and intentional hierarchy.

The base layer is the right place for element-level resets, default HTML element styles, and global styles that apply unconditionally. Common uses include setting a default body font, establishing box-sizing rules, resetting heading margins, and defining link styles. Styles in the base layer can be overridden by anything in the components or utilities layers.

The components layer is for extracting repeated utility combinations into named classes using @apply. Component classes defined here can be overridden by utility classes applied in HTML because utilities live in the later utilities layer. This makes your component classes flexible — they set sensible defaults that can always be customized per-instance with utilities.

The utilities layer is for single-purpose custom utility classes that Tailwind does not provide out of the box. These might be utilities for CSS properties not yet in Tailwind's core, browser-specific prefixed properties, or composited values too specific for the default scale. Utilities in this layer have the highest priority and override both base and component styles.

CSS specificity normally depends on selector weight. But the CSS Cascade Layers specification (which Tailwind leverages) overrides specificity: a rule in a later layer always wins over a rule in an earlier layer, regardless of selector complexity. This means a .utilities-layer class like .p-4 (single class) wins over a .components-layer class like .card.padded.extra (three classes) automatically.

You are not limited to Tailwind's three default layers. You can define entirely custom named layers using CSS @layer and control where they appear in the cascade by declaring them in the correct order at the top of your CSS file. This is useful for integrating third-party CSS libraries at specific points in the cascade or for creating a layered architecture within your own CSS.

CSS written outside any @layer block has higher specificity than any layered style. This means custom CSS you write without wrapping it in @layer will always override Tailwind's layered utilities, potentially causing unexpected layout issues. Always wrap your custom styles in the appropriate layer — or explicitly create an overrides layer — to avoid fighting Tailwind's cascade.

The @layer and @apply directives work together. You define a layer, place component or utility classes inside it, and use @apply within those classes to compose from Tailwind utilities. This combination gives you the organizational benefits of layers (predictable cascade) and the convenience of @apply (composing from existing utilities) in a single pattern.

As your project grows, split your CSS across multiple files organized by layer purpose. Import everything into a single entry file. Keep base styles minimal — only things that truly apply globally. Keep components files organized by component type. Keep utilities files for genuinely missing utilities. This structure makes onboarding new developers easier and prevents CSS from becoming a maintenance burden.

When a style is not applying as expected, open Chrome DevTools and look at the Styles panel. Crossed-out declarations indicate styles being overridden. If a utility class is being crossed out by your own component CSS, you likely placed it outside a layer (giving it higher cascade priority) or in the wrong layer. Moving it to @layer components should restore the correct utility-wins behavior.

Test your understanding of organizing custom CSS with Tailwind's @layer directive.

In this lesson you learned: Tailwind's three layers — base, components, utilities — form a cascade hierarchy where each later layer overrides earlier ones, @layer base is for element defaults, @layer components for extracted component classes, and @layer utilities for custom utility classes. Next up we explore the pitfalls of @apply and when to use component extraction instead.