Tailwind CSS
Pathrule2 Rules • 2 Memories • 1 Skill
A pattern bundle for teams building UIs with Tailwind CSS v4. It encodes the CSS-first workflow (configure in CSS with @theme, no tailwind.config.js), enforces design tokens over arbitrary values, and standardizes class ordering and conditional-class handling. Use it so AI agents and humans write Tailwind that matches your design system instead of one-off magic numbers.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
tailwind-css-review
src/
Use design tokens, not arbitrary values
No dynamic class string interpolation
styles/
Tailwind v4 is CSS-first via @theme
components/
Variant + merge stack: cva, clsx, tailwind-merge
Rules
2Use design tokens, not arbitrary values/srchighadvisoryPrefer theme-backed utilities over square-bracket arbitrary values.
| 1 | Reach for a standard utility before an arbitrary value so markup stays inside the design system. |
| 2 | |
| 3 | - Replace one-offs like `w-[137px]`, `text-[#3b82f6]`, or `mt-[13px]` with token utilities (`w-32`, `text-primary`, `mt-3`). |
| 4 | - If a value is genuinely reused, add it to `@theme` as a custom token (for example `--color-brand` or `--spacing-18`) instead of repeating the bracket form. |
| 5 | - Arbitrary values are an escape hatch for true one-offs only; each distinct one emits its own rule and bloats the output CSS. |
No dynamic class string interpolation/srchighstrictNever build Tailwind class names from runtime template strings.
| 1 | Tailwind scans source as plain text, so any class assembled at runtime is invisible to the compiler and gets purged. |
| 2 | |
| 3 | - Do not write `className={`bg-${status}-500`}` or concatenate fragments; the full literal class must appear in source. |
| 4 | - Map state to complete class strings with `class-variance-authority` (cva) or an explicit lookup object, then merge with `cn`. |
| 5 | - If a class truly must be generated, register it through `@source inline(...)` so the compiler keeps it. |
Memories
2Tailwind v4 is CSS-first via @theme/src/stylesConfigure tokens in CSS with @theme; there is no tailwind.config.js.
| 1 | Tailwind CSS v4 moved configuration out of JavaScript into your stylesheet, so do not scaffold a `tailwind.config.js`. |
| 2 | |
| 3 | - Start the entry stylesheet with `@import "tailwindcss";` then declare tokens in an `@theme { ... }` block (`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`). |
| 4 | - Theme variables become both real CSS custom properties and generated utilities, so `--color-brand` yields `bg-brand`, `text-brand`, and friends automatically. |
| 5 | - Add custom utilities with `@utility` and custom selectors with `@custom-variant` (for example a class- or data-attribute-based `dark` variant) rather than a JS plugin or `darkMode` config key. |
Variant + merge stack: cva, clsx, tailwind-merge/src/componentsStandardize a cn helper and define variants outside the component.
| 1 | Reusable components compose classes through one shared helper so conflicting utilities resolve predictably. |
| 2 | |
| 3 | - Create `cn` once: `export const cn = (...i: ClassValue[]) => twMerge(clsx(i))`, then always merge through it so a later `className` prop wins over base styles. |
| 4 | - Order matters inside `cn`: base styles first, conditional/variant classes next, caller overrides last. |
| 5 | - Declare `cva` variant maps at module scope (not inside render) to avoid recreating them each render, and keep one full class string per variant value. |
| 6 | - Let `prettier-plugin-tailwindcss` own class ordering so reviews stay focused on logic, not sort order. |
Skills
1tailwind-css-review/rootPre-merge checklist for Tailwind v4 utility and token hygiene.
| 1 | --- |
| 2 | name: tailwind-css-review |
| 3 | description: Review Tailwind CSS v4 changes for token-driven styling, no arbitrary-value or dynamic-class sprawl, CSS-first config, and conflict-safe class merging before merging. |
| 4 | --- |
| 5 | |
| 6 | # Tailwind CSS review |
| 7 | |
| 8 | - [ ] No new arbitrary values (`w-[..]`, `text-[#..]`, `mt-[..px]`); reused values promoted to `@theme` tokens instead. |
| 9 | - [ ] No runtime-interpolated class strings (`bg-${x}-500`); state mapped via cva or a literal lookup, or registered with `@source inline(...)`. |
| 10 | - [ ] Configuration stays CSS-first: tokens live in `@theme`, no `tailwind.config.js` reintroduced. |
| 11 | - [ ] Custom utilities use `@utility` and custom states use `@custom-variant` (including class/data-attribute `dark`), not JS plugins. |
| 12 | - [ ] Component classes merged through the shared `cn` helper so caller overrides win and conflicts resolve. |
| 13 | - [ ] cva variant maps defined at module scope, one full class string per variant value. |
| 14 | - [ ] Classes are sorted by `prettier-plugin-tailwindcss` and the diff is free of manual reordering churn. |
| 15 | - [ ] Responsive, dark, and state variants use real modifiers (`md:`, `dark:`, `hover:`) rather than duplicated bespoke CSS. |
Why this pattern
AI agents and rushed PRs fill Tailwind markup with arbitrary values and ad-hoc classes that drift from the design system and bloat the CSS bundle.
Built for Frontend and product teams building component-driven UIs with Tailwind CSS v4 and React or other JSX frameworks..
Keeps your assistant from:
- Arbitrary values like w-[137px] or text-[#3b82f6] replacing real design tokens
- Resurrecting a tailwind.config.js when v4 expects CSS-first @theme configuration
- Dynamic class strings such as bg-${color}-500 that Tailwind cannot detect at build time
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-06-09