feat(react-windmod-preview): a Tailwind v4 + CSS Modules styling layer for Fluent's headless components

[Ray Knight (ArrayKnight)]

What this PR proposes

A Tailwind v4 + CSS Modules styling layer for Fluent's headless components, offered for official support and discussion of a sustainable landing plan. It adds preview packages without changing the styling system shipped by existing @fluentui/react-components consumers.

Following the maintainer feedback about review size, the independent fixes have been split into their own PRs. The remaining decision is whether the styling layer should be submitted in smaller in-tree pieces or maintained as a community package. The follow-up comments describe those options.

What ships

Package	Role
@fluentui/react-tailwind-theme-preview	Fluent tokens, seven theme stylesheets, Tailwind variants, cascade layers, and density scaling
@fluentui/react-windmod-preview	Styled headless components across 52 family subpaths; 133 authored CSS Modules; per-component CSS delivery
@fluentui/postcss-tailwind-css-modules	Public PostCSS plugin that preserves Tailwind group/peer markers under CSS Modules; used by this build pipeline and Storybook

The styling packages include a 63-entry migration guide and a shipped authoring skill. Checkbox, Radio, and Switch use a grid to align the indicator with the first label line, including wrapping labels. The CSS layer and scaling contracts are documented with the packages.

Independent fixes and current status

PR	Fix	Status
#36663	Breadcrumb distributive Omit	Merged
#36664	ColorPicker zero-channel fallback	Merged
#36665	Headless popover attribute spread order	Merged
#36666	Dialog scrollbar gutter	Open; preserves host stable both-edges gutters after review
#36667	TagPicker aside-width animation frame	Open; ref-detach cleanup, valid zero handles, cancellation-aware React 18 verification
#36668	Tooltip arrow class	Merged
#36669	MenuSplitGroup context values	Merged
#36670	Headless context exports	Merged
#36671	Storybook sandbox registration on Windows	Open
#36672	API subpath generation on Windows	Open
#36673	Preservation of declared static export subpaths	Open
#36690	NavCategoryItem decorative icon accessibility	Merged

This branch incorporates current upstream and the reviewed Dialog, TagPicker, and context-export fixes. The four StackShim compiler tests were leftovers from the earlier whole-library conversion: they referenced a CSS module that is absent from this PR. That obsolete test group is removed. The existing v8-to-v9 StackShim implementation remains intact. The PostCSS declarations now match the callable CommonJS export, with type fixtures for CommonJS and ESM consumers.

Verification and evidence

The September 9 upstream-sync sweep passes all 93 scenes: 67 strict-zero / 26 within individually ratified allowances / 0 failures. The registry retains its existing 27 allowance rows; one of those rows rendered at strict zero in this run. Pixelmatch uses threshold zero with its antialiasing classifier enabled; this is not a claim of byte-identical screenshots. All 163 Windmod test suites / 3,642 tests pass. All 83 headless suites / 1,167 tests also pass, including the new axe conformance checks. Build, lint, type-check, browser mutation checks, and verification limits are recorded in the latest update.

The three TagPicker frame regressions pass on React/ReactDOM 18.3.1 and React 19.2.0. On React 18, reverting to passive-effect cleanup fails the StrictMode test; reverting the explicit null check fails the zero-handle unmount test. Dialog preservation tests cover inline and stylesheet-provided gutters.

The bundle and runtime tables in the deep-dive comment are historical measurements, not fresh measurements of this head. The runtime benchmark predates per-component CSS delivery and used the monolithic stylesheet; its heap metric covers JavaScript, excluding CSSOM. Griffel was faster on the measured re-render case. The deep dive retains the methodology and rationale alongside those limits.

Remaining dependencies and decisions

• Icons use the published @fluentui/react-icons@2.0.339 headless API. The shared Tailwind variants target its public filled/regular class tokens with zero added specificity; the local tarball resolution is removed. The extra attribute proposed in feat(react-icons): expose the bundled icon variant as a data attribute fluentui-system-icons#1228 is no longer required. All 93 visual scenes pass against the existing gates.
• [Bug]: headless TeachingPopoverCarouselFooter drops the layout prop and the slot order it drives, so the offset footer's DOM and tab order cannot be reproduced through its renderer #36684 asks whether the headless Carousel layout omission was intentional. The question remains open; the current documented Windmod behavior is retained.
• Maintainer direction on adoption and decomposition is still needed. The earlier approximate 16-PR decomposition needs to account for the separately publishable PostCSS plugin before it becomes a landing commitment.

