designsource 0.6.0 → 0.7.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 +55 -11
- package/dist/index.js +1122 -195
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,13 +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. What it does:
|
|
8
8
|
|
|
9
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
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
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
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
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.
|
|
14
15
|
|
|
15
16
|
```sh
|
|
16
17
|
npx designsource add
|
|
@@ -20,6 +21,10 @@ npx designsource add
|
|
|
20
21
|
npx designsource connect
|
|
21
22
|
```
|
|
22
23
|
|
|
24
|
+
```sh
|
|
25
|
+
npx designsource login
|
|
26
|
+
```
|
|
27
|
+
|
|
23
28
|
```sh
|
|
24
29
|
npx designsource create my-app
|
|
25
30
|
```
|
|
@@ -106,11 +111,46 @@ Every entry runs `npx -y designsource@latest mcp --project <project id>` and car
|
|
|
106
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.
|
|
107
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.
|
|
108
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.
|
|
109
|
-
- **`--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
|
|
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.
|
|
110
115
|
- **`--apps`** names the apps and skips the question; **`--yes`** (and any run outside a terminal) takes the apps found on this computer.
|
|
111
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>`.
|
|
112
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).
|
|
113
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
|
+
Waiting for you to approve it in the browser… (Ctrl+C to stop)
|
|
134
|
+
Signed in as you@example.com on this computer.
|
|
135
|
+
Saved the sign-in in the macOS keychain ✓
|
|
136
|
+
Claude Code .mcp.json ✓
|
|
137
|
+
Restart Claude Code so it loads designsource.
|
|
138
|
+
Claude Code asks once to allow the server.
|
|
139
|
+
Then ask your agent to create a design system for this app.
|
|
140
|
+
These files hold no token and are safe to commit.
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
- **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.
|
|
144
|
+
- **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.
|
|
145
|
+
- **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.
|
|
146
|
+
- **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.
|
|
147
|
+
- **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.
|
|
148
|
+
- **`--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.
|
|
149
|
+
|
|
150
|
+
### Security
|
|
151
|
+
|
|
152
|
+
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.
|
|
153
|
+
|
|
114
154
|
## `integrate` — design-system files for another stack
|
|
115
155
|
|
|
116
156
|
```sh
|
|
@@ -150,7 +190,7 @@ Writes a runnable Next.js app into a new or empty folder (default `my-design-sys
|
|
|
150
190
|
npx designsource mcp [--project <id>] [--token <project token>] [--api <origin>]
|
|
151
191
|
```
|
|
152
192
|
|
|
153
|
-
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. 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.
|
|
193
|
+
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.
|
|
154
194
|
|
|
155
195
|
| Client | Config | Shape |
|
|
156
196
|
| --- | --- | --- |
|
|
@@ -213,9 +253,12 @@ The workbench's Connect an agent dialog hands out the `connect` command and the
|
|
|
213
253
|
| `get_integration_guide` | The steps: wire the tokens, bring in the components, migrate existing styles, document. |
|
|
214
254
|
| `list_blocks` | The 34 ready-made page layouts (login, signup, sidebars, a dashboard, chart sets) with the components and files of each. |
|
|
215
255
|
| `get_block_source` | Every file of one block, headed by the path it takes under `components/blocks/`. |
|
|
256
|
+
| `list_design_systems` | With `login`: the design systems in your account, names and ids, and which one this folder uses. |
|
|
257
|
+
| `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. |
|
|
258
|
+
| `use_design_system` | With `login`: links this folder to a design system already in your account. |
|
|
216
259
|
| `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`). |
|
|
217
260
|
|
|
218
|
-
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`.
|
|
261
|
+
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.
|
|
219
262
|
|
|
220
263
|
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.
|
|
221
264
|
|
|
@@ -223,18 +266,18 @@ The tools read the design system, and `add_ui_kit` adds its UI kit to the React
|
|
|
223
266
|
|
|
224
267
|
| Flag | What it does |
|
|
225
268
|
| --- | --- |
|
|
226
|
-
| `folder` | Target folder. `integrate` defaults to `.`, `create` to `my-design-system`; `add`, `connect` and `mcp` take none (`add` works in the current folder, `connect` in the project root above it). |
|
|
269
|
+
| `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). |
|
|
227
270
|
| `names` | `add` only. Components to add, plus the kit files they import. |
|
|
228
271
|
| `--all` | `add` only. Every component, no question. |
|
|
229
|
-
| `--yes` | `add` and `
|
|
230
|
-
| `--apps` | `connect`
|
|
272
|
+
| `--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. |
|
|
273
|
+
| `--apps` | `connect` and `login`. The apps to set up, comma-separated: `claude`, `cursor`, `vscode`, `codex`, `gemini`. |
|
|
231
274
|
| `--forget` | `connect` only. Remove this folder's saved token from this computer. |
|
|
232
275
|
| `--project` | `mcp`: the saved project whose token to use. `connect --forget`: which project, when several are connected to the folder. |
|
|
233
276
|
| `--skip-install` | `add` only. Write the files, print the install command. |
|
|
234
277
|
| `--no-blocks` | `add` only. The `/design-system` section without its blocks and their libraries; blocks already written stay. |
|
|
235
278
|
| `--framework` | `integrate` only. Skip the picker: `vue`, `svelte`, `angular` or `css`. |
|
|
236
279
|
| `--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. |
|
|
237
|
-
| `--api` | API origin. Default `https://designsource.app`; point it at a
|
|
280
|
+
| `--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. |
|
|
238
281
|
| `--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. |
|
|
239
282
|
|
|
240
283
|
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.
|
|
@@ -243,6 +286,7 @@ In a terminal, `designsource` with no command shows a menu: Add the UI kit to a
|
|
|
243
286
|
|
|
244
287
|
- 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.
|
|
245
288
|
- 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.
|
|
289
|
+
- 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).
|
|
246
290
|
- Zero runtime dependencies. Node 20 or newer.
|
|
247
291
|
|
|
248
292
|
## Local development
|
|
@@ -267,11 +311,11 @@ For the MCP server, add it to Claude Code with `claude mcp add designsource -e D
|
|
|
267
311
|
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.)
|
|
268
312
|
|
|
269
313
|
1. Bump the version in `package.json` (`pnpm version patch|minor` here) and merge to `main`. Every publish needs a bump.
|
|
270
|
-
2. Rehearse, optionally: Actions → "Release designsource" → Run workflow
|
|
271
|
-
3. Tag the merge commit `designsource@<version>` and push the tag:
|
|
314
|
+
2. Rehearse, optionally: Actions → "Release designsource" → Run workflow. A manual run installs, builds, tests and packs, and never publishes, from any branch.
|
|
315
|
+
3. Tag the merge commit on `main` `designsource@<version>` and push the tag (a tag on any other commit stops the run):
|
|
272
316
|
|
|
273
317
|
```sh
|
|
274
|
-
git tag designsource@0.
|
|
318
|
+
git tag designsource@0.7.0 && git push origin designsource@0.7.0
|
|
275
319
|
```
|
|
276
320
|
|
|
277
321
|
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.
|