| name | designtools-setup |
| description | One-time machine setup for the designtools suite on macOS. Use when a designer is on the desktop surface for the first time, when the doctor script reports failures, or when they ask to get set up, install tools, or fix their environment. Installs and verifies git, Homebrew, Node, pnpm, GitHub CLI, and Vercel CLI, and signs into GitHub and Vercel. |
Machine setup (desktop, macOS)
Goal: the designer's Mac can scaffold, run, and deploy projects. You run every command; the designer only clicks approvals and types their password when macOS or a browser asks. Web-surface users skip all of this: they only need GitHub connected at claude.ai/code.
1. Diagnose first
Run scripts/doctor.sh from this skill's folder. It is read-only and installs nothing. If everything passes, say the machine is ready and stop.
2. Accounts before installs
If the doctor shows gh or vercel sign-ins are needed, one question before touching the machine: "Do you already have GitHub and Vercel accounts through MxM?" Signing in mid-setup fails without them. If either is missing, take them to the signup page in the browser and wait; for GitHub, confirm the account is in GITHUB_ORG, or flag it to whoever administers the org. Only then start installing.
3. Install what is missing, in this order
Explain each step in one plain sentence before running it ("I'm installing Node, the engine that runs the project"). Wait for each to finish before starting the next.
- Command line tools (provides git):
xcode-select --install opens a macOS dialog; the designer clicks Install. Skip if git already passes.
- Homebrew (the Mac package manager): run the official installer command from brew.sh. The terminal will ask for their Mac password; tell them that is expected and they type it themselves. Follow the printed post-install instructions to add brew to PATH before continuing.
- Node (need 20 or newer):
brew install node
- pnpm:
brew install pnpm
- GitHub CLI:
brew install gh, then gh auth login --web. Tell them a browser window will open to sign in to GitHub; they should already have an account in GITHUB_ORG.
- Vercel CLI:
npm install -g vercel, then vercel login (browser again). Choose the VERCEL_TEAM scope if asked.
4. Permissions (do this, it is the difference between usable and infuriating)
By default Claude Code asks the designer to approve every file write and every shell command. They will not know what pnpm or npx is, and twenty prompts is where a first project turns into a twenty-minute slog.
Copy designtools-core/settings.json to ~/.claude/settings.json. It sets acceptEdits (no prompt per file write) and allows the commands this suite actually runs. If they already have a ~/.claude/settings.json, merge into it rather than overwriting — read theirs, add our permissions.allow entries and defaultMode, keep everything else.
designtools-start also drops the same file into each project at .claude/settings.json, so this is belt and braces, and it is what makes cloud sessions behave too.
Turn on the sandbox — this is the real fix, recommend it by default. Enable it with /sandbox in Claude Code. On macOS it uses Seatbelt to run shell commands inside an OS-level boundary: the agent works freely inside the project folder and can use the network, but the OS physically blocks anything outside it (home files, other apps, system settings). That means commands run without prompting because the boundary — not a click — is what keeps them safe, so there is nothing to approve and nothing to maintain. Explain it in one line: "this keeps everything I do locked to your project folder, so I don't have to interrupt you to ask permission for each step." The allowlist above is the fallback for when the sandbox is off; the sandbox is what actually ends the prompts. If a genuinely-needed command ever gets blocked by the boundary, that surfaces clearly and you handle it there.
5. Verify
Re-run the doctor. All PASS: tell them the machine is ready and offer to start a project (designtools-start). Any FAIL: fix it now; never leave setup half done.
Notes
- Never install anything not listed here without saying what and why first.
- If corporate device management blocks an install, stop and name the blocker plainly. That is an IT conversation, not something to work around.
- Accounts: designers need a GitHub account (in GITHUB_ORG) and a Vercel account (in VERCEL_TEAM). Creating accounts is the one step they do themselves in the browser; take them to the right page and wait.