Related issues

#36645, #36646, #36647, #36648, #36649, #36650, #36651, #36652, #36653, #36654, #36655, #36685.

The individual fix PRs own issue closure. The larger argument, historical measurements, and detailed findings remain in the linked deep dive.

[Ray Knight (ArrayKnight)]

Updated in 937888a after merging current upstream and the reviewed fixes from #36666, #36667, and #36670.

• Resolved the main and fix(react-headless-components-preview): publish context readers from the button and link subpaths and context providers from avatar and avatar-group #36670 merge conflicts. The Avatar report retains upstream state changes and the requested context exports; MenuSplitGroup uses the upstream exported context-values hook.
• Addressed the new TagPicker review: the mock flushes only uncancelled frames and tests handle 0. The three frame regressions pass with React/ReactDOM 18.3.1 and 19.2.0. On React 18, reverting to passive-effect cleanup fails the StrictMode test; reverting the explicit null check fails the zero-handle unmount test. fix(react-tag-picker): tie aside-width frame cancellation to observer detach #36667 includes the React 18 integration-test config. Local Windows verification required corrections to the generated RIT scaffold's paths and Jest launcher, documented in that PR's reply.
• Addressed the new Dialog review: preserve an existing computed stable or stable both-edges gutter, including stylesheet-provided values, during locking and after unlocking. All 18 Dialog tests pass; restoring the unconditional fallback fails the preservation tests.
• Removed four obsolete StackShim compiler tests. They came from the earlier whole-library CSS conversion and entered this PR with the build-infrastructure port, but their StackShim.module.css never did. The existing compatibility component and its Griffel StackShim.styles.ts remain intact. These four failures were introduced by this PR, rather than being upstream test debt.
• Corrected the PostCSS plugin's declarations to match its callable CommonJS export. Strict NodeNext fixtures exercise CommonJS and ESM consumers; the previous declaration fails those call-site checks. The Storybook type boundary also accounts for the two resolved PostCSS versions. Updated the migration guide to describe the current first-line grid and existing visual allowances.

Validation on Node 22.12.0:

Check	Result
Theme generation/verifiers; headless and Windmod builds	Pass
Windmod and stories lint/type-check	Pass, with an existing unrelated stories lint warning
Windmod unit tests	163 suites / 3,642 tests pass
Headless unit tests on #36670	79 suites / 1,083 tests pass
PostCSS runtime tests and CommonJS/ESM type fixtures	24 tests pass; type-check passes
Remaining CSS Modules compiler tests	34 pass
Static Storybook and full visual sweep	93 scenes: 67 strict-zero, 26 within ratified allowances, 0 failures
Workspace sync, immutable install, formatting, change-file check	Pass

The visual registry still has 27 allowance rows; one rendered at strict zero in this run. No ceilings were raised for this follow-up. Historical bundle/runtime measurements in the deep dive have not been rerun.

Audit follow-up: the broader workspace-plugin suite still has 65 local failures, including Windows path assertions and output/snapshot mismatches. A controlled comparison with the original StackShim test group gives 69 failures; removing it gives 65, with exactly those four missing-file failures disappearing and all other failures unchanged. This establishes the cleanup's effect, not that the whole build-tool suite is green or that all 65 failures predate this PR. Those remaining failures need separate triage. The broader TagPicker default run also encountered an unrelated icon snapshot difference with the local icons dependency; no snapshot was updated.

The PR remains draft pending microsoft/fluentui-system-icons#1228 and a published dependency containing the icon stamp. The Carousel question in #36684 remains held for maintainer direction.

[Ray Knight (ArrayKnight)]

Implemented in 8ca3971.

The icons dependency blocker is removed: Windmod now targets the existing public fui-Icon-filled / fui-Icon-regular class tokens through its shared Tailwind variants, and uses published @fluentui/react-icons@2.0.339. The local tarball resolution is removed; the Windmod dependency floor is now ^2.0.339.

The selectors use [class~='…'] inside :where(), preserving exact class-token matching through CSS Modules and adding zero specificity. The existing theme import places icon rules in fui.base, below the component layers. No layer order or style declarations changed.

