[types] Validate CSSProperties against the CSS grammar, Baseline, and Flow

[henryqdineen]

What changed / motivation ?

Stacked on #1882, which made StyleXCSSTypes.d.ts a hand-maintained duplicate of the Flow types.

CSSProperties is 522 properties and roughly 2,500 keywords, all written by hand, and nothing checks it against CSS. At that size review cannot catch a keyword that is misspelled, one that was never in any spec, or one that is missing — and after #1882 there are two copies that can drift apart.

CSS is machine-readable where it matters: the value definition grammar states what each property accepts, and Baseline states what is safe to use. These tests ask those sources rather than asking a reviewer to know CSS, so the types become checkable instead of trusted.

Deliberately validating, not generating. The types stay hand-written and hand-editable; the tests only report where they disagree with CSS. Where they intentionally differ — browsers and specs disagree too — it goes in an allowlist with a reason. Today a missing keyword and a deliberate omission look identical; afterwards they do not. That turns out to be 38 decisions and 66 gaps, all currently indistinguishable from each other and from correct code.

The six tests

1. The TypeScript definitions match the Flow types — nothing else stops them diverging.
2. Every property accepts the CSS-wide keywords (initial, inherit, unset, revert, revert-layer) — valid everywhere, in no grammar, so nothing else can check them.
3. Every keyword is real, per the grammar — typos and invented values.
4. Closed unions list every keyword the grammar has — the reverse of 3: values a user cannot write at all.
5. Properties whose grammar needs arbitrary strings accept them. Not "are the literals right?" but "should this be a union of literals at all?" Would have caught url value for cursor property #1463.
6. Every Baseline-available property is typed.

Built so an agent can close the loop

Each allowlist entry is work still to do, and each failure names the property, prints its grammar or Baseline status, and states the two valid fixes. Remove an entry, run the test, read the failure, make the change, re-run — no CSS knowledge required beyond the output.

That is deliberate, because what remains is bulk cleanup rather than design. I had a small model do three of them unattended from the test output alone and it got them right. #1886 is five worked examples; what makes them trustworthy is not care in writing them but that the tests check each against the grammar and confirm both files still agree.

Linked PR/Issues

Stacked on #1882. Test 5 surfaces #1463, fixed in #1885.

Additional Context

The allowlists are two different things, and it is worth separating them. Some entries are decisions that should stay, because specs and browsers disagree and StyleX sides with browsers. The rest are a to-do list.

Deliberate deviations (38) — expected to stay:

KEPT_KEYWORDS	19	Keywords the spec dropped that browsers still ship. marginTrim is the clearest: the spec was rewritten to none | in-flow | all, but Safari ships the original block/inline
NOT_TYPED	17	SVG presentation attributes. StyleX types fill, stroke and strokeWidth, so excluding the rest is arbitrary — but x, y, d and r read oddly as style keys
NOT_TYPED	1	all, which resets every property at once and cannot work with styleq's key-based override model
NO_GRAMMAR	1	WebkitBoxOrient, which css-tree simply lacks but the -webkit-line-clamp idiom needs

Known gaps (66) — expected to reach zero:

INCOMPLETE_UNIONS	32	Closed unions missing keywords the grammar allows — display cannot take flow or table-caption, overflow cannot take overlay
NO_GRAMMAR	15	Properties in no current spec, to be deleted: abandoned drafts (motion-* became offset-*), @font-face descriptors that were never properties (src, unicode-range)
CLOSED_DESPITE_GRAMMAR	13	Types too narrow for their grammar. colorScheme and fontStyle accept neither strings nor numbers; the rest accept a bare number, so only calc(), var() and units are out of reach
NOT_TYPED	6	Baseline-available properties that should be typed — whiteSpaceCollapse is literally commented out in StyleXCSSTypes.js awaiting this

marginTrim appears in both halves, which is honest: it keeps values the spec dropped and is missing values the spec added.

Scoping test 4 is what makes it useful: restricted to closed unions it finds 125 real omissions across 32 properties, where unrestricted it demands over ten thousand additions, because shorthands like background transitively pull in every named colour.

Two new devDependencies, both test-only. css-tree supplies the grammar and its parser — a patched fork of mdn-data, and the same parser csstype uses. web-features supplies Baseline; mdn-data's status field looks like it would do instead, but it describes the spec rather than browsers, calling font-stretch obsolete though every browser has supported it since 2020 while marking its replacement font-width experimental. It is pinned exactly so that a version bump lands in package.json rather than as a lockfile line inside Dependabot's weekly grouped PR — worth knowing, because when it moves, test 6 can legitimately fail: a property reaching Baseline is the news it exists to deliver.

Why not codegen, or csstype. Generating these types from the grammar was the first thing I tried; it worked, but produced a ~4,000-line diff, replaced a file people read with generated output, and put css-tree in the build path of a public API — with no existing codegen in the repo to follow. csstype is spec-current in ways that clash: it would break roughly 24 of the deviations above, and wrapping it for StyleX's semantics (null to unset, bare numbers meaning pixels, theme, comma-list arrays) is unpleasant in Flow. The dual Flow/TypeScript requirement is what makes most off-the-shelf options awkward.

The omissions are not deliberate — I checked whether StyleX prefixes or normalises values in a way that made them redundant, and it does not.

Follow-ups. No TSDoc, unlike csstype, though most of the data is available here. And packages/@stylexjs/eslint-plugin/src/reference/cssProperties.js is a second, independent encoding of this knowledge that could use the same treatment — worth knowing before leaning on it that its conversion misassigned values, so stylex/valid-styles currently accepts zIndex: 'ideographic' and transform: 'border-box'.

Each failure was verified by injecting it. The suite runs in ~60ms.

Pre-flight checklist

• I have read the contributing guidelines
  Contribution Guidelines
• Performed a self-review of my code

🤖 Generated with Claude Code

[github-actions]

workflow: benchmarks/perf

Comparison of performance test results, measured in operations per second. Larger is better.
yarn workspace v1.22.22
yarn run v1.22.22
$ node ./compare.js /tmp/tmp.po4ejDp09G /tmp/tmp.csvCIFnYjT

Results	Base	Patch	Ratio
babel-plugin: stylex.create
· basic create	571	556	0.97	-
· complex create	63	63	1.00
babel-plugin: stylex.createTheme
· basic themes	450	446	0.99	-
· complex themes	31	31	1.00
Done in 0.08s.
Done in 0.34s.

[github-actions]

workflow: benchmarks/size

Comparison of minified (terser) and compressed (brotli) size results, measured in bytes. Smaller is better.
yarn workspace v1.22.22
yarn run v1.22.22
$ node ./compare.js /tmp/tmp.oJpRmIs4aB /tmp/tmp.9atf0ROKpO

Results	Base	Patch	Ratio
@stylexjs/stylex/lib/cjs/stylex.js
· compressed	1,535	1,535	1.00
· minified	5,166	5,166	1.00
@stylexjs/stylex/lib/cjs/inject.js
· compressed	1,793	1,793	1.00
· minified	4,915	4,915	1.00
benchmarks/size/.build/bundle.js
· compressed	496,650	496,650	1.00
· minified	4,847,840	4,847,840	1.00
benchmarks/size/.build/stylex.css
· compressed	99,735	99,735	1.00
· minified	740,755	740,755	1.00
Done in 0.08s.
Done in 0.33s.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
stylex	Ignored		Sep 11, 2026 3:15am UTC