Skip to content

[codemods] Convert shorthands, logical properties & keyframes to StyleX (Emotion→StyleX, 4/6) #1771

Open
ahmedsadid wants to merge 25 commits into
facebook:mainfrom
ahmedsadid:codemod/emotion-m3-values
Open

[codemods] Convert shorthands, logical properties & keyframes to StyleX (Emotion→StyleX, 4/6) #1771
ahmedsadid wants to merge 25 commits into
facebook:mainfrom
ahmedsadid:codemod/emotion-m3-values

Conversation

@ahmedsadid

Copy link
Copy Markdown
Contributor

What changed / motivation ?

Part of migrating Emotion styles to StyleX (#1766). Earlier PRs converted static
and conditional styles as written; this one reshapes values that don't map
one-to-one onto StyleX — shorthands, logical properties, and keyframes.

// before
<div css={{ margin: '8px 16px', color: 'navy' }}>Box</div>

// after
const styles = stylex.create({
  box: { marginBlock: '8px', marginInline: '16px', color: 'navy' },
});
<div {...stylex.props(styles.box)}>Box</div>
  • Multi-value shorthands (margin: '8px 16px') expand into longhands, since
    StyleX doesn't allow a shorthand and its longhands to coexist.
  • Physical properties become logical: marginLeftmarginInlineStart,
    paddingRightpaddingInlineEnd, leftinsetInlineStart.
  • Emotion keyframes({ … }) becomes stylex.keyframes({ … }), with the import
    and every reference to it updated.
  • Refuses two media queries on one property whose order changes the result
    (StyleX would reorder them), plus everything earlier PRs already skipped.

Testing

  • Before/after fixtures for margin/padding shorthands, logical properties, and a
    keyframes animation — each result compiles, passes lint, and renders the same
    CSS as the Emotion input.
  • One "leave it unchanged" fixture where a single property has two media queries
    whose order decides which one wins — StyleX would reorder them, so the file is
    skipped.
  • Unit tests that check each transform on its own — shorthand expansion,
    physical → logical mapping, and keyframes output — by passing style objects
    straight in and asserting the generated StyleX.

Linked PR/Issues

Part of #1766 · builds on #1770

Additional Context

Stacked on #1770, but stands on its own to review.

Pre-flight checklist

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

ahmedsadid and others added 25 commits July 23, 2026 17:03
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…te proven to fail on a broken pair

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…-written IR

Source-neutral: emit is fed hand-written IR (no Emotion) so the engine is
provably library-agnostic. Emits alphabetically-sorted keys (satisfies
stylex/sort-keys with zero autofixes) and refuses conditions/duplicates/
non-static values rather than mis-emitting. styleToObjectAst added to the
rewriter wrapper is emit's AST-rendering bridge, keeping core/emit AST-free.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…orts, orchestrator

Reads static css={{...}} / css({...}) on host elements into neutral
declarations; rewrites each site to {...stylex.props(styles.key)}; inserts a
single per-file registry above the first converted component; cleans up the
@emotion/react import and @jsxImportSource pragma. Whole-file-or-nothing
(M1 policy): any blocker (pseudo/media, template literal, shorthand overlap,
component css prop, pre-existing stylex) skips the file untouched with reasons.
core/ never imported here — the seam holds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
CSS treats 'rgb(10, 20, 30)' and 'rgb(10,20,30)' as identical and the StyleX
compiler emits the latter; without this the gate flagged every rgb()/multi-arg
value as a false diff. Comma-whitespace is now canonicalized on both sides.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…add 8 fixtures

The two M0-skipped checks (byte-exact match, per-fixture semantic-diff) now run
for real against transformEmotionFile. Skip-fixtures assert the transform
refused loudly and left the file byte-identical. New fixtures: css-call-form,
static-values, two-sites (convert) + skip-{pseudo,template-literal,
shorthand-conflict,component-css,existing-stylex} (refuse).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…red coverage

Replaces the M0 throwing stub with a real StyleX-object -> IR reader (flat
static values + fallback arrays). The harness now round-trips each covered
corpus entry (read -> emit -> compile -> semantic-diff vs original, empty
allowlist) and reports measured coverage; condition/keyframe entries remain
typed, SAFE coverage gaps (2/5 covered at M1).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Emotion emits plain CSS (browser resolves by cascade: specificity then source
order); StyleX resolves by fixed priority per condition (imported from
@stylexjs/shared, never reinvented). They disagree only among equal-specificity
conditions where CSS uses source order but StyleX uses priority. For each
property, within each pseudo-element target (different box = no competition),
the cascade order must equal the priority order — else refuse. Prevents the
silent-wrong-cascade bug class (e.g. :focus-then-:hover). Tested against
hand-written IR.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
emit groups atoms by property and nests conditions into StyleX's
property-grouped shape (the inverse of Emotion's selector-grouped input),
canonicalizing nesting order and filling default: null where a condition has
no base. Hover-guard (:hover wrapped in @media (hover: hover)) is on by
default, toggleable. buildIR carries conditions + fallback-array values; the
rewriter renders nested condition objects with string-literal keys. Tested
against hand-written IR.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
read walks nested condition objects into declarations carrying condition
paths — pseudo-classes, pseudo-elements, media queries and their nesting —
refusing non-self-targeting selectors, functional pseudos, and conditions
nested inside a pseudo-element. transform runs each rule through the referee
(refuse on disagreement) and threads the hoverGuard option into emit.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…eree & descendant refuse

Renames skip-pseudo -> hover-pseudo (now converts, hover-guarded). Adds
focus-media, pseudo-element (convert) and skip-referee-conflict (:focus before
:hover), skip-descendant-selector (refuse). Each verified across all four
harness checks.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… 5/5

The test-only StyleX-object reader now parses condition-in-value objects
(pseudo/at-rule keys, nested), proving the flip round-trips from the StyleX
side (read -> emit with hoverGuard off -> compile -> semantic-diff, identity).
The whole seed corpus now round-trips.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Maps inline-axis physical properties to logical (marginLeft->marginInlineStart,
left->insetInlineStart, ...) — a doc-sanctioned RTL behavior change covered by
the semantic-diff physical->logical allowlist and matching StyleX's own
preference. Block-axis (top/bottom) stays physical (no RTL flip). On by
default, { logicalProperties: false } to disable. Tested against hand-written IR.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…e output

verifyAndFix with all @stylexjs/eslint-plugin rules at error, so key ordering
and shorthands match StyleX's canonical form instead of a heuristic we
maintain (StyleX sort-keys is not alphabetical). Residual unfixable errors ->
caller refuses the file. File-wide is safe now (a converted file has no
pre-existing user stylex.create); M4 adds scoping. The semantic-diff gate runs
on this output, catching any sort-keys reorder that changes rendering.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A property with >=2 sibling at-rule (e.g. @media) conditions sharing a pseudo
context becomes sibling media keys; sort-keys reorders them but the compiler
treats sibling media order as semantic, and the per-coordinate semantic-diff
gate cannot see it. Refuse (never mis-emit) until the upstream inconsistency
is resolved. Verified empirically that verifyAndFix does reorder such keys.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…t) into transform

Threads logicalProperties + hoverGuard options; refuses on postprocess residual
errors.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…dia refuses

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… longhands

Emotion writes 'margin: 8px 16px' as one declaration; the codemod emits
StyleX's expanded logical form (marginBlock/marginInline). Compared by property
name these read as a diff even though they render identically. So before
diffing, both sides' margin/padding shorthands (and their logical variants) are
expanded to the four physical per-side longhands, resolving logical->physical
in LTR. This unblocks multi-value shorthand conversion, which the transform
already performs via the postprocess autofix. inset/border keep the allowlist
path.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
IR Value gains a 'reference' variant (a bare identifier, e.g. animationName
pointing at a keyframes var). emit renders it as a $$ref sentinel and emits
KeyframesRule -> named frame objects (reusing the property-grouping machinery);
the rewriter renders $$ref as an identifier. normalize maps physical->logical
inside frames too. Tested against hand-written IR.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Detects 'const NAME = keyframes({...})' from @emotion/react, reads its frames,
rewrites to stylex.keyframes, and allows 'animationName: NAME' as a preserved
identifier reference in css props. Import/pragma cleanup now strips 'keyframes'
alongside 'css'. Non-object/tagged-template/reassigned keyframes are refused.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… generated animation-name

The animation-name hash differs between Emotion and StyleX, so the gate skips
@Keyframes rules in the per-property net CSS, extracts their frame contents
separately (keyframesFromStylexMetadata), and the harness compares them as an
order-independent multiset against Emotion's serialized frames. animation-name
present only on the after side is allowlisted (it references converted
keyframes; a literal animationName stays diffed). New fixture: keyframes-spin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Records why token->defineVars is deferred to the config milestone: it needs
module-resolution gate config + multi-file fixtures (M6 infra), and a token's
value is external to the file so the semantic-diff cannot verify it (the
project's first trusted transformation). M3 is complete with a/b/c. Also
documents the trusted-transformation boundary as a principle and refreshes the
README converts/refuses table + status.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@vercel

vercel Bot commented Jul 23, 2026

Copy link
Copy Markdown

@ahmedsadid is attempting to deploy a commit to the Meta Open Source Team on Vercel.

A member of the Team first needs to authorize it.

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Jul 23, 2026
@ahmedsadid
ahmedsadid force-pushed the codemod/emotion-m3-values branch from 6a2775f to b738639 Compare July 23, 2026 23:47
@ahmedsadid
ahmedsadid marked this pull request as ready for review July 24, 2026 00:35
@ahmedsadid
ahmedsadid requested review from mellyeliu and nmn as code owners July 24, 2026 00:35
@ahmedsadid
ahmedsadid force-pushed the codemod/emotion-m3-values branch from b738639 to 6cb0fa1 Compare July 25, 2026 02:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant