@orkestralai/codesignflo 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@orkestralai/codesignflo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "CoDesignFlo CLI — keeps a Figma mirror of your Storybook in step with the code and brings designers' proposals back as code changes.",
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "codesignflo": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "THIRD_PARTY.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "playwright": "^1.63.0",
+    "ws": "^8.22.0",
+    "pngjs": "^7.0.0",
+    "pixelmatch": "^7.2.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orkestralai/codesignflo.git"
+  }
+}

package/skills/codesignflo-deliver/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: codesignflo-deliver
+description: Implement a designer's CoDesignFlo proposal in code — a ready-for-dev change to an existing component, or a brand-new component designed in Figma. Use when sync reports "ready:" or "new design:", or when the user asks to apply, implement or deliver the designer's changes.
+---
+
+# CoDesignFlo deliver
+
+The designer marked a proposal **Ready for dev** (or sent a **New design**). The CLI has already computed exactly what changed; you implement it in this session so the user sees and can steer every edit, then the CLI verifies it against the designer's copy.
+
+Run commands from the folder that contains `.codesignflo/` (use the project's package script if it has one, e.g. `pnpm codesignflo …`).
+
+**`deliver` takes minutes** (it runs Claude Code to build; a new page can take 10+ minutes): run it in the foreground with a long timeout (e.g. 20 minutes). Don't start it in the background and end your turn — in a headless session the job dies with the session.
+
+**Any way of implementing works.** CoDesignFlo closes a proposal when the code does what the designer asked — however it got there (this session, by hand, a PR merged later, a ticket). The `CoDesignFlo:` line in a commit is optional: it records which commit delivered it, and lets sync send unimplemented parts back to the designer with your notes.
+
+## 1. Make sure the changes are current
+
+If `sync` hasn't run since the designer marked it ready, run the `codesignflo-sync` skill first.
+
+## Clashes first
+
+If sync said `ready: <component> — … N conflicting`, the designer changed things that the code also changed since they claimed it. Their panel warned them ("the developer changed this too") and they sent it anyway, so **their version wins by default**:
+
+```sh
+npx codesignflo resolve <component> --design
+npx codesignflo sync
+```
+
+Only if the code's version must stay (a functional reason, not taste), ask the user, then `resolve <component> --code "<the reason, for the designer>"`: it goes back to the designer with that reason.
+
+## 2a. Changes to an existing component
+
+```sh
+npx codesignflo deliver <component> --track
+```
+
+This prints a hand-off (also saved as `.codesignflo/proposals/<component>/<claim>/HANDOFF.md`): the designer's note, the files, and one line per change (`C1 [kind] layer — property: from → to (scope)`), plus the commit trailer.
+
+Implement each change:
+- Layer names are CSS-module class names (or `data-cdf` names): `body/price` is the element with class `styles.price` inside `styles.body`. `a > b` means layer `b` inside the nested component `a`.
+- A layer named `<layer>-margin` (or `-margin-top` / `-margin-left`) stands for the CSS margin after (before) `<layer>`; a change to its size is a change to that margin.
+- A change that uses a Figma variable which is not a project token yet ("is not a project token yet") is still the designer's decision: add the token to the project's tokens file under the name given, with the value given, and use its CSS variable. Don't swap in a similar existing token.
+- Values given as tokens (`var(--space-3)`) must be used as tokens, never raw values.
+- "size" changes give width/height and how it sizes (FIXED, HUG = fits content, FILL = fills its container).
+- A change marked **ONLY when <variant>** must be a condition on the props that produce that variant; other variants stay unchanged. "(made in …, but applies to every version)" means apply it everywhere.
+- Change only the listed files and only what is listed: no refactors, no formatting, no logic changes.
+- If a change can't be implemented cleanly, don't guess: leave it out and tell the user why.
+
+Show the user the diff, then commit **with the trailer**, listing only the change ids you implemented. Put it in the message's final block of trailers — the same paragraph as any `Co-Authored-By:` line:
+
+```
+Apply design proposal to badge
+
+CoDesignFlo: badge claim=c123 items=C1,C2
+Co-Authored-By: …
+```
+
+## 2b. A new component
+
+```sh
+npx codesignflo deliver <component>
+```
+
+For a new design this builds the component from the designer's frame (`spec.json` + `design.png` in the proposal folder) with Claude Code in a new folder next to the existing components, then commits it. Afterwards review the new files with the user (read `design.png` and compare). You can instead build it yourself in this session: read the spec and picture, follow the conventions of an existing component (including its stories file, whose title must be the component's PascalCase name), add `data-cdf` names, and commit with `CoDesignFlo: <component> claim=<id> items=new`.
+
+Use `deliver <component>` without `--track` for existing components only when the user wants it done headless.
+
+## 3. Verify and close
+
+Run `codesignflo-sync`. It checks every delivered change against the designer's copy: all landed → `closed` (the designer's copy is archived); some missing → `partly delivered` and the rest goes back to the designer with your notes. For a new component, sync closes it when it appears in Storybook and reports any visual differences — then run the `codesignflo-verify` skill if the user wants them explained.

