designsource 0.4.0 → 0.5.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 +104 -17
- package/dist/index.js +2666 -256
- package/package.json +7 -6
package/README.md
CHANGED
|
@@ -4,14 +4,20 @@
|
|
|
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. Five things it does:
|
|
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. 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.
|
|
9
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.
|
|
10
12
|
- **`create`** — start a new Next.js project from it: tokens, all 61 components, the block pages (`/blocks`) and your mockup page, running after `pnpm install && pnpm dev`.
|
|
11
|
-
- **`mcp`** — serve the design system to your coding agent over MCP: tokens, every component's source, your mockup page and a step-by-step integration guide, read on demand instead of pasted. Claude Code, Cursor, Codex — any client that speaks MCP over stdio.
|
|
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.
|
|
12
14
|
|
|
13
15
|
```sh
|
|
14
|
-
npx designsource
|
|
16
|
+
npx designsource add
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
npx designsource connect
|
|
15
21
|
```
|
|
16
22
|
|
|
17
23
|
```sh
|
|
@@ -27,16 +33,87 @@ Works the same with `pnpm dlx designsource …`, `yarn dlx designsource …` and
|
|
|
27
33
|
## How it works
|
|
28
34
|
|
|
29
35
|
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.
|
|
30
|
-
2. Run the command. It asks with the arrow keys where there is a list to pick from, asks for a folder, and asks for your **project token** (workbench → Project settings). The token is typed hidden, sent
|
|
36
|
+
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.
|
|
31
37
|
3. Your app has the system in it: every colour, radius and shadow on screen is a token from your design system.
|
|
32
38
|
|
|
33
|
-
## `
|
|
39
|
+
## `add` — the UI kit in the app you have
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
npx designsource add [names…] [--all] [--yes] [--force] [--skip-install] [--token <project token>] [--api <origin>]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
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.
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
? Add which components? ❯ All
|
|
49
|
+
Pick some…
|
|
50
|
+
Adding theme… ✓
|
|
51
|
+
Adding 61 components… ✓
|
|
52
|
+
Installing libraries… ✓
|
|
53
|
+
Done. Your components now use "my-system" from designsource.app.
|
|
54
|
+
Run it again any time to pull updates.
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- **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.
|
|
58
|
+
- **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.
|
|
59
|
+
- **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.
|
|
60
|
+
- **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.
|
|
61
|
+
- **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.
|
|
62
|
+
- **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.
|
|
63
|
+
- **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.
|
|
64
|
+
- **`--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.
|
|
65
|
+
|
|
66
|
+
## `connect` — your coding apps, connected
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
npx designsource connect [--apps claude,cursor,vscode,codex,gemini] [--yes] [--token <project token>] [--api <origin>]
|
|
70
|
+
npx designsource connect --forget [--project <id>]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
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.
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
Connecting /Users/you/acme-app
|
|
77
|
+
Connect which apps? Claude Code, Cursor, VS Code
|
|
78
|
+
Project token (workbench → Project settings):
|
|
79
|
+
Saved your token for "Acme" in the macOS keychain ✓
|
|
80
|
+
Claude Code .mcp.json ✓
|
|
81
|
+
Cursor .cursor/mcp.json ✓
|
|
82
|
+
VS Code .vscode/mcp.json ✓
|
|
83
|
+
Done.
|
|
84
|
+
Restart Cursor and VS Code.
|
|
85
|
+
Claude Code asks once to allow the server.
|
|
86
|
+
Then ask your agent to add the UI kit.
|
|
87
|
+
These files hold no token and are safe to commit; teammates run npx designsource connect once.
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
| App | File | Entry |
|
|
91
|
+
| --- | --- | --- |
|
|
92
|
+
| Claude Code | `.mcp.json` | `mcpServers.designsource` |
|
|
93
|
+
| Cursor | `.cursor/mcp.json` | `mcpServers.designsource`, `type: "stdio"` |
|
|
94
|
+
| VS Code (Copilot) | `.vscode/mcp.json` | `servers.designsource`, `type: "stdio"` |
|
|
95
|
+
| Codex | `.codex/config.toml` | `[mcp_servers.designsource]`, with `startup_timeout_sec = 60` |
|
|
96
|
+
| Gemini CLI | `.gemini/settings.json` | `mcpServers.designsource` |
|
|
97
|
+
|
|
98
|
+
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.
|
|
99
|
+
|
|
100
|
+
- **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.
|
|
101
|
+
- **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.
|
|
102
|
+
- **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.
|
|
103
|
+
- **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.
|
|
104
|
+
- **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.
|
|
105
|
+
- **`--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`; passing `--api` still wins, and connecting again without it on the default removes it.
|
|
106
|
+
- **`--apps`** names the apps and skips the question; **`--yes`** (and any run outside a terminal) takes the apps found on this computer.
|
|
107
|
+
- **`--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>`.
|
|
108
|
+
- **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).
|
|
109
|
+
|
|
110
|
+
## `integrate` — design-system files for another stack
|
|
34
111
|
|
|
35
112
|
```sh
|
|
36
113
|
npx designsource integrate [folder] [--framework vue|svelte|angular|css] [--token <project token>] [--api <origin>] [--force]
|
|
37
114
|
```
|
|
38
115
|
|
|
39
|
-
Writes `design-system/` into the folder (default: the current one). Refuses when that folder already has one, unless `--force`.
|
|
116
|
+
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`.
|
|
40
117
|
|
|
41
118
|
| File | What it is |
|
|
42
119
|
| --- | --- |
|
|
@@ -66,10 +143,10 @@ Writes a runnable Next.js app into a new or empty folder (default `my-design-sys
|
|
|
66
143
|
## `mcp` — serve it to a coding agent
|
|
67
144
|
|
|
68
145
|
```sh
|
|
69
|
-
npx designsource mcp [--token <project token>] [--api <origin>]
|
|
146
|
+
npx designsource mcp [--project <id>] [--token <project token>] [--api <origin>]
|
|
70
147
|
```
|
|
71
148
|
|
|
72
|
-
Not a command you run in a terminal: put it in your MCP client's config and the agent runs it. The server is plain stdio MCP, so every client takes the same command and env — only the config file's shape differs.
|
|
149
|
+
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.
|
|
73
150
|
|
|
74
151
|
| Client | Config | Shape |
|
|
75
152
|
| --- | --- | --- |
|
|
@@ -118,7 +195,7 @@ VS Code:
|
|
|
118
195
|
}
|
|
119
196
|
```
|
|
120
197
|
|
|
121
|
-
The workbench's
|
|
198
|
+
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.
|
|
122
199
|
|
|
123
200
|
| Tool | Returns |
|
|
124
201
|
| --- | --- |
|
|
@@ -132,27 +209,35 @@ The workbench's Copy dialog hands out all three. Then ask the agent to integrate
|
|
|
132
209
|
| `get_integration_guide` | The steps: wire the tokens, bring in the components, migrate existing styles, document. |
|
|
133
210
|
| `list_blocks` | The 34 ready-made page layouts (login, signup, sidebars, a dashboard, chart sets) with the components and files of each. |
|
|
134
211
|
| `get_block_source` | Every file of one block, headed by the path it takes under `components/blocks/`. |
|
|
212
|
+
| `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`. Optional `components` and `replace_existing` (for files designsource did not write). |
|
|
135
213
|
|
|
136
214
|
New in 0.4.0: `list_blocks` and `get_block_source`, the page layouts built from the components. `create` now also writes them as `/blocks` pages, and `integrate` drops them under `design-system/reference/blocks/`. Against an older server the two tools answer that the server sent no blocks.
|
|
137
215
|
|
|
138
|
-
|
|
216
|
+
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.
|
|
139
217
|
|
|
140
218
|
## Options
|
|
141
219
|
|
|
142
220
|
| Flag | What it does |
|
|
143
221
|
| --- | --- |
|
|
144
|
-
| `folder` | Target folder. `integrate` defaults to `.`, `create` to `my-design-system`; `mcp`
|
|
222
|
+
| `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). |
|
|
223
|
+
| `names` | `add` only. Components to add, plus the kit files they import. |
|
|
224
|
+
| `--all` | `add` only. Every component, no question. |
|
|
225
|
+
| `--yes` | `add` and `connect`. No questions, also outside a terminal: for `add`, all components on a first run, your edits kept; for `connect`, the apps found on this computer. |
|
|
226
|
+
| `--apps` | `connect` only. The apps to set up, comma-separated: `claude`, `cursor`, `vscode`, `codex`, `gemini`. |
|
|
227
|
+
| `--forget` | `connect` only. Remove this folder's saved token from this computer. |
|
|
228
|
+
| `--project` | `mcp`: the saved project whose token to use. `connect --forget`: which project, when several are connected to the folder. |
|
|
229
|
+
| `--skip-install` | `add` only. Write the files, print the install command. |
|
|
145
230
|
| `--framework` | `integrate` only. Skip the picker: `vue`, `svelte`, `angular` or `css`. |
|
|
146
|
-
| `--token` | The project token, or set `DS_SYNC_TOKEN` for scripts.
|
|
231
|
+
| `--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. |
|
|
147
232
|
| `--api` | API origin. Default `https://designsource.app`; point it at a self-hosted instance. |
|
|
148
|
-
| `--force` | `integrate` and `create
|
|
233
|
+
| `--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. |
|
|
149
234
|
|
|
150
|
-
Outside a terminal (CI, pipes) the pickers become numbered prompts, and
|
|
235
|
+
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.
|
|
151
236
|
|
|
152
237
|
## Safety
|
|
153
238
|
|
|
154
|
-
- 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.
|
|
155
|
-
- The project token authorises read-only access to one project. Regenerate it in Project settings to revoke it; the
|
|
239
|
+
- 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.
|
|
240
|
+
- 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.
|
|
156
241
|
- Zero runtime dependencies. Node 20 or newer.
|
|
157
242
|
|
|
158
243
|
## Local development
|
|
@@ -166,6 +251,8 @@ pnpm --filter designsource start -- create my-app --api http://localhost:3001
|
|
|
166
251
|
DS_SYNC_TOKEN=<project token> pnpm --filter designsource start -- mcp --api http://localhost:3001
|
|
167
252
|
```
|
|
168
253
|
|
|
254
|
+
`add` works in the current folder, and `pnpm --filter` runs from `apps/designsource`, so run the built file from inside a scratch React app instead: `node <repo>/apps/designsource/dist/index.js add --api http://localhost:3001`.
|
|
255
|
+
|
|
169
256
|
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.
|
|
170
257
|
|
|
171
258
|
`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.
|
|
@@ -179,7 +266,7 @@ By the maintainer, through GitHub Actions with npm trusted publishing: no npm to
|
|
|
179
266
|
3. Tag the merge commit `designsource@<version>` and push the tag:
|
|
180
267
|
|
|
181
268
|
```sh
|
|
182
|
-
git tag designsource@0.
|
|
269
|
+
git tag designsource@0.5.0 && git push origin designsource@0.5.0
|
|
183
270
|
```
|
|
184
271
|
|
|
185
272
|
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.
|