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 installthe published@kofile/*packages and you're done.
Time: ~15 minutes once onboarding is complete.
Prerequisites (from onboarding)
- Node.js 24 — matches CI, and pinned in
.nvmrc: runnvm usein the repo. CI also tests Node 22. Node 18 and 20 are past end-of-life and no longer get security fixes, so don't use them. ghauthenticated and access tokofile/design-system(you used this to clone).
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,
cdthere 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. Usenpm installonly 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:siteis 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-serverthen 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:
- both test baselines only shrinking;
- every
var(--…)you added being defined; "use client"not removed;- styled and unstyled demos changing together;
- no secrets;
- Prettier on your files;
- the unit tests for what you touched;
- branch, commit and ticket naming.
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
- MCP tool reference — the MCP Server page.
- Component docs — the React and Web Components Storybooks (or run them locally as above).
- Contributing —
CONTRIBUTING.mdandREVIEW.mdin the repo root. - Releases — Matt publishes them; you never need to.
RELEASE.mdexplains how, if you're curious.
If a command here drifts from the repo, the package.json scripts and each
project's project.json are the source of truth.