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

.agents/skills/fluentui-windmod/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: fluentui-windmod
+description: Use when styling, theming or overriding Fluent UI components from @fluentui/react-windmod-preview or @fluentui/react-tailwind-theme-preview, when authoring or verifying component styles inside those packages, or when users say "style this Fluent component", "override the button styles", "theme this app", "switch to dark theme", "restyle windmod", "fui-button", "group variant", "cascade layer", or when working with .module.css files in a windmod project or migrating an app off @fluentui/react-components and Griffel. Provides the override model (cascade layers, not props), the public class and data-attribute surface, the variant catalog, theme class names, the base-scale density knob, and the authoring and verification conventions used inside the library itself.
+license: MIT
+---
+
+# Fluent windmod
+
+The full skill is vendored with the package it documents, so that the copy published to consumers
+and the copy used in this repository can never drift apart.
+
+**Read it here — start with `SKILL.md`, then follow its routing:**
+
+```
+packages/react-components/react-windmod-preview/library/skills/fluentui-windmod/
+  SKILL.md                            the agent contract — read this first
+  references/setup.md                 installing, the two stylesheets, wiring your own Tailwind
+  references/overriding.md            restyling a component from an app
+  references/variant-catalog.md       the two catalogs and the group-variant vocabulary
+  references/tokens-and-scale.md      token namespaces, --base-scale, density
+  references/griffel-deltas.md        the deliberate differences from @fluentui/react-components
+  references/css-var-values.md        reading a resolved token value in JavaScript
+  references/authoring-conventions.md CONTRIBUTORS: authoring rules + the verification protocol
+  references/troubleshooting.md       a style that will not apply
+  assets/                             a worked override example
+```
+
+**Changing anything inside `packages/react-components/react-windmod-preview`** — a `*.module.css`, a
+styles hook, a VR scene, a mutation table, a pixel allowance — means loading
+`references/authoring-conventions.md` completely first. Those rules are strict and violations are
+rejected.
+
+Consumer-facing install and adoption notes live in the same directory's `README.md`.

.claude/skills/fluentui-windmod/SKILL.md

@@ -0,0 +1 @@
+@../../../.agents/skills/fluentui-windmod/SKILL.md

.github/CODEOWNERS

@@ -334,6 +334,8 @@ packages/react-components/react-menu-grid-preview/library @microsoft/teams-prg
 packages/react-components/react-menu-grid-preview/stories @microsoft/teams-prg
 packages/react-components/react-headless-components-preview/library @microsoft/cxe-prg
 packages/react-components/react-headless-components-preview/stories @microsoft/cxe-prg
+packages/react-components/react-windmod-preview/library @microsoft/cxe-prg
+packages/react-components/react-windmod-preview/stories @microsoft/cxe-prg
 # <%= NX-CODEOWNER-PLACEHOLDER %>
 
 # Deprecated v9 packages - exposed as part of `/unstable` api

.gitignore

@@ -161,3 +161,11 @@ gulp-cache
 .cursor/rules/nx-rules.mdc
 .github/instructions/nx.instructions.md
 .playwright-cli
+
+# session scratch space (never committed)
+.scratch/
+
+# knowledge-graph tool output (never committed) — lands at the repo root and, because it is
+# written relative to the invocation directory, sometimes under packages/ where nx and beachball
+# then scan it. 2,177 cache files at last count, all regenerable.
+graphify-out/

.storybook/main.js

