Fluent 2 Design System

Microsoft Fluent 2 Design System — Core Knowledge Base

Overview

Fluent 2 is Microsoft's open-source design system powering Microsoft 365, Teams, Copilot, Windows, and the broader Microsoft ecosystem. It provides a unified design language with design tokens, a React component library (@fluentui/react-components), and platform-specific implementations for Web, iOS, and Android.

Key packages:

@fluentui/react-components — Main component library (Fluent UI React v9)
@fluentui/react-icons — Fluent icon system (filled + regular variants)
@fluentui/tokens — Design token definitions
@fluentui/react-theme — Theme definitions and brand ramp utilities

Design resources:

Fluent 2 site: https://fluent2.microsoft.design/
Storybook: https://react.fluentui.dev/
GitHub: https://github.com/microsoft/fluentui
Developer portal: https://developer.microsoft.com/en-us/fluentui

Core Design Principles

1. Content-First

The design serves the content. Chrome, ornamentation, and UI framework recede so content takes center stage.

2. Inclusive by Default

Every component must be accessible. WCAG 2.1 AA compliance is the floor, not the ceiling.

3. Coherent, Not Uniform

Products share tokens, components, and patterns — but each adapts them to its unique context.

4. Calm Computing

Interfaces should reduce cognitive load. Motion is purposeful. Color draws focus, not distraction.

5. Universal Design Language

Fluent 2 works across web, mobile, and desktop. Design tokens abstract platform differences.

External resources:

Design principles: https://fluent2.microsoft.design/design-principles
Get started with design: https://fluent2.microsoft.design/get-started/design

Design Tokens

Design tokens are the atomic values of the design system — named constants for colors, spacing, typography, shadows, border radii, and motion.

Token Architecture

Fluent 2 uses a three-tier token architecture:

Global tokens — Raw palette values (e.g., grey10, brandPrimary). Never used directly in components.
Alias tokens — Semantic references (e.g., colorNeutralBackground1). Theme-aware.
Component tokens — Component-specific overrides (rare).

Spacing Tokens (Global Spacing Ramp)

Base unit: 4px. All spacing derives from this unit.

Token	Value
`spacingHorizontalNone` / `spacingVerticalNone`	0px
`spacingHorizontalXXS` / `spacingVerticalXXS`	2px
`spacingHorizontalXS` / `spacingVerticalXS`	4px
`spacingHorizontalSNudge` / `spacingVerticalSNudge`	6px
`spacingHorizontalS` / `spacingVerticalS`	8px
`spacingHorizontalMNudge` / `spacingVerticalMNudge`	10px
`spacingHorizontalM` / `spacingVerticalM`	12px
`spacingHorizontalL` / `spacingVerticalL`	16px
`spacingHorizontalXL` / `spacingVerticalXL`	20px
`spacingHorizontalXXL` / `spacingVerticalXXL`	24px
`spacingHorizontalXXXL` / `spacingVerticalXXXL`	32px

Border Radius Tokens

Token	Value
`borderRadiusNone`	0px
`borderRadiusSmall`	2px
`borderRadiusMedium`	4px
`borderRadiusLarge`	6px
`borderRadiusXLarge`	8px
`borderRadiusCircular`	10000px

Shadow / Elevation Tokens

Token	Usage
`shadow2`	Subtle lift (cards at rest)
`shadow4`	Light elevation (dropdowns)
`shadow8`	Medium elevation (popovers)
`shadow16`	High elevation (dialogs)
`shadow28`	Highest elevation (teaching callouts)
`shadow64`	Maximum elevation

Typography Tokens

Font family: 'Segoe UI Variable', 'Segoe UI', system-ui, sans-serif

Token	Size	Line Height
`fontSizeBase100`	10px	14px
`fontSizeBase200`	12px	16px
`fontSizeBase300`	14px	20px
`fontSizeBase400`	16px	22px
`fontSizeBase500`	20px	28px
`fontSizeBase600`	24px	32px
`fontSizeHero700`	28px	36px
`fontSizeHero800`	32px	40px
`fontSizeHero900`	40px	52px
`fontSizeHero1000`	68px	92px

