← Neumo Design System docs

Local development — run the design system repo

This picks up where the onboarding guide leaves off. By now you should have: Claude Code working 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 — npm install the published @kofile/* packages and you're done.

Time: ~15 minutes once onboarding is complete.


Prerequisites (from onboarding)

Move into the repo before running anything below:

cd ~/Desktop/neumo/design-system

That's where onboarding puts it. If you keep yours somewhere else, cd there instead — nothing below depends on the location.


1. Install dependencies

npm ci

Expected: installs cleanly. If you get an E401 on a @kofile/* package, an old npm token in your ~/.npmrc is being refused. The packages are public, so you don't need one: remove it with npm config delete //registry.npmjs.org/:_authToken and re-run.

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:4400
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)
npx nx run mcp-server:test         # MCP server (Vitest)

The Storybook story tests and the accessibility scan need Storybook running; the commands are in CONTRIBUTING.md, section 4.


6. Before you open a PR

The process from Jira ticket to release is in CONTRIBUTING.md at the repo root (also in the React Storybook under Contributing). Before you push:

npm run check:pr                   # add --quick to skip the unit tests

It compares your branch with main and checks what a reviewer would otherwise send back:

Then review your own diff against REVIEW.md. In Claude Code, /review-pr does both and adds a general bug review. To review someone else's PR without leaving your branch, run npm run check:pr -- --pr <number> or /review-pr <number>.

Read STATUS.md before you start: what's in progress, what's known to be broken, and the decisions behind both.


Troubleshooting / common pitfalls

What you see Cause Fix
npm ci fails with E401 on @kofile/* An old or expired npm token in ~/.npmrc (npm sends it even for public packages) npm config delete //registry.npmjs.org/:_authToken, then re-run
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 nvm use (Node 24, from .nvmrc)
/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


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