design-pact 0.2.1 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ for when you want the tokens as committed project files.
 
 ## Install the skill (recommended)
 
-Get the `design-system` skill into your agent with the open
+Get the `design-pact` skill into your agent with the open
 [`skills`](https://github.com/vercel-labs/skills) CLI — one command, works
 across Claude Code / Cursor / Codex:
 
@@ -38,6 +38,9 @@ npx design-pact inspect design.md
 
 # Audit source files: find color literals outside the contract
 npx design-pact check design.md src/ app/
+
+# Derive a draft design.md from an existing codebase
+npx design-pact import src/ [--out design.md] [--force]
 ```
 
 ### `check` — enforce the contract
@@ -49,6 +52,19 @@ into CI or an agent loop: the agent generates UI against `design.md`, runs
 `check`, and fixes anything flagged. `node_modules` / build output are skipped
 automatically; whitelist intentional exceptions with `--allow "#hex,#hex"`.
 
+### `import` — adopt design-pact in an existing project
+
+`import` scans tailwind configs, CSS custom properties, and raw color usage,
+then assigns the six roles: colors from variables literally named
+background/primary/border/… win outright; the rest are filled by OKLCH
+heuristics (lightness, chroma, hue distance, contrast) and every assignment is
+labeled `named` / `heuristic` / `derived` in the summary so you know what to
+review. Radius, spacing, body font, and base size are detected when declared.
+The output is a complete design.md — dark face and status colors derived the
+same way the studio does it — and the command prints a studio URL to eyeball
+the palette before you commit to it. A dark codebase is handled correctly: it
+becomes the `@media (prefers-color-scheme: dark)` face.
+
 Outputs:
 
 | Format | File | Source |

package/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: design-system
+name: design-pact
 description: >-
   Establish and apply the project's design system. Invoke at the start of UI
   work, or whenever the user says "use my design system", "apply my tokens",
@@ -7,7 +7,7 @@ description: >-
   build/restyle UI. The skill first looks for a design.md in the repo:
   if present it generates UI against it; if absent it clarifies the product
   direction, YOU (the agent) propose 2–3 palettes, and it opens the
-  design-system web app where the user picks one visually and tunes it into a full
+  design-pact studio where the user picks one visually and tunes it into a full
   design system to export. All AI runs on the agent's own compute — the web app has no AI and
   no backend.
 ---
@@ -15,7 +15,7 @@ description: >-
 # Design system
 
 The project's design system lives in a single file — `design.md` at the
-repo root — exported from the design-system web app. It carries the canonical
+repo root — exported from the design-pact studio. It carries the canonical
 color / type / spacing / radius / shadow / motion tokens plus a copy-verbatim
 `:root` contract. That one file is the source of truth; you do not need the web
 app or network access once it exists.
@@ -30,7 +30,7 @@ Look for `design.md`, in order:
 1. A path the user gave you.
 2. `design.md` at the repo root.
 3. Search the repo for the file's frontmatter marker:
-   `rg -l "^design-system:" --type md`.
+   `rg -l "^design-pact:" --type md`.
 
 Then branch:
 
@@ -41,6 +41,18 @@ Then branch:
 
 ## Create — no design.md yet
 
+**If the project already has real styling** (a tailwind config, CSS custom
+properties, an established look), offer to derive the draft from it instead of
+inventing palettes:
+
+```bash
+npx design-pact import <src-dirs> --out design.md
+```
+
+Show the user the printed summary + studio link to confirm the mapping, then
+continue to **Apply**. Only fall through to palette proposal when the project
+is greenfield or the user wants a fresh direction.
+
 There's no design system yet. The division of labor: **you (the agent) do the
 creative part — clarify direction and propose 2–3 palettes; the web app does
 the deterministic part — render each palette so the user picks one visually,
@@ -157,7 +169,7 @@ can still switch in the top-right). Omit it and the app falls back to the
 browser language. Only matters on the user's first visit; after that their
 own choice is remembered.
 
-Full URL: `http://localhost:3000/?<query>` (`DESIGN_SYSTEM_URL` defaults to
+Full URL: `http://localhost:3000/?<query>` (`DESIGN_PACT_URL` defaults to
 `http://localhost:3000`; use a hosted URL if the user has one and skip the CLI).
 
 **Do these IN ORDER. Step 1 always happens — even if 2 fails, the printed URL is