Impertio-Studio Tailwind CSS : Base Utility Classes
The canonical vocabulary. Every utility documented here is a literal token Tailwind generates from theme tokens. ALWAYS write classes as complete literals; see [tailwind-core-architecture] for why partial token construction breaks the content scanner.
Quick Reference
The ten base utility families
| Family | Examples | Coverage in this skill |
|---|---|---|
| Spacing | p-4, px-2, m-auto, mt-8, space-y-4, gap-6 |
section 1 |
| Color | bg-red-500, text-white, border-slate-200, ring-blue-500/50 |
section 2 |
| Typography | text-lg, font-bold, tracking-tight, leading-relaxed |
section 3 |
| Layout (display + position) | flex, grid, block, hidden, absolute, top-0, z-10 |
section 4 |
| Flexbox | flex-row, justify-center, items-center, flex-1, shrink-0 |
section 5 |
| Grid | grid-cols-3, col-span-2, grid-rows-2, grid-flow-col, auto-cols-fr |
section 6 |
| Sizing | w-full, h-screen, min-w-0, max-h-96, size-10 |
section 7 |
| Border | border, border-2, rounded-md, divide-y |
section 8 |
| Background | bg-white, bg-[url('/img.png')], bg-cover, bg-center |
section 9 |
| Effects | shadow-md, opacity-75, mix-blend-multiply, backdrop-blur-sm |
section 10 |
Three invariants
- ALWAYS write class names as complete literal tokens. NEVER assemble them dynamically.
- ALWAYS read responsive prefixes (
sm:,md:, ...) as "and up". See [tailwind-syntax-responsive]. - ALWAYS check the v4 callouts in this skill before assuming a v3 utility name still applies.
v4 changes affecting base utilities (callouts)
- Shadow scale shifted (BREAKING) : v4 inserted
shadow-2xsandshadow-xs. v3shadow-smis approximately v4shadow-md. See section 10. - Same shift applies to
blur-*,rounded-*,drop-shadow-*,backdrop-blur-*(-xsinserted below-sm). - Opacity utilities removed : v4 removed
bg-opacity-50,text-opacity-*,border-opacity-*,divide-opacity-*,ring-opacity-*,placeholder-opacity-*. ALWAYS use the slash syntaxbg-red-500/50instead. - Gradient family renamed : v3
bg-gradient-to-rbecomes v4bg-linear-to-r. See [tailwind-syntax-gradients]. - Flex shorthand changes : v3
flex-shrink-*,flex-grow-*become v4shrink-*,grow-*. - Text overflow : v3
overflow-ellipsisbecomes v4text-ellipsis. - Important modifier position : v3
!font-boldbecomes v4font-bold!. - Dynamic spacing : v4 generates
p-{any-integer},m-{any-integer},w-{any-integer},grid-cols-{any-integer}automatically; v3 was scale-limited. - Default color palette : v4 ships in oklch wide-gamut with 22 family names: 9 neutrals (slate, gray, zinc, neutral, stone, taupe, mauve, mist, olive) and 13 colors (red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose) plus
blackandwhite.
1. Spacing
Padding
| Class | Property | Notes |
|---|---|---|
p-<n> |
padding: calc(var(--spacing) * <n>) |
All sides |
px-<n> / py-<n> |
inline / block padding | Horizontal / vertical |
pt-<n> / pr-<n> / pb-<n> / pl-<n> |
single-side | Top / right / bottom / left |
ps-<n> / pe-<n> |
logical (start / end) | RTL-aware |
p-[<value>] |
arbitrary | p-[37px], p-[1.5em] |
p-(--var) |
CSS variable | v4 only |
Margin
| Class | Property | Notes |
|---|---|---|
m-<n> |
margin |
All sides |
mx-<n> / my-<n> |
horizontal / vertical | |
mt-<n> / mr-<n> / mb-<n> / ml-<n> |
single-side | |
ms-<n> / me-<n> |
logical | RTL-aware |
-m-<n>, -mt-<n>, etc. |
negative | ALWAYS prefix with - |
m-auto |
margin: auto |
Centering trick with mx-auto |
Spacing scale (<n> values)
0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96.
In v4 ANY integer works because spacing is calc(var(--spacing) * <n>) with --spacing: 0.25rem by default. p-17, m-23, w-29 ALL emit valid CSS in v4.
Gap and space-between
| Class | Property |
|---|---|
gap-<n> |
gap (flex + grid both) |
gap-x-<n> / gap-y-<n> |
column-gap / row-gap |
space-x-<n> / space-y-<n> |
gap between siblings (legacy; prefer gap-* with flex or grid) |
ALWAYS prefer flex flex-col gap-<n> over space-y-<n> per the v4 upgrade-guide recommendation; the space-* family uses fragile sibling selectors and changed behaviour in v4.
2. Color
Color palette (v4 oklch)
22 family names :
- Neutrals (9) :
slate,gray,zinc,neutral,stone,taupe,mauve,mist,olive - Hues (13) :
red,orange,amber,yellow,lime,green,emerald,teal,cyan,sky,blue,indigo,violet,purple,fuchsia,pink,rose - Plus
black,white,transparent,current(currentColor),inherit
Each named family has 11 shades : 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950.
Color utilities by property
| Class | Property |
|---|---|
text-<color>-<shade> |
color |
bg-<color>-<shade> |
background-color |
border-<color>-<shade> |
border-color |
border-{t,r,b,l}-<color>-<shade> |
per-side border colour |
outline-<color>-<shade> |
outline-color |
ring-<color>-<shade> |
box-shadow ring colour |
divide-<color>-<shade> |
sibling-border colour |
accent-<color>-<shade> |
accent-color (form controls) |
caret-<color>-<shade> |
caret-color (text input) |
decoration-<color>-<shade> |
text-decoration-color |
fill-<color>-<shade> |
SVG fill |
stroke-<color>-<shade> |
SVG stroke |
placeholder-<color>-<shade> |
::placeholder { color } |
from-<color>-<shade> / via- / to- |
gradient stops |
Opacity modifier (v4 + v3.3+)
ALWAYS use the slash syntax :
<div class="bg-red-500/50">50% opacity background</div>
<div class="text-white/[0.85]">85% with arbitrary precision</div>
In v4 the bg-opacity-*, text-opacity-*, etc. utility families are REMOVED. NEVER write bg-red-500 bg-opacity-50 in v4 code.
Arbitrary and variable colors
<div class="bg-[#1da1f2]">arbitrary hex</div>
<div class="bg-(--brand-color)">v4 CSS variable</div>
<div class="bg-[var(--brand-color)]">v3 CSS variable</div>
3. Typography
| Class | Property |
|---|---|
text-<size> |
font-size + paired line-height |
text-<size>/<leading> |
font-size + custom line-height (e.g., text-sm/6) |
font-<family> |
font-family (defaults : sans, serif, mono) |
font-<weight> |
font-weight |
leading-<value> |
line-height |
tracking-<value> |
letter-spacing |
text-<align> |
text-align : left, center, right, justify, start, end |
uppercase, lowercase, capitalize, normal-case |
text-transform |
italic, not-italic |
font-style |
underline, overline, line-through, no-underline |
text-decoration-line |
decoration-<style> |
text-decoration-style : solid, dotted, dashed, wavy, double |
decoration-<thickness> |
text-decoration-thickness : auto, from-font, 0, 1, 2, 4, 8 |
whitespace-<value> |
white-space : normal, nowrap, pre, pre-line, pre-wrap, break-spaces |
text-ellipsis, text-clip |
text-overflow (v4; v3 used overflow-ellipsis) |
truncate |
three-in-one : overflow: hidden, text-overflow: ellipsis, white-space: nowrap |
Font sizes (v4 defaults)
| Class | Font size | Line height |
|---|---|---|
text-xs |
0.75rem (12px) | calc(1 / 0.75) |
text-sm |
0.875rem (14px) | calc(1.25 / 0.875) |
text-base |
1rem (16px) | calc(1.5 / 1) |
text-lg |
1.125rem (18px) | calc(1.75 / 1.125) |
text-xl |
1.25rem (20px) | calc(1.75 / 1.25) |
text-2xl |
1.5rem (24px) | calc(2 / 1.5) |
text-3xl |
1.875rem (30px) | calc(2.25 / 1.875) |
text-4xl |
2.25rem (36px) | calc(2.5 / 2.25) |
text-5xl |
3rem (48px) | 1 |
text-6xl |
3.75rem (60px) | 1 |
text-7xl |
4.5rem (72px) | 1 |
text-8xl |
6rem (96px) | 1 |
text-9xl |
8rem (128px) | 1 |
Font weights
font-thin (100), font-extralight (200), font-light (300), font-normal (400), font-medium (500), font-semibold (600), font-bold (700), font-extrabold (800), font-black (900).
Letter spacing
tracking-tighter (-0.05em), tracking-tight (-0.025em), tracking-normal (0), tracking-wide (0.025em), tracking-wider (0.05em), tracking-widest (0.1em).
Line height (standalone)
leading-none (1), leading-tight (1.25), leading-snug (1.375), leading-normal (1.5), leading-relaxed (1.625), leading-loose (2). Arbitrary : leading-[1.2].
4. Layout (display + position + z-index)
| Class | Property |
|---|---|
block, inline-block, inline, flex, inline-flex, grid, inline-grid, table, inline-table, table-row, table-cell, flow-root, contents, hidden, list-item |
display |
static, fixed, absolute, relative, sticky |
position |
top-<n> / right-<n> / bottom-<n> / left-<n> |
per-side offset (uses spacing scale) |
inset-<n> |
shorthand for all four sides |
inset-x-<n> / inset-y-<n> |
horizontal / vertical |
z-<n> |
z-index : 0, 10, 20, 30, 40, 50, auto (v4 dynamic : any integer) |
overflow-<value> |
auto, hidden, clip, visible, scroll |
overflow-x-<value> / overflow-y-<value> |
per-axis |
visible, invisible, collapse |
visibility |
5. Flexbox
| Class | Property |
|---|---|
flex-row, flex-row-reverse, flex-col, flex-col-reverse |
flex-direction |
flex-wrap, flex-wrap-reverse, flex-nowrap |
flex-wrap |
flex-1, flex-auto, flex-initial, flex-none |
flex shorthand |
flex-<n>, flex-<fraction>, flex-[<value>], flex-(--var) |
arbitrary flex values |
grow, grow-0, grow-<n> (v4) |
flex-grow (v3 used flex-grow-*) |
shrink, shrink-0, shrink-<n> (v4) |
flex-shrink (v3 used flex-shrink-*) |
basis-<n>, basis-<fraction>, basis-full, basis-auto |
flex-basis |
order-<n>, order-first, order-last, order-none |
order |
justify-<value> |
justify-content : start, end, center, between, around, evenly, stretch, normal |
items-<value> |
align-items : start, end, center, baseline, stretch, last-baseline |
content-<value> |
align-content : start, end, center, between, around, evenly, stretch, normal, baseline |
self-<value> |
align-self : auto, start, end, center, stretch, baseline |
6. Grid
| Class | Property |
|---|---|
grid-cols-<n> |
grid-template-columns: repeat(<n>, minmax(0, 1fr)) (v4 any integer) |
grid-cols-none, grid-cols-subgrid, grid-cols-[<value>] |
non-numeric |
grid-rows-<n>, grid-rows-none, grid-rows-subgrid |
rows version |
col-span-<n>, col-span-full, col-start-<n>, col-end-<n> |
column placement |
row-span-<n>, row-span-full, row-start-<n>, row-end-<n> |
row placement |
grid-flow-row, grid-flow-col, grid-flow-row-dense, grid-flow-col-dense, grid-flow-dense |
grid-auto-flow |
auto-cols-auto, auto-cols-min, auto-cols-max, auto-cols-fr |
grid-auto-columns |
auto-rows-auto, auto-rows-min, auto-rows-max, auto-rows-fr |
grid-auto-rows |
place-content-<value>, place-items-<value>, place-self-<value> |
combined *-content, *-items, *-self |
7. Sizing
| Class | Property |
|---|---|
w-<n> |
width |
h-<n> |
height |
size-<n> |
shorthand : width + height (v3.4+ and v4) |
min-w-<n>, max-w-<n>, min-h-<n>, max-h-<n> |
min/max width/height |
w-full, w-screen, w-svw, w-lvw, w-dvw, w-min, w-max, w-fit, w-auto |
named widths |
h-full, h-screen, h-svh, h-lvh, h-dvh, h-min, h-max, h-fit, h-auto |
named heights |
w-<fraction> (e.g., w-1/2, w-2/3, w-5/12) |
fractional widths |
max-w-xs, max-w-sm, ..., max-w-7xl, max-w-prose, max-w-screen-md |
container scale |
aspect-square, aspect-video, aspect-[16/9], aspect-auto |
aspect-ratio |
8. Border
| Class | Property |
|---|---|
border, border-0, border-2, border-4, border-8, border-<n> |
border-width |
border-x-<n>, border-y-<n>, border-t-<n>, border-r-<n>, border-b-<n>, border-l-<n> |
per-axis / side |
border-<color>-<shade> |
border-color (see section 2) |
border-{style} |
border-style : solid, dashed, dotted, double, hidden, none |
rounded, rounded-none, rounded-xs, rounded-sm, rounded-md, rounded-lg, rounded-xl, rounded-2xl, rounded-3xl, rounded-full |
border-radius |
rounded-t-*, rounded-r-*, rounded-b-*, rounded-l-* |
per-side radius |
rounded-tl-*, rounded-tr-*, rounded-br-*, rounded-bl-* |
per-corner |
divide-x-<n>, divide-y-<n>, divide-<color> |
sibling-border between flex/grid children |
outline, outline-<n>, outline-<style>, outline-<color>, outline-offset-<n> |
outline family |
ring-<n>, ring-<color>-<shade>, ring-offset-<n>, ring-inset |
box-shadow-based ring |
v3 vs v4 border-color and ring-width
- v3 default border color :
gray-200. v4 default :currentColor. ALWAYS add an explicitborder-<color>-<shade>on bordered elements when migrating, OR add a shim in@layer base. - v3 default
ringwidth : 3px. v4 defaultringwidth : 1px. ALWAYS usering-3to preserve v3 behaviour, OR a shim.
See [tailwind-errors-v4-migration].
9. Background
| Class | Property |
|---|---|
bg-<color>-<shade> |
background-color (see section 2) |
bg-[url('/img/hero.png')], bg-(image:--my-img) |
background-image arbitrary |
bg-none, bg-linear-to-r, bg-conic-*, bg-radial-* |
gradient utilities (see [tailwind-syntax-gradients]) |
bg-cover, bg-contain, bg-auto |
background-size |
bg-[length:200px_100px] |
arbitrary size with type hint |
bg-center, bg-top, bg-right, etc. |
background-position |
bg-repeat, bg-no-repeat, bg-repeat-x, bg-repeat-y, bg-repeat-space, bg-repeat-round |
background-repeat |
bg-fixed, bg-local, bg-scroll |
background-attachment |
bg-clip-border, bg-clip-padding, bg-clip-content, bg-clip-text |
background-clip |
bg-origin-border, bg-origin-padding, bg-origin-content |
background-origin |
10. Effects
Shadow (the v4 scale-shift trap)
| v4 class | v3 equivalent | Notes |
|---|---|---|
shadow-2xs |
n/a | v4-only; smallest |
shadow-xs |
n/a (closest : v3 shadow-sm) |
INSERTED |
shadow-sm |
v3 shadow (no suffix) |
shifted up |
shadow-md |
v3 shadow-md (same name, slightly different value) |
|
shadow-lg |
v3 shadow-lg |
|
shadow-xl |
v3 shadow-xl |
|
shadow-2xl |
v3 shadow-2xl |
|
shadow-none |
shadow-none |
unchanged |
shadow-[<value>] |
arbitrary | |
shadow-<color>-<shade> |
shadow color | colored shadows |
ALWAYS read v4 shadow-sm as roughly equivalent to v3's shadow (default). NEVER assume v4 shadow-sm matches v3 shadow-sm visually : v3's shadow-sm is closer to v4's shadow-xs.
The same shift applies to blur-*, rounded-*, drop-shadow-*, backdrop-blur-* : v4 inserted -xs below -sm.
Inset shadow (v4-only)
inset-shadow-2xs, inset-shadow-xs, inset-shadow-sm, inset-shadow-none, inset-shadow-[<value>], inset-shadow-<color>-<shade>. See [tailwind-syntax-modern-utilities].
Other effects
| Class | Property |
|---|---|
opacity-<n> |
opacity : 0, 5, 10, 15, ..., 100; v4 dynamic any integer |
mix-blend-<mode> |
mix-blend-mode |
bg-blend-<mode> |
background-blend-mode |
blur-<size>, blur-[<value>], blur-none |
filter: blur(...) |
brightness-<n>, contrast-<n>, grayscale, hue-rotate-<n>, invert, saturate-<n>, sepia |
filter family |
backdrop-blur-<size> |
backdrop-filter: blur(...) |
backdrop-brightness-<n>, etc. |
backdrop-filter family |
drop-shadow-<size>, drop-shadow-[<value>], drop-shadow-<color>-<shade> |
filter: drop-shadow(...) |
Anti-patterns (summary; full list in references/anti-patterns.md)
NEVER do these :
- NEVER use removed v4 utilities :
bg-opacity-50,text-opacity-*,border-opacity-*. ALWAYS use slash syntaxbg-red-500/50. - NEVER assume
shadow-smis identical between v3 and v4. v4 insertedshadow-xs, shifting the entire scale. - NEVER write
flex-shrink-0orflex-grow-1in v4 code. ALWAYS useshrink-0andgrow. - NEVER write
bg-gradient-to-rin v4 code. ALWAYS usebg-linear-to-r. - NEVER write
overflow-ellipsisin v4. ALWAYS usetext-ellipsis. - NEVER assume
borderalone gives a visible border in v4 : the default border color iscurrentColor, notgray-200. ALWAYS add an explicitborder-<color>-<shade>.
Reference Links
- references/methods.md : complete property mappings for all ten families, value-scale tables, v3/v4 deltas
- references/examples.md : real layout patterns (centered card, sidebar layout, stat grid, hero) using only base utilities
- references/anti-patterns.md : full anti-pattern catalogue with v4-migration traps
Cross-references
- tailwind-core-architecture : why complete-literal tokens matter
- tailwind-core-design-system : the theme tokens that drive these utilities
- tailwind-core-v3-vs-v4 : full v3-to-v4 breaking-change catalogue
- tailwind-syntax-variants : hover/focus/dark/aria/data prefixes
- tailwind-syntax-responsive :
sm:,md:, container queries - tailwind-syntax-arbitrary-values :
p-[17px],bg-[url(...)] - tailwind-syntax-gradients : v4
bg-linear-*,bg-conic-*,bg-radial-* - tailwind-syntax-modern-utilities :
inset-shadow-*,inset-ring-*,@starting-style - tailwind-errors-v4-migration : shadow shift, border colour, ring width
Sources
- https://tailwindcss.com/docs/padding (spacing utilities + dynamic scale)
- https://tailwindcss.com/docs/colors (22-family oklch palette + opacity modifier)
- https://tailwindcss.com/docs/font-size (text-* scale with line-height pairings)
- https://tailwindcss.com/docs/flex (flexbox family)
- https://tailwindcss.com/docs/grid-template-columns (grid family + dynamic grid-cols-{any})
- https://tailwindcss.com/docs/box-shadow (v4 shadow scale with inserted xs/2xs)
- https://v3.tailwindcss.com/docs (v3 baseline for comparison)
- https://tailwindcss.com/docs/upgrade-guide (rename and removal list)
Verified 2026-05-19.