designsource 0.7.2 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +14 -258
  2. package/dist/index.js +9 -4
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -4,14 +4,14 @@
4
4
 
5
5
  # designsource
6
6
 
7
- The command line for a [DS source](https://designsource.app) design system. What it does:
7
+ The command line for a [DS source](https://designsource.app) design system. Node 20 or newer, zero runtime dependencies; also installed as **`dss`**.
8
8
 
9
- - **`add`** — add the UI kit to the React app you already have: your theme in its global stylesheet, the 61 components and the libraries they import, with Tailwind v4, the `@/` alias and the shadcn config set up first when the app lacks them, plus a `/design-system` section showing them. Run it again to pull updates.
10
- - **`connect`** — connect your coding apps to the design system: saves the project token once, privately, on this computer, and writes each app's MCP settings in the project with no token in them. Claude Code, Cursor, VS Code, Codex and Gemini CLI.
11
- - **`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.
12
- - **`create`** — start a new Next.js project from it: tokens, all 61 components, a front page on `/` and the design system under `/design-system` (components, blocks, sample pages and your mockup page), running after `pnpm install && pnpm dev`.
13
- - **`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, and a tool that adds the UI kit to your app for you. Claude Code, Cursor, Codex — any client that speaks MCP over stdio.
14
- - **`login`** / **`logout`** — sign this computer in to your designsource account for coding agents, so your agent can create a design system for the app it is working on, pick one you already have, and add its UI kit, without you opening the website.
9
+ - **[`add`](https://designsource.app/docs/cli/add)** — add the UI kit to the React app you already have: your theme in its global stylesheet, the 61 components and the libraries they import, the Tailwind and shadcn setup when the app lacks it, and a `/design-system` section showing them. Run it again to pull updates.
10
+ - **[`connect`](https://designsource.app/docs/cli/connect)** — connect your coding apps (Claude Code, Cursor, VS Code, Codex, Gemini CLI) to the design system: the project token saved once, privately, on this computer, and each app's MCP settings written in the project with no token in them.
11
+ - **[`login`](https://designsource.app/docs/cli/login-and-logout)** / **`logout`** — sign this computer in to your account for coding agents, so your agent can create a design system for the app it is working on and add its UI kit.
12
+ - **[`create`](https://designsource.app/docs/cli/create-and-integrate)** — a new Next.js project from it: tokens, every component, a front page and the design system under `/design-system`.
13
+ - **[`integrate`](https://designsource.app/docs/cli/create-and-integrate)** — a `design-system/` folder for Vue, Svelte, Angular or plain CSS: your tokens as CSS variables, a prompt for your coding agent, the component kit as reference.
14
+ - **[`mcp`](https://designsource.app/docs/cli/mcp)** — serve the design system to your coding agent over MCP: tokens, component source, blocks, your mockup page, an integration guide, and tools that add the UI kit or create a design system. `connect` and `login` write its config for you.
15
15
 
16
16
  ```sh
17
17
  npx designsource add
@@ -25,11 +25,7 @@ npx designsource connect
25
25
  npx designsource login
26
26
  ```
27
27
 
28
- ```sh
29
- npx designsource create my-app
30
- ```
31
-
32
- 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`**.
28
+ Works the same with `pnpm dlx designsource …`, `yarn dlx designsource …` and `bunx designsource …`.
33
29
 
34
30
  <p align="center">
35
31
  <img src="https://designsource.app/designsource/demo.gif" alt="Terminal demo: pick what to do with the arrow keys, paste the project token, files are written" width="100%">
@@ -38,256 +34,16 @@ Works the same with `pnpm dlx designsource …`, `yarn dlx designsource …` and
38
34
  ## How it works
39
35
 
40
36
  1. Design your system at [designsource.app](https://designsource.app) — colours, radii, shadows, typography, three tiers of tokens, a component kit and an AI-generated mockup page.
41
- 2. Run the command. It asks with the arrow keys where there is a list to pick from, asks for a folder where the command takes one, and asks for your **project token** (workbench → Project settings). The token is typed hidden, sent as a bearer header, and never printed; only `connect` keeps it, in this computer's private store (below), never in the project.
37
+ 2. Run the command. It asks with the arrow keys where there is a list to pick from, asks for a folder where the command takes one, and asks for your **project token** (workbench → Project settings). The token is typed hidden, sent as a bearer header, and never printed; only `connect` keeps it, in this computer's private store, never in the project.
42
38
  3. Your app has the system in it: every colour, radius and shadow on screen is a token from your design system.
43
39
 
44
- ## `add` — the UI kit in the app you have
45
-
46
- ```sh
47
- npx designsource add [names…] [--all] [--yes] [--force] [--skip-install] [--no-blocks] [--token <project token>] [--api <origin>]
48
- ```
49
-
50
- Run it in your React app's folder. It writes your theme into the app's global stylesheet, the kit's components under the app's `components/ui` and the `cn` helper in `lib/utils.ts`, then installs the libraries those components import with the package manager the app already uses (pnpm, npm, yarn or bun). Every setup step it takes is named in one line as it runs.
51
-
52
- ```
53
- ? Add which components? ❯ All
54
- Pick some…
55
- Adding theme… ✓
56
- Adding 61 components… ✓
57
- Adding the /design-system section… ✓
58
- Installing libraries… ✓
59
- Your design system: /design-system
60
- Done. Your components now use "my-system" from designsource.app.
61
- Run it again any time to pull updates.
62
- ```
63
-
64
- - **Needs** React 19 and TypeScript. It stops with one line otherwise; for Vue, Svelte, Angular, plain CSS or React 18 use `integrate` or the AI prompt in the workbench's Export dialog.
65
- - **Sets up what is missing**, each step named: Tailwind v4 (through PostCSS, or the Vite plugin), an older Tailwind upgraded with Tailwind's own upgrade tool (which refuses a git tree with uncommitted changes: commit them first), the `@/` import alias, and `components.json`. An app already on shadcn keeps its `components.json`; component paths and import aliases follow it. In an app not on shadcn, an existing `lib/utils.ts` is left as it is, so it has to export the `cn` helper; one that does not stops the run before anything changes.
66
- - **An app that was not on Tailwind** gets no page-wide reset: only Tailwind's theme and utilities, plus a small reset scoped to the kit's own elements, so your existing screens look as they did.
67
- - **The theme** sits between `designsource:theme` markers in the global stylesheet. In an app already on shadcn it replaces the `:root`, `.dark` and `@theme inline` blocks shadcn wrote, and variables of yours there that the theme does not define are kept just after it; in an app that was not, your own blocks are left exactly as they are. The theme also makes `<html>` the `stage` container the components' responsive classes query. If a rule of your own after the theme still sets one of the theme's variables, yours wins and `add` prints that line, naming the variables and the file, so you can rename them.
68
- - **Libraries** are installed only when a component you added imports them. One already in your `package.json` at the same major keeps your version; at a different major it is left alone and the components that need it are skipped, with a line saying which.
69
- - **Reruns** refresh the theme and every component `add` wrote before; `add <names…>` adds more, and `--all` adds everything. A component file carries a `// designsource: <name> <hash>` first line, which is how a rerun tells a file you edited from one it can update. Edited files are kept by default (Enter on "Keep your edits to …?") and named at the end; `--force` replaces them.
70
- - **Files designsource did not write**, such as stock shadcn components, are replaced only on a yes ("Replace N existing components with your design system's?") or with `--force`; a no changes nothing. Without a terminal, or with `--yes`, no question is asked: all components on a first run, your edits kept, and the run stops naming any such file unless `--force` is given.
71
- - **`--skip-install`** writes the files and prints the install command instead of running it. A failed install leaves the files in place and says which command finishes it.
72
- - **The `/design-system` section** comes with the full kit: a first run answered All, `--all`, `--yes` or a run outside a terminal, or a bare rerun in an app that already has every component. It is your design system inside your app: the component gallery, the 34 blocks, the sample pages and your mockup page, each on its own route, with its own copy of your theme and its own light/dark switch, so your app's theme rules do not reach it. In a Next.js app (App Router) it is a route folder, `app/design-system/` (or `src/app/design-system/`), drawn over your app's own header and footer; its pieces go under `components/design-system/` and `components/blocks/`. In a Vite app it is its own page, `/design-system.html` beside `index.html`, with its own stylesheet, and `add` lists it among `vite.config`'s build inputs so `vite build` builds it (a config it cannot edit safely is left alone and the lines to add are printed; a custom `base` or `root` is not handled). `add <names…>` and Pick some write no section and say so in one line; in an app that already has it they leave it as it is. A Pages Router app gets one line and no section. When a library the section needs is in your app at another major, the section is skipped with a line saying why. Section files are stamped like components, so reruns refresh them and keep your edits; its JSON data is written fresh every run.
73
- - **`--no-blocks`** writes the section without its blocks and installs none of the libraries only they need; the section then has no Blocks menu. After that, blocks follow what is on disk: a rerun does not add back blocks a `--no-blocks` run skipped, and `--no-blocks` on an app that has them leaves them as they are and says how many (`Left 34 blocks in place; --no-blocks does not remove them.`).
74
-
75
- ## `connect` — your coding apps, connected
76
-
77
- ```sh
78
- npx designsource connect [--apps claude,cursor,vscode,codex,gemini] [--yes] [--token <project token>] [--api <origin>]
79
- npx designsource connect --forget [--project <id>]
80
- ```
81
-
82
- Run it once in your project. It asks which apps to connect (the ones found on this computer are ticked), asks for your project token, saves the token on this computer and writes each app's MCP settings into the project folder — the nearest folder holding `.git`, else the current one, which it names first. It refuses to run when that folder is your home folder, one of its parents or a filesystem root: those settings files are the apps' user-wide ones, and every project under it would count as connected.
83
-
84
- ```
85
- Connecting /Users/you/acme-app
86
- Connect which apps? Claude Code, Cursor, VS Code
87
- Project token (workbench → Project settings):
88
- Saved your token for "Acme" in the macOS keychain ✓
89
- Claude Code .mcp.json ✓
90
- Cursor .cursor/mcp.json ✓
91
- VS Code .vscode/mcp.json ✓
92
- Done.
93
- Restart Cursor and VS Code.
94
- Claude Code asks once to allow the server.
95
- Then ask your agent to add the UI kit.
96
- These files hold no token and are safe to commit; teammates run npx designsource connect once.
97
- ```
98
-
99
- | App | File | Entry |
100
- | --- | --- | --- |
101
- | Claude Code | `.mcp.json` | `mcpServers.designsource` |
102
- | Cursor | `.cursor/mcp.json` | `mcpServers.designsource`, `type: "stdio"` |
103
- | VS Code (Copilot) | `.vscode/mcp.json` | `servers.designsource`, `type: "stdio"` |
104
- | Codex | `.codex/config.toml` | `[mcp_servers.designsource]`, with `startup_timeout_sec = 60` |
105
- | Gemini CLI | `.gemini/settings.json` | `mcpServers.designsource` |
106
-
107
- Every entry runs `npx -y designsource@latest mcp --project <project id>` and carries no `env`: the server reads the token from this computer's store. Only the `designsource` entry is added or replaced; your other servers and settings stay as they are. A file with comments, or one that is not plain JSON, is not rewritten: `connect` prints the entry to add by hand and carries on with the other apps. An entry that already names this project is left alone, so teammates on other systems do not rewrite each other's. Codex reads the project file once you trust the project in Codex; Gemini CLI skips it when folder trust is on and the folder is not trusted.
108
-
109
- - **Where the token lives.** macOS: the login keychain (service `designsource`). Linux: the Secret Service (`secret-tool`) when it works, else the file below. Windows: protected for your user with DPAPI, in the file below. The file is `$XDG_CONFIG_HOME/designsource/credentials.json` (else `~/.config/designsource/credentials.json`; `%APPDATA%\designsource\credentials.json` on Windows), readable only by you; it always holds the project names and connected folders, and the token itself only when no OS store is available, which `connect` says.
110
- - **Safe to commit.** The settings files hold no token. A teammate who pulls the repo runs `npx designsource connect` once to save their own token; everything else is already wired. `add`, `create`, `integrate` and `mcp` find the saved token on their own.
111
- - **Reruns** ask nothing: in a folder already connected, the apps whose files already point at the project are the ones set up again (`--apps` names others), the saved token is reused, and nothing that already points at the project is rewritten. A token given with `--token` or `DS_SYNC_TOKEN` replaces the saved one. Cursor and VS Code are told to restart only when their file changed.
112
- - **One folder, one design system.** Connecting a folder to a project takes it (and the folders inside it) from any project it was connected to before, so `add` and the other verbs find exactly one saved token there. A credentials file this version cannot read (not JSON, or a newer format) is copied to `credentials.json.bak-<time>` before the next save replaces it, and `connect` says where.
113
- - **A regenerated token.** When the server refuses the saved token, `connect` in a terminal asks for the new one and saves it; outside a terminal it stops and asks you to run it again with `--token` (or `DS_SYNC_TOKEN`). A running agent's server reads the new token on its next tool call; no restart needed.
114
- - **`--api`** points at another server (a local dev server, staging). The origin is saved with the token when it is not the default, so `mcp --project` and `add`, `create` and `integrate` in the folder use it without `--api`, and connecting again without it on the default removes it. A saved token is only ever sent to the server it was connected with: `--api` naming another one is refused (pass `--token` for that server). `mcp` also sends a `--token` or `DS_SYNC_TOKEN` only to the default server, a localhost one, or the one `connect` saved, since its arguments come from a settings file in the repo.
115
- - **`--apps`** names the apps and skips the question; **`--yes`** (and any run outside a terminal) takes the apps found on this computer.
116
- - **`--forget`** removes this folder's saved token from this computer and says which store it was in; the settings files are left as they are. When several design systems are connected to the folder it asks which, or takes `--project <id>`.
117
- - **Claude Code on Windows** may need `npx` run through `cmd /c`. Changing `.mcp.json` for that changes a committed file for everyone, so add it in your own local scope instead: `claude mcp add --scope local designsource -- cmd /c npx -y designsource@latest mcp --project <project id>` (not committed; it wins over the project entry on your machine).
118
-
119
- ## `login` and `logout` — let your agent create design systems
120
-
121
- ```sh
122
- npx designsource login [--apps claude,cursor,vscode,codex,gemini] [--yes] [--api <origin>]
123
- npx designsource logout [--api <origin>]
124
- ```
125
-
126
- `connect` hands your agent one design system you already made. `login` hands it your **account**, so it can make one: ask it to "create a design system for this app" and it reads your codebase (colours, fonts, logo), writes a recipe, and creates the project in your account, then adds its UI kit. Creating is free; adding the kit and reading the tokens need Pro, as every export does.
127
-
128
- **You run it, not your agent**, once on each computer and once in each project folder, in your own terminal (like `gh auth login`): it shows a code and waits for you to approve it in the browser, which an agent's shell cannot show you while it waits, and a coding app picks up the new tools only after a restart. An agent that finds no sign-in says exactly that and asks you to run it.
129
-
130
- ```
131
- Signing in for /Users/you/acme-app
132
- Open https://designsource.app/device and enter BCDF-GHJK
133
- No account yet? Sign up on that page; it's free.
134
- Waiting for you to approve it in the browser… (Ctrl+C to stop)
135
- Signed in as you@example.com on this computer.
136
- Saved the sign-in in the macOS keychain ✓
137
- Claude Code .mcp.json ✓
138
- Restart Claude Code so it loads designsource.
139
- Claude Code asks once to allow the server.
140
- Then ask your agent to create a design system for this app.
141
- These files hold no token and are safe to commit.
142
- ```
143
-
144
- - **Approving.** The browser opens `designsource.app/device` (signed in, email verified); type the code, check what the page shows (the computer's name, where the request started, how long ago, what it may do) and Approve. Only approve a code you started yourself, just now: designsource never asks for one by email or chat. Your account is emailed when a device is approved. The code lives 10 minutes and works once; `login` prints the account's email so you notice if you signed in to the wrong one.
145
- - **What it writes.** The sign-in (an account token, `dsa_…`) goes to this computer's private store, as `connect`'s token does: the macOS keychain, the Secret Service on Linux, DPAPI on Windows, else a file readable only by you. The index beside `credentials.json`, `account.json`, holds the account's email, its trusted folders and which design system each folder uses; never the token unless no OS store works, which `login` says. In the project it writes each app's MCP settings with the entry `npx -y designsource@latest mcp`: no `--project`, no token, safe to commit. Codex reads its project file only once you trust this project in Codex (it asks when you first open the folder), and Gemini CLI skips it when its folder trust is on and the folder is not trusted; `login` says so for each.
146
- - **Trusted folders.** The account is used only in the exact project folders you ran `login` in: the nearest folder holding `.git` (after symlinks), not merely somewhere inside one, so a repository cloned under a trusted one is not trusted. `login` refuses your home folder, its parents, a filesystem root and a folder that is neither a repository nor a package (one with no `.git` and no `package.json`). Each folder links to one design system: the one your agent last created or picked there. A folder set up earlier with `connect` keeps its `--project` entry: that app stays on the one design system it was connected to and does not use the sign-in, which `login` says, naming the file to remove `--project` from. A second `login` in a terminal on a computer already signed in skips the browser and only trusts the new folder; outside a terminal it always asks for a fresh approval.
147
- - **The agent's tools.** In a trusted folder, `list_design_systems`, `create_design_system` and `use_design_system` act on your account, and the other tools, `add_ui_kit` included, read the folder's linked design system. Your client asks before `create_design_system` runs. Every result names the account it used.
148
- - **Revoking.** `logout` revokes this computer's sign-in on the server and removes it, with its trusted folders and links, from this computer (settings files are left; they hold no token). From anywhere, your profile page's **Coding apps** card lists every approved device with its last use and revokes one or all. A password change, unlinking a sign-in method or deleting the account ends every device's sign-in too, and an unused one expires after 90 days. A revoked sign-in stops everything on that computer at once, `add_ui_kit` included: no project token is ever handed out this way.
149
- - **`--api`** signs in to another server (a local dev server, staging), reduced to its origin. From a script it is refused unless it is the default server or one on this computer.
150
-
151
- ### Security
152
-
153
- The account token never lands in a repository file, a command line, an environment variable or anything your agent sees: the MCP server holds it, and no tool result carries it. A saved token is sent only to the server it was saved for, so a repo's settings file naming another `--api` gets nothing, and the account is used only in folders you ran `login` in, so a cloned stranger's repo that starts `designsource mcp` cannot reach it. A repo's own `designsource` entry carrying an `env` or extra keys is not counted as set up; `login` prints the entry to write instead. Known limit: a repo's committed `.npmrc` can point `npx` at another registry, which swaps any `npx` package the repo starts, this one included; only let repos you trust start MCP servers.
154
-
155
- ## `integrate` — design-system files for another stack
156
-
157
- ```sh
158
- npx designsource integrate [folder] [--framework vue|svelte|angular|css] [--token <project token>] [--api <origin>] [--force]
159
- ```
160
-
161
- Writes `design-system/` into the folder (default: the current one). For Vue, Svelte, Angular and plain CSS; React apps want `add`. Refuses when that folder already has one, unless `--force`.
162
-
163
- | File | What it is |
164
- | --- | --- |
165
- | `tokens.css` | Every token as plain CSS custom properties, light and dark (`[data-theme="dark"]` plus a guarded `prefers-color-scheme` block). |
166
- | `tokens.json` | The canonical export, with references. |
167
- | `page.json` | Your mockup page as a layout spec, when the project has one. |
168
- | `PROMPT.md` | Paste into your coding agent: where to import `tokens.css` for your framework, how to wire an existing theme toggle, how to port the components idiomatically, and how to migrate the styles you already have. |
169
- | `reference/` | The component kit, renderer and page schema as annotated React source ("port, do not run") plus `components.md`, an index of every variable each component reads. |
170
-
171
- ## `create` — a new Next.js project
172
-
173
- ```sh
174
- npx designsource create [folder] [--token <project token>] [--api <origin>] [--force]
175
- ```
176
-
177
- 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`, a front page on `/`, and the design system under `/design-system`: the component gallery (`/design-system/components`), the blocks (`/design-system/blocks`, one page each at `/design-system/blocks/<id>`), the sample pages and your mockup page (`/design-system/custom`); 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`.
178
-
179
- <p align="center">
180
- <img src="https://designsource.app/designsource/starter-dark-home.png" alt="Generated Next.js starter, home page, dark" width="49%">
181
- <img src="https://designsource.app/designsource/starter-light-home.png" alt="Generated Next.js starter, home page, light" width="49%">
182
- </p>
183
- <p align="center">
184
- <img src="https://designsource.app/designsource/starter-dark-components.png" alt="Component gallery, dark" width="49%">
185
- <img src="https://designsource.app/designsource/starter-light-components.png" alt="Component gallery, light" width="49%">
186
- </p>
187
-
188
- ## `mcp` — serve it to a coding agent
189
-
190
- ```sh
191
- npx designsource mcp [--project <id>] [--token <project token>] [--api <origin>]
192
- ```
193
-
194
- Not a command you run in a terminal: put it in your MCP client's config and the agent runs it — `connect` writes that config for Claude Code, Cursor, VS Code, Codex and Gemini CLI, with `--project` and no token in it, and `login` writes it with neither. With `--project`, `--token` or `DS_SYNC_TOKEN` it serves that one project as before; with none of them it uses the account `login` saved, in the exact folders you ran `login` in. For any other client, write it by hand as below. The server is plain stdio MCP, so every client takes the same command and env — only the config file's shape differs.
195
-
196
- | Client | Config | Shape |
197
- | --- | --- | --- |
198
- | Claude Code | `.mcp.json` in the repo, or `claude mcp add designsource -e DS_SYNC_TOKEN=<project token> -- npx -y designsource mcp` | `mcpServers` JSON |
199
- | Cursor | `.cursor/mcp.json` | `mcpServers` JSON |
200
- | Windsurf, Cline, Gemini CLI | their `mcp_config.json` / `settings.json` | `mcpServers` JSON |
201
- | Codex | `~/.codex/config.toml` | `mcp_servers` TOML |
202
- | VS Code (Copilot) | `.vscode/mcp.json` | `servers` JSON with `type: "stdio"` |
203
- | Anything else | its MCP config | command `npx -y designsource mcp`, env `DS_SYNC_TOKEN` |
204
-
205
- `mcpServers` JSON:
206
-
207
- ```json
208
- {
209
- "mcpServers": {
210
- "designsource": {
211
- "command": "npx",
212
- "args": ["-y", "designsource", "mcp"],
213
- "env": { "DS_SYNC_TOKEN": "<project token>" }
214
- }
215
- }
216
- }
217
- ```
218
-
219
- Codex TOML:
220
-
221
- ```toml
222
- [mcp_servers.designsource]
223
- command = "npx"
224
- args = ["-y", "designsource", "mcp"]
225
- env = { DS_SYNC_TOKEN = "<project token>" }
226
- ```
227
-
228
- VS Code:
229
-
230
- ```json
231
- {
232
- "servers": {
233
- "designsource": {
234
- "type": "stdio",
235
- "command": "npx",
236
- "args": ["-y", "designsource", "mcp"],
237
- "env": { "DS_SYNC_TOKEN": "<project token>" }
238
- }
239
- }
240
- }
241
- ```
242
-
243
- The workbench's Connect an agent dialog hands out the `connect` command and the project token, and keeps these three snippets in an "Other apps" fold for clients `connect` does not cover. Then ask the agent to add the UI kit or 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.
244
-
245
- | Tool | Returns |
246
- | --- | --- |
247
- | `get_project` | Name, token count, corner-radius strategy, font families, whether there is a mockup page. |
248
- | `get_tokens` | Tokens as `{path, $type, $value: {light, dark}, ref}`; filter by `tier`, `category`, `component`. |
249
- | `get_css_variables` | Every token as plain CSS custom properties, light and dark — for any stack. |
250
- | `get_shadcn_theme` | The shadcn/ui theme stylesheet for Tailwind v4. |
251
- | `list_components` | The 61 components and the CSS variables each reads. |
252
- | `get_component_source` | One component's React source (`utils` for the `cn` helper): verbatim in React + Tailwind, the spec to port from elsewhere. |
253
- | `get_mockup_page` | Your mockup page as a layout spec plus the renderer that paints it. |
254
- | `get_integration_guide` | The steps: wire the tokens, bring in the components, migrate existing styles, document. |
255
- | `list_blocks` | The 34 ready-made page layouts (login, signup, sidebars, a dashboard, chart sets) with the components and files of each. |
256
- | `get_block_source` | Every file of one block, headed by the path it takes under `components/blocks/`. |
257
- | `list_design_systems` | With `login`: the design systems in your account, names and ids, and which one this folder uses. |
258
- | `create_design_system` | With `login`: creates a design system in your account from a recipe the agent writes after reading your codebase (ramps as hue and chroma, the semantic colours, corners, fonts, shadows), links this folder to it and answers its score, the contrast repairs and font fallbacks the server made (the brand colour is never moved), any rows still failing, and a link to tweak it in the workbench. Your client asks first. |
259
- | `use_design_system` | With `login`: links this folder to a design system already in your account. |
260
- | `add_ui_kit` | Adds the UI kit to the React app in the project folder: the theme, the components and their libraries, with the same setup as `add`, and the `/design-system` section when it adds every component. Optional `components`, `replace_existing` (for files designsource did not write) and `no_blocks` (the section without its blocks, as `--no-blocks`). |
261
-
262
- New in 0.4.0: `list_blocks` and `get_block_source`, the page layouts built from the components; `integrate` drops them under `design-system/reference/blocks/`. Against an older server the two tools answer that the server sent no blocks. New in 0.6.0: `add_ui_kit` writes the `/design-system` section as `add` does, and takes `no_blocks`. New in 0.7.0: `login`, and the three account tools; with no `--project` and no token, `mcp` uses the account `login` saved, in the folders you ran it in.
263
-
264
- The tools read the design system, and `add_ui_kit` adds its UI kit to the React app in the project folder (with `--project`, the folder `connect` saved for it: the one the client started in or under, else the only saved one, and it refuses with a line telling the agent to run `connect` there when it cannot tell; with `--token` alone, the folder the client started in; it never overwrites a component you edited, only replaces other existing files when told to, and your client asks before running it; the install it runs keeps the project token out of its environment and its output off the protocol stream); nothing an agent does here changes the design system itself. 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.
265
-
266
- ## Options
267
-
268
- | Flag | What it does |
269
- | --- | --- |
270
- | `folder` | Target folder. `integrate` defaults to `.`, `create` to `my-design-system`; `add`, `connect`, `login`, `logout` and `mcp` take none (`add` works in the current folder, `connect` in the project root above it). |
271
- | `names` | `add` only. Components to add, plus the kit files they import. |
272
- | `--all` | `add` only. Every component, no question. |
273
- | `--yes` | `add`, `connect` and `login`. No questions, also outside a terminal: for `add`, all components on a first run, your edits kept; for `connect` and `login`, the apps found on this computer. |
274
- | `--apps` | `connect` and `login`. The apps to set up, comma-separated: `claude`, `cursor`, `vscode`, `codex`, `gemini`. |
275
- | `--forget` | `connect` only. Remove this folder's saved token from this computer. |
276
- | `--project` | `mcp`: the saved project whose token to use. `connect --forget`: which project, when several are connected to the folder. |
277
- | `--skip-install` | `add` only. Write the files, print the install command. |
278
- | `--no-blocks` | `add` only. The `/design-system` section without its blocks and their libraries; blocks already written stay. |
279
- | `--framework` | `integrate` only. Skip the picker: `vue`, `svelte`, `angular` or `css`. |
280
- | `--token` | The project token, or set `DS_SYNC_TOKEN` for scripts. Else the one `connect` saved for this folder; asked hidden when there is none. |
281
- | `--api` | API origin. Default `https://designsource.app`; point it at a local dev server or staging. A saved token goes only to the origin it was connected with. |
282
- | `--force` | `add`, `integrate` and `create`. Overwrite files that already exist: for `add`, component files designsource did not write and ones you edited. Without it the command refuses (`add`: asks) rather than touching them. |
283
-
284
- In a terminal, `designsource` with no command shows a menu: Add the UI kit to a React app, Connect your coding apps, Add to an existing project, Create a new project. Outside a terminal (CI, pipes) the pickers become numbered prompts, and no command prints usage instead of the menu. Ctrl+C or Esc in a picker exits 130 with nothing written.
40
+ Every flag, every line the CLI can stop with, and where tokens are kept: [designsource.app/docs/cli](https://designsource.app/docs/cli). Every export needs the project's account on Pro.
285
41
 
286
42
  ## Safety
287
43
 
288
44
  - 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. `add` also edits your Tailwind, alias and stylesheet setup when it is missing; each change is named as it happens, and a failure after setup says what was kept.
289
- - The project token authorises read-only access to one project. Regenerate it in Project settings to revoke it; every computer that saved the old one then runs `connect` again, which asks for the new token in a terminal (elsewhere, pass it with `--token` or `DS_SYNC_TOKEN`). Only `connect` stores it, in this computer's private store and never in the project; the installs `add` runs never see it; `mcp` reads it from that store, or from the environment your MCP client passes, and prints it nowhere.
290
- - The account sign-in `login` saves can create design systems in your account and read the ones there; it cannot delete or change anything. Revoke it with `logout` or on your profile page (see `login` above).
45
+ - The project token authorises read-only access to one project. Regenerate it in Project settings to revoke it; every computer that saved the old one then runs `connect` again. Only `connect` stores it, in this computer's private store and never in the project; the installs `add` runs never see it; `mcp` reads it from that store, or from the environment your MCP client passes, and prints it nowhere.
46
+ - The account sign-in `login` saves can create design systems in your account and read the ones there; it cannot delete or change anything. Revoke it with `logout` or on your profile page. It is used only in the folders you ran `login` in and sent only to the server it was saved for. Known limit: a repo's committed `.npmrc` can point `npx` at another registry, which swaps any `npx` package the repo starts, this one included; only let repos you trust start MCP servers.
291
47
  - Zero runtime dependencies. Node 20 or newer.
292
48
 
293
49
  ## Local development
@@ -305,7 +61,7 @@ DS_SYNC_TOKEN=<project token> pnpm --filter designsource start -- mcp --api http
305
61
 
306
62
  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.
307
63
 
308
- `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.
64
+ `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. `src/docs-contract.test.ts` holds the web app's CLI docs pages to this package's usage strings and messages.
309
65
 
310
66
  ## Publishing
311
67
 
@@ -324,7 +80,7 @@ By the maintainer, through GitHub Actions with npm trusted publishing: no npm to
324
80
 
325
81
  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.
326
82
 
327
- 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`).
83
+ 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. The README links to `designsource.app/docs/cli`, so publish only once those pages are live.
328
84
 
329
85
  `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.
330
86
 
package/dist/index.js CHANGED
@@ -4027,7 +4027,7 @@ async function runLogout(args, io, deps = defaultLoginDeps(process.env)) {
4027
4027
  import { homedir as homedir4 } from "node:os";
4028
4028
 
4029
4029
  // src/version.ts
4030
- var VERSION = true ? "0.7.2" : "0.0.0-dev";
4030
+ var VERSION = true ? "0.8.0" : "0.0.0-dev";
4031
4031
 
4032
4032
  // src/mcp/account-session.ts
4033
4033
  var NOT_SIGNED_IN_FOR = (root) => `Not signed in on this computer for ${printable(root)}. Ask the user to run npx designsource login in a terminal in that folder, then restart this app.`;
@@ -4197,11 +4197,13 @@ var RECIPE_LISTS = {
4197
4197
  fontGenerics: ["sans-serif", "serif", "monospace", "cursive"],
4198
4198
  shadowLevels: ["flat", "subtle", "crisp", "normal", "diffuse", "dramatic"],
4199
4199
  chromaMax: 0.37,
4200
- radiusStrategies: ["concentric", "uniform", "custom"]
4200
+ radiusStrategies: ["concentric", "uniform", "custom"],
4201
+ iconSets: ["lucide", "phosphor", "tabler", "material"]
4201
4202
  };
4202
4203
  var quoted = (xs) => xs.map((x) => `"${x}"`).join("|");
4203
4204
  var L = RECIPE_LISTS;
4204
4205
  var RECIPE_DESCRIPTION = `The design system as a recipe (the server validates it and builds every token from it): {"projectName": string (1-40 chars), "ramps": {each of ${L.rampRoles.map((r) => `"${r}"`).join(", ")} (all 6): {"hue": 0-360, "chroma": 0-${L.chromaMax}}} (the server builds 19 shades per ramp; hue 0 red, 30 orange, 60 amber, 90 yellow, 145 green, 195 teal, 230 blue, 260 indigo, 300 violet, 330 magenta; chroma 0.01 grey, 0.05 muted, 0.12 balanced, 0.2 vivid; neutral at chroma 0.02 or less), "semantics": {each of ${L.semantics.map((s) => `"${s}"`).join(", ")} (all 19): {"light": Ref, "dark": Ref}}, "radius": ${quoted(L.radius)} (the control corner; cards follow one step rounder), "fonts": {"sans": ${quoted(L.sansFonts)} | WebFont, "mono": ${quoted(L.monoFonts)} | WebFont}, "shadowLevel": ${quoted(L.shadowLevels)}, "shadowColor"?: Ref} where Ref = "<ramp role>.<shade>" (shade ${L.shades.join("|")}, e.g. "brand.600") | "white" | "black", and WebFont = {"family": a Google Fonts family spelled exactly as Google lists it, "generic"?: ${quoted(L.fontGenerics)}}.`;
4206
+ var ICONS_DESCRIPTION = 'Optional: the icon set the design system draws with, {"set": "lucide"|"phosphor"|"tabler"|"material", "style": string, "weight"?: number, "filledWhenSelected"?: boolean}: lucide style "line" with weight 1.5|2|2.5 (default), tabler style "outline" with weight 1.5|2|2.5, phosphor style "thin"|"light"|"regular"|"bold"|"fill"|"duotone" with no weight, material style "outlined"|"rounded"|"sharp" (add "-filled" for filled glyphs) with weight 300|400; filledWhenSelected (phosphor line weights and material line styles only) draws the filled glyph in a selected control. Leave it out for Lucide.';
4205
4207
  var CREATE_DESCRIPTION = "Create a new design system in the signed-in designsource account from a recipe you write, and link this folder to it, so the other tools and add_ui_kit read it. Before writing the recipe, read this codebase: its existing colours (Tailwind config, CSS variables, the global stylesheet), its fonts and its logo, and match them. Pick one brand hue (the brand ramp, which primary points at), keep the neutral ramp near grey, keep destructive red, success green and warning amber, and use only Google Fonts family names or the catalog font keys. The recipe's shape is in the recipe property's description. The server repairs contrast without moving primary and reports what it changed and what still fails. Creates a project in the user's account, so your client will ask the user first. The answer names the account and a link where the user can tweak the result.";
4206
4208
  function accountOf(ctx) {
4207
4209
  if (ctx.account) return ctx.account;
@@ -4235,16 +4237,18 @@ async function listDesignSystems(ctx) {
4235
4237
  async function createDesignSystem(args, ctx) {
4236
4238
  const account = accountOf(ctx);
4237
4239
  if (isResult(account)) return account;
4238
- const { name, recipe, mockup, radius_strategy: strategy } = args;
4240
+ const { name, recipe, mockup, radius_strategy: strategy, icons } = args;
4239
4241
  if (typeof name !== "string" || !name.trim()) return errorResult(`"name" must be the design system's name.`);
4240
4242
  if (!isPlainObject(recipe)) return errorResult('"recipe" must be an object (see the tool description for its shape).');
4241
4243
  if (mockup !== void 0 && !isPlainObject(mockup)) return errorResult('"mockup" must be an object, or left out.');
4242
4244
  if (strategy !== void 0 && !L.radiusStrategies.includes(strategy)) {
4243
4245
  return errorResult(`"radius_strategy" must be one of: ${L.radiusStrategies.join(", ")}.`);
4244
4246
  }
4247
+ if (icons !== void 0 && !isPlainObject(icons)) return errorResult('"icons" must be an object (see the tool description), or left out.');
4245
4248
  const body = { name, recipe };
4246
4249
  if (mockup !== void 0) body.mockupSpec = mockup;
4247
4250
  if (strategy !== void 0) body.radiusStrategy = strategy;
4251
+ if (icons !== void 0) body.icons = icons;
4248
4252
  const res = await requestJson({ api: account.api, path: PROJECTS_PATH, method: "POST", token: account.token, body }, ctx.fetchImpl);
4249
4253
  if (res.status !== 201) return serverError(res.status, res.body, account.api);
4250
4254
  const c = res.body;
@@ -4293,7 +4297,8 @@ var ACCOUNT_TOOLS = [
4293
4297
  name: { type: "string", description: "The design system's name, as the user will see it (up to 60 characters). Usually the app's name." },
4294
4298
  recipe: { type: "object", description: RECIPE_DESCRIPTION },
4295
4299
  mockup: { type: "object", description: "Optional: a page layout in the shape get_mockup_page returns for an existing design system. Leave it out when unsure." },
4296
- radius_strategy: { type: "string", enum: [...L.radiusStrategies], description: "How corners nest: concentric (default, recommended), uniform or custom." }
4300
+ radius_strategy: { type: "string", enum: [...L.radiusStrategies], description: "How corners nest: concentric (default, recommended), uniform or custom." },
4301
+ icons: { type: "object", description: ICONS_DESCRIPTION }
4297
4302
  },
4298
4303
  required: ["name", "recipe"],
4299
4304
  additionalProperties: false
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "designsource",
3
- "version": "0.7.2",
3
+ "version": "0.8.0",
4
4
  "description": "The DS source CLI: add your design system's UI kit to a React app (add), add the design system to any other app (integrate), start a new Next.js project from it (create), or serve it to a coding agent over MCP (mcp) — tokens, every component and your mockup page.",
5
5
  "license": "MIT",
6
6
  "repository": {