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.
- package/README.md +14 -258
- package/dist/index.js +9 -4
- 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.
|
|
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
|
-
-
|
|
10
|
-
-
|
|
11
|
-
- **`
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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": {
|