A comprehensive design system for NHS digital services built with React, TypeScript, and design tokens.
The NHS FDP Design System provides a complete set of reusable components, design tokens, and guidelines to help teams build consistent, accessible NHS digital services.
npm install @nhsdigital/fdp-design-systemIf the npm package is not yet available, you can install from GitHub Packages:
-
Create or edit
.npmrcin your project root:@nhsdigital:registry=https://npm.pkg.github.com -
Authenticate with GitHub Packages (requires a GitHub PAT with
read:packagesscope):npm login --registry=https://npm.pkg.github.com
-
Install the package:
npm install @nhsdigital/fdp-design-system
import { Button, Panel, Heading } from '@nhsdigital/fdp-design-system';
import '@nhsdigital/fdp-design-system/dist/nhs-fdp-design-system.css';
function App() {
return (
<Panel>
<Heading level={1}>Welcome to NHS FDP Design System</Heading>
<Button variant="primary">Get Started</Button>
</Panel>
);
}You can import individual components via stable subpaths to keep bundles lean and make intent explicit:
// Import a single component (JS + types)
import Button from '@nhsdigital/fdp-design-system/components/Button';
// Many components are available this way, e.g.
import Card from '@nhsdigital/fdp-design-system/components/Card';
import Grid from '@nhsdigital/fdp-design-system/components/Grid';
// Server-only variants (where available)
import { HeaderServer } from '@nhsdigital/fdp-design-system/components/Header/server';
// Styles can still be brought in globally or per-component via CSS subpaths
import '@nhsdigital/fdp-design-system/components/Button/css';Notes:
- Subpath exports are generated from the built
dist/src/components/*/index.{js,d.ts}entries. - Server subpaths (e.g.
components/Header/server) are available where a server-safe variant exists. - Tree-shaking works with both the root entry and component subpaths; choose whichever suits your project structure.
Interactive components (Header overflow, CharacterCount, etc.) require the behaviour bundle to run on the client. Keep your root layout as a Server Component and add a tiny client-only initializer.
// app/layout.tsx (Server Component)
import '@nhsdigital/fdp-design-system/dist/nhs-fdp-design-system.css';
import { HeaderServer } from '@nhsdigital/fdp-design-system/ssr';
import { NHSBehavioursInit } from '@nhsdigital/fdp-design-system/nextjs';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<NHSBehavioursInit /> {/* client island ensures behaviours are bundled and initialised */}
<HeaderServer serviceName="Service" navigation={{ items: [ { href: '/', text: 'Home' } ] }} />
{children}
</body>
</html>
);
}Why this works:
- Your layout stays server-rendered (no "use client").
- NHSBehavioursInit runs only on the client and imports the behaviours bundle so the Header can enhance.
Complete Next.js Setup Guide – Detailed setup, verification, and troubleshooting
nhs-fdp-design-system/
├── docs/ # Documentation
│ ├── components/ # Component guides
│ ├── migration/ # Migration documentation
│ ├── tokens/ # Design token documentation
│ ├── testing/ # Testing guides
│ └── guides/ # Development guides
├── src/ # Source code
│ ├── components/ # React components
│ ├── styles/ # Global styles
│ └── tokens/ # Design token definitions
├── examples/ # Usage examples
├── config/ # Configuration files
├── tests/ # Test suites
└── storybook/ # Storybook configuration
- Full Documentation - Comprehensive guides and references
- Migration Guide - Upgrade from legacy systems
- Design Tokens - Token system overview
- Component Library - Interactive Storybook
- SSR Testing Guide - Unified server-side test patterns
- Hydration Testing - Split SSR / client / hydration test pattern & helper
- Multi‑Render Architecture - React and Nunjucks macro generation & parity
- Behaviour Layer - Progressive enhancement, events & teardown API
Some interactive components adopt an explicit split to guarantee deterministic, hook‑free server markup and eliminate hydration warnings while still providing a progressive enhancement path:
Component.render.tsx– Pure render function producing static JSX (no hooks / side effects). Shared source of truth.Component.tsx– Client interactive variant that wraps the pure renderer and adds state, effects and data attributes for behaviours.Component.server.tsx– Server (static) variant invoking the pure renderer only. Contains no React hooks (enforced vianpm run verify:server-variants).
Current migrated components: Radios, Header (exporting RadiosServer, HeaderServer). You can import server variants via @nhsdigital/fdp-design-system/components/ComponentName/server.
Quick SSR usage (Next.js server components):
// Import SSR-safe components only
import { Header, ButtonServer, SummaryList, Input, Textarea, Select } from '@nhsdigital/fdp-design-system/ssr';- Node.js 18+
- npm 9+
# Clone the repository
git clone https://github.com/NHSDigital/fdp-react-design-system.git
cd fdp-react-design-system
# Install dependencies
npm install
# Build design tokens
npm run build:tokens
# Start development server
npm run storybook# Build
npm run build # Full production build (alias for build:parity)
npm run build:parity # Complete build with all verification steps
npm run build:quiet # Clean build output (filters npm warnings)
npm run build:fast # Quick dev build (skips some verification)
# Design tokens
npm run build:tokens # Build design tokens (smart rebuild)
# Storybook
npm run storybook # Start Storybook (dev)
npm run build-storybook # Build Storybook (static)
# Tests
npm run test:components # Run full component test suite (quiet summary)
npm run test:metrics # Run full suite with metrics summary (and text coverage)
npm run test:ssr-components # Run server-side rendering compatibility tests
# Code quality
npm run lint # ESLint
npm run typecheck # TypeScript type checkingBuilt with Style Dictionary, our design tokens provide:
- Semantic tokens for consistent theming
- Component tokens for specific component styling
- Multi-platform output (CSS, SCSS, JavaScript, iOS, Android)
- React functional components with TypeScript
- Compound component patterns for flexible APIs
- Polymorphic components for semantic flexibility
- CSS Modules with design token integration
Primary overview: Data Visualisation Overview
We welcome contributions! Please see our contributing guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Components: Add new components in
src/components/ - Stories: Create Storybook stories for documentation
- Tests: Write unit and visual regression tests
- Tokens: Update design tokens in
packages/nhs-fdp/tokens/
- NHS Design System - Official NHS design guidance
- NHS.UK Frontend - Original NHS.UK frontend library
- Style Dictionary - Design token build system
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Project Documentation
Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.
Any HTML or Markdown documentation is © Crown Copyright and available under the terms of the Open Government Licence v3.0.