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.

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.

Before you start

• You need to be able to install software on your Mac (you'll be asked for your Mac password a couple of times). If this is a company-managed laptop and installs are locked down, contact IT first — some steps will fail without admin rights.
• You need a Claude account — a Claude Pro/Max subscription or a Claude for Work (Team/Enterprise) seat. Ask your lead which one we use.
• You need to be a member of the @kofile npm organization (for the private MCP server). Not sure, or don't have npm access? Message Scott Stroupe on Teams to be added before you reach Step 7.

Plain-English glossary

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

• Terminal — a Mac app where you type commands instead of clicking. It looks like a plain text window.
• Command — a line of text you type into the terminal and run by pressing Enter.
• Homebrew — a tool that installs other developer tools for you, cleanly.
• Node.js — the engine our tools run on.
• Git — the tool used to download and track code projects.
• Repo — short for "repository": a project's folder of code, stored on GitHub and downloaded to your Mac with Git.
• npm — where code packages are downloaded from (comes with Node.js).
• Token — a secret password-like string that proves you're allowed to download our private packages.
• Claude Code — the AI assistant you run in the terminal.
• MCP server — a small program that lets Claude Code use external tools — here, our design system.

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 6 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. (Coming soon.)

Sections 3–5 aren't written yet — 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

• Homebrew, Node.js, and Git installed.
• Claude Code installed and logged in.
• The Neumo MCP server connected, so you can ask Claude things like "list the design system components" and it answers from the real design system.

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

• If a window pops up asking to install, click Install and wait for it to finish (a few minutes), then come back here.
• If you instead see command line tools are already installed, great — move on.

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)"

• It will ask for your Mac password — type it (you won't see characters as you type; that's normal) and press Enter.
• It may ask you to press Enter to continue — do so.

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 18 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 18, 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.

• Sign in with the Claude account from "Before you start."
• If the browser doesn't open, press c to copy the login URL, then paste it into your browser.

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 your npm token (for the private MCP server)

Our MCP server (@kofile/neumo-mcp-server) is a private package, so npm needs proof you're allowed to download it. You set this up once.

1. Go to npmjs.com and sign in with the account that's a member of the @kofile org.

2. Click your avatar (top-right) → Access Tokens.

3. Click Generate New Token → Classic Token, choose type Read-only, give it a name like neumo-ds, and click Generate.

4. Copy the token now — you can't see it again after you leave the page.

5. Back in the Terminal, save it (replace PASTE_TOKEN_HERE with what you copied):

   npm config set //registry.npmjs.org/:_authToken=PASTE_TOKEN_HERE
   

6. Confirm it works:

   npm view @kofile/neumo-mcp-server version
   

   Expected: a version number prints. If you see 404 or 401, the token or your org membership isn't right — see Troubleshooting.

Never put this token in a file you share or commit to a project. The command above stores it in your private ~/.npmrc, which is the right place.

Need more detail or hit an error here? The npm access token guide covers this step on its own, with a troubleshooting table.

Step 8 — Get the project onto your Mac

You need the design-system project (a "repo") on your machine. You'll need access to the kofile/design-system repo on GitHub — if you don't have it, ask your lead.

The friendliest way is 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 into your home folder:

cd ~
gh repo clone kofile/design-system

Expected: a new design-system folder appears. Move into it — this is where the remaining steps run:

cd ~/design-system

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 9 — 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 8) so your whole team gets it when they open the repo.

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:

Step 10 — 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

Where to go next

• Contributing / running the repo locally — build and run the design system itself (Storybooks + local MCP server): the Local development guide.
• MCP tools reference — every tool, with examples: the MCP Server page.
• Figma users — the Figma Toolkit bridges the design system into Figma.
• Component docs — the React and Web Components Storybooks.

Coming next

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

• Windows & Linux setup — the same walkthrough for non-Mac machines.
• The Neumo MCP server — deep dive. Every tool, real request/response examples, and common workflows. (Start with the MCP Server page today.)
• Lovable. Getting the design system into Lovable. (Coming soon.)
• Figma Make. Getting the design system into Figma Make. (Coming soon.)
• Our setup — close to the metal. How the DS team actually works day to day. (Start with the Local development guide — running the repo, both Storybooks, and a local MCP build.)

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.