@royalnavy/css-framework

Royal Navy Design System

Build web applications that meet the Royal Navy service standards.

Browse the components, usage guidelines and code snippets in Storybook.

Packages

This is a pnpm + Lerna monorepo. All packages are published to the npm registry under the @royalnavy scope and follow semantic versioning.

Package	Description
@royalnavy/react-component-library	React component library — the primary consumable package.
@royalnavy/design-tokens	Design tokens (colour, spacing, typography, breakpoints) consumed by the components and available to applications.
@royalnavy/icon-library	SVG icon set as React components.
@royalnavy/fonts	Web fonts and the CSS to load them.
@royalnavy/eslint-config-react	Shared ESLint configuration used across the repo (not published for app use).

Installation

Install the component library alongside its peer dependencies:

# with pnpm
pnpm add @royalnavy/react-component-library @royalnavy/fonts styled-components

# ...or with npm
npm install @royalnavy/react-component-library @royalnavy/fonts styled-components

Note: styled-components (v6+) is a required peer dependency. The components are built for React 18.

Quick start

Wrap your application in GlobalStyleProvider and import the fonts once at the root:

import React from 'react'
import { createRoot } from 'react-dom/client'
import '@royalnavy/fonts'
import { GlobalStyleProvider, Button } from '@royalnavy/react-component-library'

function App() {
  return (
    <GlobalStyleProvider>
      <Button variant="primary">Hello, World!</Button>
    </GlobalStyleProvider>
  )
}

createRoot(document.getElementById('root')).render(<App />)

See Storybook for the full component catalogue and props documentation.

Developing locally

You'll need Git and Node.js installed. This repo uses pnpm as its package manager (see the packageManager field in package.json) and pins a Node.js version in .nvmrc.

External contributors should fork the repository first.

# 1. Clone (or clone your fork)
git clone git@github.com:Royal-Navy/design-system.git
cd design-system

# 2. Use the pinned Node.js version (optional, requires nvm)
nvm install

# 3. Enable pnpm via Corepack (ships with Node.js)
corepack enable

# 4. Install dependencies for every package
pnpm install

# 5. Run Storybook for the component library on http://localhost:6006
pnpm --filter @royalnavy/react-component-library storybook

pnpm workspaces link the packages together, so a change to @royalnavy/design-tokens (for example) is reflected live in Storybook. Add dependencies to a package with pnpm add <pkg> --filter <package-name>.

Scripts

Run from the repository root; each delegates to the relevant packages via Lerna:

Script	Description
pnpm build	Build all packages.
pnpm lint	Lint all packages.
pnpm test	Run the Jest unit tests in all packages.
pnpm storybook:static	Build the static Storybook site.

Package-specific scripts (such as storybook, test:e2e and test:a11y) live in each package's package.json and can be run with pnpm --filter <package-name> <script>.

Conventions

• Commits follow the Conventional Commits specification and are validated on commit and in CI.
• Git hooks (Husky) lint and format staged files before each commit.
• Formatting is enforced with Prettier.

Browser support

The Royal Navy Design System supports all major evergreen browsers.

Contributing

Read the Contributing Guidelines before opening a pull request.

Licensing

Royal-Navy/design-system is licensed under the Apache License 2.0.

Thanks

We use Chromatic for visual regression testing of Storybook.