Introduction

Welcome to the Design System

A comprehensive, accessible UI kit inspired by UK Government Digital Service (GDS) principles.

About This System

This design system combines GDS usability principles with a modern, neutral aesthetic. It's built for clarity, accessibility, and real-world application development.

🎯 GDS-Inspired

Task-focused design patterns, progressive disclosure, and "one thing per page" principles.

♿ Accessibility First

WCAG 2.1 Level AA compliant with proper ARIA attributes, keyboard navigation, and focus management.

🎨 Neutral Palette

Clean, professional colour scheme using the Inter font family and an 8px spacing system.

Understanding This Documentation

Components

The actual design system – reusable UI elements, templates, and layouts you can copy and implement.

Examples: Button, Card, Input, Dashboard Layout

Shell

The documentation interface – grey containers, navigation, and section headers that help you explore.

Examples: This grey wrapper, the sidebar navigation, section descriptions

How to Use This System

This is a copy-paste design system. All components are built with vanilla React and CSS custom properties, making them easy to integrate into any project without heavy dependencies.

1. Copy the Foundation Styles

Start by copying the CSS custom properties from /styles/globals.css into your project. These define the design tokens (colors, spacing, typography) used throughout.

Copy variables like:
  --color-button, --space-4, --text-lg, etc.
Then use them in your own stylesheets

2. Pick Components You Need

Browse through the documentation and copy individual component code directly from the sections:

  • Individual components (Button, Input, Card) – Copy the React component code into your /components folder
  • Layout templates – Copy entire layout structures as starting points for your pages
  • Page patterns – Use complete page examples as blueprints for common user journeys

3. Customise As Needed

Components are designed to be flexible:

  • Modify design tokens – Change colours, spacing, or typography in your CSS variables
  • Extend components – Add your own props, variants, or functionality
  • Mix and match – Use only what you need; components don't depend on each other
  • Brand it – Replace the neutral palette with your brand colours while maintaining accessibility

4. Dependencies

Minimal external dependencies required:

  • react – All components are React functional components
  • lucide-react – Icons used in some components (optional, swap for your preferred icon library)
  • sonner – Toast notifications library (only if using the Notifications component)

💡 Pro Tip: Start Small

You don't need to adopt the entire system at once. Copy the CSS variables first, then grab individual components as you need them. Each component is self-contained and works independently.

Design Foundations

Typography

Inter font family with a modular scale from 12px to 48px for clear hierarchy and readability.

Spacing

8px baseline grid system (8px, 16px, 24px, 32px, 40px, 48px, 64px, 80px) for consistent rhythm.

Radius

8px border radius across all components for a modern, cohesive appearance.

Colours

Text
Primary
Success
Warning
Error

Getting Started

Explore the navigation sidebar to discover components organised by category:

  • Foundations – Core elements like buttons, inputs, and typography
  • Layout – Grid systems and page structure templates
  • Components – Complex UI patterns like modals, tables, and navigation
  • Patterns – Complete page templates and user journeys