Build a design system with AI - Part 1: Environment Setup

---

How to Use This Guide

Every step has two paths. Choose the one that suits you.

Path	When to use it
🤖 Guided Path	Copy the prompt into Claude.ai Chat mode. Claude walks you through each step for your specific machine. No need to understand the commands — Claude explains everything.
⌨️ Terminal Path	Run the commands directly in Terminal. Faster if you're comfortable with the command line.

💬 Stuck at any point?

Open Claude.ai (browser or desktop app — Chat mode). Describe what happened, paste the full error message, and ask:

'I'm setting up for the Slalom design system workshop and got stuck on [step name]. Here's what I see: [paste error or describe]. How do I fix it?'

Claude can diagnose and walk through fixing almost any setup issue in a few messages. If you're still stuck, share a screenshot in the Slack channel so the team can assist.

---

Step 1 — Install Node.js

The engine that runs the project. Install once, forget about it.

Node.js lets your computer run project commands like npm install and npm run dev. You don't write Node.js code — you just need it installed. Think of it like a printer driver.

🤖 Guided Path

Paste into Claude.ai — Chat mode

👉 I need to install Node.js on my Mac. I'm a designer with no coding experience.
Please walk me through, one step at a time:

1. Downloading and installing Node.js LTS version 20

2. Verifying it installed correctly

3. What to do if something goes wrong

Wait for me to confirm each step before moving to the next.

Explain any technical terms in plain language.

Follow Claude's instructions. Come back here once it's installed.

⌨️ Terminal Path

Direct download (simplest):

1. Go to nodejs.org
2. Click the green LTS button
3. Open the downloaded .pkg and follow the installer
4. Open Terminal — Cmd+Space → type Terminal → Enter
5. Run:

node --version

✅ You should see v20.x.x — any v18 or v20 is fine.

If you see command not found — close Terminal completely, reopen it, and try again.

Via nvm (if you manage multiple Node versions):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Close Terminal completely, then reopen it
nvm install 20
nvm use 20
node --version

✓  You're ready to continue when:

node --version  prints a version starting with v18 or v20 or higher.

---

Step 2 — Install Cursor

Your code editor. Like Word, but for code files.

Cursor is where you open your project, write instructions to Claude Code, and watch files update in real time. It's built on the same foundation as VS Code with AI features added.

Already use VS Code? You can keep using it — the workflow is the same. This guide uses Cursor in all examples.

🤖 Guided Path

Paste into Claude.ai — Chat mode

👉 I need to install Cursor IDE on my Mac. It's a free code editor at cursor.sh.
I'm a designer who has never installed a code editor before.

Please walk me through:

1. Downloading Cursor from cursor.sh

2. Installing it on Mac

3. Opening it for the first time and creating a free account

4. What the interface looks like when it has opened correctly

Be thorough — I haven't done this before.

⌨️ Terminal Path

1. Go to cursor.sh
2. Click Download
3. Open the .dmg and drag Cursor to your Applications folder
4. Open Cursor and create a free account when prompted

✓  You're ready to continue when:

Cursor opens without errors.

You have a Cursor account and are signed in.

---

Step 3 — Set Up Claude Code

Claude Code is an AI coding assistant. Once it's connected to your project, you give it instructions in plain English — 'Build a Button component using only design tokens', 'Add a spacing token', 'Generate the CLAUDE.md rules file' — and it reads your files, understands your conventions, and makes the changes.

Claude Code follows rules in CLAUDE.md

Every project has a CLAUDE.md file. This is where the design system rules live:

'never use raw hex values', 'only use tokens that already exist', 'follow this component pattern'.

Claude Code reads CLAUDE.md at the start of every session and follows those rules throughout.

This is what stops it from inventing values or ignoring your conventions.

You'll write CLAUDE.md together in the Wednesday session — for now, just know it exists.

Two options — choose one

Option A — Cursor extension	Claude Code runs as a panel inside Cursor. Instructions on the left, files updating on the right. Everything in one window.
⭐ Option B — Claude desktop app (recommended)	Three modes: Chat (questions), Co-work (file automation), Code (the agent). Switch between them instantly — ask something in Chat, return to Code without losing your session.

💡 Why the desktop app works well for designers

While building a design system, you'll frequently want to:

- Ask a quick clarifying question mid-task ('what does semantic token mean again?')
- Run a focused coding session without distractions
- Jump to Chat for an explanation, then return to exactly where you left off

Chat stays conversational. Code stays clean. Switch in one click.

Option A — Claude Code extension inside Cursor

🤖 Guided Path

Paste into Claude.ai — Chat mode

👉 I've just installed Cursor IDE and want to add the Claude Code extension.
Please walk me through:

1. How to open the Extensions panel in Cursor

