design-sync ships Tailwind v4 --tw-* internals that check_design_system cannot classify (false-positive adherence warnings)

design-sync ships Tailwind v4 --tw-* internals that check_design_system cannot classify (false-positive adherence warnings)

Environment

• Claude Code: 2.1.186
• design-sync skill: 2.1.185 (/design-sync, storybook source shape)
• Tailwind CSS: 4.2.4 (tailwindcss v4.2.4, confirmed in the compiled bundle header and yarn.lock)
• App stack: React 19.2.6 + Vite 8.0.16 + TypeScript 5.9.3, Storybook @storybook/react-vite 10.2.0
• Design renderer: Chrome (claude.ai/design)
• Project type: an application (not a published component library) synced as a design system

Summary

/design-sync (storybook shape) ships the project's compiled Tailwind v4 utility engine verbatim as _ds_bundle.css. That output contains Tailwind's internal --tw-* composition variables — which are not design tokens. check_design_system (claude.ai/design) enumerates every CSS custom property as a candidate design token and has no @kind / ignore rule for --tw-* or for @property-registered customs, so it raises adherence warnings for all of them.

This is systemic: every Tailwind v4 design system synced this way produces the same warnings. They are cosmetic — generated designs render correctly — but they create persistent, unfixable-in-repo noise in the design-system check.

Findings (from one real sync)

check_design_system reported, for this design system:

• ~50 "component-selector properties", and
• ~42 unclassifiable --tw-* tokens.

The compiled _ds_bundle.css defines 86 distinct --tw-* engine variables, each emitted in two forms:

1. Inert fallback (the "component-selector properties" finding). Tailwind v4 emits, for browsers without @property:

``css
@layer properties {
@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline)))
or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))) {
*, ::before, ::after, ::backdrop {
--tw-translate-x: 0; --tw-translate-y: 0; /* …86 vars… */
}
}
}
`
The @supports condition is **false in Chrome**, so this block **never applies** in the design renderer. The checker still flags the declarations because they sit on the universal selector (a "component selector", not :root`).

1. Load-bearing @property registrations (the "unclassifiable tokens" finding).

``css
@property --tw-translate-x { syntax: "*"; inherits: false; initial-value: 0; }
/* …translate / rotate / skew / gradient / ring / shadow / space-y /
leading / tracking / enter-exit animation vars, etc… */
`
These are **rendering-critical**: composed utilities such as
translate: var(--tw-translate-x) var(--tw-translate-y) depend on the
registered initial-value`s. They cannot be removed without breaking
transforms/animations in generated designs.

Compiled utility selectors like .table-dense and .space-y-0 are flagged on the same basis.

Why it can't be fixed in the synced repo

• _ds_bundle.css (and the app-generated _ds_manifest.json / _adherence.oxlintrc.json) are read-only synced output, regenerated on every /design-sync — any hand-edit is overwritten.
• The inert @layer properties fallback could be stripped safely (it never runs in Chrome), but that only addresses the ~50 finding.
• The @property --tw-* registrations (the ~42 finding) must stay — stripping them breaks rendering. So there is no in-repo edit that clears the warnings without regressing output.
• The design-sync converter has no token-classification / @kind logic, and the @kind/ignore contract is owned by check_design_system, not the sync tooling.

Proposed fix (either side resolves it)

• Converter side: when shipping a Tailwind v4 bundle, emit the --tw-* /

@property engine in a form check_design_system skips (e.g. an annotation /
segregated layer the checker excludes), keeping it fully functional at render time; or

• Checker side: have check_design_system ignore --tw-*-named custom

properties and @property-registered customs by default (treat them as engine
internals, not design tokens) — optionally surfaced as @kind other.

Repro

1. In a Tailwind v4 app/library with Storybook, run /design-sync to a claude.ai/design project.
2. In a Design session on that project, run the design-system check.
3. Observe adherence warnings for ~50 universal-selector --tw-* declarations and ~42 unclassifiable --tw-* @property tokens.

Impact & severity

• Impact: affects any Tailwind v4 design system synced via /design-sync.
• Severity: cosmetic — no functional or rendering impact; designs render correctly. The cost is persistent, unactionable false-positive warnings in the design-system check.