@nnc-digital/nnc-design-system/README.md

Design system for West & North Northamptonshire Councils, two unitary councils encompassing Wellingborough, Corby, Daventry, East Northants, Kettering, Northampton, Northamptonshire County and South Northants.

# 🎨 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:

```bash
npm ci
```

3. Start Storybook locally:

```bash
npm run storybook -- --no-open
```

4. Run component tests:

```bash
npm run storybook:test
```

5. Build the component library:

```bash
npm run build
npm run postbuild
```

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

```bash
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:

```bash
npm install nnc-design-system
```

Install peer deps (example):

```bash
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`).

```tsx
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:

```tsx
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:

```bash
npm run generate NewComponentName
```

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

## Publishing

1. Run tests and build locally:

```bash
npm run storybook:test
npm test
npm run build
npm run storybook:export
```

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

```bash
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.](https://docs.npmjs.com/creating-a-new-npm-user-account)

1. Test locally before publishing (recommended)

```bash
# 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:

```bash
# 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:

```bash
# 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.