package/skills/codesignflo-status/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: codesignflo-status
+description: Answer questions about the state of design and code in a CoDesignFlo project without touching Figma — which components the designer is working on, what is ready for dev, what changed in code. Use when the user asks for the design status, open proposals, or what is waiting on them.
+---
+
+# CoDesignFlo status
+
+Read `.codesignflo/STATUS.md` (written by the last sync). Each row is a component:
+
+| State | Meaning | Who acts |
+|---|---|---|
+| In sync | Live matches the code; no open proposal | — |
+| Changed in code | code changed since the designer last looked | designer (review in Figma) |
+| In design | the designer is editing a copy | designer |
+| Ready for dev | the designer's proposal waits for implementation | developer → `codesignflo-deliver` |
+| New design | a component designed in Figma, not in code yet | developer → `codesignflo-deliver` |
+| New in code | built in code without a design | designer (accept, ignore or redesign) |
+| Needs a look | code changed in the same places the designer edited | both: talk before delivering |
+| Ignored | the designer said it needs no design | — |
+
+Summarise what is waiting on the developer first, with the designer's notes. Mention the time of the last sync (`.codesignflo/state.json` has its commit); if the user needs the designer's latest actions, they appear only after a new sync — offer `codesignflo-sync`.
+
+Details per proposal live in `.codesignflo/proposals/<component>/<claim>/` (`changes.json`, `HANDOFF.md`, `report.json`); the full history is `.codesignflo/events.jsonl` (one JSON event per line).

package/skills/codesignflo-sync/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: codesignflo-sync
+description: Keep the Figma "Live" mirror in step with the code and pick up the designer's work (CoDesignFlo). Use at the end of any task that changed UI components, pages, styles or tokens in a project with a .codesignflo/ folder; when the user asks what the designer did, whether design and code are in sync, or to sync with Figma; and before delivering design changes.
+---
+
+# CoDesignFlo sync
+
+CoDesignFlo keeps a Figma file in two parts: **Live** (generated from the code's Storybook — never edited by hand) and **Proposals** (the designer's copies). `sync` is the developer side of the loop. Everything deterministic is done by the CLI; your job is to run it at the right moment and explain the result.
+
+## Run it
+
+From the folder that contains `.codesignflo/` (the app folder):
+
+```sh
+CODESIGNFLO_WAIT_S=40 npx codesignflo sync
+```
+
+Use the project's package script instead if it defines one (e.g. `pnpm codesignflo sync`). It builds Storybook, renders it, and needs **Figma desktop open on the project's file with the CoDesignFlo plugin running**. If it says the plugin did not connect, tell the user to open the plugin in Figma (Plugins → Development → CoDesignFlo) and offer to retry — do not retry in a loop.
+
+If it says Live mirrors another branch: syncing from a feature branch would show unmerged code to the designer. Explain this; only pass `--allow-branch` if the user explicitly wants it.
+
+## Explain the output
+
+Report in plain language, most important first:
+
+- `ready: <component> — N code change(s)` → the designer finished a proposal. Offer to deliver it (skill `codesignflo-deliver`). Mention "conflicting" counts: code changed under the designer in the same places.
+- `new design: <component> …` → the designer drew a component that doesn't exist in code yet. Offer to build it (`codesignflo-deliver`).
+- `designer: <component> claimed / ready / unclaimed (…)` → what the designer did since the last sync.
+- `closed: …` → a delivered proposal was verified against the designer's copy and closed. `partly delivered` → some changes were sent back to the designer with questions; say which.
+- `! <component>: Live had been edited by hand …` → someone edited Live directly; it was saved as a proposal before Live was regenerated. Nothing is lost; the designer can continue from that proposal.
+- `N element(s) without a semantic name — run: codesignflo name` → offer to run it (it adds `data-cdf` attributes; review the diff with the user).
+- `updated` / `created` lines → Live now reflects the code changes; the designer sees them as "Changed in code".
+
+## After syncing
+
+`sync` writes files under `.codesignflo/` (ledger, snapshots, registry, `STATUS.md`). They are part of the project's history: include them in the commit with the code change that caused them (or commit them on their own: "codesignflo sync").

package/skills/codesignflo-verify/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: codesignflo-verify
+description: Check that the Figma Live mirror looks like the real UI, variant by variant, and explain any differences. Use when the user asks whether Figma matches the code, after delivering a new component, or when the designer reports that something in Live looks wrong.
+---
+
+# CoDesignFlo verify
+
+```sh
+npx codesignflo verify [component…] [--screens]
+```
+
+(From the folder with `.codesignflo/`; needs Figma open with the plugin, like sync. Run `codesignflo-sync` first if code changed since the last sync.)
+
+Each variant story is screenshotted in the browser and compared with Figma's export of its Live variant. Output: one line per variant — `✓` or `!`, sizes (browser vs Figma) and the share of differing pixels — plus images in `.codesignflo/verify/<component>/<variant>.png` laid out as **browser | Figma | difference** (differences in red), and `report.json`.
+
+For every `!` row, read its image and explain in a sentence what differs and where (e.g. "the − and + buttons are 9 px narrower in Figma", "text sits 1 px higher"). Then say which kind it is:
+
+- **Rendering limit** (not a bug in the user's code): text anti-aliasing, sub-pixel rounding, images shown as placeholders, fonts missing in Figma. Under ~3% pixels with equal sizes is usually only this.
+- **Translation gap** in CoDesignFlo (Live doesn't express some CSS yet: margins, shadows, line clamps, `line-height: normal`): Live is less faithful than the code. Note it for the CoDesignFlo maintainers; the designer should be aware when editing that component.
+- **Real difference**: Live shows an older or different state — usually solved by running sync.
+
+Never change the user's code to make Live match unless the user asks: Live is generated from the code, not the other way round.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.