Colour and Borders

Colour in Tailwind works like spacing: you pick from a ready-made palette with names and numbers, and the same names work on text, backgrounds, borders, rings and shadows. The edges of things (borders, rounded corners, rings, shadows) are a similar small system. This chapter covers both, including a measured look at colour contrast, which is the part people most often get wrong.

The Palette

The default theme has 26 colour families, each with 11 shades numbered 50, 100, 200, 300, 400, 500, 600, 700, 800, 900 and 950, plus black and white. I counted them in Tailwind's own theme.css: red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose; the greys slate, gray, zinc, neutral and stone; and mauve, olive, mist and taupe (those last four were added in v4.2). A low number is light and a high number is dark: blue-50 is nearly white, blue-950 nearly black, and blue-500 is the middle.

Every colour is a theme variable, written in oklch():

The three numbers are lightness, chroma (how vivid) and hue (the angle on the colour wheel). It is a good notation for building a palette because shades of one hue look evenly spaced. You never need to type it: you use the name, and Tailwind writes the variable only if you use the colour.

Putting Colour on Things

A colour class is a prefix, which says what to colour, followed by the family and shade. Each prefix maps to one CSS property:

There are also a few special values that are not in the palette: bg-transparent (transparent), bg-current and border-current (currentcolor, meaning "the text colour"), and text-inherit (inherit). For a colour that is not in the palette use brackets, bg-[#bada55], or a variable, bg-(--brand), which compile to background-color: #bada55 and background-color: var(--brand). The colour of an input's placeholder text has two spellings that give the same result: placeholder-gray-400 and the variant form placeholder:text-gray-400 both compiled to a ::placeholder rule setting color. The variant form is the one that generalises (chapter 6).

Opacity: the Slash

To make a colour partly transparent, add a slash and a percentage to any colour class: bg-blue-500/50 is the blue at 50%. It works with every prefix in the table above, and with arbitrary values (bg-blue-500/[0.37] gave 37%). Here is what Tailwind wrote for bg-blue-500/50:

It uses color-mix(): a plain version first for older browsers, then, where the browser supports it, a version that mixes in the oklab colour space using the theme variable. Chrome painted it as oklab(0.623 -0.0378 -0.2106 / 0.5), which on a white page is a lighter blue (pixel value 44, 128, 255 at half alpha).

Readable Colour: Contrast

A colour scheme is only useful if people can read it. The WCAG accessibility guidelines measure the contrast between text and background as a ratio from 1:1 to 21:1. Level AA asks for at least 4.5:1 for normal text and 3:1 for large text (24px, or about 19px bold); AAA asks for 7:1. I painted common pairs in Chrome, read the real colours back, and computed the ratio:

Two habits follow. The light-grey captions that look elegant (text-gray-400 on white) are hard to read and fail the guideline; gray-500 is the lightest shade of this grey that passes on white. And the popular white-on-blue-500 button fails for ordinary text size; moving one step darker, to bg-blue-600, fixes it. In general, for light backgrounds use shades 600 or darker for text, and for a coloured button with white text use shade 600 or darker. (Always check your own pairs: a different family has different numbers.) Exercise 1 gives you a snippet to do the measurement.

Backgrounds and Gradients

Colour is one kind of background; images and gradients are others. The small utilities map directly to properties:

A gradient is made from a direction class plus colour stops:

bg-linear-to-r sets the direction (to right; there are eight, such as -to-br for bottom-right), from-*, via-* and to-* set the colours, and the three stops sit at 0%, 50% and 100%. Move a stop with a percentage: from-10% and to-90% are --tw-gradient-from-position: 10% and --tw-gradient-to-position: 90%. The same family gives you bg-linear-45 (an angle), bg-radial and bg-conic. In the generated CSS the colours are mixed in the oklab colour space (to right in oklab), which keeps the middle of a gradient from going grey; add /oklch (as in bg-linear-to-r/oklch) to ask for a different space. The older class name bg-gradient-to-r still compiles in v4, but bg-linear-to-r is the current name.

Borders

A border has a width, a style and a colour, and Tailwind sets each by class. The width classes:

Rounded corners come from the radius scale:

A bare rounded is 0.25rem, the same as rounded-sm in v4. Round one side or corner with a suffix: rounded-t-lg (both top corners), rounded-s-md (both start-side corners, which flip in right-to-left text), or an exact value with rounded-[10px]. rounded-none removes rounding.

Rings and Outlines

A ring is a solid line around an element that takes up no space, which makes it ideal for focus and selected states, because the layout does not move when it appears. It is drawn with box-shadow, so ring-2 ring-blue-500 is a 2px blue ring:

Two things are different from older Tailwind, according to the official v4 upgrade guide, and I checked the generated CSS. A bare ring is now 1px (v3's was 3px), and its default colour is currentcolor (v3's was blue-500), so a ring with no colour class matches the text. For the old width write ring-3, which compiled to a 3px ring. ring-offset-2 leaves a 2px gap between the element and the ring. inset-ring draws the ring inside the element.

An outline is the browser's own outline: outline (1px), outline-2, outline-blue-500, outline-offset-2. Browsers show an outline on keyboard focus by default, and the usual Tailwind pattern for custom focus styles is to replace it with your own, and v4 has two classes for "no outline". outline-hidden compiled to outline-style: none plus a rule that restores a transparent 2px outline in forced-colours mode (Windows High Contrast, @media (forced-colors: active)), so the focus indicator is not lost for people who use that mode. outline-none compiled to just outline-style: none. The upgrade guide says v3's outline-none behaved like today's outline-hidden, so older code that uses outline-none for focus styles should be outline-hidden now. Never remove the focus indicator without giving a visible replacement.

Shadows and Filters

Shadows come in a size scale. Each is made of one or two box-shadow layers at low opacity:

Bigger offset and blur means the element looks higher above the page. The clever part is how they combine. Every shadow and ring class writes into its own variable, and box-shadow reads all five, so classes stack rather than replace each other. A card with shadow-md ring-2 ring-blue-500 has the blue ring and the shadow, which Chrome showed as one list: four ring and offset layers (three empty, then the 2px blue ring) followed by 0 4px 6px -1px and 0 2px 4px -2px. Without the ring classes the same list has an empty slot where the ring was. Other shadow classes: inset-shadow-sm (a shadow inside), and a coloured shadow with shadow-blue-500/50.

A warning for code you copy from v3 projects: v4 renamed the scales so that every size has a name. The upgrade guide's table: v3 shadow-sm is now shadow-xs and v3 shadow is now shadow-sm; the same shift applies to rounded, blur, drop-shadow and backdrop-blur. The bare names still work (I saw that shadow and shadow-sm generate the same CSS in 4.3.3), but copied shadow-sm classes will look slightly stronger than they did in v3.

Filters. drop-shadow-md is a different tool: it is a filter that traces the shape of what is drawn, so it follows a transparent PNG or SVG outline where box-shadow would draw a rectangle. blur-sm blurs the element (blur(8px)); backdrop-blur-md blurs what is behind the element (blur(12px)), which gives the "frosted glass" panel when combined with a partly transparent background such as bg-white/50. The blur sizes come from the theme: xs 4px, sm 8px, md 12px, lg 16px, xl 24px, 2xl 40px, 3xl 64px.

Hands-On Exercises