Verification:

• 96 browser cascade comparisons passed across hover/checked states, direct-child/deeper glyph selectors, LTR/RTL, forced colors, and stylesheet order. A same-layer override still wins; changing :where() to :is() makes that specificity check fail.
• All 82 affected compiled rules changed only their icon selectors; the theme's compiled rules are unchanged.
• All 93 visual scenes passed: 67 strict-zero and 26 within existing allowances, with no ceiling changes.
• All 163 Windmod unit suites / 3,642 tests passed after updating the InfoButton glyph assertion to the exported class constants.
• Theme/headless/Windmod builds, theme verifiers, package/story lint and type checks, immutable installation, formatting, and beachball validation passed.

The unlayered-icons negative control fails with both selector approaches, confirming that consumers should keep the existing layered import and avoid an additional unlayered copy. The icon attribute proposal in microsoft/fluentui-system-icons#1228 is no longer required for this implementation.

[Ray Knight (ArrayKnight)]

Synced with the latest master through 43665d5 and pushed 94a9319.

The headless update in #36712 replaces NavCategoryItem's data-open with data-expanded. Windmod now uses the existing group-expanded variant for the chevron, and its state tests follow the new attribute. The remaining state attributes and AvatarGroup context-helper changes are incorporated, along with the new headless accessibility conformance checks from #36576. The component/export comparison found no new components requiring a Windmod implementation.

Validation on the merged tree:

• Theme, headless, and Windmod builds; headless/Windmod/story type and lint checks; theme verifiers, formatting, and beachball checks passed.
• Headless: 83 suites / 1,167 tests passed. Windmod: 163 suites / 3,642 tests passed.
• Browser checks verified actual open/close clicks and chevron rotation in LTR, RTL, and forced-colors mode. A control restoring the former selector broke expanded chevrons; restoring the new selector passed.
• All 93 visual comparisons passed: 67 strict-zero and 26 within existing documented allowances. No ceilings or baselines changed.

The PR remains ready for review. Published icon class selectors remain in use; the icons tarball dependency is removed.

[Ray Knight (ArrayKnight)]

Synced latest master through #36723 (50ddff229c) in merge commit 648e372219.

This update changes release pipelines and release-tool authentication, adds the ESRP release helper, and updates beachball. It introduces no new headless components or changes to component code, styles, runtime dependencies, or Storybook/build-tool sources. Windmod's Tailwind and formatter dependencies are preserved.

Scoped validation passed: immutable installation; all 4 scripts-executors suites / 10 tests; script type/lint checks; parsing all 11 changed YAML files; and beachball checks. No release or publish task was run. The September 9 component validation, including 93 visual scenes, remains the latest component sweep; those unchanged sources were not retested for this release-tooling-only merge.

[Ray Knight (ArrayKnight)]

Updated status and reposted below the commit history for visibility.

Thanks Dmytro Kirpa (@dmytrokirpa) — completely fair on size, and I'll take you up on the fixes offer immediately: each in-tree fix from this PR is now its own isolated PR, one per linked issue:

