CLI not removing unused variables until ran a second time

[danbisso]

What version of Tailwind CSS are you using?

v4.1.13

What build tool (or framework if it abstracts the build tool) are you using?

None/Tailwind CLI

What version of Node.js are you using?

v24.5.0

What browser are you using?

N/A, checking CSS output

What operating system are you using?

macOS

Reproduction URL

https://github.com/danbisso/tailwindbug

Describe your issue

I'm using one utility class in the HTML, text-5xl.
When I run the CLI,

npx @tailwindcss/cli -i ./input.css -o ./output.css 

I see the utility class .text-5xl and related variables --text-5xl: in output.css, as expected:

@layer theme {
  :root, :host {
    [...]
    --text-5xl: 3rem;
    --text-5xl--line-height: 1;
    [...]
  }
}
[...]
@layer utilities {
  .text-5xl {
    font-size: var(--text-5xl);
    line-height: var(--tw-leading, var(--text-5xl--line-height));
  }
}

However, the issue is that when I change the utility class in my HTML, from say text-5xl to text-4xl, the utility class is updated correctly but not the variables:

@layer theme {
  :root, :host {
    [...]
    --text-4xl: 2.25rem; <== ✅ New variable
    --text-4xl--line-height: calc(2.5 / 2.25);
    --text-5xl: 3rem; <== ❌ Old unused variable is not removed
    --text-5xl--line-height: 1;
    [...]
  }
}
[...]
@layer utilities {
  .text-4xl {  <== ✅ This gets updated correctly
    font-size: var(--text-4xl);
    line-height: var(--tw-leading, var(--text-4xl--line-height));
  }
}

I would expect the variables to also get cleaned up since this is a full rebuild and not an incremental one (I'm not using --watch).

Interestingly, I can run the same CLI command twice, and the second time it will clean up the variables correctly.

What gives?

[wongjn]

This is due to Tailwind scanning for used CSS variables that match its theme tokens. So after changing to text-4xl:

1. Run build.
2. Scan files.
3. See var(--text-5xl) and var(--text-5xl--line-height) usage in output.css. Save them for later.
4. On output, add --text-5xl and --text-5xl--line-height.

Usually this doesn't happen because most of the time, the output CSS is git-ignored, and thus step 3 never happens.

Thus, as a workaround, you should exclude output.css from being scanned by one of:

• Adding /output.css to your .gitignore:

  --- a/.gitignore
  +++ b/.gitignore
  @@ -1 +1,2 @@
  -node_modules
  \ No newline at end of file
  +node_modules
  +/output.css

• Or use @source not to exclude output.css from being scanned:

  --- a/input.css
  +++ b/input.css
  @@ -1,2 +1,3 @@
  @import "tailwindcss";
  
  +@source not "./output.css";