designtools

Frontend conventions for MxM projects. Use whenever building, editing, or reviewing screens, components, layouts, or styles in a project generated by designtools-start: creating a page, adding a component, changing visual design, or any React or CSS work. Encodes the stack rules: Base UI, CSS Modules, design tokens, Lucide, motion, accessibility, and the three states.

Use when dialing in a precise visual value on a running web app — box-shadow, an exact color or color token, gradient stops, padding/margin/gap, border-radius, opacity, type size/weight/line-height — and describing it in words is the long way round. Surface is a deterministic visual editor that opens over the running app, takes direct-manipulation input (sliders, scrubs, color swatches, drag handles), and writes each change back to source (a Tailwind class, a CSS property, or a token) as a clean, formatting-preserving edit. Reach for it after a couple of failed attempts to hit an exact visual value by prose ("a bit softer", "slightly warmer"). Do NOT use it for structural/layout changes, copy, logic, or any change you can just write.

The pinned facts and permissions the designtools suite is built on. Not usually invoked directly; designtools-start reads it to begin each new project. Consult when questions arise about pinned dependency versions, Claude Code permissions, or how to bump and test the stack. Holds versions.json, settings.json, and the smoke test. It ships no project source — the project is generated from the conventions in designtools-frontend.

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

Use when dialing in a precise visual value on a running web app — box-shadow, an exact color or color token, gradient stops, padding/margin/gap, border-radius, opacity, type size/weight/line-height — and describing it in words is the long way round. Surface is a deterministic visual editor that opens over the running app, takes direct-manipulation input (sliders, scrubs, color swatches, drag handles), and writes each change back to source (a Tailwind class, a CSS property, or a token) as a clean, formatting-preserving edit. Reach for it after a couple of failed attempts to hit an exact visual value by prose ("a bit softer", "slightly warmer"). Do NOT use it for structural/layout changes, copy, logic, or any change you can just write.

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.

Generate a complete colour token system from a brand colour and write it into a scaffolded project. Drives the @designtools/tokens generator; CSS custom properties are the lead output, with Tailwind v3/v4, DTCG, and Lovable exports available. Use at scaffold time (designtools-start) or whenever a project's palette needs regenerating from a brand colour.

Content and data rules for MxM projects. Use when a project needs example content, realistic data, lists, images, or a live data source, or when the designer asks for real data, an API, or realistic copy. Mock-first, with a curated shortlist of free keyless APIs and hard rules about keys and personal data.

Deploy and share MxM projects on Vercel. Use when a designer wants a link, wants to share or show the project, mentions deploying or publishing, or at the end of a working session. Handles first-time project linking, preview versus production, and shareable URLs.

Run, fix, checkpoint, and undo for MxM projects. Use when starting or restarting the dev server, when something looks broken or blank, when the designer wants to go back to an earlier state, and continuously while iterating. Owns the dev loop so the designer never touches a terminal or sees an error.

Entry point for the designtools suite. Use whenever a designer asks to create, build, edit, run, preview, share, or deploy a project, demo, mockup, or proof of concept. Checks the environment, routes to the other designtools- skills, and sets the rules for working with non-technical designers. Read this first for any designtools request.