The Tailwind class that vanishes without an error

The failure looks like this: the component is handed className="text-body-sm text-foreground", and the built HTML carries only text-foreground. No error, no warning — just text at the default size where the design called for another.

1. Work out what removes the class

tailwind-merge resolves conflicting classes: between px-2 and px-4, the last one wins. To decide, it has to file every class into a group — and it only knows Tailwind’s own groups. A custom scale declared in @theme is unknown to it: text-body-sm gets filed with text colours, is therefore judged to conflict with text-foreground, and is dropped.

2. Reproduce it in a test, not in a browser

The cn function is pure. The test that catches this fits on one line — expect(cn("text-body-sm", "text-foreground")) — and needs neither a build nor a DOM. Chased through the browser, the same failure presents as “a style that doesn’t apply”, and the stylesheet is the first thing you wrongly suspect.

3. Declare the custom scales

extendTailwindMerge takes the theme’s groups: spacing, text sizes, radii. Every value declared there is recognised as such, and stops being mistaken for a colour.

4. Stop the two files from drifting apart

The list handed to extendTailwindMerge has to mirror the @theme block in the stylesheet. Nothing in the tooling holds them together: adding a token without listing it here brings back exactly the same failure, silent in exactly the same place. A comment at each end, and one test per group, are what make the omission visible.