2. Searching for and installing the Claude Code extension (by Anthropic)

3. Signing in with my Anthropic / Claude.ai account

4. What the Claude Code panel looks like when it's working

5. How to send a test message to confirm it responds

I've never installed an extension in a code editor before.

⌨️ Terminal Path

1. Open Cursor
2. Press Cmd+Shift+X to open Extensions
3. Search: Claude Code
4. Install the extension by Anthropic
5. Click the Claude Code icon in the sidebar
6. Sign in with your Claude.ai account

Option B — Claude code desktop app ⭐

🤖 Guided Path

Paste into Claude.ai — Chat mode

⌨️ Direct Path

👉 I want to install the Claude desktop app on my Mac and use it for a coding project.
Please walk me through:

1. Where to download the Claude desktop app

2. Installing it and signing in with my Anthropic account

3. How to find the Chat, Co-work, and Code modes

4. How to open a project folder in Code mode

5. How to send a test message to confirm Code mode is working

⌨️ Terminal Path

1. Go to claude.ai, sign in, and download the desktop app
2. Open the .dmg and drag Claude to Applications
3. Open the app and sign in
4. Find the mode switcher — click Code
5. Open your project folder using the folder icon or File → Open

The three modes

Mode	What it's for
Chat	Questions, explanations, planning. Keeps your Code session clean and separate.
Co-work	Desktop file and task automation. Not needed for the workshop.
Code	The Claude Code agent. Reads your project, follows CLAUDE.md, writes and edits files. This is what you use to build.

No Anthropic account yet? Sign up at claude.ai — it's free. One account works for claude.ai, the desktop app, and the Cursor extension.

⚠️ When Claude Code asks: 'Allow all edits during this session?'

Select:  Yes, allow all edits during this session.

Without this, Claude Code pauses and asks permission before every single file change,

which makes the workflow very slow. You can always undo any edit with Cmd+Z.

✅ Step 3 done when Claude Code is installed, you're signed in, and it responds to a test message in Code mode.

---

Step 3b — Connect the Figma MCP

Links Claude Code to Figma for bidirectional sync.

⏰ Needed before Friday — optional to do now. Not required for Wednesday or Thursday. Set it up now or come back before Friday.

MCP (Model Context Protocol) lets Claude Code talk to external tools. The Figma MCP lets Claude Code push component frames into Figma and read design changes back into code.

Direction	What happens
Code → Figma	Claude Code captures your dev server UI and creates Figma frames
Figma → Code	Paste a Figma frame URL into a prompt — Claude Code updates the component to match
Token sync	Export tokens as JSON → Token Studio imports as Figma Variables → stays in sync

Get your Figma access token

1. Open figma.com → profile picture → Settings → Security tab
2. Under Personal access tokens → Generate new token
3. Name it claude-code, set File content to Read & Write
4. Click Generate — copy it immediately, shown only once

🔒 Treat this like a password. Don't paste it into Slack, email, or shared docs.

Create .mcp.json in your project

Right-click the root of your project in the Cursor sidebar → New File → name it .mcp.json

Paste this, replacing YOUR_FIGMA_TOKEN_HERE with your token:

{
  "mcpServers": {
    "figma": {
      "type": "streamable-http",
      "url": "https://mcp.figma.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_FIGMA_TOKEN_HERE"
      }
    }
  }
}

Not sure how to create the file? Ask Claude Code: "Create a .mcp.json in the project root for the Figma MCP — I'll paste my token in manually."

Test the connection

Send this in Claude Code (Code mode):

👉 Can you confirm the Figma MCP is configured in this project?
What URL is it pointing to?

Claude Code should confirm it can see the file and name the server. If it can't — check .mcp.json is at the root of your project, not inside a subfolder.

✅ Step 3b done when Claude Code confirms the Figma MCP is connected.

---

Step 3c — Optional Tools

Token Studio and Git. Not needed until Thursday/Friday — set up now if you want to get ahead.

Token Studio — Figma plugin

Token Studio imports your design tokens as Figma Variables. It's the bridge between tokens.ts in code and Figma's Variables panel.

Direct Link: https://www.figma.com/community/plugin/843461159747178978/tokens-studio-for-figma

Or,

1. Open Figma → Community icon (left sidebar)
2. Search: Token Studio for Figma
3. Find the plugin by Jan Six → Install
4. Access it via: right-click canvas → Plugins → Token Studio

What Token Studio does

When you export your tokens as a tokens.json file (Thursday session), Token Studio reads it


and creates Figma Variable collections automatically — Primitive tokens in one collection,


Semantic tokens in another. All alias relationships are preserved. No manual entry required.

Git — version control

Git tracks file changes and lets you push work to Github. Needed for Thursday/Friday when working with the Bunch repo.

