/design-sync: no way to declare a stylesheet 'stylesheet-only' — check_design_system scans the full styles.css closure for tokens

Summary

The claude.ai/design token checker (check_design_system) extracts tokens from the FULL styles.css import closure. For design systems synced from a compiled-Tailwind app (package shape, cfg.cssEntry pointing at compiled output), the closure necessarily includes the compiled utility stylesheet (_ds_bundle.css) — which the upload contract requires to ship complete so rendered designs receive component styles. Result: the checker permanently flags compiler internals as unclassifiable theme tokens, even when the sync ships a curated tokens-only file.

Reproduction (real project)

• Tailwind v4 app synced with the bundled /design-sync skill (package shape, synth entry).
• Sync emits a curated tokens/theme.css (144 authored tokens, extracted only from :root/.dark/[data-*] scopes; --tw-*, --ease-in-out, --animate-*, --default-*, --shimmer-* excluded), imported first from styles.css, followed by @import "./_ds_bundle.css".
• check_design_system reports a census of 178 (34 extra vs the curated 144): every residual name comes from _ds_bundle.css — --tw-translate-x/-y, --tw-scroll-snap-strictness, --tw-outline-style, --ease-in-out, --animate-spin/pulse, ~60 custom properties declared under utility selectors (:where(.-space-x-2 > :not(:last-child)), .file\:font-medium::file-selector-button), and ~25 utility classes (.-translate-x-1\/2, .snap-mandatory, .leading-none) read as theme scopes.
• The skill's own lib/css.mjs documents this as a known trade-off ('the app's scope filter is a permissive heuristic … the price of designs actually receiving component CSS').

Ask

A way for the sync to declare token-source scope, e.g. either:

1. a marker/manifest field declaring a stylesheet stylesheet-only (loaded by designs, never scanned for tokens) — the upload contract currently only defines @ds-bundle/@ds-css-runtime/@ds-styles/@ds-font-face-dropped; or
2. when tokens/*.css files exist, the checker treats them as the exclusive token source (mirroring the converter's own README census logic) instead of scanning the whole closure.

Secondary: /* @kind … */ annotations only work if present in the file the checker reads; Tailwind strips source comments, so synced projects must post-process compiled CSS to keep annotations — worth documenting or honoring annotations from tokens/*.css for same-named declarations elsewhere in the closure.

Impact

Cosmetic but persistent: the warnings reappear on every recompile and cannot be resolved from the sync side. Runtime is unaffected (tokens resolve, components render).

🤖 Filed via Claude Code on behalf of the project owner