Fluent 2 Design System (Fluent UI React v9)
This skill defines the authoritative architecture, styling rules, component patterns, and accessibility standards for Microsoft's Fluent 2 Design System (fluent2.microsoft.design) and Fluent UI React v9 (@fluentui/react-components).
CRITICAL RULE: Always target Fluent UI React v9 (
@fluentui/react-components) and Griffel (makeStyles,mergeClasses,shorthands). Never introduce legacy v8 (@fluentui/react/ Office UI Fabric) imports,stylesprop objects, or hardcoded hex/pixel values when a Fluent 2 design token exists.
Fluent 2 Core Design Principles (fluent2.microsoft.design/design-principles)
Every UI decision must embody the four official Fluent 2 pillars:
- Natural on every platform: Adapt fluidly to the target environment (Web, Windows, macOS) using familiar conventions while maintaining cohesive token foundations.
- Built for focus: Keep interfaces calm, clean, and purposeful. Rely on proximity, surface layering (
Background3->Background2->Background1), and whitespace (4px grid) rather than excessive divider lines or visual clutter. - One for all, all for one: Ground every interaction in Inclusive Design — WCAG 2.1 AA contrast, full keyboard operability, and High-Contrast (
forced-colors) resilience. - Unmistakably Microsoft: Craft trustworthy, responsive experiences through Segoe UI Variable typography, subtle elevation (
shadow2..shadow64), physics-grounded motion (curveDecelerate*/curveAccelerate*), and crispRegular->Filledicon state transitions.
Progressive Disclosure & Reference Map
To keep context focused, read only the reference file(s) relevant to your immediate task:
| Task / Domain | Reference File | When to Read |
|---|---|---|
| Tokens & Theming | design-tokens.md | Choosing semantic colors (colorNeutral*, colorBrand*), typography (typographyStyles), spacing (spacingHorizontal*/Vertical*), elevation (shadow*), corners (borderRadius*), motion (duration*/curve*), or configuring FluentProvider for Light, Dark, and High-Contrast modes. |
| Griffel Styling | griffel-styling.md | Writing or refactoring makeStyles, makeResetStyles, mergeClasses, and shorthands. Resolving CSS shorthand conflicts, specificity bugs, pseudo-selectors, media queries, or replacing inline styles/CSS files. |
| Components & Patterns | components-and-patterns.md | Selecting and composing v9 components (Button, Card, Dialog, Drawer, DataGrid/Table, TabList, Toolbar, Menu, Popover, Toast/Toaster, Field/Input/Combobox, MessageBar), layout hierarchy, density, or desktop chrome (Tauri/Electron). |
| Icons & Assets | icons-and-assets.md | Using @fluentui/react-icons: Regular vs Filled states, bundleIcon, standard sizes (16/20/24/28/48), and mandatory per-icon named imports for bundler tree-shaking. |
| A11y & Anti-Patterns | accessibility-and-anti-patterns.md | Auditing WCAG AA contrast, custom focus rings (createFocusOutlineStyle), keyboard navigation (Tab/Arrow/Esc), icon-only aria-label rules, or checking the pre-delivery checklist and anti-pattern catalog. |
Core Non-Negotiables (Quick Checklist)
-
Wrap Root in
<FluentProvider theme={...}>- Every Fluent 2 tree must sit inside a
FluentProvider(e.g.,webLightTheme,webDarkTheme,teamsLightTheme,teamsDarkTheme,teamsHighContrastTheme, or custom brand themes built viacreateLightTheme(brandVariants)/createDarkTheme(brandVariants)). - Never hardcode light-only colors; rely on
tokens.*CSS custom properties injected byFluentProvider.
- Every Fluent 2 tree must sit inside a
-
Use Semantic Design Tokens (
tokens.*), Never Raw Values- Import
tokensandtypographyStylesfrom@fluentui/react-components. - Use surface hierarchy (
colorNeutralBackground1->Background2->Background3), semantic foregrounds (colorNeutralForeground1..4), and strokes (colorNeutralStroke1..2). - Spread
...typographyStyles.body1,subtitle1,title2, etc., instead of ad-hocfontSize/lineHeightpairs.
- Import
-
Idiomatic Griffel (
makeStyles+mergeClasses)- Define static styles at module scope with
makeStyles({ ... }). - Combine class names exclusively with
mergeClasses(styles.base, isActive && styles.active, className)— never string concatenation (${styles.a} ${styles.b}) orclsx/classnames(Griffel requires atomic property deduplication viamergeClasses). - Prefer longhand properties (
paddingTop,borderRadius,borderTopWidth) orshorthands.*helpers to avoid Griffel CSS shorthand collision bugs.
- Define static styles at module scope with
-
Strict Component & Form Composition
- Always wrap form controls (
Input,Combobox,Dropdown,Select,Textarea,Switch,Checkbox,RadioGroup) inside<Field label="..." validationMessage="..." validationState="...">for automatic accessibility wiring (id,aria-labelledby,aria-describedby,aria-invalid). - Use
Dialog->DialogTrigger->DialogSurface->DialogBody->DialogTitle+DialogContent+DialogActions. - Use
Toast+Toaster+useToastControllerfor transient notifications, andMessageBarfor persistent inline status alerts.
- Always wrap form controls (
-
Tree-Shakeable Icon Imports & State Pairing
- Import individual icons directly (
import { HomeRegular, HomeFilled, bundleIcon } from '@fluentui/react-icons'). Never useimport * as Icons. - Use
Regularicons for default/resting states andFilledicons (viabundleIcon(Filled, Regular)) for active/selected/hovered navigation states.
- Import individual icons directly (
-
Built-In Accessibility First
- Every icon-only
ButtonorToolbarButtonmust have an explicitaria-label(and ideally a<Tooltip content="..." relationship="label">). - Custom interactive elements must use
createFocusOutlineStyle()so keyboard focus indicators adapt automatically across Light, Dark, and High-Contrast themes.
- Every icon-only
Standard Workflow for Agent Tasks
- Inspect Existing Setup: Check
package.jsonfor@fluentui/react-componentsand@fluentui/react-iconsversions, and locate the rootFluentProviderand theme definition. - Consult Targeted References: Read the relevant files in
./references/before writing or refactoring code. - Implement with Tokens & Griffel: Build components using v9 slots,
tokens,typographyStyles, andmakeStyles+mergeClasses. - Verify Quality: Cross-check your implementation against accessibility-and-anti-patterns.md before finalizing.