Fluent 2 Design System
Build production-grade interfaces using Microsoft's Fluent 2 design system with @fluentui/react-components (v9).
Quick Start
Every Fluent 2 React app requires a FluentProvider wrapping the component tree with a theme:
import {
FluentProvider,
webLightTheme,
webDarkTheme,
Button,
tokens,
makeStyles,
mergeClasses,
} from "@fluentui/react-components";
export default function App() {
return (
<FluentProvider theme={webLightTheme}>
<Button appearance="primary">Hello Fluent 2</Button>
</FluentProvider>
);
}
Install: npm install @fluentui/react-components
Core Architecture
Theming
- Built-in themes:
webLightTheme, webDarkTheme, teamsLightTheme, teamsDarkTheme, teamsHighContrastTheme
- Custom branding: Use
createLightTheme(brandRamp) / createDarkTheme(brandRamp) with a BrandVariants object (keys 10–160)
- Nesting:
FluentProvider can nest for sub-trees with different themes
- Theme values are emitted as CSS custom properties on the provider element
Styling with Griffel
Use makeStyles (from @fluentui/react-components) — never inline styles or external CSS for token-aware styling.
const useStyles = makeStyles({
root: {
backgroundColor: tokens.colorNeutralBackground1,
color: tokens.colorNeutralForeground1,
display: "flex",
gap: tokens.spacingHorizontalM,
padding: tokens.spacingVerticalM,
},
active: {
backgroundColor: tokens.colorBrandBackground,
color: tokens.colorNeutralForegroundOnBrand,
},
});
function MyComponent({ isActive }) {
const styles = useStyles();
return (
<div className={mergeClasses(styles.root, isActive && styles.active)}>
Content
</div>
);
}
Critical rules:
- Define
makeStyles outside components (module scope)
- Use
mergeClasses() to compose classes — never concatenate strings
- Use
tokens.* for all colors, spacing, typography, radii, shadows — never hardcode hex/px values
- CSS shorthands (
border, borderRadius, padding, etc.) are not supported — use shorthands.* helper or longhand properties
- Pseudo-selectors use nested objects:
":hover": { color: tokens.colorBrandForeground1 }
- Media queries use nested objects:
"@media (min-width: 768px)": { flexDirection: "row" }
Component Model
All v9 components follow a consistent pattern:
- Slots: Named sub-parts (e.g.,
root, icon, content) that accept props or JSX
- Appearance variants:
"primary", "secondary", "subtle", "transparent", "outline"
- Size variants:
"small", "medium", "large"
- Shape variants:
"rounded", "circular", "square"
Override component styles via className with makeStyles/mergeClasses.
Design Tokens
Tokens are the bridge between design intent and code. Always use tokens.* — never raw values.
For complete token reference tables (color, typography, spacing, elevation, stroke, corner radius), see references/tokens.md.
Token Categories at a Glance
| Category |
Prefix |
Example |
| Neutral colors |
colorNeutral* |
tokens.colorNeutralBackground1 |
| Brand colors |
colorBrand* |
tokens.colorBrandBackground |
| Status colors |
colorPalette{Color}* |
tokens.colorPaletteRedForeground1 |
| Typography |
fontFamily*, fontSize*, fontWeight*, lineHeight* |
tokens.fontSizeBase300 |
| Spacing |
spacingHorizontal*, spacingVertical* |
tokens.spacingHorizontalM |
| Border radius |
borderRadius* |
tokens.borderRadiusMedium |
| Stroke width |
strokeWidth* |
tokens.strokeWidthThin |
| Shadow |
shadow* |
tokens.shadow4 |
| Duration |
duration* |
tokens.durationNormal |
| Easing |
curve* |
tokens.curveEasyEase |
Two-Layer Token System
- Global tokens — context-agnostic raw values (e.g.,
colorBlue60, fontSize300)
- Alias tokens — semantic meaning applied to globals (e.g.,
colorBrandBackground → blue, colorNeutralForeground1 → dark gray)
In code, consume alias tokens via the tokens object.
Layout
- Grid: Use CSS Grid/Flexbox — Fluent 2 v9 has no
Stack component
- Spacing scale: 4px base unit. Values:
XXS(2), XS(4), S(8), M(12), L(16), XL(20), XXL(24), XXXL(32)
- Column grid: 12-column framework recommended for web; use CSS grid
- Alignment: Use
tokens.spacingHorizontal* and tokens.spacingVertical* for consistent spacing
Typography
- Primary typeface: Segoe UI (web), Segoe UI Variable (Windows), SF Pro (macOS/iOS), Roboto (Android)
- Font stack:
tokens.fontFamilyBase = Segoe UI → system fallbacks → sans-serif
- Monospace:
tokens.fontFamilyMonospace
- Text presets: Use
<Text> component with preset variants — Caption1, Body1, Body1Strong, Subtitle1, Subtitle2, Title1, Title2, Title3, LargeTitle, Display
- Alignment: Left-align for LTR; Fluent handles RTL automatically via Griffel
Color System
Three palettes:
- Neutral — blacks, whites, grays for surfaces, text, layout
- Brand — accent colors reinforcing identity (default Microsoft brand = blue)
- Shared/Status — cross-product colors: red (danger), green (success), yellow (warning), blue (informational)
Interaction states: rest → hover (darker) → pressed (darkest). Focus adds a thicker stroke, not a color change.
Accessibility
- All components include ARIA roles, keyboard navigation (via Tabster), and focus management
- High contrast: use
teamsHighContrastTheme or handle @media (forced-colors: active) with system colors (ButtonText, Highlight, etc.)
- Focus indicators are visible by default — never remove them
- Ensure WCAG contrast via semantic token pairing (e.g.,
colorNeutralForeground1 on colorNeutralBackground1)
Component Inventory
For the full categorized component list with usage notes, see references/components.md.
Most-Used Components
Actions: Button, CompoundButton, SplitButton, ToggleButton, MenuButton, Link
Inputs: Input, Textarea, Select, Combobox, Dropdown, Checkbox, RadioGroup, Switch, Slider, SpinButton, DatePicker, TimePicker
Layout: Card, Divider, Drawer, Dialog, Popover, Tooltip
Data Display: Table, DataGrid, Tree, Accordion, Badge, Avatar, AvatarGroup, Tag, Persona
Navigation: TabList, Breadcrumb, Nav (preview)
Feedback: Toast, MessageBar, ProgressBar, Spinner, Skeleton
Surfaces: Menu, Toolbar, Overflow
Common Patterns
App Shell Layout
const useStyles = makeStyles({
app: {
backgroundColor: tokens.colorNeutralBackground1,
display: "grid",
gridTemplateColumns: "1fr",
gridTemplateRows: "auto 1fr auto",
height: "100vh",
width: "100%",
},
header: {
borderBottom: `${tokens.strokeWidthThin} solid ${tokens.colorNeutralStroke1}`,
paddingTop: tokens.spacingVerticalS,
paddingBottom: tokens.spacingVerticalS,
paddingLeft: tokens.spacingHorizontalM,
paddingRight: tokens.spacingHorizontalM,
},
content: {
display: "grid",
gridTemplateColumns: "280px 1fr",
overflow: "hidden",
},
nav: {
borderRight: `${tokens.strokeWidthThin} solid ${tokens.colorNeutralStroke1}`,
overflowY: "auto",
},
main: {
overflowY: "auto",
paddingLeft: tokens.spacingHorizontalL,
paddingRight: tokens.spacingHorizontalL,
paddingTop: tokens.spacingVerticalL,
paddingBottom: tokens.spacingVerticalL,
},
});
Custom Brand Theme
import { createLightTheme, createDarkTheme } from "@fluentui/react-components";
const myBrand = {
10: "#020305", 20: "#111723", 30: "#16263D",
40: "#193253", 50: "#1B3F6A", 60: "#1B4C82",
70: "#18599B", 80: "#1267B4", 90: "#3174C2",
100: "#4F82C8", 110: "#6790CF", 120: "#7F9ED5",
130: "#96ADDC", 140: "#ADBCE3", 150: "#C4CBE9",
160: "#DBDBF0",
};
const lightTheme = createLightTheme(myBrand);
const darkTheme = createDarkTheme(myBrand);
Dark Mode Toggle
function App() {
const [isDark, setIsDark] = useState(false);
return (
<FluentProvider theme={isDark ? webDarkTheme : webLightTheme}>
<Switch
label="Dark mode"
checked={isDark}
data) => setIsDark(data.checked)}
/>
</FluentProvider>
);
}
Anti-Patterns
- ❌ Hardcoded colors (
color: "#333") — use tokens.colorNeutralForeground1
- ❌ CSS shorthand properties in
makeStyles (border: "1px solid red") — use longhand or shorthands.*
- ❌ String concatenation of classNames — use
mergeClasses()
- ❌ Inline
style props for token-based values — use makeStyles with tokens
- ❌ Importing from
@fluentui/react (v8) in v9 projects — use @fluentui/react-components
- ❌ Using v8
Stack — use CSS Grid or Flexbox
- ❌ Overriding CSS custom properties from the color system directly in CSS — the adaptive color system is JS-driven
- ❌ Removing focus indicators — accessibility requirement
1---
2name: fluent2-design-system
3description: >
4 Build interfaces using Microsoft's Fluent 2 design system via @fluentui/react-components (v9).
5 Use when the user requests UI built with Fluent UI, Fluent 2, Microsoft design language,
6 Teams-style UI, or Office-style interfaces. Covers: React component usage, theming with
7 FluentProvider, styling with makeStyles/tokens/Griffel, design token application, layout
8 patterns, typography, color system, accessibility, dark/light/high-contrast themes, and
9 custom branding. Also triggers for: "make it look like Teams/Outlook/Office", "use Fluent",
10 "Microsoft design system", "@fluentui", or any request to build UI that follows Microsoft's
11 design language. Do NOT use for Fluent UI v8 (@fluentui/react) unless migrating to v9.
12metadata:
13 source: https://skillmd.com/skills/majiayu000/fluent2-design-system
14---
15
16# Fluent 2 Design System
17
18Build production-grade interfaces using Microsoft's Fluent 2 design system with `@fluentui/react-components` (v9).
19
20## Quick Start
21
22Every Fluent 2 React app requires a `FluentProvider` wrapping the component tree with a theme:
23
24```jsx
25import {
26 FluentProvider,
27 webLightTheme,
28 webDarkTheme,
29 Button,
30 tokens,
31 makeStyles,
32 mergeClasses,
33} from "@fluentui/react-components";
34
35export default function App() {
36 return (
37 <FluentProvider theme={webLightTheme}>
38 <Button appearance="primary">Hello Fluent 2</Button>
39 </FluentProvider>
40 );
41}
42```
43
44Install: `npm install @fluentui/react-components`
45
46## Core Architecture
47
48### Theming
49
50- **Built-in themes**: `webLightTheme`, `webDarkTheme`, `teamsLightTheme`, `teamsDarkTheme`, `teamsHighContrastTheme`
51- **Custom branding**: Use `createLightTheme(brandRamp)` / `createDarkTheme(brandRamp)` with a `BrandVariants` object (keys `10`–`160`)
52- **Nesting**: `FluentProvider` can nest for sub-trees with different themes
53- Theme values are emitted as CSS custom properties on the provider element
54
55### Styling with Griffel
56
57Use `makeStyles` (from `@fluentui/react-components`) — never inline styles or external CSS for token-aware styling.
58
59```jsx
60const useStyles = makeStyles({
61 root: {
62 backgroundColor: tokens.colorNeutralBackground1,
63 color: tokens.colorNeutralForeground1,
64 display: "flex",
65 gap: tokens.spacingHorizontalM,
66 padding: tokens.spacingVerticalM,
67 },
68 active: {
69 backgroundColor: tokens.colorBrandBackground,
70 color: tokens.colorNeutralForegroundOnBrand,
71 },
72});
73
74function MyComponent({ isActive }) {
75 const styles = useStyles();
76 return (
77 <div className={mergeClasses(styles.root, isActive && styles.active)}>
78 Content
79 </div>
80 );
81}
82```
83
84**Critical rules**:
85- Define `makeStyles` outside components (module scope)
86- Use `mergeClasses()` to compose classes — never concatenate strings
87- Use `tokens.*` for all colors, spacing, typography, radii, shadows — never hardcode hex/px values
88- CSS shorthands (`border`, `borderRadius`, `padding`, etc.) are **not supported** — use `shorthands.*` helper or longhand properties
89- Pseudo-selectors use nested objects: `":hover": { color: tokens.colorBrandForeground1 }`
90- Media queries use nested objects: `"@media (min-width: 768px)": { flexDirection: "row" }`
91
92### Component Model
93
94All v9 components follow a consistent pattern:
95- **Slots**: Named sub-parts (e.g., `root`, `icon`, `content`) that accept props or JSX
96- **Appearance variants**: `"primary"`, `"secondary"`, `"subtle"`, `"transparent"`, `"outline"`
97- **Size variants**: `"small"`, `"medium"`, `"large"`
98- **Shape variants**: `"rounded"`, `"circular"`, `"square"`
99
100Override component styles via `className` with `makeStyles`/`mergeClasses`.
101
102## Design Tokens
103
104Tokens are the bridge between design intent and code. Always use `tokens.*` — never raw values.
105
106**For complete token reference tables (color, typography, spacing, elevation, stroke, corner radius), see** `references/tokens.md`.
107
108### Token Categories at a Glance
109
110| Category | Prefix | Example |
111|---|---|---|
112| Neutral colors | `colorNeutral*` | `tokens.colorNeutralBackground1` |
113| Brand colors | `colorBrand*` | `tokens.colorBrandBackground` |
114| Status colors | `colorPalette{Color}*` | `tokens.colorPaletteRedForeground1` |
115| Typography | `fontFamily*`, `fontSize*`, `fontWeight*`, `lineHeight*` | `tokens.fontSizeBase300` |
116| Spacing | `spacingHorizontal*`, `spacingVertical*` | `tokens.spacingHorizontalM` |
117| Border radius | `borderRadius*` | `tokens.borderRadiusMedium` |
118| Stroke width | `strokeWidth*` | `tokens.strokeWidthThin` |
119| Shadow | `shadow*` | `tokens.shadow4` |
120| Duration | `duration*` | `tokens.durationNormal` |
121| Easing | `curve*` | `tokens.curveEasyEase` |
122
123### Two-Layer Token System
124
1251. **Global tokens** — context-agnostic raw values (e.g., `colorBlue60`, `fontSize300`)
1262. **Alias tokens** — semantic meaning applied to globals (e.g., `colorBrandBackground` → blue, `colorNeutralForeground1` → dark gray)
127
128In code, consume alias tokens via the `tokens` object.
129
130## Layout
131
132- **Grid**: Use CSS Grid/Flexbox — Fluent 2 v9 has no `Stack` component
133- **Spacing scale**: 4px base unit. Values: `XXS`(2), `XS`(4), `S`(8), `M`(12), `L`(16), `XL`(20), `XXL`(24), `XXXL`(32)
134- **Column grid**: 12-column framework recommended for web; use CSS grid
135- **Alignment**: Use `tokens.spacingHorizontal*` and `tokens.spacingVertical*` for consistent spacing
136
137## Typography
138
139- **Primary typeface**: Segoe UI (web), Segoe UI Variable (Windows), SF Pro (macOS/iOS), Roboto (Android)
140- **Font stack**: `tokens.fontFamilyBase` = Segoe UI → system fallbacks → sans-serif
141- **Monospace**: `tokens.fontFamilyMonospace`
142- **Text presets**: Use `<Text>` component with preset variants — `Caption1`, `Body1`, `Body1Strong`, `Subtitle1`, `Subtitle2`, `Title1`, `Title2`, `Title3`, `LargeTitle`, `Display`
143- **Alignment**: Left-align for LTR; Fluent handles RTL automatically via Griffel
144
145## Color System
146
147Three palettes:
1481. **Neutral** — blacks, whites, grays for surfaces, text, layout
1492. **Brand** — accent colors reinforcing identity (default Microsoft brand = blue)
1503. **Shared/Status** — cross-product colors: red (danger), green (success), yellow (warning), blue (informational)
151
152**Interaction states**: rest → hover (darker) → pressed (darkest). Focus adds a thicker stroke, not a color change.
153
154## Accessibility
155
156- All components include ARIA roles, keyboard navigation (via Tabster), and focus management
157- High contrast: use `teamsHighContrastTheme` or handle `@media (forced-colors: active)` with system colors (`ButtonText`, `Highlight`, etc.)
158- Focus indicators are visible by default — never remove them
159- Ensure WCAG contrast via semantic token pairing (e.g., `colorNeutralForeground1` on `colorNeutralBackground1`)
160
161## Component Inventory
162
163**For the full categorized component list with usage notes, see** `references/components.md`.
164
165### Most-Used Components
166
167**Actions**: Button, CompoundButton, SplitButton, ToggleButton, MenuButton, Link
168**Inputs**: Input, Textarea, Select, Combobox, Dropdown, Checkbox, RadioGroup, Switch, Slider, SpinButton, DatePicker, TimePicker
169**Layout**: Card, Divider, Drawer, Dialog, Popover, Tooltip
170**Data Display**: Table, DataGrid, Tree, Accordion, Badge, Avatar, AvatarGroup, Tag, Persona
171**Navigation**: TabList, Breadcrumb, Nav (preview)
172**Feedback**: Toast, MessageBar, ProgressBar, Spinner, Skeleton
173**Surfaces**: Menu, Toolbar, Overflow
174
175## Common Patterns
176
177### App Shell Layout
178
179```jsx
180const useStyles = makeStyles({
181 app: {
182 backgroundColor: tokens.colorNeutralBackground1,
183 display: "grid",
184 gridTemplateColumns: "1fr",
185 gridTemplateRows: "auto 1fr auto",
186 height: "100vh",
187 width: "100%",
188 },
189 header: {
190 borderBottom: `${tokens.strokeWidthThin} solid ${tokens.colorNeutralStroke1}`,
191 paddingTop: tokens.spacingVerticalS,
192 paddingBottom: tokens.spacingVerticalS,
193 paddingLeft: tokens.spacingHorizontalM,
194 paddingRight: tokens.spacingHorizontalM,
195 },
196 content: {
197 display: "grid",
198 gridTemplateColumns: "280px 1fr",
199 overflow: "hidden",
200 },
201 nav: {
202 borderRight: `${tokens.strokeWidthThin} solid ${tokens.colorNeutralStroke1}`,
203 overflowY: "auto",
204 },
205 main: {
206 overflowY: "auto",
207 paddingLeft: tokens.spacingHorizontalL,
208 paddingRight: tokens.spacingHorizontalL,
209 paddingTop: tokens.spacingVerticalL,
210 paddingBottom: tokens.spacingVerticalL,
211 },
212});
213```
214
215### Custom Brand Theme
216
217```jsx
218import { createLightTheme, createDarkTheme } from "@fluentui/react-components";
219
220const myBrand = {
221 10: "#020305", 20: "#111723", 30: "#16263D",
222 40: "#193253", 50: "#1B3F6A", 60: "#1B4C82",
223 70: "#18599B", 80: "#1267B4", 90: "#3174C2",
224 100: "#4F82C8", 110: "#6790CF", 120: "#7F9ED5",
225 130: "#96ADDC", 140: "#ADBCE3", 150: "#C4CBE9",
226 160: "#DBDBF0",
227};
228
229const lightTheme = createLightTheme(myBrand);
230const darkTheme = createDarkTheme(myBrand);
231```
232
233### Dark Mode Toggle
234
235```jsx
236function App() {
237 const [isDark, setIsDark] = useState(false);
238 return (
239 <FluentProvider theme={isDark ? webDarkTheme : webLightTheme}>
240 <Switch
241 label="Dark mode"
242 checked={isDark}
243 onChange={(_, data) => setIsDark(data.checked)}
244 />
245 </FluentProvider>
246 );
247}
248```
249
250## Anti-Patterns
251
252- ❌ Hardcoded colors (`color: "#333"`) — use `tokens.colorNeutralForeground1`
253- ❌ CSS shorthand properties in `makeStyles` (`border: "1px solid red"`) — use longhand or `shorthands.*`
254- ❌ String concatenation of classNames — use `mergeClasses()`
255- ❌ Inline `style` props for token-based values — use `makeStyles` with `tokens`
256- ❌ Importing from `@fluentui/react` (v8) in v9 projects — use `@fluentui/react-components`
257- ❌ Using v8 `Stack` — use CSS Grid or Flexbox
258- ❌ Overriding CSS custom properties from the color system directly in CSS — the adaptive color system is JS-driven
259- ❌ Removing focus indicators — accessibility requirement