Skill / UI / Tailwind
First-class utilities before custom CSS
Prefer Tailwind v4's first-class utility families before arbitrary properties or handwritten CSS.
Goal
Keep styling composable, token-aware, and isolated by letting Tailwind own utility state and generated CSS whenever it supports the effect.
Styling rules for Tailwind v4, token discipline, component reuse, and className boundaries.
Checks
1Before writing an arbitrary property or custom CSS, check the pinned Tailwind v4 utility family and use it when it expresses the same behavior.
2Use generated spacing and sizing utilities such as `min-w-100`, `w-150`, `size-6`, `mt-17`, `grid-cols-15`, `h-dvh`, `w-dvw`, `h-lh`, and container max-width utilities when they fit.
3Use boolean data variants such as `data-current:opacity-100`; keep bracketed values for real values like `data-[state=open]:opacity-100`.
4Keep class strings complete and statically detectable by mapping props to full class names, for example `{ success: "bg-positive1" }[tone]`.
5Use a first-class utility with an arbitrary value when only the value is custom, such as `max-h-[calc(100dvh-3rem)]`, `bg-size-[18px_18px]`, or `transform-[translateX(var(--x))]`.
6For scroll-edge fades, compose overflow-state variants with `mask-l-from-*`, `mask-r-from-*`, `mask-t-from-*`, and `mask-b-from-*`; Tailwind supplies mask intersection and non-inheriting internal state.
7Reserve arbitrary properties for unsupported CSS such as `[writing-mode:vertical-rl]`; use `mask-type-luminance` instead of `[mask-type:luminance]`.
Avoid
1Reimplementing supported behavior with arbitrary properties or custom utility state; `[mask-image:linear-gradient(...)]` plus manual gradient stops and composite variables is the ScrollArea smell.
2Building Tailwind class fragments dynamically, such as concatenating `bg-`, a tone, and `-500`, because the compiler cannot reliably detect them.
Source
Imported as local Control UI skill guidance, with this repo owning the final wording.
Mastra tailwind-v4
../mastra/.claude/skills/tailwind-v4