canicode 0.9.1 → 0.10.0

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://github.com/let-sunny/canicode/actions/workflows/release.yml"><img src="https://github.com/let-sunny/canicode/actions/workflows/release.yml/badge.svg" alt="Release"></a>
 </p>
 
-<p align="center"><strong>Stop explaining your designs. Get scored by AI-calibrated rules.</strong></p>
+<p align="center"><strong>Make your Figma file information-complete — so AI generates code that actually works.</strong></p>
 
 <p align="center">
   <strong><a href="https://let-sunny.github.io/canicode/">Try it in your browser</a></strong> — no install needed.
@@ -22,28 +22,30 @@
 
 ---
 
-## Why CanICode
+## How it works
 
-AI can turn Figma designs into code — but the quality depends heavily on **how the design is structured**. Missing Auto Layout drops pixel accuracy from 95% to 63% at different viewports. Raw JSON input wastes 5× more tokens for 15%p worse results.
+AI can turn Figma designs into code — but the quality depends heavily on **how the design is structured**. CanICode runs a **roundtrip** over your Figma file: analyze the design, surface the gotchas it can't answer on its own, apply fixes back to Figma, re-analyze until the design is clean, then hand off to Figma's `figma-implement-design` skill for code generation. canicode does the design augmentation; code generation lives downstream (see [ADR-013](.claude/docs/ADR.md) for the scope boundary).
 
-CanICode solves this:
-
-1. **Analyzes** your Figma design for patterns that hurt AI implementation quality
-2. **Generates a design-tree** — a curated, CSS-ready representation that AI implements more accurately and efficiently than raw Figma data
-3. **Scores** responsive readiness, so you fix the design before generating code
+### How the analyzer knows what to fix
 
 - **16 rules** across 6 categories: Pixel Critical, Responsive Critical, Code Quality, Token Management, Interaction, Semantic
 - **Deterministic** — no AI tokens consumed per analysis, runs in milliseconds