🤖 Guided Path

Paste into Claude.ai — Chat mode

👉 I need to install Git on my Mac for the first time.
I'm a designer who has never used version control.

Please walk me through:

1. Installing Git on Mac

2. Configuring my name and email (required once per machine)

3. Confirming it installed correctly

Keep it simple — I just need Git working.

⌨️ Terminal Path

git --version
# If macOS prompts to install Xcode Command Line Tools — click Install

Configure your identity (once per machine):

git config --global user.name "Your Name"
git config --global user.email "you@slalom.com"

---

Step 4 — Create Your Project Folder

An empty folder where your design system will live.

A project folder is just a regular folder on your Mac containing all the design system files. When you open it in Cursor or Code mode, Claude Code can see and edit everything inside.

🤖 Guided Path

Paste into Claude.ai — Chat mode

👉 I need to create a new empty folder called 'slalom-design-system' on my Desktop on my Mac.
Please walk me through:

1. Creating the folder

2. Opening it in Cursor (or Claude desktop app Code mode)

3. Confirming Claude Code can see the folder

4. Sending a test message to verify everything is connected

⌨️ Terminal Path

mkdir ~/Desktop/slalom-design-system

Then open the folder in your editor:

• Cursor: File → Open Folder → Desktop → select slalom-design-system → Open
• Claude desktop app: Code mode → folder icon → select slalom-design-system

Test the connection

With the folder open, send this in Code mode:

👉 Hello. What is the name of the folder I have open? What files are in it?

Claude Code should name the folder and say it's empty. If it does — you're set.

✅ Step 4 done when Claude Code can name your folder and describe its contents.

---

Setup Checklist

	How to verify
☐ Step 1	node --version prints v18 or higher in Terminal
☐ Step 2	Cursor opens and you're signed in
☐ Step 3	Claude Code responds to a test message in Code mode
☐ Step 4	slalom-design-system folder is open and Claude Code can name it
☐ Step 3b (before Fri)	.mcp.json is in the project root and Claude Code confirms it
☐ Step 3c (before Thu)	Token Studio installed in Figma · git --version works

✅ Steps 1–4 done? You're ready for Wednesday.

---

Homework — Setup Validation

10–15 minutes. Complete before Wednesday.

Why this task?
🎯 The goal isn't to build anything yet — it's to confirm your setup works before we're all in a room together. If something breaks, now is the right time to find out.

Four steps

1. Complete Steps 1–4 and tick all four checkboxes
2. Open the slalom-design-system folder in Cursor or Claude desktop app Code mode
3. Send this message to Claude Code and screenshot the response
4. Share the screenshot in the team Slack channel or send to Rotash

Test message — paste this exactly into Claude Code

👉 I am testing my setup. Please tell me:

1. What folder do I currently have open?

2. What files are in it right now?

3. What is one thing you could help me build in this design system project?

A good response will:

• Name the folder correctly (slalom-design-system)
• Describe the contents — probably just .mcp.json if you did Step 3b, otherwise empty
• Suggest something it could build — a Button component, a tokens file, etc.

💡 If Claude Code can't see the folder: confirm you used File → Open Folder (not a single file). If using the desktop app, confirm you're in Code mode not Chat.

The week ahead

This week	Steps 1–4 + homework. Share screenshot
Wednesday	Build a client design system together — with ‘Prompt’ scaffold
Thursday	Components, tokens, CLAUDE.md hands-on
Friday	Governance, debugging, Figma sync, Bunch comparison

📄 Parts 2–5 will be shared before Wednesday.

---

Troubleshooting

If your issue isn't here — paste the full error into Claude.ai Chat and ask for help.

Problem	Fix
node --version → command not found	Close Terminal completely, reopen it, try again. If still failing — repeat Step 1.
npm install fails	Check node --version is v18+. If it is, paste the full error into Claude.ai Chat.
localhost:5173 not loading	npm run dev must stay running in an open Terminal tab. Open a new tab and run it again.
Claude Code panel not visible in Cursor	View → Extensions → search "Claude Code" → confirm installed. Restart Cursor.
Claude Code in Chat mode instead of Code	Check the mode switcher in the desktop app — click Code.
Claude Code can't see my folder	You likely opened a file, not a folder. Use File → Open Folder and select the project folder.
Claude Code inventing token names	CLAUDE.md isn't being read — confirm it's at the project root, not in a subfolder.
.mcp.json not found	Must be at the project root — same level as CLAUDE.md, not inside src/.
Token Studio missing from Figma	Right-click canvas → Plugins → search Token Studio. If missing, reinstall from Community.
Any other error	Copy the full error. Open Claude.ai Chat: "Setting up for Slalom DS workshop, got this error on [step]: [paste]."