🎨 North Northants Design System

Design system for North Northamptonshire.

Quick overview

• Storybook: v10 (Vite builder)
• Bundler: Rollup for library artifacts
• Types: TypeScript
• Tests: Vitest with Storybook addon

Requirements

Node 20 is recommended. Use nvm use 20 or your preferred Node manager.

Development

Prerequisites: node and npm installed.

1. Clone the repo
2. Install dependencies:

npm ci

3. Start Storybook locally:

npm run storybook -- --no-open

4. Run component tests:

npm run storybook:test

5. Build the component library:

npm run build
npm run postbuild

5. Export static Storybook (used by CI and publishing):

npm run storybook:export

Notes:

• Storybook now uses the Vite builder (@storybook/react-vite) — we no longer use webpack or @storybook/react-webpack5.
• The MDX runtime integration (@storybook/mdx2-csf) was removed in favor of Storybook v10 built-in MDX handling.

Using the design system in your project

Install from npm:

npm install nnc-design-system

Install peer deps (example):

npm install react react-dom styled-components

This design system uses theming — wrap components with a ThemeProvider from styled-components and pass a theme (e.g., GDS_theme, north_theme, west_theme).

import { ThemeProvider } from 'styled-components';
import { GDS_theme, Button } from 'nnc-design-system';

const MyComponent = () => (
  <ThemeProvider theme={GDS_theme}>
    <Button text="Button Label" />
  </ThemeProvider>
);

Configuration

This design system requires configuration for API endpoints and keys. Wrap your app with DesignSystemProvider and pass a config object:

import { ThemeProvider } from 'styled-components';
import { DesignSystemProvider, GDS_theme, Button } from 'nnc-design-system';

const config = {
  postcodeSearchApiUrl: 'https://api.example.com/postcode/',
  binCollectionApiBaseUrl: 'https://api.example.com/bin/',
  googleMapsApiKey: 'your-api-key',
};

const MyApp = () => (
  <DesignSystemProvider config={config}>
    <ThemeProvider theme={GDS_theme}>
      <Button text="Button Label" />
    </ThemeProvider>
  </DesignSystemProvider>
);

Creating and generating new components

Use the generator:

npm run generate NewComponentName

It scaffolds component source, stories, tests and types under src/.

Publishing

1. Run tests and build locally:

npm run storybook:test
npm test
npm run build
npm run storybook:export

2. Update the version in package.json and publish:

npm publish

The CI will also produce a static Storybook artifact.

Local development tips

• If you need to work with an unpublished local copy, prefer tarball install or npm link (instructions below).
• For older Windows builds you may need a specific Node version; prefer Docker if you hit native build issues.

Migration notes

• We migrated Storybook to v10 with built-in MDX handling. During the migration we:
  • removed runtime mdx2-csf integration
  • aligned @mdx-js/* packages
  • removed @storybook/react-webpack5 usage and moved to @storybook/react + Vite builder
• Added Vitest with Storybook addon for component testing in browser mode using Playwright.

How to publish a new version to NPM

First, make sure you have an NPM account and are logged into NPM using the npm login command.

1. Test locally before publishing (recommended)

# build the library and create a tarball
npm run build && npm pack
# example tarball: nnc-digital-nnc-design-system-1.0.0-beta18.tgz

• Install the tarball into a local frontend project to verify integration:

# from your frontend project root
npm install /absolute/path/to/nnc-digital-nnc-design-system-1.0.0-beta18.tgz
# or with yarn
yarn add file:/absolute/path/to/nnc-digital-nnc-design-system-1.0.0-beta18.tgz

• Start the frontend dev server (npm start / npm run dev) and verify:

  • The app builds without errors.
  • Components import from @nnc-digital/nnc-design-system and render correctly.
  • Styles and theming are applied (wrap with ThemeProvider if needed).
  • No unresolved peer dependency warnings (install matching versions of react, react-dom, etc. if required).

• Iterative alternatives for development without re-packing:

  • npm link — link the library into your frontend for live changes:

# in the design system root
npm link
# in the frontend project
npm link @nnc-digital/nnc-design-system

2. If tests pass and local verification is successful
3. Increment the next version number in the package.json file.
4. npm publish. This will:
   • Run the tests
   • Bundle and transpile the code
   • Create and publish a tarball to NPM
5. If you are wanting to utilise the updated design system you will then need to update the version number of the design system in the package.json file within that repo.