feat(react-components)!: migrate styling from Griffel to Tailwind v4 + CSS Modules (Griffel-zero)

[Ray Knight (ArrayKnight)]

DRAFT — under author review only. Not yet ready for maintainer review; will be marked ready by Ray Knight (@ArrayKnight). Do not merge before its dependency (see Merge order below).

Migrate react-components styling from Griffel to Tailwind v4 + CSS Modules

This PR replaces the runtime CSS-in-JS styling system (Griffel makeStyles/mergeClasses) across the entire non-deprecated v9 surface — every react-components package, the charts package, the test/VR/SSR/perf harness, and the stories and docs pages — with build-time CSS Modules + Tailwind v4 tokens under a cascade-layer contract (@layer fui.theme, fui.base, fui.components(.l1–l5), fui.utilities). The repo ends Griffel-zero outside deprecated/ packages: the Griffel AOT pass runs in 3 packages / 6 files, all under packages/react-components/deprecated/, and no *.styles.raw.js is emitted anywhere else. Per-stage counts are in GRIFFEL_ZERO_CLOSURE.md.

Why

• Runtime cost out, build-time CSS in: styles ship as static, per-package dist/styles.css compiled at build time; no style computation or injection at runtime, and no Griffel AOT compilation step.
• Measured wins — re-measured on this branch's HEAD with the repo's own metrics/capture.sh, same machine, cold, clean tree (full data and provenance: migration/griffel-to-tailwind/reports/FINAL_REPORT.md §2.0):
  • Griffel AOT: 62 packages / 277 source files transformed → 3 packages / 6 files, all under packages/react-components/deprecated/ (react-alert 1, react-infobutton 2, react-virtualizer 3)
  • Dead *.styles.raw.js shipped in every tarball: 700,829 B → 0 across non-deprecated react-components (12 files / 44,304 B remain on disk, all under deprecated/)
  • Shipped lib/ JS across react-components: −15.57% (like-for-like, 4,556,347 → 3,846,978 B; baseline restricted to HEAD's 84-package set, since react-conformance-griffel left it for deprecated/)
  • @fluentui/react-button npm tarball: −34.14% packed (124,354 → 81,896 B), −41.18% unpacked (1,050,635 → 617,951 B), 185 → 176 files
  • Honest trades, stated in the report: CSS aggregates per-package rather than deduplicating atomically, so a single-component consumer pays its package's whole stylesheet; and the VR storybook's static output is +12.95% (34,569,262 → 39,045,618 B). That last one is not a clean like-for-like and is not offered as one: the storybook also gained 24 story files, and it is a bundled artifact whose HEAD leg links the icons fork below where the baseline leg linked published icons. Neither confounder is netted out — see FINAL_REPORT.md §2.7 — because doing so honestly requires the post-revert re-capture.
  • Bundle-size and build-time figures are deliberately absent. Bundle numbers are blocked on the icons dependency below and will be published from a post-revert capture. Build time is not publishable at all: five cold identical-scope runs on one unchanged tree measured 167/163/161/158/156 s in run order — a monotone warming trend spanning 6.8% of the median — against a single-observation baseline, so no percentage in that range is defensible. Client-runtime figures are cited from their own dated reports below rather than restated here.
• Simpler consumer contract: standard CSS with cascade layers replaces a proprietary runtime styling API.

Developer experience

Beyond the measurements, the authoring model changes in ways that matter day-to-day (expanded rationale: Less variant nesting in Tailwind with compound and stacked syntax):

• You write CSS. No object notation, no camelCased property names, no JS-based abstraction standing between the author and the stylesheet — CSS-in-JS is an indirection layer that has to be learned, tooled, and mentally translated back to the CSS it produces. Tailwind introduces some indirection of its own (it isn't perfect), but the escape hatch is always the same: when its vocabulary doesn't cover a case, you drop to plain CSS in the same file — not to another abstraction.
• Styles are grouped, not scattered. A component's entire appearance lives in one *.module.css, organized by slot and state, instead of being distributed across atomic utility classes. That also bounds the blast radius of change: editing a component's rule affects that component — whereas editing a shared atomic/utility class (in code or live in DevTools) changes every element on the page that happens to use it.
• Separation of concerns. Behavior stays in .tsx, appearance in .module.css. Reviews get smaller and more focused; styling changes stop churning component logic files.
• The DOM is parseable. Emitted class names are scoped but semantic (fuicm-<component>-<slot>-<hash>), so component structure is identifiable by reading the markup in DevTools — versus a hashed atomic class soup where nothing in the element tells you what it is.
• States are single-sourced. Tailwind v4's compound/stacked variant syntax (@variant hover, focus-visible { … }, @variant dark:hover { … }) expresses "these states share this appearance" once, instead of duplicated blocks that silently drift apart — the source reads the way you'd describe the design out loud.
• Overrides are predictable. Cascade layers give deterministic precedence (fui.theme → fui.base → fui.components.l1–l5 → fui.utilities): a consumer override wins by layer, not by specificity games, source-order luck, or !important.
• Theming is just a class. A theme is a CSS class containing only custom-property declarations, so scoping it is a DOM operation rather than an API call: put webDarkThemeClassName on <FluentProvider>, on a bare <aside>, or on <html> — no provider is required for a scoped theme, portals and nested providers inherit automatically, and the default (web light) resolves at :root with no wrapper at all. Custom themes are authored the same way, which means they are inspectable and overridable in DevTools like any other stylesheet, and switching themes is a className swap instead of rebuilding and re-injecting a rule set.
• Work moves from per-render JavaScript into the per-frame cascade. Class resolution that a runtime styling engine performs inside every component render — including renders that get batched or never produce a visual change — is expressed declaratively and resolved by the browser's cascade instead: coalesced once per frame, scoped by the engine's invalidation machinery to the elements that actually changed, and executed as native code that improves with every browser release. Style recalculation still shares the main thread, so this is a claim about where and how often the work is paid, not about it becoming free — but the JavaScript savings are real and serialized with everything else the app does, which is main-thread time handed back to application code. Measurements are in reports/perf-eval.md and reports/perf-consumer-dynamic-class.md, each dated to the commit pair it traced.

Runtime-performance deep dive (state-toggle investigation)

An observed state-toggle regression was investigated to root cause across eight controlled experiments (migration/griffel-to-tailwind/reports/perf-*.md): selector policy, selector ordering, attribute-vs-class form, named groups, will-change, transition tightening, @layer structure, and value literalization each measured null. The mechanism the investigation landed on: Blink charges a fixed per-started-transition cost whenever the document's custom-property registry is non-empty — any @property rule, related to the transition or not, reproduced by injecting a single dummy registration into the unmigrated build, which slowed it equally. The migrated theme had registered a handful of focus-ring knob properties; those registrations are now removed, with the same nesting-isolation guarantee reproduced at the cascade level. Verified on this branch: across all 63 dist/styles.css artifacts under packages/, the theme package and every component package emit zero @property rules — the only two that remain are Tailwind-internal and confined to a dev-only storybook addon that no shipped package depends on. The remedy brings Button toggle cost back to Griffel parity and recovers most of Switch's; the remainder is custom-property resolution during transition-triggered recalc, the accepted cost of a fully var-driven theme.

The per-cell timings, the µs-per-transition figure and the recovery percentages live in reports/perf-mechanism-diagnostic.md, reports/perf-property-remedy.md and reports/perf-layers-vs-literals.md, each stamped with the commit pair it traced. They are cited rather than restated here because they have not been re-run against the current HEAD, which has since had theming Phase 2b remove provider rule-building entirely. The diagnostic recommends filing the underlying behavior as a Chromium optimization gap; it affects any page that registers custom properties, regardless of styling system.

Validation

Pixel identity was the non-negotiable gate throughout. Every conversion batch was captured against pre-change baselines via StoryWright and diffed at zero tolerance, with per-batch gates plus full-suite sweeps at phase boundaries. Where states lacked coverage, VR stories were added and baselined before converting (focus states, icon filled/regular swaps across hover/open/pressed/disabled, chart popovers, RTL/dark/high-contrast) — the VR story count under apps/vr-tests-react-components/src went from 137 files at the baseline commit to 161 today. Behavioral gates: full jest suites at parity, the SSR render+hydration suite, and CDP computed-style/matched-rules equivalence probes for cascade-sensitive changes.

Per-gate set and screenshot counts are deliberately not restated here: each was recorded against the tree that existed when it ran, and quoting one as a current status would misdate it. Every batch, decision, gate result and adjudication is in-repo with its own date under migration/griffel-to-tailwind/ — see DECISIONS.md, GRIFFEL_ZERO_CLOSURE.md, theming-css-native.md (the most recent full-VR sweep), the per-batch reports, and the post-campaign consistency audits.

Breaking changes (major-version)

Consumer-facing walkthrough of all of the below, with before/after for each: Concepts/Migration/Upgrading from v9 on the docsite, plus the full 467-row token map at .../FromV9/TokenRename.mdx.

0. @fluentui/react-tailwind-theme must be installed and its stylesheet imported once per document. It carries the cascade @layer order, the token values (Web Light at :root, :host), the spacing/stroke scales and the shipped theme classes — everything the component CSS references. This is the break most likely to be missed, because skipping it does not throw: components render with collapsed spacing, no radii and no shadows. Two of the breaks in this list fail silently; this is one, the token rename (item 7) is the other.
1. Static BEM class names removed (fui-Component/fui-Component__slot and the xClassNames slot maps). The supported styling contract is: per-slot className props; one public identity marker per component (group/fui-<component>, usable via fuiSelector() from react-utilities and as a Tailwind group target); data-* state attributes; and the documented layer system for cascade-safe overrides. This is a type change, not a deprecation: 215 *ClassNames constants typed SlotClassNames<…Slots> on master are 193 typed { root: string } here, so every non-root slot reference is a compile error. The one step the type system cannot force is `.${x.root}` → fuiSelector(x.root), since string building type-checks fine.
2. Umbrella Griffel re-exports removed from @fluentui/react-components (12 runtime symbols + 3 types) along with its @griffel/react dependency.
3. @fluentui/react-conformance-griffel retired (moved to deprecated/, per repo precedent).
4. v0→v9 migration style mixins retired (their static output is inlined into the migration guides).
5. FluentProvider: Griffel renderer APIs removed. The provider no longer renders Griffel's TextDirectionProvider — direction flows via dir + CSS logical properties, so RTL now follows the DOM rather than React context. (That was an internal render detail, not a published export; it appears in no api.md at master.) The interim first-class nonce prop was itself removed by item 7 — the provider no longer creates any style element, so there is nothing to sign; cover the static .css assets with a CSP style-src source list.
6. @fluentui/react-icons v3 (headless) required — see Merge order.
7. Theming is CSS-native; the JS theming path is removed. All 467 token CSS variables were renamed to a single canonical kebab vocabulary aligned to Tailwind v4 namespaces (--colorNeutralBackground1 → --color-neutral-background-1, --spacingHorizontalM → --spacing-horizontal-m, --strokeWidthThin → --stroke-width-thin, …; complete old→new map committed at migration/griffel-to-tailwind/reports/token-rename-map.json and published as a docsite page with a find/replace script) — the old camelCase variables no longer exist in any shipped CSS. This one fails silently: a var() on an undefined custom property drops the declaration with no error, warning or log. The tokens object is unaffected — same JS key names, updated values — so only hand-written CSS needs rewriting. Themes ship as static CSS classes in @fluentui/react-tailwind-theme (.fui-theme-web-dark, …; web-light values are the :root defaults), applied via FluentProvider's new themeClassName prop (typed constants: webLightThemeClassName, …) or directly on any DOM node for scoped theming; portals and nested providers inherit automatically. REMOVED: FluentProvider's theme prop and runtime theme <style> tag, its nonce prop, createCSSRuleFromTheme, useFluentProviderThemeStyleTag, ThemeContext_unstable, and the umbrella/react-theme exports of the theme objects, create*Theme factories, themeToTokensObject and Theme/PartialTheme/BrandVariants types (theme objects remain in @fluentui/tokens as build-time tooling input). Custom themes are CSS classes containing only custom-property declarations; runtime value reads go through useCssVarValue (from @fluentui/react-utilities, which the umbrella does not re-export). Provider mount no longer builds or injects a rule set at all — the work is gone rather than reduced, though this PR quotes no re-measured mount timing for it.

Merge order / dependencies — IMPORTANT

This is PR 2 of 2 and must not merge first:

1. feat(react-icons)!: promote the headless API to the package default fluentui-system-icons#1204 merges first and publishes @fluentui/react-icons 3.0.0 (headless default + required styles.css). This PR's icon integration (the icons stylesheet imported at layer(fui.components.l1), layered icon-state selectors, and retirement of the Griffel jest snapshot serializer) was validated against exactly that code.
2. This branch currently carries two clearly-marked LOCAL-ONLY(revert-before-PR) commits (90d1096404, b0248a57f1) that point the workspace at a packed tarball of the icons fork for development. Before this PR is marked ready they are reverted — but the revert alone is not enough, and the remaining steps are load-bearing:
   • Bump the declared range. Across every tracked package.json there are 42 @fluentui/react-icons range declarations and zero declare ^3.0.0 (36 × ^2.0.245, plus ^2.0.306 ×2, ^2.0.311, ^2.0.239, ^2.0.237, and the one file: resolution). Reverting without bumping resolves the workspace to published 2.x, which is the Griffel-based build this PR's icon integration assumes is gone.
   • yarn install, then re-run the icon-integration VR gate.
   • Re-capture the size metrics (bash migration/griffel-to-tailwind/metrics/capture.sh <leg>) and publish the bundle numbers from that leg. Every monosize figure currently on the branch is measured against the fork tarball, so none is quoted in this PR body — see FINAL_REPORT.md §2.0 for what is and is not publishable and why.
3. Then this PR undrafts.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XB8ax95bxM4N23bUkSm455