SayDeploy Plain comparisons of developer tools, AI coding tools included

How to validate class names against the Tailwind config for component library authors in 2026

Unknown utilities and stray class names can ship in a component library unnoticed. Here is how authors can check them against the Tailwind config.

By SayDeploy ยท

SayDeploy is published by LunarWerx, which makes some of the tools compared here.

Scan your component source files against the Tailwind config, review the suggested changes before applying them, and then run the same check automatically on each change so that only new problems fail the build.

OptionWhat it doesCost
NormWindFinds class pairs that can be one shorthand class, flags arbitrary values that match a named class, can rewrite findings, and can fail a CI job when new findings appear. [1] [1] [1] [1] [1]Free. [1]
Tailwind CLInot publishednot published
stylelint Tailwind pluginnot publishednot published
PostCSS plugin for Tailwindnot publishednot published

What you need before you start

Before validating anything, a component library author needs a Tailwind config that describes the design system the library publishes. Keep that file in source control so its history is visible to everyone who works on the library.

All component source files that contain class names should be available in the repository, including Vue, Svelte, Astro, HTML, JavaScript, TypeScript, JSX, and TSX files. A check that skips a file type will miss violations in that type.

Decide where the check runs: on a developer's machine during work, in a continuous integration (CI) pipeline that runs automatically on each change, or in both places. Make a list of the utilities the library exposes, so you can tell whether a class name is intended or stray. Confirm which operating systems your CI jobs run on, so the tool runs in the same environment. If you want the check to look only at changed lines in a pull request, note the name of the main branch to compare against, such as origin/main. If you plan to install a tool from npm, you need Node.js and npm on the machine. [1] Having these items ready helps the first check start cleanly.

Step by step

Work through these steps in order.

  1. List every file that contains Tailwind class names. Record the path, language, and component name so each finding can be traced back to its source.
  1. Confirm that the Tailwind config loads without errors in your normal build. A config that fails to load can make later results unreliable.
  1. Run the validation in a report-only mode first, if the tool offers one, so you can read the findings without any file changing.
  1. Review each suggested shorthand. A pair of classes such as px-4 py-4 may be replaceable by one class such as p-4, but confirm that the replacement keeps the spacing you intended.
  1. Review arbitrary values that match a named utility. A value written in square brackets may match a standard class with the same meaning. Choose the named class when it produces the same result.
  1. Apply the fixes in a separate commit, so the changes are easy to review and to revert.
  1. Compare the generated CSS before and after the change. If the output differs, skip that change, because the component may look different to users.
  1. Add the validation step to CI. Begin by reporting only findings on changed lines, or by recording existing findings as a baseline, so old problems do not block unrelated work.
  1. Decide the exit behavior. The job should fail when new findings appear and pass when none appear.
  1. Watch the first few CI runs. Check that the findings are accurate and that each failure points to the right file.

Tools that can do it

NormWind is made by the team that publishes this site. NormWind finds pairs of classes like px-4 py-4 that can be written as one shorthand class such as p-4. [1] It flags values like rounded-[24px] that match a named class such as rounded-3xl, using Tailwind's own canonicalizeCandidates engine. [1] It can rewrite findings in Vue, Svelte, Astro and HTML files. [1] It can show which files a fix would change without writing anything to disk. [1] Before merging classes, it compares the generated CSS before and after the change, and skips the merge if they differ. [1] Results can be printed as plain text, as JSON, or as SARIF 2.1.0 for GitHub code scanning. [1] It ships as a GitHub Action that annotates pull requests inline. [1] You can install it from npm as a dev dependency, or run it with npx. [1] Check whether your project uses Tailwind CSS v4, since that is the version the tool is described as working with. [1]

The table lists three other options that this page names. No source facts about them are available here, so their features and costs are not published on this page. Check each option's own documentation for what it reads, reports, and costs before comparing it with the others.

Common mistakes to avoid

Adding new utilities to the Tailwind config without updating the validation step can cause false alarms, because the check still treats the new class as unknown. Skipping the comparison of generated CSS before merging classes can introduce visual changes that nobody reviewed. Running the check on only some of the files leaves violations hidden in the parts of the library that were not included. Reviewing every finding in one large batch, instead of in small commits, makes it hard to tell which change caused a visual difference. Assuming that a tool covers every file type the library uses, without checking its list of supported files, leads to gaps. Treat the first CI run as a test of the setup, and read its output closely before making the check block merges.

Frequently asked questions

How do component library authors validate Tailwind class names against the config?

Authors can run a check that reads the Tailwind config, scans component files for class names, and reports any name the config does not define. The check can also suggest shorter classes and flag arbitrary values that match a named class. Running the check in a report-only mode first lets authors read the findings before any file changes, which makes the first review safer and easier to follow.

Is NormWind free to use?

NormWind is free. [1] It is released under the MIT licence. [1] Read the licence text yourself before relying on the tool in a published library. This page does not give legal advice, so the licence text is the place to confirm what is allowed.

Can Tailwind class name validation run in a CI pipeline?

Yes. The tool can report only findings on lines changed since a git reference such as origin/main. [1] It can also record current finding counts for each file, so only new findings fail the build. [1] The audit exits with code 1 when it finds anything, which fails the CI job. [1]

Does NormWind work with Vue, Svelte, Astro and other component files?

NormWind can rewrite findings in Vue, Svelte, Astro and HTML files. [1] A wider option also covers JavaScript, TypeScript, JSX and TSX files. [1] It works with Tailwind CSS v4 projects, and CI runs on Ubuntu, Windows and macOS. [1] Check your own file types against this list before deciding.

What should component library authors check before choosing a validation tool for class names?

Check whether the tool reads your Tailwind config and which file types it covers, since a gap in file types leaves violations unseen. Look at whether it offers a report-only mode and a way to review fixes before they are applied. Confirm that it fits your CI setup and the operating systems your jobs use. Review its licence and cost, and read its documentation for how it reports results.

NormWind is free with no paid tier. [1]

Try NormWind

Sources

  1. NormWind's own description of itself (the product of this site's publisher)

Related comparisons