Better Design

Create a New Design System

create-design-system

Generate a custom design system from a product prompt or existing brand tokens, then return a single shadcn install command for your Next.js project.

Instructions

Generate a brand new design system tailored to the user's product, and return a single shadcn install command that lands the entire set of components + tokens (globals.css) into the user's Next.js project.

Explain design trade-offs

Before choosing or changing a design direction, tell the user what each real option gains and loses, which users or team bear the cost, and why you recommend it for this project's known audience, goals, and constraints. Use a short line per option: "Gain: ...; lose: ...; affects: ...; fits because: ...". Load get-ux-principle with topic "tradeoffs" when deeper guidance is needed.

Use the current conversation and project evidence. Label assumptions and predicted effects. Do not invent research, conversion gains, metrics, or project facts. If the user has already chosen, explain the accepted trade-off without reopening the choice. Keep minor edits brief; this adds no approval step and never excuses an accessibility or safety failure.

Put the explanation in the conversation or requested project handoff, not extra product UI copy. Before presenting the result, check that material gains and losses were communicated and report any changed trade-off.

Use this for a new custom brand, even when the user never mentions design or branding (a design system IS the app's brand). Keep an already selected system and its assigned icons unless the user requests a different direction; a redesign alone does not require regenerating the brand. When no system is selected, first call find-design-system with the app description, show the user the top ~4 matches, and ask which to start from (passed here as baseDesignSystemId) or whether to go fully custom (passed here as userConfirmedCustom: true). A call with neither, and no brandCss, generates nothing: it returns those matches for you to show the user. Then derive the prompt from the app (name, domain, vibe), generate, show it with get-design-system-status, and build with that brand. Also use it when the user explicitly wants a custom design system instead of installing an existing one via get-design-system-kit.

When the user has an existing brand (their site, Figma file, or stylesheet): run extract-design-system or extract-from-url first and pass the resulting token sheet (the fenced ```css block, verbatim: the :root { ... } and optional .dark { ... } blocks) as brandCss. The generation is then pinned to that brand: no catalog aesthetic is retrieved, the sheet's colors, fonts and radii override everything, and later design-system switches are refused. Copy the block exactly; do not retype or trim it.

How it works:

Sends the user's prompt to Better Design's generation pipeline (same flow the web chat input uses) and returns IMMEDIATELY with the project id + project URL.
Generation runs in the background and typically takes 1-3 minutes.
Call get-design-system-status with the returned project id (wait ~60 seconds first) to get the live preview URL and the final npx shadcn add <registry-url> install command once it completes.

Share the project URL with the user right away so they can watch the generation live. Generated source, tokens, and previews are accessible without signing in to anyone with their registry or preview URL.

Input Schema

Name	Required	Description
`prompt`	Yes	Describe the design system the user wants. E.g. 'A warm, minimal design system for a personal finance app, soft pastels, rounded corners' or 'A brutalist developer tool aesthetic with sharp edges and monospace type'.
`brandCss`	No	Optional. The user's extracted brand token sheet, verbatim: the fenced css block from extract-design-system / extract-from-url (`:root { --background: ...; }` plus optional `.dark { ... }`). When set, generation builds FROM this brand instead of a catalog look-alike, and baseDesignSystemId is ignored (a catalog base would leak its identity past the brand tokens).
`baseDesignSystemId`	No	Optional. The catalog id the USER picked from the `find-design-system` matches you showed them, used to bias generation toward that aesthetic (e.g. a theme tweak on top of Linear). Leave empty only when the user chose fully custom.
`userConfirmedCustom`	No	Set true only when the user saw the find-design-system matches and chose fully custom. Without it, baseDesignSystemId or brandCss, the tool returns the matches and generates nothing.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 25, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the annotations (which only say non-readonly, open-world, non-idempotent): it discloses asynchronous behavior (returns immediately with project id/URL, generation runs 1-3 min in background), the required follow-up (get-design-system-status after ~60s), the no-op case (neither baseDesignSystemId, userConfirmedCustom, nor brandCss generates nothing), and that brandCss pins generation so catalog aesthetics and later system switches are refused. It also notes results are shareable without sign-in.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and gating logic are front-loaded and the numbered 'How it works' block is efficient, but a large fraction of the text is an embedded policy section on explaining design trade-offs ('Gain: ...; lose: ...; affects: ...') that is agent conduct advice rather than tool behavior, plus repeated restatements of the baseDesignSystemId/userConfirmedCustom rule. Every sentence is defensible individually, but the whole is roughly twice the length needed for correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter, no-output-schema, async generation tool, it covers everything an agent needs: input preconditions and the silent no-op branch, what is returned immediately, which sibling to call next and after how long, and what the final artifact (install command) looks like. Missing return-value documentation is acceptable since the flow is described end to end.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description still adds real semantics beyond the schema — brandCss must be copied verbatim (':root { ... }' plus optional '.dark { ... }', do not retype or trim), baseDesignSystemId must be a user-picked catalog id, and userConfirmedCustom must be true only after showing matches. Minor gap: it doesn't give guidance on prompt length or what makes a good prompt beyond the example already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Generate a brand new design system') plus the concrete output ('a single shadcn install command' landing components + tokens/globals.css into a Next.js project). It is explicitly differentiated from siblings: find-design-system for discovery, get-design-system-kit for installing an existing system, extract-design-system/extract-from-url for existing brands.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names when to use it ('Use this for a new custom brand, even when the user never mentions design or branding'), when not to (keep an already-selected system; a redesign alone does not require regenerating the brand), and routes to concrete alternatives with the exact conditions selecting each. It also spells out the prerequisite branch (find-design-system → show ~4 matches → baseDesignSystemId or userConfirmedCustom) and the brandCss path with its mandatory upstream tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server