Tailwind

Tailwind CSS (v4)

Assumes Tailwind v4: CSS-first configuration — @import "tailwindcss" and design tokens declared with @theme in CSS. tailwind.config.js is the legacy v3 mechanism; do not add one to a v4 project (check the installed major before assuming either way).

Design tokens

• Tokens live in @theme (colors, spacing, radii, fonts, breakpoints) — ONE file, the single

source of truth. @theme variables compile to CSS custom properties, so non-Tailwind CSS can consume the same tokens via var(--color-…).

• A raw value appearing twice is a token that hasn't been promoted yet. Never scatter arbitrary

values (p-[13px], text-[#3366ff]) for recurring design decisions — add the token to @theme and use the generated utility. Arbitrary values are for genuine one-offs only.

Classes in markup

• No dynamic class concatenation: ` text-${color}-500 ` produces classes the compiler

never sees — silently unstyled. Write full class names; branch with clsx/cva over complete strings (isError ? 'text-red-600' : 'text-gray-900').

• Class order is machine-enforced by prettier-plugin-tailwindcss — install it and stop thinking

about order. Don't hand-sort.

• Long class lists are a smell of a missing component, not a missing @apply. Extract a React

component (variants via cva); reach for @apply only in small, justified doses (e.g. styling third-party markup you don't control).

• State styling: prefer aria-* and data-* variants (aria-expanded:rotate-180,

data-[state=open]:…) — they force the markup to carry real semantics (pairs with a11y).

Responsive & dark mode

• Mobile-first: unprefixed = smallest; add sm: md: lg: upward. Component-level responsiveness

uses container queries (@container + @sm: variants), not viewport breakpoints.

• Dark mode: pick ONE strategy for the project (media dark: default, or class/data-attribute

strategy declared via @custom-variant) and document it in the @theme file. Tokens that change with theme are defined once as CSS variables, not re-specified per-utility everywhere.

Boundaries

• Do not mix styling systems: no CSS Modules, no CSS-in-JS, no inline style attributes

(dynamic values that must be inline — e.g. computed positions — go through a CSS variable: style={{ '--x': … }} consumed by [--x]-based utilities or plain CSS).

• Escape hatch for genuinely un-utility-able CSS (complex keyframes, third-party overrides):

one co-located .css file layered with @layer components, consuming @theme tokens.

• prefers-reduced-motion: gate animation utilities with motion-safe:/motion-reduce:

(see motion for what to animate at all).

Enforcement

• prettier-plugin-tailwindcss (class order) is the one mandatory tool.
• Lint plugins for Tailwind v4 vary in maturity — verify current v4 support before adding one

(see tooling's "verify the installed major" doctrine); do not assume the v3-era plugin works.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Syo-M
• Source: Syo-M/fable5_skills
• License: MIT

Install and usage instructions live in the source repository linked above.