tailwind: scope the content scan to theme markup

[next-devin]

What

Tailwind v4 scans every non-ignored file for class names. Spark never told it otherwise, so a word in a doc or a code comment that happens to spell a utility compiles that utility into assets/main.css. Twelve were riding along:

Utility	Came from
collapse	docs/section-roster.md — "long tables collapse on mobile"
grayscale	scripts/sass-compat.py comment, and docs/section-roster.md
invert	tests/test_sass_compat.py assertions
top-24, z-40, z-60, z-70	DESIGN.md — the sticky-sidebar note and the z-layer table
ease-in, ease-in-out, ease-out	DESIGN.md animation table
start, table	prose

None of the twelve appears in a class attribute anywhere in the theme.

This is the failure that forced the comment reword in 7e6f446 (#52) to get the CSS drift gate green. Rewording prose does not scale: the next contributor who writes "truncate" in a docstring re-breaks the gate, and the fix is to make the scan set explicit instead.

How

css/input.css now opens with @import "tailwindcss" source(none) and names the four directories that legitimately carry class names:

@source "../templates";
@source "../partials";
@source "../layouts";
@source "../assets/js";

Two things worth flagging in review:

assets/js is a source, not an exclusion. theme.js toggles hidden, border-slate-200, and border-slate-800 at runtime, and those classes appear in no template. An allowlist that omits it compiles clean and silently breaks the mobile nav and variant selection.

There are no @source not rules. With auto-detection off, nothing outside the list is scanned, so exclusions for docs//scripts//tests/ would be dead config. The allowlist is also strictly stronger: a new stray directory can't leak, whereas a blocklist only covers the directories someone remembered to name.

The tradeoff is real and worth stating: a new directory containing class attributes now generates nothing until it is listed. test_source_list_is_exactly pins the list so that omission surfaces as a failing test rather than as missing styles on the storefront, and CLAUDE.md documents the three-step path (add @source, update EXPECTED_SOURCES, rerun make release).

Proof

tests/test_tailwind_source_guard.py plants a utility token (pt-73, used nowhere) in docs/, scripts/, and tests/, compiles, and asserts it never reaches the CSS.

Those three assertions are not self-sufficient — they also pass if the compile silently produced nothing, which is exactly the failure mode an allowlist introduces. So a positive control plants the same token in templates/ and asserts it does compile. Only the pair separates "the guard holds" from "the test is blind".

Mutation-verified. Restoring the bare @import "tailwindcss":

Ran 6 tests
FAILED (failures=4)

All three negative controls fail plus the source(none) contract test; the positive control still passes, which is the correct signature.

CI change

The test compiles CSS, so it needs ./tailwindcss. It fails with a pointer to make install-tailwind rather than skipping — a skip would retire the guard invisibly the first time the binary went missing. CI ran unittest discover before installing the CLI, so that step now runs after it. No other reordering.

Local make test on a checkout without the binary will now fail; make verify-theme already required it.

Verification

make verify-theme     56 tests OK, sass-compat clean
make css-drift        passed (48219 bytes)
settings parity       119 data values / 141 schema settings
template integrity    62 files
JS module tests       12/12

assets/main.css: 49208 → 48219 bytes, rebuilt with make release and committed alongside the source change.

🤖 Generated with Claude Code