-- **Validated** — [ablation experiments](https://github.com/let-sunny/canicode/wiki) confirmed design-tree achieves 94% pixel accuracy with 5× fewer tokens than raw JSON
+- **Ablation-validated** — [experiments](https://github.com/let-sunny/canicode/wiki) confirmed the curated design-tree achieves 94% pixel accuracy with 5× fewer tokens than raw JSON
 
-### Scores You Can Trust
+Rule scores aren't guesswork. The calibration pipeline converts real Figma designs to HTML, measures pixel-level similarity (via `visual-compare`), and adjusts scores based on actual implementation difficulty — hard-to-implement patterns get a higher penalty, easy ones get demoted. The pipeline runs on community fixtures, not on every analysis. See the [Calibration wiki](https://github.com/let-sunny/canicode/wiki/Calibration).
 
-Rule scores aren't guesswork. The calibration pipeline converts real Figma designs to HTML, measures pixel-level similarity (via `visual-compare`), and adjusts scores based on actual implementation difficulty.
+---
 
-- Design that's hard to implement accurately → rule score goes **up**
-- Design that's easy despite the flag → rule score goes **down**
+## The Roundtrip Workflow
 
-The pipeline runs on community fixtures, not on every analysis. Strip ablation uses six `DESIGN_TREE_INFO_TYPES` passes (including `size-constraints` for responsive sizing rules — see [`CLAUDE.md`](CLAUDE.md)). See the [Calibration wiki](https://github.com/let-sunny/canicode/wiki/Calibration).
+1. **Analyze** — run the 16 rules against the Figma design and grade it.
+2. **Surface gotchas** — the analyzer emits questions for design information it can't infer (missing states, unclear variants, responsive intent).
+3. **Apply fixes to Figma** — the `/canicode-roundtrip` skill writes answers back via `use_figma`. Each write shows up in the summary with one of three outcome markers:
+   - ✅ **scene write succeeded** — the property was written directly to the scene node or instance override.
+   - 📝 **annotated the scene node** — the skill left a structured annotation instead of writing the property. This is the [ADR-012](.claude/docs/ADR.md) default for instance-child layout writes, because propagating a property to the component definition (and therefore every instance of it) is almost never what the user wants. **A summary full of 📝 markers is correct behavior, not failure.**
+   - 🌐 **definition write propagated** — the property was written to the component definition and every instance inherited it. Only happens when the user opted in up front with `allowDefinitionWrite`.
+4. **Re-analyze** — verify the grade improved. Repeat step 2 if new gotchas surface.
+5. **Hand off** to `figma-implement-design` — canicode's scope ends here ([ADR-013](.claude/docs/ADR.md)). Figma's official code-generation skill takes the now-clean design and produces code.
 
 ---
 
@@ -51,7 +53,19 @@ The pipeline runs on community fixtures, not on every analysis. Strip ablation u
 
 **Quickest way:** **[Open the web app](https://let-sunny.github.io/canicode/)** — paste a Figma URL, get a report.
 
-**For your workflow:**
+**Design-to-code in Claude Code (recommended):**
+
+```bash
+# 1. Save your Figma token AND install the /canicode-roundtrip skill
+canicode init --token figd_xxxxxxxxxxxxx
+
+# 2. Run the roundtrip on a Figma URL
+/canicode-roundtrip https://www.figma.com/design/ABC123/MyDesign?node-id=1-234
+```
+
+> **Prerequisite:** the roundtrip skill calls the Figma MCP server to read and write the design. Install it once with `claude mcp add -s project -t http figma https://mcp.figma.com/mcp` — see the **MCP Server** install section below.
+
+**If you only want analysis (no writes back to Figma):**
 
 ```bash
 # CLI — one command
@@ -69,9 +83,9 @@ claude mcp add canicode -- npx -y -p canicode canicode-mcp
 | **[Web App](https://let-sunny.github.io/canicode/)** | Quick check, no install |
 | **[Figma Plugin](https://www.figma.com/community/plugin/1617144221046795292/canicode)** | Analyze inside Figma (under review) |
 | **MCP Server** | Claude Code / Cursor / Claude Desktop integration |
-| **Claude Code Skill** | Lightweight, no MCP install |
+| **`/canicode-roundtrip` Skill** | Full design-to-code roundtrip via Claude Code (analyze → fix → re-analyze → handoff) |
+| **`/canicode` Skill** | Lightweight analyze-only skill, no MCP install |
 | **CLI** | Full control, CI/CD, offline analysis |
-| **`canicode implement`** | Generate code-ready package (analysis + assets + prompt) |
 | **[GitHub Action](https://github.com/marketplace/actions/canicode-action)** | PR gate with score threshold |
 
 </details>
@@ -102,7 +116,7 @@ Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggest
 npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 ```
 
-Setup: `canicode init --token figd_xxxxxxxxxxxxx`
+Setup: `canicode init --token figd_xxxxxxxxxxxxx` — saves the token AND installs the Claude Code skills (see below).
 
 > **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token
 
@@ -113,7 +127,7 @@ Setup: `canicode init --token figd_xxxxxxxxxxxxx`
 | View, Collab | 6 req/month | 6 req/month |
 | Dev, Full | 6 req/month | 10–20 req/min |
 
-Hitting 429 errors? Make sure the file is in a paid workspace. Or `save-fixture` once and analyze locally. [Full details](https://developers.figma.com/docs/rest-api/rate-limits/)
+Hitting 429 errors? Make sure the file is in a paid workspace. Or save a fixture once and analyze locally. [Full details](https://developers.figma.com/docs/rest-api/rate-limits/)
 
 </details>
 
@@ -140,38 +154,19 @@ For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZA
 
 
 <details>
-<summary><strong>Design to Code</strong> (prepare implementation package)</summary>
+<summary><strong>Claude Code Skills</strong> (lightweight, no MCP install)</summary>
 
 ```bash
-canicode implement ./fixtures/my-design
-canicode implement "https://www.figma.com/design/ABC/File?node-id=1-234" --prompt ./my-react-prompt.md --image-scale 3
+canicode init --token figd_xxxxxxxxxxxxx
 ```
 
-Outputs a ready-to-use package for AI code generation:
-- `analysis.json` — issues + scores
-- `design-tree.txt` — DOM-like tree with CSS styles + token estimate
-- `images/` — PNG assets with human-readable names (`hero-banner@2x.png`)
-- `vectors/` — SVG assets
-- `PROMPT.md` — code generation prompt (default: HTML+CSS, or your custom prompt)
+Saves your Figma token AND installs three skills into `./.claude/skills/`:
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--prompt` | built-in HTML+CSS | Path to your custom prompt file for any stack |
-| `--image-scale` | `2` | Image export scale: `2` for PC, `3` for mobile |
-| `--output` | `./canicode-implement/` | Output directory |
-
-Feed `design-tree.txt` + `PROMPT.md` to your AI assistant (Claude, Cursor, etc.) to generate code.
-
-</details>
-
-<details>
-<summary><strong>Claude Code Skill</strong> (lightweight, no MCP install)</summary>
-
-```bash
-cp -r .claude/skills/canicode /your-project/.claude/skills/
-```
+- **canicode** — lightweight CLI wrapper (use `/canicode <figma-url>`)
+- **canicode-gotchas** — standalone gotcha survey (use `/canicode-gotchas <figma-url>`)
+- **canicode-roundtrip** — full analyze → gotcha → apply roundtrip (use `/canicode-roundtrip <figma-url>`)
 
-Requires FIGMA_TOKEN. Then use `/canicode` with a Figma URL.
+Flags: `--global` installs into `~/.claude/skills/` instead. `--no-skills` skips skill install (token only). `--force` overwrites existing skill files without prompting. Run `canicode docs setup` for the full setup guide.
 
 </details>