Local development — run the design system repo

This picks up where the onboarding guide leaves off. By now you should have: Claude Code working, an npm access token configured, and the repo cloned to your machine. This guide is for contributors — people who want to build, run, and change the design system itself (not just consume the published packages).

Not a contributor? If you just want to use the components, you don't need any of this — install the published packages per the npm access token guide and you're done.

Time: ~15 minutes once onboarding is complete.

Prerequisites (from onboarding)

Node.js 20 — matches CI. There's no enforced version pin in the repo, but 18 or 20 are what CI runs; 20 is the safe choice.
gh authenticated and access to kofile/design-system (you used this to clone).
npm access token configured — required, because the repo's own dependencies are the private @kofile/* packages. Without it, npm ci fails. See the npm access token guide.

Move into the repo before running anything below:

cd ~/design-system

1. Install dependencies

npm ci

Expected: installs cleanly. If you get a 404/E401 on a @kofile/* package, your npm token isn't set or valid — fix it via the npm access token guide, then re-run. (npm ci reads your ~/.npmrc; it does not read a .env file.)

Use npm ci (clean, lockfile-exact) for a normal setup. Use npm install only when you're intentionally changing dependencies.

2. Build the packages

This monorepo uses Nx. Build everything:

npx nx run-many -t build

Or build a single package:

npx nx build react-bundle     # @kofile/gds-react
npx nx build wc               # @kofile/gds-wc
npx nx build mcp-server       # @kofile/neumo-mcp-server

Expected: each target ends with a green "Successfully ran target build".

3. Run the Storybooks locally

Two component explorers, run independently:

npm run docs            # React Storybook  → http://localhost:6006
npm run wc:storybook    # Web Components   → http://localhost:4600

Both are live-reload dev servers — edit a component or story and the browser updates. Stop a server with Ctrl-C.

To preview the whole combined docs site exactly as it deploys (both Storybooks + the doc tiles + landing bento), build and serve the static tree:

npm run docs:site       # builds everything, serves → http://localhost:3000

docs:site is a static build (no live reload) — re-run it after edits. Use the two dev servers above for iterating on components.

4. Run the MCP server from your local build

Onboarding wired Claude Code to the published @kofile/neumo-mcp-server. As a contributor you'll want Claude to use your local build so your changes to the server are reflected.

Build it, then register a local-scope server pointing at the built entry (local scope keeps it separate from the project's published-package .mcp.json, so the two don't collide):

npx nx build mcp-server
claude mcp add --scope local neumo-ds-local -- node ./apps/mcp-server/dist/index.js

That entry looks like:

{
  "mcpServers": {
    "neumo-ds-local": {
      "type": "stdio",
      "command": "node",
      "args": ["./apps/mcp-server/dist/index.js"]
    }
  }
}

Start Claude Code in the repo and run /mcp — you should see neumo-ds-local as ✓ Connected. Rebuild (npx nx build mcp-server) and restart Claude Code after changing the server's code.

Iterating on the server? npx nx build mcp-server then reconnect in /mcp. The server reads the design-system data bundled at build time, so a rebuild is needed to pick up data or code changes.

5. Run the tests

npm run test:jest       # React bundle (Jest)
npx nx test wc          # Web Components (Jest)

Troubleshooting / common pitfalls

What you see	Cause	Fix
`npm ci` fails with `404`/`E401` on `@kofile/*`	No/invalid npm token (the repo depends on the private packages)	Configure your token — npm access token guide — and re-run
`npm whoami` says 401 but your token is valid	An old token in `~/.npmrc` is overriding it (npm ignores `.env`)	Re-run `npm config set //registry.npmjs.org/:_authToken=YOUR_TOKEN`
Nx errors about native bindings / stale plugins (e.g. SWC, `@nx/nx-*`)	Cached bindings for the wrong platform, or a stale Nx cache	`npx nx reset`, then re-run. If it persists, `npm rebuild`
A build behaves oddly after switching branches	Stale Nx computation cache	`npx nx reset`
Node version errors	Node too old	Use Node 20 (matches CI)
`/mcp` doesn't show `neumo-ds-local`	Server not built, or you're outside the repo	`npx nx build mcp-server`, run `claude` from the repo root, re-check `/mcp`

Where to go next

MCP tool reference — the MCP Server page.
Component docs — the React and Web Components Storybooks (or run them locally as above).
Publishing — see RELEASE.md in the repo root for the release/versioning flow.

If a command here drifts from the repo, the package.json scripts and each project's project.json are the source of truth.