| name | designtools-start |
| description | Start a new project for a designer. Use when they want to begin a new project, app, demo, or idea. Generates the project shell from the designtools-frontend conventions, pins versions and permissions from designtools-core, themes it from a brand colour, and starts the dev loop. Components are composed from Base UI primitives on demand as screens need them (see designtools-frontend). |
Start a new project
Never npm create, never npx degit. Pin the two things the agent can't safely infer — dependency versions and permissions — from designtools-core, and generate everything else from the conventions in designtools-frontend. There is no template to copy; a generated shell fits the project and can't rot on a shelf.
Pin the facts, generate the rest. package.json is built from designtools-core/versions.json and .claude/settings.json is copied verbatim from designtools-core/settings.json — those two only. The config, base styles, HTML document, and app entry you write to the designtools-frontend conventions. The tokens are generated from the brand colour. Components are not shipped as a set — styling is the app, and unrelated projects should never get the same buttons, so components are composed from Base UI primitives on demand as screens need them (see designtools-frontend).
Gather (infer first, one message at most)
Read the brief and any attachments before asking anything. If the designer shares a Figma link or brand assets, extract the primary colour and typeface from them (use the Figma tools when connected) instead of asking. Invent the kebab-case project name yourself and state it. Then ask only for what is still unknown, in a single message, every question skippable:
- What are we making, in a line? (only if no brief was given)
- Brand colour: paste one, or say "you pick" (default DEFAULT_BRAND; any CSS colour works)
- Phone or desktop first? (default desktop; it is responsive either way, this sets which viewport to design and demo in)
- A brand font, if there is one (default: the system stack in base.css; one Google Font maximum)
Scaffold
On desktop, run the designtools-setup doctor first if this machine is unverified this session. Then, in order:
- Create the folder, pin the two facts, generate the shell:
package.json built from designtools-core/versions.json (its runtime and dev objects, verbatim pins, plus scripts dev/build/preview)..claude/settings.json copied verbatim from designtools-core/settings.json — this is what stops the designer being asked to approve every command. Put it in place before running anything else.- Generate to the designtools-frontend conventions:
index.html (a finished <head> — title, description, favicon, theme-color), vite.config.ts, tsconfig.json, src/vite-env.d.ts (/// <reference types="vite/client" /> — required, or tsc && vite build breaks on the first .module.css/asset import), src/styles/base.css (cascade layers, reset, the scale), src/main.tsx (entry, importing tokens.css then base.css), src/app.tsx (the router shell), and src/screens/home/home.tsx (a placeholder that renders once, replaced by the first real screen). No component set — components get built from primitives as screens need them.
- Theme it (designtools-tokens):
npx @designtools/tokens --primary "<colour>" [--neutral "<colour>"] --vanilla --out src/styles/tokens.css
Always --vanilla (no shadcn aliases; this stack is Base UI plus vanilla CSS). Inside the designtools monorepo, run it from source instead: npx tsx packages/tokens/src/cli.ts ….
pnpm installgit init and commit: git add -A && git commit -m "checkpoint: new project, themed <colour>". Local only. No GitHub yet — that waits for designtools-deploy, so a designer who only wants to sketch never touches accounts.- Write
PROJECT.md: the one-line brief, brand colour(s), font, device target, audience, and a running list of screens. Keep it current; it is the memory across sessions.
- If a brand font was chosen, add its
<link> to index.html and set --font-sans in base.css.
Desktop: start the dev server and open it (designtools-run). Say: "Here's your project, running and themed in your brand colour. Tell me the first screen and I'll build it."
Web (claude.ai/code): same scaffold in the sandbox. No local dev server; the preview is a Vercel URL on each push (designtools-deploy).
Offer a style-guide page. Once it's themed — and especially once a few components exist — ask once: "Want a living style-guide page, with all your colours, type, and components in one place?" If yes, add a /styleguide route (see designtools-frontend). Keep it off the main nav; it doubles as the best surface to open @designtools/surface against. It's optional, so only build it if they want it.
What the designer gets
A working, themed codebase on the pinned stack: React + TypeScript on Vite, Base UI as the primitive layer, CSS Modules with generated tokens, react-router, and the accessibility floor — themed from one brand colour and ready to build on. Data comes mock-first when a screen needs it (see designtools-data).
Nothing is pre-styled. Components are composed from Base UI primitives and styled to the brief as screens need them (see designtools-frontend) — so the project comes out looking like itself, not like every other generated app.
Artifact mode (throwaway sketch only)
A single self-contained HTML file: vanilla JS, no build, no dependencies, no git. Run npx @designtools/tokens if a container is available and inline the :root and light-mode blocks plus the essentials of base.css into a <style> tag. Icons are inline Lucide SVGs, never emojis. Say plainly what it is: a sketch with no components, no history, no URL.
