designsource

designsource

The command line for a DS source design system. Three things it does:

• integrate — add the design system to the app you already have: a design-system/ folder with your tokens as CSS variables, a prompt that tells your coding agent how to wire them in, and the component kit as reference. Vue, Svelte, Angular or plain CSS.
• create — start a new Next.js project from it: tokens, all 61 components, the block pages (/blocks) and your mockup page, running after pnpm install && pnpm dev.
• mcp — serve the design system to your coding agent over MCP: tokens, every component's source, your mockup page and a step-by-step integration guide, read on demand instead of pasted. Claude Code, Cursor, Codex — any client that speaks MCP over stdio.

npx designsource integrate

npx designsource create my-app

Works the same with pnpm dlx designsource …, yarn dlx designsource … and bunx designsource …. Installed globally (npm i -g designsource) it is also available as dss.

How it works

1. Design your system at designsource.app — colours, radii, shadows, typography, three tiers of tokens, a component kit and an AI-generated mockup page.
2. Run the command. It asks with the arrow keys where there is a list to pick from, asks for a folder, and asks for your project token (workbench → Project settings). The token is typed hidden, sent once as a bearer header, and never written to disk or printed.
3. Your app has the system in it: every colour, radius and shadow on screen is a token from your design system.

integrate — add to an existing app

npx designsource integrate [folder] [--framework vue|svelte|angular|css] [--token <project token>] [--api <origin>] [--force]

Writes design-system/ into the folder (default: the current one). Refuses when that folder already has one, unless --force.

create — a new Next.js project

npx designsource create [folder] [--token <project token>] [--api <origin>] [--force]

Writes a runnable Next.js app into a new or empty folder (default my-design-system): Tailwind v4 with the shadcn theme CSS built from your tokens, 61 UI components under components/ui, your mockup page on /, a component gallery on /components, light and dark via next-themes. Next steps print in the dialect of the runner you used (pnpm, npm, yarn or bun); a pnpm run pins packageManager.

mcp — serve it to a coding agent

npx designsource mcp [--token <project token>] [--api <origin>]

Not a command you run in a terminal: put it in your MCP client's config and the agent runs it. The server is plain stdio MCP, so every client takes the same command and env — only the config file's shape differs.

mcpServers JSON:

{
  "mcpServers": {
    "designsource": {
      "command": "npx",
      "args": ["-y", "designsource", "mcp"],
      "env": { "DS_SYNC_TOKEN": "<project token>" }
    }
  }
}

Codex TOML:

[mcp_servers.designsource]
command = "npx"
args = ["-y", "designsource", "mcp"]
env = { DS_SYNC_TOKEN = "<project token>" }

VS Code:

{
  "servers": {
    "designsource": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "designsource", "mcp"],
      "env": { "DS_SYNC_TOKEN": "<project token>" }
    }
  }
}

The workbench's Copy dialog hands out all three. Then ask the agent to integrate the design system: in Claude Code, /mcp__designsource__integrate-design-system does it; elsewhere, "integrate the design system using the designsource MCP" — the integrate-design-system prompt is there for clients that expose MCP prompts, and get_integration_guide carries the same steps as a tool for those that don't. Running the agent headless (claude -p) needs its MCP tools allowed, e.g. --allowedTools "mcp__designsource__*"; interactive sessions prompt instead.

New in 0.4.0: list_blocks and get_block_source, the page layouts built from the components. create now also writes them as /blocks pages, and integrate drops them under design-system/reference/blocks/. Against an older server the two tools answer that the server sent no blocks.

Read-only: nothing an agent does here changes the design system. The project is fetched on the first tool call and refreshed every 60 seconds, so a Save in the workbench shows on the next call. Like every export, it needs the project's account on Pro; on the free plan every tool answers with one line saying so.

Options

Outside a terminal (CI, pipes) the pickers become numbered prompts, and designsource with no command prints usage instead of the menu. Ctrl+C or Esc in a picker exits 130 with nothing written.

Safety

• Every write is contained to the target folder. On any failure the command removes what it created, restores what it overwrote, and says so in one line.
• The project token authorises read-only access to one project. Regenerate it in Project settings to revoke it; the command never stores it; mcp reads it from the environment your MCP client passes and prints it nowhere.
• Zero runtime dependencies. Node 20 or newer.

Local development

From the design-system repo, against a dev server:

pnpm --filter designsource build
pnpm --filter designsource start -- integrate --framework vue --api http://localhost:3001
pnpm --filter designsource start -- create my-app --api http://localhost:3001
DS_SYNC_TOKEN=<project token> pnpm --filter designsource start -- mcp --api http://localhost:3001

For the MCP server, add it to Claude Code with claude mcp add designsource -e DS_SYNC_TOKEN=… -- node apps/designsource/dist/index.js mcp --api http://localhost:3001 and run /mcp__designsource__integrate-design-system in a scratch app.

pnpm --filter designsource test builds and runs the unit tests plus an end-to-end run of the binary against a throwaway local HTTP server, asserting the token never reaches stdout or stderr.

Publishing

By the maintainer, through GitHub Actions with npm trusted publishing: no npm token exists anywhere; npm accepts the release because GitHub vouches for the repository and workflow that built it. Nothing publishes on an ordinary push or merge. (npm attaches a provenance attestation only when the source repository is public, so while this one is private the releases carry none.)

1. Bump the version in package.json (pnpm version patch|minor here) and merge to main. Every publish needs a bump.

2. Rehearse, optionally: Actions → "Release designsource" → Run workflow with dry run on. It installs, builds, tests and packs without publishing.

3. Tag the merge commit designsource@<version> and push the tag:

   git tag designsource@0.4.0 && git push origin designsource@0.4.0
   

   The workflow (.github/workflows/release-designsource.yml) refuses a tag that does not match package.json, runs the tests (which build dist/ first), publishes, then installs the published version from npm and runs --help against it.

4. Check the npm page shows the new version.

One-time setup, done on npmjs.com: package settings → Trusted publishing → GitHub Actions, repository KaroMourad/design-system, workflow release-designsource.yml, no environment. Publishing from a laptop still works (npm login, pnpm publish --access public from this folder; prepublishOnly rebuilds dist/), but it needs your npm login and 2FA.

The README's images live in the web app at apps/web/public/designsource/ and are served from designsource.app; ship image changes there before the npm publish that references them. Their sources are in assets/ here (cover.html, make-gif.mjs).

create-ds-app was this package's first name (0.1.x, September 2026). It was deleted from npm the day after designsource shipped; nothing points at it any more.

License

MIT