Interface: Tailwind Authoring

Rule

Class-level Tailwind guidance for writing cleaner, more consistent UI code.

Markup Hygiene

  • MUSTPut text-* and leading-* classes on block-level text containers, not inline formatting tags like <span>, <a>, <strong>, or <em> unless the inline element is intentionally acting as a text container.
  • MUST NOTAdd redundant display classes such as block on <div> or inline on <span> unless a variant changes them.
  • MUST NOTStack conflicting classes for the same property unless a variant, breakpoint, or state distinguishes them.
  • SHOULDKeep semantics first. If a list is really a list, use <ul> or <ol>.
  • SHOULDAdd role="list" to <ul> / <ol> when list styling is intentionally removed.
  • MUSTApply antialiased on the app root.
  • SHOULDApply isolate on the main app shell so overlays and layering stay predictable.

Class Preferences

  • MUSTPrefer gap-* on the parent over mt-* / mb-* between flex or grid children.
  • MUSTPrefer size-* over paired h-* and w-* when both dimensions match.
  • MUSTPrefer shorthands like p-6 over split axis classes when values are identical.
  • SHOULDSplit axes only when one axis genuinely differs or is overridden by a variant.
  • MUSTPrefer named scale values over arbitrary values whenever the scale can express the intent.
  • MUSTPrefer z-50 style classes over z-[50]; use arbitrary z values only when no scale value works.
  • MUSTPrefer slash opacity modifiers like bg-neutral-950/5 over bracket opacity syntax.
  • MUSTUse rem for arbitrary font sizes, not pixel literals.
  • MUSTReference design tokens for arbitrary radii, spacing, and colors rather than raw pixel literals.
  • SHOULDPrefer not-* variants over a base class immediately overridden elsewhere.
  • SHOULDPrefer data-closed:* style variants over bracket syntax when Tailwind exposes a named variant.
  • MUSTUse min-h-dvh, min-h-svh, or min-h-lvh for full-height layouts; avoid min-h-screen.
  • MUSTUse bg-linear-* utilities, not legacy bg-gradient-*.
  • MUSTUse shrink-* / grow-*, not flex-shrink-* / flex-grow-*.
  • SHOULDKeep grid ratios whole-number and readable when using arbitrary fractional tracks.
  • MUST NOTUse named line-height shorthands like leading-tight for product UI. Use scale-backed values such as leading-6 or combined text/leading shorthands.
  • MUSTAdd tabular-nums anywhere numbers change over time or compare against neighboring numbers.

CSS Variable Patterns

  • MUSTUse the --spacing() helper when available instead of calc(var(--spacing) * n).
  • MUSTPrefer CSS variables for arbitrary colors; do not call theme() inside authored UI code.
  • SHOULDExpress static CSS variables with arbitrary property syntax rather than inline styles.
  • MUSTFor dynamic values, set a CSS variable inline and reference it from the class (class="w-(--progress)" style="--progress: 72%").

Custom Utilities

  • MUSTPrefer @utility to ad hoc class selectors in authored Tailwind CSS.
  • SHOULDUse parameterized @utility definitions with --value() / --modifier() when the pattern repeats.
  • SHOULDUse @variant inside @utility when wiring into existing variants.
  • MUSTUse @custom-variant only for genuinely new semantics.
  • MUST NOTNest @utility inside @media or @supports.

Import Order

  • MUSTPut remote @import URLs at the top of the stylesheet, before @import "tailwindcss".

Review Questions

  • Are repeated child spacing rules expressed as parent gap-*?
  • Are arbitrary values justified, or should they be promoted to tokens or scale values?
  • Would a second engineer read this class string and immediately understand the intended hierarchy?