← Neumo Design System docs

Onboarding — get set up from zero (Mac)

Welcome. This guide gets you from a brand-new Mac with nothing installed to a working setup where an AI assistant (Claude Code) talks to the Neumo Design System directly.

It's written for designers and engineers alike, and it assumes no prior experience — you may have never opened a terminal, and that's fine. Follow the steps in order, top to bottom. You only do this setup once.

Prefer to watch first? Here's the whole setup, start to finish (with narration):

This guide covers macOS only for now. Windows and Linux walkthroughs are on the roadmap. If you're on one of those, ask your lead for help in the meantime.

Time: plan for about 30–45 minutes the first time. A few steps download things and can sit for a minute or two — that's normal.


What this setup is

This guide sets up the design engineer's path — Claude Code in your terminal, wired directly to the Neumo Design System. It's close to the metal: the most flexible and most accurate way to put the design system to work, and frankly the bleeding edge of design-to-code right now.

Everything you generate is grounded in the design system, so it comes out mostly right on the first pass — not 100%, but close, and easy to finish:

The Input component in Figma
Designed in Figma — the source of truth
Components documented in Storybook
Documented in Storybook
A running app built with the design system
Running in a real app (React · Vue · .NET)
The Neumo Toolkit Figma plugin
Tooling you build — the Neumo Toolkit

This isn't the only path. Lighter prototyping tools — Lovable, Figma Make — are quicker to pick up and great for plenty of work; they're just not as precise or flexible as this. Guides for those are on the way (see the map below).

So take what you need and leave the rest. This setup will always be here to experiment with, and we keep these docs as verbose and machine-readable as we can — for you and for the AI reading alongside you.


Before you start

You need one invite before Step 7: read access to the kofile/design-system repo on GitHub. The repo is private, the access is granted by a person, and it often takes a day. Message Scott Stroupe on Teams for it before you start. Steps 1–6 set up your machine and work without it, so you can start now and have the invite by the time you need it.

You don't need an npm account or token. The @kofile packages, including the MCP server, are public on npm.


Plain-English glossary

You'll see these words below. Quick, no-jargon definitions:

Tip: in the terminal, you type or paste a command, then press Enter. If nothing seems to happen, it's usually still working — wait for the blinking cursor / prompt to come back before typing the next one. To paste, use ⌘V.


The onboarding map

What this hub will cover (this page is step 1; the rest link in as they land):

  1. Claude Code in the terminal — install the assistant and connect the design system. (This guide, below.)
  2. The Neumo MCP server — deep dive. (Setup is in Step 8 here; full tool reference on the MCP Server page.)
  3. Lovable — using the design system in Lovable. (Coming soon.)
  4. Figma Make — using the design system in Figma Make. (Coming soon.)
  5. Our setup — close to the metal — how the DS team works day to day. (Partly written: CONTRIBUTING.md covers the process from ticket to release.)

Sections 3 and 4 aren't written yet, and 5 is partly written — they're on the roadmap. Everything below is complete and verified.


1. Claude Code in the terminal (macOS)

What you'll have at the end


Step 1 — Open the Terminal

  1. Press ⌘ (Command) + Space to open Spotlight search.
  2. Type Terminal and press Enter.

A window opens with some text and a blinking cursor. This is where every command below goes. Leave it open for the whole guide.

First time seeing this? You type a command, press Enter, and wait until the prompt (the line ending in $ or %) comes back before the next one.


Step 2 — Install Apple's Command Line Tools

Fresh Macs need Apple's basic developer tools before anything else works. Run:

xcode-select --install

Step 3 — Install Homebrew

Homebrew installs the rest of our tools cleanly. Paste this whole line and press Enter:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Important — finish the setup it prints. On Apple-silicon Macs (M1/M2/M3/M4), Homebrew prints two "Next steps" commands at the end. Run them so your terminal can find Homebrew:

echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify Homebrew works:

brew --version

Expected: something like Homebrew 4.x.x. If you get command not found, close the Terminal, reopen it (Step 1), and run brew --version again.


Step 4 — Install Node.js and Git

With Homebrew installed, this is one command:

brew install node git

Wait for it to finish, then verify both:

node -v
git --version

Expected: a Node version 22 or higher (e.g. v22.3.0) and a Git version (e.g. git version 2.44.0). If node -v shows something lower than 22, run brew upgrade node.


Step 5 — Install Claude Code

curl -fsSL https://claude.ai/install.sh | bash

Then close the Terminal and reopen it (this lets it find the new claude command), and verify:

claude --version
claude doctor

Expected: claude --version prints a version number. claude doctor runs a health check and should show mostly green/OK. If claude: command not found, close and reopen the Terminal once more, then retry.


Step 6 — Log in to Claude

From anywhere, start Claude Code:

claude

The first time, it opens your browser to sign in.

Expected: after signing in, you land at the Claude Code prompt (you can type a message to it). Type /exit and press Enter to leave for now.

Using an API key instead of a subscription? Set ANTHROPIC_API_KEY in your environment before running claude. Most people should use the subscription login above.


Step 7 — Get the project onto your Mac

You need the design-system project (a "repo") on your machine. The repo is private, so you need read access to kofile/design-system on GitHub before this step will work. If you don't have it yet, message Scott Stroupe on Teams.

If gh repo clone below says Could not resolve to a Repository, that is what it means — the repo exists, you just can't see it yet.

