Keeping Tailwind CSS Output Small on Static Sites

Tailwind's promise on a static site is a small stylesheet: it generates only the utilities your markup uses. That promise holds as long as Tailwind sees only your markup. In practice, the stylesheet creeps up release by release — 9 KB at launch, 23 KB a year later, 61 KB after a migration — and nobody notices until a performance audit points at render-blocking CSS. The causes are rarely the design itself. They are the scanner finding class-like strings in data, safelists that only grow, and hundreds of one-off arbitrary values.

This guide takes the Tailwind output of an Astro documentation and marketing site from 61 KB to 11 KB compressed, shows how to find which utilities are in the stylesheet and why, and sets a budget that holds it there. It belongs to CSS and JavaScript Asset Optimization; the opposite failure, classes that are missing, is covered in Fixing Missing Tailwind Classes in Production Builds.

Prerequisites

• Tailwind 4 (the approach applies to 3.x with content paths instead of @source).
• A production build whose CSS can be inspected.
• A way to measure compressed size: brotli -c file.css | wc -c.

Step 1: Measure and Inventory

npx astro build
for f in dist/_astro/*.css; do echo "$(brotli -c "$f" | wc -c) $f"; done
# 62,480 dist/_astro/global.Bq3k.css  (61 KB brotli, 412 KB raw)

Then list what is in it. A short script extracts every selector and groups by utility family:

const css = fs.readFileSync(file, 'utf8');
const sels = [...css.matchAll(/^\s*\.((?:\\.|[^\s{,:])+)/gm)].map((m) => m[1].replace(/\\/g, ''));
const family = (s) => s.replace(/^[\w-]+:/, '').split('-')[0];
console.log(Object.entries(Object.groupBy(sels, family)).map(([k, v]) => [k, v.length]).sort((a, b) => b[1] - a[1]).slice(0, 15));

The stylesheet had 6,140 selectors. A design system with 40 components does not need 6,140 utilities.

Attributing selectors to sources was done by elimination: build with one source excluded, diff the selector lists, repeat. Five builds of about 40 seconds each told the whole story.

Step 2: Stop Scanning Data

The largest source was a src/data/ folder of JSON files — a product catalogue export, changelog data and translated strings — that automatic detection scanned because it lived inside src. Words in product descriptions matched utility names: "block", "flex", "grid", "table", "hidden", "contents", colours like "red" and "blue" combined with numbers in SKU strings. 2,410 accidental utilities. Excluding it:

@import 'tailwindcss';
@source not '../data';

In Tailwind 3 the equivalent is narrowing content to template files only (./src/**/*.{astro,md,mdx,tsx}). The general rule: scan markup, not data.

Step 3: Shrink the Safelist

A safelist had been added during a migration "to be safe":

safelist: [{ pattern: /(bg|text|border)-(red|green|blue|amber|slate|indigo)-(50|100|200|300|400|500|600|700|800|900)/, variants: ['hover', 'dark'] }]

That one pattern generated 1,520 rules. The classes it protected came from two places: a CMS colour picker with eight allowed values, and a status badge that built class names from fragments. The badge was rewritten with a lookup of full class names, and the CMS's eight values became one explicit inline source, as in the missing-classes guide. The safelist went from 1,520 rules to 8.

Step 4: Reduce Arbitrary Values

