tailwind-errors-specificity

name	tailwind-errors-specificity
description	Use when a Tailwind utility class is in the compiled CSS but does NOT visually override a component class or a third-party rule, when @apply produces output that does not behave like the utility applied to a real element, when a custom utility you authored inside CSS does not respect responsive or hover variants, when plugin-emitted classes get overridden by your own classes in unexpected ways, or when you reach for !important and want to know the right syntax for v3 vs v4. Prevents the unlayered-CSS trap (custom CSS written outside @layer wins over any utility because unlayered styles defeat the cascade), the @apply !important-strip trap (v3 silently removes !important from utilities pulled in via @apply), the v3-vs-v4-important syntax flip (v3 prefix !bg-red-500, v4 suffix bg-red-500!), the wrong-layer trap (custom CSS in @layer base when you wanted utility-level priority), the plugin-order trap (v3 plugins array : LAST entry wins when two plugins emit the same class), and the same-property in @apply trap (only the LAST applied utility for one CSS property survives). Covers the three Tailwind layers (base, components, utilities) and their ordering, where custom CSS must live to participate, @apply semantics + the !important rule, the !-prefix and !-suffix important-modifier syntax for both v3 and v4, declaration-order rules inside a single class, plugin-array ordering in v3 config, @utility directive in v4 vs @layer utilities, @reference for scoped styles (Vue/Svelte/CSS modules), and how to debug "this utility is in CSS but I don't see it apply". Keywords: tailwind specificity, @layer base, @layer components, @layer utilities, custom utility specificity, unlayered css, unlayered styles, important modifier, !important tailwind, v3 important prefix, v4 important suffix, font-bold!, !font-bold, apply not working, @apply important, @apply stripped, plugin order v3, plugins array order, last plugin wins, declaration order tailwind, same property apply, cascade tailwind, my class is in css but not applied, utility does not override component, why is my background color not changing, why is my padding ignored, third-party css winning, override mui tailwind, override bootstrap tailwind, scoped style apply, @reference vue svelte, @utility directive specificity, conflict in apply, multiple plugins same class, tailwind cascade order, tailwind layer order, debug tailwind cascade
license	MIT
compatibility	Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Tailwind Specificity & Cascade Failures

Tailwind delegates ordering to native CSS @layer plus declaration- order rules. Conflicts trace to FIVE distinct mechanisms :

1. Layer-level priority (base < components < utilities < unlayered).
2. Class-level specificity (single-class selectors -> 0,0,1,0).
3. Declaration order WITHIN one class (last property wins).
4. !important modifier (overrides cascade entirely).
5. Plugin loading order (when two plugins emit the same class).

This skill is the diagnostic flow for all five.

Companion skills :

• tailwind-syntax-apply-directive : @apply deep dive
• tailwind-impl-plugins-custom : authoring your own plugins
• tailwind-impl-config-v3 and tailwind-impl-config-v4 : where to declare custom utilities
• tailwind-errors-build-failures : when the class is NOT in CSS
• tailwind-errors-runtime : DOM-level issues (wrong attribute, React class vs className)

Quick Reference : The Layer Order

Tailwind emits a native CSS @layer block. Browser cascade resolves in this order (HIGHER wins) :

1. Unlayered styles                  (HIGHEST -> "naked" CSS)
2. @layer utilities                  (Tailwind utilities)
3. @layer components                 (Tailwind components, prose, btn)
4. @layer base                       (Preflight reset, typography defaults)
5. Browser defaults                  (LOWEST)

A utility (bg-red-500) ALWAYS beats a component (prose) which ALWAYS beats base (h1 reset). Unlayered CSS (custom rules NOT inside @layer) ALWAYS wins over any Tailwind output. That last rule is the most common source of "my utility doesn't work".

Decision Tree : "My Utility Is Not Applied"

Inspect the element in DevTools. Is the utility selector visible
with a strike-through ?
  ├── YES (something overrides it)
  │   ├── Override is in :hover, :focus, :active etc
  │   │   -> Add hover:/focus: variant to your utility
  │   ├── Override is from an unlayered CSS rule (e.g. ".my-card { padding: 20px; }")
  │   │   -> Move that rule into @layer components or remove it
  │   ├── Override is a plugin-emitted component (prose-*, form-*)
  │   │   -> Your utility is correct ; the component is winning
  │   │      because Tailwind v3 plugin classes register in the
  │   │      components layer. Add !-modifier OR a more specific
  │   │      utility variant.
  │   └── Override comes from a third-party CSS file (Bootstrap, etc.)
  │       -> Apply the !-important modifier OR move third-party CSS
  │          into a lower layer.
  │
  └── NO (selector not shown at all)
      ├── Class not in compiled CSS -> see tailwind-errors-build-failures
      ├── Class is in markup but DOM attribute is `class` in JSX (not className)
      │   -> Fix the JSX (use className)
      └── Class targets a pseudo-element you cannot style (e.g. ::-webkit-scrollbar)
          -> Use vendor-specific utility or raw CSS in @layer utilities