Fluent UI v9

The brochure UI uses Fluent UI React v9 (@fluentui/react-components) styled with Griffel (makeStyles / makeStaticStyles). Icons from @fluentui/react-icons.

Why a component library (vs hand-rolled CSS): ADR-0003.

Provider and theme

The app shell wraps pages in FluentProvider with a custom light theme:

Concern	Typical home
Theme factory	createLightTheme + full 16-stop brand ramp (primary stop locked to brand hex)
Shared tokens	Brand colours, neutrals, spacing scale for Griffel
Global reset	makeStaticStyles once at the shell

No dark-mode toggle for a simple brochure site.

Styling patterns

import { makeStyles } from '@fluentui/react-components';

const useStyles = makeStyles({
  card: {
    padding: '16px',
    // prefer shared brand/space tokens over raw hex in real code
  },
});

Prefer	Avoid
Shared brand / space tokens	One-off hex and magic half-pixels
Fluent controls for interactive UI	Rebuilding Field / Button / MessageBar
Semantic <h1>–<h3> + fluid clamp() type	Fluent Title* for marketing page headings
Container queries / auto-fit grids for tiles	Viewport breakpoints for every strip

Griffel gotcha

makeStaticStyles only resolves a flat top-level map. Nested :hover or @media under an object key can silently fail. Use a raw CSS string for nested rules.

Interactive components (examples)

Fluent	Typical use
Field, Input, Select, Textarea, Button	Forms
MessageBar	Success / error banners
OverlayDrawer, Accordion	Mobile navigation
Carousel primitives	Hero sliders

SSR / FOUC

_document should use Fluent’s RendererProvider + renderToStyleElements so Griffel rules ship in HTML before hydration.

Bundle note

Enable Next optimizePackageImports for @fluentui/react-components and @fluentui/react-icons so barrel imports tree-shake.

Adding UI checklist

1. Prefer existing layout primitives (grid system).
2. Style with makeStyles + shared tokens.
3. Use Fluent for controls; keep headings semantic.
4. Hit targets ≥ 44×44 where interactive.
5. Run the project quality gate and relevant e2e specs.