• [Bug]: BreadcrumbButtonBaseProps collapses the ARIA button union, so href is not assignable #36645 → fix(react-breadcrumb): make BreadcrumbButtonBaseProps distribute over the ARIA button union #36663 (Breadcrumb distributive Omit) — merged
• [Bug]: ColorPicker sliders break for any channel whose value is 0 (|| fallthrough in adjustChannel) #36646 → fix(react-color-picker): use nullish fallback in adjustChannel so zero channel values resolve #36664 (ColorPicker zero-channel fallthrough) — merged
• [Bug]: headless Popover/Menu/Listbox pin the popover attribute after the props spread, so only one surface can be open per page #36647 → fix(react-headless-components-preview): let the consumer popover prop win on the PopoverSurface, MenuPopover and Listbox slots #36665 (headless popover attribute pinned after spread) — merged
• [Bug]: headless Dialog's scroll lock does not reserve the scrollbar gutter, so opening a modal shifts the page #36648 → fix(react-headless-components-preview): reserve the scrollbar gutter while a dialog locks scroll #36666 (headless Dialog scrollbar-gutter)
• [Bug]: TagPickerControl cancels its aside-width frame in the effect body, so the width token is written only ~25% of the time #36649 → fix(react-tag-picker): tie aside-width frame cancellation to observer detach #36667 (TagPicker rAF cleanup race)
• [Bug]: headless renderTooltip silently discards state.arrowClassName #36650 → fix(react-headless-components-preview): apply state.arrowClassName in renderTooltip #36668 (headless renderTooltip arrowClassName) — merged
• [Bug]: headless MenuSplitGroup renders without a contexts argument, so useIsInMenuSplitGroup can never return true #36651 → fix(react-headless-components-preview): provide MenuSplitGroup's context #36669 (headless MenuSplitGroup contexts) — merged
• [Bug]: headless subpaths publish context values hooks but not their readers, so a styling layer cannot read the look context the package's own renderers provide #36652 → fix(react-headless-components-preview): publish context readers from the button and link subpaths and context providers from avatar and avatar-group #36670 (headless subpath context readers) — merged
• [Bug]: react-storybook-addon-export-to-sandbox never finds its own registration on Windows #36653 → fix(react-storybook-addon-export-to-sandbox): find the addon registration on Windows #36671 (export-to-sandbox addon on Windows)
• [Bug]: workspace-plugin generate-api silently skips every export-subpath rollup on Windows #36654 → fix(workspace-plugin): generate-api emits export-subpath rollups on Windows #36672 (generate-api subpath rollups on Windows)
• [Bug]: export-maps-sync silently deletes any export-map key it cannot derive from a source entry point #36655 → feat(workspace-plugin): let export-maps-sync preserve hand authored asset subpaths #36673 (export-maps-sync static subpaths)
• [Bug]: headless NavCategoryItem drops the aria-hidden default on its expandIcon slot, so a custom chevron leaks into the button's accessible name #36685 → fix(react-headless-components-preview): default aria-hidden on NavCategoryItem's expandIcon slot #36690 (NavCategoryItem decorative icon aria-hidden) — merged

On the rest — before I move it to a community repo, I'd like to understand which cost is the actual blocker, because they point to different paths:

1. If it's this PR's review surface, I can decompose much further — theme package alone first, then per-family batches, each pixel-verified independently.
2. If it's the prospect of maintaining two styling systems indefinitely, that's the conversation I'd most value having, because the design goal was the opposite: the layer holds pixel-parity with Griffel across 93 VR scenes precisely so it can serve as a migration path — one that would let Griffel be deprecated over time and shrink the maintenance surface rather than double it. We proposed the big-bang version of this before and understood the appetite wasn't there; the preview-package shape was meant as the incremental route to the same destination. If there's any appetite for that direction, I'd gladly shape the work to whatever on-ramp the team could sustain.

If neither lands, I'll host it as a community package — in that case: would the team be open to a discoverability pointer (docs/community listing), and is the headless package's public API + DOM structure a contract you'd consider stable enough for an external styling layer to build against?

[Ray Knight (ArrayKnight)]

Updated status and reposted below the commit history for visibility.

Dmytro Kirpa (@dmytrokirpa) Following up with a proposed submission order if review size is the main concern:

1. Theme package. Fluent tokens, seven theme stylesheets, the generator, and its checks. This can be useful independently of the component layer.
2. PostCSS plugin and build infrastructure, with Button as the first complete example. The plugin is now a separately publishable package used by the build and Storybook paths. It could be reviewed separately from the infrastructure if that makes the first component PR easier to assess.
3. Component-family batches. Order each batch after the families whose state selectors it depends on. Each submission would carry its build/type/lint results, visual comparisons, and relevant migration-guide entries.
4. Remaining documentation and migration guidance. Include shared documentation with the change it explains, then finish the cross-package guidance.

The earlier sizing exercise estimated roughly 16 PRs and a five-PR critical path. That estimate predates the separately publishable PostCSS plugin and is a starting point, not a final count. I would recut the batches and sizes against the current tree once there is agreement on the approach and a review cadence the team can sustain.

The independent fixes are already separate (#36663–#36673, plus #36690), and seven have merged. The remaining fixes can proceed independently of the decision on Windmod.

If the main concern is maintaining a second styling system over time, the longer-term direction in my earlier comment is the decision to settle first; the community-package route remains available.