Easiest — let Claude do it. You installed Claude Code back in Step 6, so you can hand this whole step to it. Start Claude anywhere (claude) and ask:

"I don't have Git yet. Install Git and the GitHub CLI, sign me in to GitHub, then clone kofile/design-system into ~/Desktop/neumo/design-system and move into it."

Claude installs Git and gh, walks you through the one-time browser sign-in, clones the repo, and drops you in the folder — no Git knowledge needed. When it's done, skip to Step 8.

Prefer to run it yourself? The manual path uses GitHub's CLI, which handles login for you:

brew install gh          # install GitHub's command-line tool
gh auth login            # follow the prompts: GitHub.com → HTTPS → login in browser

When gh auth login asks, choose GitHub.com, then HTTPS, then "Login with a web browser" and follow the steps. Once you're logged in, download the project. We keep it in a neumo folder on your Desktop, so it's somewhere you can actually see and open in Finder:

mkdir -p ~/Desktop/neumo
cd ~/Desktop/neumo
gh repo clone kofile/design-system

Expected: a neumo folder appears on your Desktop with design-system inside it. Move into it — this is where the remaining steps run:

cd ~/Desktop/neumo/design-system

Why there? It's the same place setup.sh uses, so the setup check finds it without being told. You can keep it anywhere you like — the check looks in the usual spots and you can always point it somewhere specific with NEUMO_DIR=/your/path. Desktop is just the one a designer can find without a terminal.

Already have the folder (someone shared it, or you cloned it before)? Just cd into it instead. Tip: you can drag the folder onto the Terminal window to fill in its path, then press Enter.


Step 8 — Connect the Neumo MCP server

"MCP" lets Claude Code use the design system as a set of tools. You'll add the server to the project (the folder you're now in from Step 7), so Claude Code connects to it whenever you work in that folder.

Add the server:

claude mcp add --scope project --transport stdio neumo-ds -- npx @kofile/neumo-mcp-server

That creates a .mcp.json file in the project that looks like this (you could also create it by hand):

{
  "mcpServers": {
    "neumo-ds": {
      "type": "stdio",
      "command": "npx",
      "args": ["@kofile/neumo-mcp-server"]
    }
  }
}

Scopes — where the config lives and who sees it:

Scope Lives in Who gets it
project (used above) .mcp.json in the repo folder you, in this project. In this repo .mcp.json is gitignored, so it isn't shared; each person runs the command once
user your ~/.claude.json just you, in every project
local your ~/.claude.json (per-project) just you, this project only

Step 9 — Verify it's working

Start Claude Code inside the project:

claude

The first time, it will ask you to approve the project's MCP server (a one-time trust prompt) — say yes. Then type:

/mcp

Expected: neumo-ds listed as ✓ Connected with a number of tools. (From the Terminal you can also run claude mcp list to see the same.)

Now try it — ask Claude:

"Use the neumo-ds tools to list the design system components."

Expected: it responds with real component names from the design system. If it does, you're fully set up. 🎉


Troubleshooting

What you see Likely cause Fix
A command "does nothing" for a while It's downloading/working Wait for the prompt to return before typing more
brew: command not found Homebrew's setup line wasn't run Re-run the three eval/.zprofile lines in Step 3, reopen Terminal
command line tools are already installed Not an error Continue to the next step
Password does nothing when typing Terminal hides password characters Keep typing and press Enter — it's working
node -v shows below v22 Old Node brew upgrade node, reopen Terminal
claude: command not found Terminal not reopened after install Close and reopen Terminal; re-run Step 5; try claude doctor
/mcp shows No MCP servers configured You ran claude outside the project cd into the project folder, run claude again
neumo-ds shows ⏸ Pending approval Project server not trusted yet Approve the prompt, or run /mcp and approve
neumo-ds shows ✗ Failed to connect Server didn't start Run npx @kofile/neumo-mcp-server directly to see the error
npm error 401 on a @kofile package An old or expired npm token in ~/.npmrc. npm sends it even for public packages, and a bad one is refused Remove it: npm config delete //registry.npmjs.org/:_authToken, then retry
Connection times out first run npx is downloading the package Wait, or retry with MCP_TIMEOUT=60000 claude
Still stuck — Run claude doctor; inside Claude type /debug for detailed logs; ask in the team channel

Where to go next

What to use — and what's still growing

An honest read so you know what to reach for:


Appendix — the one-command shortcut

Everything above can also be done by one script. Do the manual walkthrough first if this is your first time — it is what the video follows, and it shows you what each piece is for. Come back here when you are setting up a second machine, or helping someone who already has the GitHub invite.

curl -fsSL https://kofile.github.io/design-system/setup.sh | bash

It installs what is missing, skips what you already have, and is safe to run again.

It does not get you past the GitHub invite. The script stops at the GitHub clone (Step 7 above), prints who to ask, and picks up where it left off when you re-run it. It automates the typing, not the permissions — which is why the manual guide above is the real path for a new teammate.

Already set up, but something broke? This checks everything and changes nothing:

curl -fsSL https://kofile.github.io/design-system/setup.sh | bash -s -- --doctor

It is particularly good at catching an old npm token left in ~/.npmrc, which looks harmless but makes every install fail with 401, even though the packages are public. If you already have the repo cloned, you can run the same check from inside it with ./scripts/designer-setup.sh --doctor.


Coming next

Planned sections that will appear here as they're written:


Verified against Claude Code v2.1.2xx (2026-07). If a command has changed, claude doctor and the official docs are the source of truth.