Font weights: fontWeightRegular (400), fontWeightMedium (500), fontWeightSemibold (600), fontWeightBold (700)

Motion Tokens

Token	Value
`durationUltraFast`	50ms
`durationFaster`	100ms
`durationFast`	150ms
`durationNormal`	200ms
`durationGentle`	250ms
`durationSlow`	300ms
`durationSlower`	400ms
`durationUltraSlow`	500ms

External resources:

Design tokens overview: https://fluent2.microsoft.design/design-tokens
Color tokens: https://fluent2.microsoft.design/design-tokens/color-tokens
Elevation: https://fluent2.microsoft.design/design-tokens/elevation
Motion: https://fluent2.microsoft.design/design-tokens/motion

Color System

Neutral Colors

Backgrounds:

colorNeutralBackground1 — Primary surface
colorNeutralBackground2 — Secondary surface
colorNeutralBackground3 through 6 — Tertiary+
colorSubtleBackground — Transparent at rest, visible on hover
colorTransparentBackground — Fully transparent

Foregrounds:

colorNeutralForeground1 — Primary text (high contrast)
colorNeutralForeground2 — Secondary text
colorNeutralForeground3 — Tertiary text
colorNeutralForegroundDisabled — Disabled text

Strokes:

colorNeutralStroke1 — Primary border
colorNeutralStrokeAccessible — AA-contrast border
colorNeutralStrokeDisabled — Disabled border

Brand Colors

Brand tokens use a 16-shade ramp (shade10 through shade160) generated from a primary color:

import { createLightTheme, createDarkTheme, BrandVariants } from '@fluentui/react-components';

const myBrand: BrandVariants = {
  10: '#020305', 20: '#111723', 30: '#16212F', 40: '#1B2C3D',
  50: '#1F374B', 60: '#24425A', 70: '#284D69', 80: '#2D5979',
  90: '#366B8E', 100: '#437DA3', 110: '#548FB7', 120: '#6BA1C9',
  130: '#85B3D7', 140: '#A1C5E3', 150: '#BFD7ED', 160: '#DDE9F6',
};

const lightTheme = createLightTheme(myBrand);
const darkTheme = createDarkTheme(myBrand);

Status Colors

Token	Usage
`colorStatusSuccessBackground1` / `Foreground1`	Success states
`colorStatusWarningBackground1` / `Foreground1`	Warning states
`colorStatusDangerBackground1` / `Foreground1`	Error/danger states

Layout System

Breakpoints / Size Classes

Size Class	Range	Typical Use
`small`	320–479px	Phone portrait
`medium`	480–639px	Phone landscape / small tablet
`large`	640–1023px	Tablet
`x-large`	1024–1365px	Small desktop / laptop
`xx-large`	1366–1919px	Desktop
`xxx-large`	1920px+	Large desktop / ultrawide

Responsive Techniques

Reposition — Move elements from vertical to horizontal layout
Resize — Adjust element dimensions and margins
Reflow — Single-column to multi-column
Show/Hide — Display or hide elements based on viewport
Re-architect — Restructure layout entirely

Touch Targets

iOS and Web: minimum 44×44px
Android: minimum 48×48px

External resources:

Layout system: https://fluent2.microsoft.design/layout
Accessibility: https://fluent2.microsoft.design/accessibility

Component Library

The @fluentui/react-components package provides the full Fluent UI React v9 component library.

Category	Components
Actions	Button, CompoundButton, SplitButton, ToggleButton, MenuButton, Link
Inputs	Input, Textarea, Select, Combobox, Dropdown, SearchBox, SpinButton, Slider, Switch, Checkbox, RadioGroup, DatePicker, TimePicker, ColorPicker, Rating
Layout	Card, CardHeader/Footer/Preview, Divider, Drawer, Dialog, Accordion, TabList/Tab, Toolbar, Breadcrumb
Data Display	Avatar, AvatarGroup, Badge, CounterBadge, PresenceBadge, Tag/TagGroup, DataGrid, Table, Tree, Persona, Text, Label, InfoLabel
Feedback	Toast/Toaster, MessageBar, ProgressBar, Spinner, Skeleton, Alert
Navigation	Menu/MenuItem/MenuList, Nav/NavItem, Overflow/OverflowItem
Overlays	Popover, Tooltip, TeachingPopover, InfoButton
Media	Image

