microsoft · Ray Knight (ArrayKnight) · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
@@ -63,13 +63,15 @@ Required if any published package source code changed (not just tests/stories/do
 
 Only for files in `packages/react-components/react-*/library/src/`:
 
-| Check               | Look for                                                                                            | Severity |
-| ------------------- | --------------------------------------------------------------------------------------------------- | -------- |
-| No `React.FC`       | `React.FC`, `: FC<`, `React.FunctionComponent` in added lines                                       | BLOCKER  |
-| No hardcoded styles | Hex colors `#[0-9a-fA-F]{3,8}`, hardcoded `px` values for spacing/radius/font in `.styles.ts` files | WARNING  |
-| Griffel usage       | Style files must use `makeStyles` from `@griffel/react`, not inline styles                          | WARNING  |
-| mergeClasses order  | User `className` must be the LAST argument in `mergeClasses()`                                      | WARNING  |
-| Slot system         | New components must use `slot.always`/`slot.optional` and `assertSlots`                             | WARNING  |
+| Check               | Look for                                                                                                                                                  | Severity |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| No `React.FC`       | `React.FC`, `: FC<`, `React.FunctionComponent` in added lines                                                                                             | BLOCKER  |
+| No hardcoded styles | Hex colors `#[0-9a-fA-F]{3,8}`, hardcoded `px` values for spacing/radius/font in `.module.css` files                                                      | WARNING  |
+| CSS Modules usage   | Styles must live in a co-located `*.module.css`, not in `makeStyles`/`makeResetStyles` or inline styles                                                   | WARNING  |
+| Layer discipline    | Library modules author into `fui.components.l1` (or `l2` when styling another component's output); `l3`–`l5` are consumer space and must stay empty       | WARNING  |
+| clsx order          | User `className` must be the LAST argument to `clsx()`; the unconditional module class must be first, so the `group/fui-*` marker is never `classList[0]` | WARNING  |
+| No state mutation   | Styles hooks must return a new state object, not assign to `state.<slot>.className`                                                                       | WARNING  |
+| Slot system         | New components must use `slot.always`/`slot.optional` and `assertSlots`                                                                                   | WARNING  |
 
 Reference: [docs/architecture/component-patterns.md](../../../docs/architecture/component-patterns.md)
 
@@ -79,7 +81,8 @@ For changes to `package.json` files or new imports in Tier 3 component packages:
 
 - **BLOCKER** if a Tier 3 package (`react-button`, `react-menu`, etc.) adds a dependency on another Tier 3 package
 - Allowed Tier 2 deps: `react-utilities`, `react-theme`, `react-shared-contexts`, `react-tabster`, `react-positioning`, `react-portal`
-- Allowed Tier 1 deps: `@griffel/react`, `@fluentui/tokens`, `@fluentui/react-jsx-runtime`
+- Allowed Tier 1 deps: `@fluentui/tokens`, `@fluentui/react-jsx-runtime`, `clsx`, and
+  `@fluentui/react-tailwind-theme` as a **devDependency** only (build-time `#theme` alias)
 
 Reference: [docs/architecture/layers.md](../../../docs/architecture/layers.md)
 

@@ -110,7 +110,7 @@ For each issue, read the title + body + existing labels. If repro evidence is am
 - `packages/react-components/react-field/` — label/description/validation composition (if the ask is form-control adornments)
 - The component's stories for worked examples of the composition pattern
 
-v9 defaults to composition over configuration. An ask like "add a `shouldFadeIn` prop" usually has an answer like "compose with `<Fade>`" or "use `onLoad` + `makeStyles` keyframes". Surface the v9 pattern in the comment so the reporter isn't left hanging.
+v9 defaults to composition over configuration. An ask like "add a `shouldFadeIn` prop" usually has an answer like "compose with `<Fade>`" or "use `onLoad` plus a `@keyframes` rule in your own stylesheet". Surface the v9 pattern in the comment so the reporter isn't left hanging.
 
 When checking for duplicates, search first:
 

@@ -41,11 +41,27 @@ yarn nx g @fluentui/workspace-plugin:react-component --name $ARGUMENTS --project
 
 1. **Review generated files** against [docs/architecture/component-patterns.md](../../../docs/architecture/component-patterns.md) and fill in component-specific logic.
 
-2. **Add styles** in `use${ARGUMENTS}Styles.styles.ts` using design tokens:
+2. **Add styles** in a co-located `${ARGUMENTS}.module.css`, using token custom properties:
+
+   ```css
+   @reference '#theme';
+
+   @layer fui.theme, fui.base, fui.components, fui.components.l1, fui.components.l2, fui.components.l3, fui.components.l4, fui.components.l5, fui.utilities;
+
+   @layer fui.components.l1 {
+     .root {
+       @apply flex items-center;
+
+       color: var(--colorNeutralForeground1);
+     }
+   }
+   ```
+
+   Then compose the class names in `use${ARGUMENTS}Styles.styles.ts`:
 
    ```tsx
-   import { makeStyles } from '@griffel/react';
-   import { tokens } from '@fluentui/react-theme';
+   import { clsx } from 'clsx';
+   import styles from './${ARGUMENTS}.module.css';
    ```
 
 3. **Create a default story** at the appropriate stories package location if not generated.
@@ -58,8 +74,11 @@ yarn nx g @fluentui/workspace-plugin:react-component --name $ARGUMENTS --project
 ## Critical Rules
 
 - Always use `ForwardRefComponent` with `React.forwardRef` — never `React.FC`
-- Always use design tokens from `@fluentui/react-theme` — never hardcoded colors/spacing/typography
-- Always preserve user `className` as the LAST argument in `mergeClasses()`
+- Always use design tokens — `var(--colorNeutralForeground1)` in CSS, the `tokens` object from
+  `@fluentui/react-theme` in TS — never hardcoded colors/spacing/typography
+- Always preserve user `className` as the LAST argument to `clsx()` (convention; the cascade layer,
+  not the argument position, decides which rule wins)
+- Styles hooks must **return** the composed state, never mutate the state they are handed
 - Use `_unstable` suffix on exported hooks: `use$ARGUMENTS_unstable`, `use${ARGUMENTS}Styles_unstable`, `render${ARGUMENTS}_unstable`
 - Guard any `window`/`document`/`navigator` access with `canUseDOM()` from `@fluentui/react-utilities`
 - Do not add dependencies on other Tier 3 component packages (see [docs/architecture/layers.md](../../../docs/architecture/layers.md))

@@ -43,13 +43,19 @@ steps:
     env:
       DANGER_GITHUB_API_TOKEN: $(DANGER_GITHUB_API_TOKEN)
 
+  # `verify-tokens-css` exists on exactly one project (@fluentui/react-tailwind-theme). It asserts
+  # the checked-in css/tokens.css AND css/themes.css still match what the generator produces from
+  # @fluentui/tokens (tokens.ts + theme-values.json), so a token added or renamed upstream — or a
+  # theme value changed without regenerating — cannot silently leave the Tailwind theme layer stale.
+  # `verify-theme-values` (@fluentui/tokens) asserts the committed theme-values.json snapshot matches
+  # the built theme objects, closing the loop from the values side (theming Phase 2b).
   - script: |
-      yarn nx affected -t build test lint type-check test-ssr test-integration verify-packaging --nxBail $(sinceArg)
+      yarn nx affected -t build test lint type-check test-ssr test-integration verify-packaging verify-tokens-css verify-theme-values --nxBail $(sinceArg)
     displayName: build, test, lint, test-ssr (affected)
     condition: eq(variables.isPR, true)
 
   - script: |
-      yarn nx run-many -t build test lint type-check test-ssr test-integration verify-packaging --nxBail
+      yarn nx run-many -t build test lint type-check test-ssr test-integration verify-packaging verify-tokens-css verify-theme-values --nxBail
     displayName: build, test, lint, test-ssr (all)
     condition: eq(variables.isPR, false)
 

@@ -153,7 +153,7 @@ packages/react-components/react-aria @microsoft/teams-prg
 packages/react-components/react-aria/library @microsoft/teams-prg
 packages/react-components/react-aria/stories @microsoft/teams-prg
 packages/react-cards @microsoft/cxe-red @khmakoto
-packages/react-components/react-conformance-griffel @microsoft/teams-prg
+packages/react-components/deprecated/react-conformance-griffel @microsoft/teams-prg
 packages/react-components/react-context-selector @microsoft/teams-prg
 packages/react-date-time @microsoft/cxe-red
 packages/react-docsite-components @microsoft/fluentui-v8-website

@@ -24,7 +24,7 @@ This is a large Nx monorepo with the following key characteristics:
 
    - Location: `packages/react-components/`
    - Nx Project Tags: `vNext`
-   - Features: Current stable version, actively developed. Tree-shakeable, atomic CSS classes
+   - Features: Current stable version, actively developed. Tree-shakeable, precompiled CSS shipped as `dist/styles.css` per package
 
 2. **Fluent UI v8** (`@fluentui/react`) - **MAINTENANCE ONLY**
 
@@ -145,7 +145,8 @@ packages/react-components/react-component-name/
 │   │   ├── index.ts                            # Local exports
 │   │   ├── renderComponentName.tsx             # JSX rendering
 │   │   ├── useComponentName.ts                 # State management
-│   │   └── useComponentNameStyles.styles.ts    # Griffel styling
+│   │   ├── ComponentName.module.css            # Authored styles (CSS Module)
+│   │   └── useComponentNameStyles.styles.ts    # Class composition (clsx)
 │   ├── testing/                                # Test utilities
 │   └── utils                                   # Reusable utils (if needed)
 └── stories/src/                                # Storybook documentation
@@ -164,7 +165,8 @@ react-component-name/
 │   │   ├── ComponentName.tsx                   # Main component export
 │   │   ├── ComponentName.types.ts              # Props, State, Slots types
 │   │   ├── useComponentName.ts                 # State management hook
-│   │   ├── useComponentNameStyles.styles.ts    # Griffel styling
+│   │   ├── ComponentName.module.css            # Authored styles (CSS Module)
+│   │   ├── useComponentNameStyles.styles.ts    # Class composition (clsx)
 │   │   └── renderComponentName.tsx             # JSX rendering logic
 │   └── index.ts                                # Package exports
 └── stories/                                    # Storybook stories
@@ -175,7 +177,7 @@ react-component-name/
 Components use three core hooks:
 
 1. **`useComponent_unstable()`** - Processes props, slots and main component logic into normalized state
-2. **`useComponentStyles_unstable()`** - Creates Griffel CSS-in-JS styling
+2. **`useComponentStyles_unstable()`** - Composes the CSS-Module class names onto the state and returns the new state (never mutates it)
 3. **`renderComponent_unstable()`** - Pure JSX rendering from state
 
 ### Slot System
@@ -207,54 +209,81 @@ export const renderButton_unstable = (state: ButtonState) => {
 };
 ```
 
-### Build-Time CSS-in-JS with Atomic Classes
+### Precompiled CSS with Tailwind-flavored CSS Modules
 
-**Critical**: v9 uses Griffel for compile-time CSS generation - styles are extracted into atomic CSS classes at build time, not runtime:
+**Critical**: v9 authors styles as plain CSS in a co-located `*.module.css`, compiled at build time
+into the package's `dist/styles.css`. There is no runtime style engine and no atomic-class merge
+step — every conflict is settled by the CSS cascade, using one `@layer` family:
+
+```css
+/* Button.module.css */
+@reference '#theme';
+
+/* `@reference` emits nothing, so the layer order has to be restated in every module —
+   otherwise first-appearance order would decide the ranking. Restating it is a no-op. */
+@layer fui.theme, fui.base, fui.components, fui.components.l1, fui.components.l2, fui.components.l3, fui.components.l4, fui.components.l5, fui.utilities;
+
+@layer fui.components.l1 {
+  .root {
+    @apply inline-flex items-center;
+
+    /* Use token custom properties, not hardcoded values */
+    color: var(--colorNeutralForeground1);
+    background-color: var(--colorNeutralBackground1);
+    padding: var(--spacingVerticalS) var(--spacingHorizontalM);
+  }
+
+  .root:hover {
+    background-color: var(--colorNeutralBackground1Hover);
+  }
+
+  /* Size variations */
+  .small {
+    padding: var(--spacingVerticalXS);
+  }
+
+  .large {
+    padding: var(--spacingVerticalL);
+  }
+}
+```
 
 ```tsx
 // useButtonStyles.styles.ts
-import { makeStyles } from '@griffel/react';
-import { tokens } from '@fluentui/react-theme';
+import { clsx } from 'clsx';
+import styles from './Button.module.css';
 
-export const useButtonStyles = makeStyles({
+/** The component's public identity class — a named group marker, not a BEM static. */
+export const buttonClassNames: { root: string } = {
+  root: 'group/fui-button',
+};
+
+export const useButtonStyles_unstable = (state: ButtonState): ButtonState => ({
+  ...state,
   root: {
-    // Use design tokens, not hardcoded values
-    color: tokens.colorNeutralForeground1,
-    backgroundColor: tokens.colorNeutralBackground1,
-    padding: `${tokens.spacingVerticalS} ${tokens.spacingHorizontalM}`,
-
-    // Pseudo-selectors and media queries supported
-    ':hover': {
-      backgroundColor: tokens.colorNeutralBackground1Hover,
-    },
-
-    ':focus-visible': {
-      outline: `${tokens.strokeWidthThick} solid ${tokens.colorStrokeFocus2}`,
-    },
+    ...state.root,
+    className: clsx(
+      // Unconditional module class first: the `group/fui-*` marker must never be classList[0].
+      styles.root,
+      'group/fui-button',
+      state.size === 'small' && styles.small,
+      state.size === 'large' && styles.large,
+      // Always preserve the user's className, last by convention.
+      state.root.className,
+    ),
   },
-
-  // Size variations
-  small: { padding: tokens.spacingVerticalXS },
-  large: { padding: tokens.spacingVerticalL },
 });
+```
 
-// Apply in component hook
-export const useButton_unstable = (props, ref) => {
-  const classes = useButtonStyles();
-  const state = {
-    /* ... */
-  };
-
-  state.root.className = mergeClasses(
-    classes.root,
-    props.size === 'small' && classes.small,
-    props.size === 'large' && classes.large,
-    state.root.className, // Always preserve user className
-  );
+Three rules follow from the cascade-first model:
 
-  return state;
-};
-```
+1. **`clsx` argument order carries no cascade meaning.** It is a plain string join. Which rule wins
+   is decided by layer, then specificity, then source order — record intended winners in the
+   module's layer assignment.
+2. **Styles hooks return state, they do not mutate it** (`react-hooks/immutability` enforces this).
+   Call sites rebind: `state = useButtonStyles_unstable(state);`.
+3. **Library modules author into `fui.components.l1`**, or `l2` when deliberately styling another
+   component's output. `l3`–`l5` are consumer space; unlayered consumer CSS beats all of it.
 
 ### Design Tokens System
 
@@ -274,22 +303,30 @@ borderRadius: '4px';
 
 ### Theme Architecture
 
-Themes define CSS custom properties consumed by components:
+Themes define CSS custom properties consumed by components. They ship as static CSS classes in
+`@fluentui/react-tailwind-theme` (import `@fluentui/react-tailwind-theme/styles.css` once per
+document; web-light values are the `:root` defaults):
 
 ```tsx
-// FluentProvider injects CSS variables into DOM
-<FluentProvider theme={webLightTheme}>
+// FluentProvider applies a static theme class (and propagates it to portals)
+<FluentProvider themeClassName={webLightThemeClassName}>
   <App />
-</FluentProvider>;
+</FluentProvider>
+```
 
-// Components reference tokens which resolve to CSS variables
-makeStyles({
-  root: {
-    color: tokens.colorNeutralForeground1, // becomes 'var(--colorNeutralForeground1)'
-  },
-});
+Components reference the custom properties directly in their `*.module.css`:
+
+```css
+@layer fui.components.l1 {
+  .root {
+    color: var(--color-neutral-foreground-1);
+  }
+}
 ```
 
+From TypeScript, use the `tokens` object — it maps each token name to the same reference
+(`tokens.colorNeutralForeground1 === 'var(--color-neutral-foreground-1)'`).
+
 ### TypeScript Patterns (v9)
 
 **Strict typing with consistent interfaces:**
@@ -345,7 +382,7 @@ export const Component: ForwardRefComponent<ComponentProps> = React.forwardRef((
 - Comprehensive prop interfaces with JSDoc comments
 - Consistent naming conventions (PascalCase for components, camelCase for props)
 - Use React hooks and modern patterns for v9 components
-- Focus on the slot system, Griffel styling, and hook-based architecture for v9
+- Focus on the slot system, CSS-Modules styling with the `@layer fui.*` family, and hook-based architecture for v9
 
 ### Testing Requirements
 

@@ -15,3 +15,8 @@ plop-templates-_
 
 ; TODO: temporary ignore - remove once https://github.com/microsoft/fluentui/pull/32371 is merged
 scripts/\*/just.config.ts
+
+; local scratch workspace (gitignored) — contains copies of the repo tree from measurement
+; runs; without this nx discovers them as duplicate projects and the project graph fails to build
+.scratch
+**/.scratch/**
@@ -1,5 +1,9 @@
 # generated or imported files
 package-deps.json
+# generated theme CSS — byte-exact against packages/tokens values (generator --check);
+# prettier would rewrite value bytes (rgba spacing, trailing zeros, line wraps)
+packages/react-components/react-tailwind-theme/css/tokens.css
+packages/react-components/react-tailwind-theme/css/themes.css
 CHANGELOG.*
 # generated from `web-features` via `yarn generate-browser-support`
 **/browser-support-data.generated.json

@@ -47,11 +47,29 @@ module.exports = /** @type {import('./types').StorybookConfig} */ ({
           test: /\.stories\.tsx$/,
           include: /stories/,
         },
+        /**
+         * Converted packages import `*.module.css`; without this the sandbox export drops
+         * those imports and every exported story opens unstyled. The addon side has supported
+         * this since the CSS-modules work landed — only the option was never passed.
+         */
+        cssModules: true,
       },
     }),
   ],
   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.
+     *
+     * Every converted package's `*.module.css` opens with `@reference '#theme'` and uses
+     * `@apply`, which are not valid CSS until Tailwind's PostCSS pass has run. Without this
+     * wiring this storybook — and the ~76 package storybooks and the public docsite that
+     * compose it — render every converted package 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) {