@@ -51,7 +51,19 @@ module.exports = /** @type {import('./types').StorybookConfig} */ ({
     }),
   ],
   webpackFinal: config => {
-    registerRules({ config, rules: [rules.swcRule] });
+    /**
+     * Narrow storybook's own implicit `/\.css$/` rule FIRST, then add ours — webpack applies
+     * every matching rule, so the builder's plain style-loader/css-loader pair has to stop
+     * matching `*.module.css` (it would hand back an empty class map) and the Tailwind theme
+     * entry (it would emit `@import … source(none)` verbatim) before these are registered.
+     *
+     * windmod-preview `*.module.css` files open with `@reference '#theme'` and use `@apply`,
+     * which are not valid CSS until Tailwind's PostCSS pass has run. Without this wiring
+     * this storybook — and the package storybooks and docsites that compose it — render
+     * windmod components unstyled.
+     */
+    rules.excludeTailwindCssFromDefaultCssRule(config);
+    registerRules({ config, rules: [rules.swcRule, rules.cssModulesRule, rules.tailwindThemeRule] });
     registerTsPaths({ config, configFile: tsConfigPath });
 
     if ((process.env.CI || process.env.TF_BUILD) && config.plugins) {

.storybook/preview.js

@@ -1,7 +1,29 @@
+// Emits the shared Tailwind theme layer once per document (see the file's header).
+// Required by windmod-preview `*.module.css`. Package/app previews import this module,
+// so the side effect reaches all of them.
+import '../scripts/storybook/src/tailwind-theme.css';
 import '../packages/react-components/react-storybook-addon/src/styles.css';
 import '../packages/react-components/react-storybook-addon-export-to-sandbox/src/styles.css';
+import { webLightThemeClassName } from '@fluentui/react-tailwind-theme-preview/theme-class-names';
 import { withLinks } from '@storybook/addon-links';
 
+/*
+ * Stands in for the theme class a real application applies at its root.
+ *
+ * The theme stylesheet bakes no default (operator ruling 2026-08-28, "Theme delivery"):
+ * importing a theme file makes its class AVAILABLE, and the class still has to be applied —
+ * the same two steps Griffel asks for with `import { webLightTheme }` +
+ * `<FluentProvider theme={webLightTheme}>`. Web light is the storybook's document theme, so
+ * this is where it gets set. A story that wants another theme wraps its subtree in a
+ * FluentProvider with that theme's class, which overrides this one locally.
+ *
+ * On `documentElement`, and `add` rather than assignment, so it composes with anything else
+ * that classes the root and reaches shadow-DOM-free subtrees the same way `:root` did before
+ * the split. The class name is imported rather than written out so it stays in lockstep with
+ * the generated stylesheet.
+ */
+document.documentElement.classList.add(webLightThemeClassName);
+
 /** @typedef {import('../packages/react-components/react-storybook-addon-export-to-sandbox/src/index').Parameters & import('@storybook/react').Parameters} Parameters */
 
 /** @type {import('@storybook/react').Decorator[]} */

change/@fluentui-babel-preset-storybook-full-source-2643295e-cd5a-4161-9b35-c42234d6c9e1.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "fix: format through @prettier/sync and declare it as a dependency, so the preset works under prettier 3",
+  "packageName": "@fluentui/babel-preset-storybook-full-source",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-breadcrumb-303eadd0-08bf-49e2-96da-d47362b73490.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "fix: use DistributiveOmit in BreadcrumbButtonBaseProps so the anchor variant of the root slot survives, restoring href",
+  "packageName": "@fluentui/react-breadcrumb",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-color-picker-48823fe7-aa92-48cc-a2e5-5b4de941f337.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: use nullish coalescing in adjustChannel so a channel whose value is 0 no longer falls through to the hue action",
+  "packageName": "@fluentui/react-color-picker",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-headless-components-preview-20d8bde3-f688-43cc-b7a2-4eeb62ae1b35.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: publish the Button, Link and Avatar contexts so a styling layer can read the look values the render functions already provide",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-headless-components-preview-53c1f6b8-bdc6-4e94-9a74-9b427f2b39b8.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: apply state.arrowClassName to the Tooltip arrow element, which renderTooltip was dropping",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-headless-components-preview-9b3831cb-664b-4ed6-9ed9-3919af4d5a77.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: let a consumer popover prop win on PopoverSurface by moving the default into the surface slot defaultProps, so more than one Popover can be open per page",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-headless-components-preview-a905c087-3177-47a7-9b13-a6d4ab0981c9.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: merge the popover attribute default before the base state in useMenuPopover and useListbox so a consumer value is no longer overwritten",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-headless-components-preview-aeb7e042-1610-425b-8743-4d45b486f843.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: give MenuSplitGroup a stable contexts value so useIsInMenuSplitGroup resolves true for descendant halves",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-headless-components-preview-cd6ca79d-a43a-46f5-95f7-b37575bc8d25.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: reserve the scrollbar gutter on documentElement when Dialog locks scroll, so opening a modal on a scrolling page no longer shifts fixed and centred content",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-headless-components-preview-d7a700d2-1b2d-4ce6-8079-984826fc7bb3.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: publish the AvatarGroup context reader and provider from the ./avatar-group subpath",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-storybook-addon-export-to-sandbox-ca41b16c-8185-494b-857f-d447cf5769f6.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: match both path separators when detecting the addon registration so the addon options are not silently dropped on Windows",
+  "packageName": "@fluentui/react-storybook-addon-export-to-sandbox",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-tag-picker-0744b931-aca3-460f-a24b-7ad2d12d5ccf.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: cancel the pending TagPickerControl resize frame in the effect cleanup instead of the effect body, which raced away the aside-width custom property",
+  "packageName": "@fluentui/react-tag-picker",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-tailwind-theme-preview-17f09739-cf84-42dd-93ed-6555318201d4.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: add react-tailwind-theme-preview, the Fluent design tokens and themes as a Tailwind v4 CSS layer",
+  "packageName": "@fluentui/react-tailwind-theme-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-windmod-preview-3f5a9c21-8e4d-4b7a-9c0e-52d1a7f0b4e6.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: release preview package",
+  "packageName": "@fluentui/react-windmod-preview",
+  "email": "array.knight@gmail.com",
+  "dependentChangeType": "patch"
+}

jest.preset.js

@@ -26,6 +26,27 @@ const reactDepsPaths = {
   '^react-test-renderer$': path.join(__dirname, 'node_modules/react-test-renderer'),
 };
 
+/**
+ * CSS Modules support (react-windmod-preview / react-tailwind-theme-preview).
+ *
+ * Jest resolves `@fluentui/*` to SOURCE via the tsconfig path aliases above, so any suite
+ * that renders a windmod component evaluates `import styles from './X.module.css'`.
+ * Without a mapper those suites fail to *run*, so the mapper is repo-wide rather than
+ * per-package (it only matches `*.module.css`, which no Griffel package imports).
+ *
+ * Resolved by path (not via `require('@fluentui/scripts-jest')`) to keep this file free
+ * of workspace requires: scripts/jest pulls in @fluentui/scripts-monorepo, which walks
+ * the repo on load.
+ *
+ * Caveat: Jest MERGES `moduleNameMapper` from a preset, but a project-level
+ * `snapshotSerializers` REPLACES the preset's array — packages that declare their own
+ * serializers AND consume windmod classes must list the css-modules serializer themselves.
+ */
+const cssModulesJest = {
+  moduleNameMapperTarget: require.resolve('./scripts/jest/src/css-modules/proxy.js'),
+  snapshotSerializer: require.resolve('./scripts/jest/src/css-modules/serializer.js'),
+};
+
 /**
  * @type {import('@jest/types').Config.InitialOptions}
  */
@@ -37,7 +58,12 @@ const baseConfig = {
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
   testPathIgnorePatterns: ['/node_modules/', '/lib/', '/lib-commonjs/', '/dist/'],
   testEnvironment: 'jsdom',
-  moduleNameMapper: { ...tsPathAliases, ...reactDepsPaths },
+  moduleNameMapper: {
+    ...tsPathAliases,
+    ...reactDepsPaths,
+    '\\.module\\.css$': cssModulesJest.moduleNameMapperTarget,
+  },
+  snapshotSerializers: [cssModulesJest.snapshotSerializer],
   cacheDirectory: '<rootDir>/node_modules/.cache/jest',
   clearMocks: true,
   watchPlugins: ['jest-watch-typeahead/filename', 'jest-watch-typeahead/testname'],

package.json

@@ -94,6 +94,7 @@
     "@oddbird/css-anchor-positioning": "0.4.0",
     "@phenomnomnominal/tsquery": "6.1.3",
     "@playwright/test": "1.56.1",
+    "@prettier/sync": "0.6.1",
     "@react-native/babel-preset": "0.73.21",
     "@rnx-kit/eslint-plugin": "0.8.6",
     "@rollup/plugin-node-resolve": "13.3.0",
@@ -107,6 +108,7 @@
     "@swc/core": "1.11.24",
     "@swc/helpers": "0.5.1",
     "@swc/jest": "0.2.38",
+    "@tailwindcss/postcss": "^4.3.2",
     "@testing-library/dom": "10.4.0",
     "@testing-library/jest-dom": "5.16.5",
     "@testing-library/react": "16.3.0",
@@ -144,7 +146,6 @@
     "@types/markdown-table": "2.0.0",
     "@types/micromatch": "4.0.2",
     "@types/node": "^22.0.0",
-    "@types/prettier": "2.7.2",
     "@types/progress": "2.0.5",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",
@@ -182,6 +183,7 @@
     "circular-dependency-plugin": "5.2.2",
     "clean-css": "4.2.3",
     "clean-webpack-plugin": "4.0.0",
+    "clsx": "2.1.1",
     "connect-history-api-fallback": "1.6.0",
     "copy-webpack-plugin": "12.0.2",
     "cross-env": "^5.1.4",
@@ -267,7 +269,8 @@
     "postcss": "8.5.18",
     "postcss-loader": "4.1.0",
     "postcss-modules": "4.1.3",
-    "prettier": "2.8.8",
+    "prettier": "3.9.6",
+    "prettier-plugin-tailwindcss": "0.8.1",
     "progress": "2.0.3",
     "puppeteer": "24.42.0",
     "raw-loader": "4.0.2",
@@ -304,6 +307,7 @@
     "swc-loader": "0.2.6",
     "swc-plugin-de-indent-template-literal": "1.5.0",
     "syncpack": "10.6.1",
+    "tailwindcss": "^4.3.2",
     "terser": "5.39.1",
     "terser-webpack-plugin": "5.3.10",
     "through2": "4.0.2",
@@ -360,6 +364,7 @@
     }
   },
   "resolutions": {
+    "@fluentui/react-icons": "file:../fluentui-system-icons/packages/react-icons/fluentui-react-icons-local.tgz",
     "@nx/devkit/minimatch": "^9.0.7",
     "@nx/jest/minimatch": "^9.0.7",
     "@phenomnomnominal/tsquery": "6.1.3",
@@ -377,7 +382,6 @@
     "micromatch/braces": "^3.0.3",
     "nx/minimatch": "^9.0.7",
     "playwright": "1.56.1",
-    "prettier": "2.8.8",
     "prismjs": "1.30.0",
     "puppeteer": "24.42.0",
     "shell-quote": "^1.8.2",

packages/react-components/babel-preset-storybook-full-source/package.json

@@ -11,9 +11,10 @@
   "license": "MIT",
   "dependencies": {
     "@babel/core": "^7.10.4",
+    "@prettier/sync": "^0.6.1",
     "@swc/helpers": "^0.5.1",
     "pkg-up": "^3.1.0",
-    "prettier": "^2.8.8"
+    "prettier": "^3.0.0"
   },
   "exports": {
     ".": {

packages/react-components/babel-preset-storybook-full-source/src/fullsource.ts

@@ -1,5 +1,7 @@
 import * as Babel from '@babel/core';
-import * as prettier from 'prettier';
+// Babel visitors are synchronous, but prettier 3's `format` is async — use the official
+// synchronous wrapper (runs prettier in a worker thread under the hood).
+import * as prettier from '@prettier/sync';
 import * as fs from 'fs';
 import * as nodePath from 'path';
 

packages/react-components/babel-preset-storybook-full-source/src/modifyImports.ts

@@ -29,10 +29,13 @@ export function modifyImportsPlugin(babel: typeof Babel, options: BabelPluginOpt
       parserOptions.plugins.push('typescript');
     },
     pre() {
-      this.imports = Object.keys(importMappings).reduce((acc, cur) => {
-        acc[importMappings[cur].replace] = [];
-        return acc;
-      }, {} as PluginState['imports']);
+      this.imports = Object.keys(importMappings).reduce(
+        (acc, cur) => {
+          acc[importMappings[cur].replace] = [];
+          return acc;
+        },
+        {} as PluginState['imports'],
+      );
     },
     visitor: {
       Program: {