690 selectors were arbitrary values such as w-[37px], mt-[13px], text-[#3a4b5c] and grid-cols-[1fr_2fr_1fr]. Grouping them showed most were near-misses of theme values: 212 spacing values within 2 px of a theme step, 140 colours that were slight variations of palette colours. The design team mapped each to the nearest token and added six genuinely needed values to the theme. A lint rule now flags new arbitrary values in review (eslint-plugin-tailwindcss's no-arbitrary-value as a warning), and the reviewer decides whether the value should become a token.

Step 5: Scan Libraries' Output, Not Their Source

A component library vendored into src/vendor/ included its source, its stories and its tests. Tailwind scanned all of them, including classes used only in stories for components the site never rendered. Pointing the scanner at the library's built output only — the components the site actually imports — removed 610 selectors' worth of matches down to about 90.

Step 6: Trim the Theme

The theme defined 18 custom colours with 11 shades each and three extra font sizes scales from an old brand. Theme definitions in Tailwind 4 become CSS variables, which are emitted for every token whether used or not in @theme (unless declared with @theme reference or in a separate file). Removing unused palettes and keeping only used shades as variables cut another 2 KB. A quick check: search the built HTML for each palette name; a palette with no matches can go.

Step 7: Set a Budget

The CSS size is now checked in CI against a budget of 15 KB compressed, leaving headroom over the current 11 KB:

size=$(brotli -c dist/_astro/global.*.css | wc -c)
[ "$size" -le 15360 ] || { echo "Tailwind CSS is $size bytes (budget 15360)"; exit 1; }

The same budget lives in the Lighthouse CI configuration for the stylesheet resource, as in Writing a Performance Budget That Fails Builds. The CI step's output also prints the top five utility families by count, so a sudden jump shows where it came from.

Component Libraries and Prefixes

Two smaller habits keep the output tidy as more teams contribute. Shared components should use the same theme tokens as the site, so a "primary button" in the library and on a page generate the same bg-brand-600 rule rather than two near-identical colours. And when a third-party widget brings its own Tailwind build, isolating it — its own stylesheet loaded only where the widget appears, or a prefix — keeps its utilities out of the site-wide file every page downloads.

Measured Impact

The stylesheet is render-blocking, so on a throttled mobile profile shrinking it moved first render and LCP directly. Inlining critical CSS is the other option for that problem; at 11 KB it was no longer worth the complexity here, as discussed in Inlining Critical CSS on Static Sites.

Pitfalls & Rollback

• Scanning data and content exports. Words in data match utility names.
• Pattern safelists. They grow combinatorially; list exact classes instead.
• Unchecked arbitrary values. They add rules and erode the design scale.
• No budget. The output drifts upward release by release.
• Rollback: each change is a source directive, a safelist edit or a theme edit; reverting one restores its selectors, and the budget check shows the size change.

Conclusion

Tailwind output grows when the scanner sees more than markup: data files, pattern safelists, library sources and a long tail of arbitrary values. On this site, excluding data, replacing a pattern safelist with eight explicit classes, mapping arbitrary values to tokens, scanning the library's output and trimming the theme took the stylesheet from 61 KB to 11 KB compressed, and a 15 KB budget keeps it there.

FAQ

How small should Tailwind's CSS output be on a static site?

Most content sites end up between 8 and 25 kilobytes compressed. The site in this guide reached 11 kilobytes for about 1,400 pages. Output above 40 kilobytes compressed usually means the scanner is picking up class-like strings from places it should not, or a large safelist, rather than a genuinely large design.

Why is my Tailwind CSS file so large?

Because Tailwind generates a rule for every string in scanned files that matches a utility name. Scanning data files, generated content, vendored libraries or minified bundles can match thousands of accidental utilities. Large safelists, many arbitrary values and big custom theme scales add more. Inspect the output to see which utilities exist and where they came from.

Do arbitrary values like w-37px increase CSS size?

Each distinct arbitrary value generates its own rule, so a codebase with hundreds of one-off values produces hundreds of rules that a design scale would have shared. They also signal design drift. Limiting them with a lint rule and adding common values to the theme keeps both the CSS and the design tidier.

Should I split Tailwind CSS per page on a static site?

Usually not. One shared stylesheet of 10 to 20 kilobytes compressed is cached after the first page and costs nothing afterwards, while per-page stylesheets lose that sharing. Split only when one section, such as an interactive app or a marketing microsite, uses a very different set of utilities.

Related

• Parent: CSS and JavaScript Asset Optimization — CSS and JS weight.
• Fixing Missing Tailwind Classes in Production Builds — the opposite problem.
• Tailwind v4 in Astro Without PostCSS Plugins — the setup used here.
• Purging Unused CSS with Tailwind and Lightning CSS — removing non-Tailwind CSS.
• Eliminating Render-Blocking CSS on Static Sites — why CSS size affects LCP.