tailwind-impl-apply-directive

name	tailwind-impl-apply-directive
description	Use when writing custom CSS that needs to share design tokens with Tailwind utilities via @apply, organizing component / base / utility CSS via @layer, or fixing the "Cannot apply unknown utility class" error in Vue, Svelte, or CSS-module scoped styles by adding @reference. Prevents the utility-extraction anti-pattern (wrapping every utility in @apply destroys utility-first benefits like JIT pruning, in-context readability, and consistent design tokens), the scoped-style trap in v4 (Vue SFC, Svelte SFC, and CSS modules evaluate @apply against an empty token registry without @reference, failing with "Cannot apply unknown utility class"), the layer-order trap (custom CSS outside @layer leaks above utilities and gets overridden), the important-modifier syntax flip between v3 (leading bang, !font-bold) and v4 (trailing bang, font-bold!), and the @apply !important keyword vs modifier confusion. Covers @apply semantics (copies utility declarations into the current rule), @layer base / components / utilities (specificity ascends in that order, matches @tailwind ordering in v3 and @import "tailwindcss" cascade in v4), @reference "path" (v4 only, makes tokens visible in scoped contexts without duplicating CSS), the v3 vs v4 important syntax flip, plugin-vs-layer ordering, and when @apply is the right tool versus when component extraction (React / Vue / Svelte component) is the right tool instead. Keywords: tailwind @apply, @apply utility, apply directive, custom CSS tailwind, share tokens custom CSS, @layer base components utilities, layer order tailwind, tailwind 3 @apply !important, tailwind 4 @apply font-bold!, important modifier tailwind, !font-bold v3, font-bold! v4, leading bang vs trailing bang, @reference tailwindcss, @reference app.css, Cannot apply unknown utility class, Cannot apply unknown utility, vue scoped style apply, svelte scoped style apply, css modules apply, scoped @apply broken v4, tailwind component extraction, when not to use @apply, @apply anti pattern, button class @apply, when to extract utilities, plugin order @layer, third-party library override tailwind, override third party styles, @apply inside scoped style, tailwind 3-4 directive differences.
license	MIT
compatibility	Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

@apply, @layer, @reference

@apply lets custom CSS reuse Tailwind utility declarations. @layer sorts custom CSS into Tailwind's cascade. @reference (v4) makes tokens visible inside scoped style blocks.

ALWAYS prefer component extraction (React, Vue, Svelte component) over @apply when the consumer is a component framework. NEVER reach for @apply just because a class name appears twice. See references/anti-patterns.md AP-1 for the full philosophy.

Companion skills :

• tailwind-impl-config-v3 : v3 JS-config and PostCSS pipeline
• tailwind-impl-config-v4 : v4 CSS-first config and directives
• tailwind-impl-build-vite : Vite plugin wiring

Quick Reference

@apply (both versions)

.btn-primary {
  @apply rounded-lg bg-blue-500 px-4 py-2 text-white;
}

ALWAYS use inside a regular CSS selector, NEVER at the top level. The declarations are copied verbatim from the utility class into the rule.

@layer (both versions)

@layer base {
  h1 { @apply text-4xl font-bold; }
}

@layer components {
  .btn { @apply rounded bg-blue-500 px-4 py-2 text-white; }
}

@layer utilities {
  .text-shadow-sm { text-shadow: 0 1px 2px rgb(0 0 0 / 0.1); }
}

Order in the cascade : base < components < utilities. Anything in utilities wins over components ; anything in wins over .