Theming

FluentProvider

All Fluent components must be wrapped in a FluentProvider:

import { FluentProvider, webLightTheme } from '@fluentui/react-components';

<FluentProvider theme={webLightTheme}>
  <App />
</FluentProvider>

Built-in themes: webLightTheme, webDarkTheme, teamsLightTheme, teamsDarkTheme, teamsHighContrastTheme

Nested Themes

<FluentProvider theme={webLightTheme}>
  <MainContent />
  <FluentProvider theme={webDarkTheme}>
    <Sidebar />
  </FluentProvider>
</FluentProvider>

Accessibility

Color contrast: 4.5:1 for normal text, 3:1 for large text, 3:1 for non-text UI
Focus indicators: Visible 2px focus ring on all interactive elements
Keyboard navigation: All interactive components reachable via keyboard
Screen readers: Proper ARIA attributes on all components
Reduced motion: prefers-reduced-motion support
High contrast: Full Windows High Contrast Mode support

Focus utilities:

import { useArrowNavigationGroup, useFocusableGroup } from '@fluentui/react-components';

Iconography

Package: @fluentui/react-icons — 20,000+ icons in Regular (outline) and Filled styles.

Sizes: 16px, 20px, 24px, 28px, 32px, 48px. Default export = 20px.

import { CalendarRegular, CalendarFilled, bundleIcon } from '@fluentui/react-icons';
const CalendarIcon = bundleIcon(CalendarFilled, CalendarRegular);

Cross-Reference: Specialized Skills

For detailed coverage of specific topics, see these dedicated skills:

Skill	Topics
fluent-nextjs	Next.js App Router + Pages Router setup, SSR, `use client` boundaries, Griffel AOT with Next.js
fluent-griffel	makeStyles deep dive, AOT compilation, shorthands, selectors, RTL, DevTools
fluent-extensibility	Slots (4 levels), custom variants, customStyleHooks, headless patterns, v8→v9 migration
fluent-web-components	Web Components (`@fluentui/web-components`), framework-agnostic usage
fluent-charting	`@fluentui/react-charting` — chart types, theming, accessibility
fluent-cross-platform	iOS (Swift/UIKit) and Android (Kotlin) Fluent implementations
fluent-forms	Form orchestration with Formik/Yup, React Hook Form/Zod, Field validation
fluent-integration	B2C UI customization, Office Add-ins, SharePoint integration

Reference Files

${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/references/design-tokens-reference.md — Complete token catalog
${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/references/component-catalog.md — All components with props
${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/references/teams-integration.md — Teams multi-surface architecture
${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/references/advanced-patterns.md — Advanced UI patterns
${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/references/motion-framer-reference.md — Motion system deep dive
${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/examples/theme-examples.md — Theme creation walkthroughs
${CLAUDE_PLUGIN_ROOT}/skills/fluent-design-system/examples/layout-patterns.md — Responsive layout examples

About this skill

Overview

Core Design Principles

1. Content-First

2. Inclusive by Default

3. Coherent, Not Uniform

4. Calm Computing

5. Universal Design Language

Design Tokens

Token Architecture

Spacing Tokens (Global Spacing Ramp)

Border Radius Tokens

Shadow / Elevation Tokens

Typography Tokens

Motion Tokens

Color System

Neutral Colors

Brand Colors

Status Colors

Layout System

Breakpoints / Size Classes

Responsive Techniques

Touch Targets

Component Library

Theming

FluentProvider

Nested Themes

Accessibility

Iconography

Cross-Reference: Specialized Skills

Reference Files