canicode 0.12.2 → 0.12.4

package/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres
+to [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and, once
+published as v1, will follow [Semantic Versioning](https://semver.org/).
+While in v0.x, minor versions may carry breaking changes — they are called
+out explicitly in the relevant entry.
+
+Each entry summarises the user-visible change. Per-PR detail lives in the
+[GitHub release notes](https://github.com/let-sunny/canicode/releases) for
+the corresponding tag, and architecture rationale lives in
+[ADR.md](.claude/docs/ADR.md).
+
+## [Unreleased]
+
+## [0.12.3] - 2026-04-29
+
+### Added
+
+- **Phase 3 — bootstrap a design system from screens** (Workflow 3 epic
+  [#508](https://github.com/let-sunny/canicode/issues/508)) shipped GA. After
+  upgrading, `canicode-roundtrip` performs the full **componentize+swap loop**
+  end-to-end on any Stage 3 (`missing-component:structure-repetition`) group:
+  one `yes` answer componentizes the document-order first member and swaps
+  the rest with instances of the new component. Optional Code Connect
+  registration follows automatically when prereqs are present.
+- `applyComponentize` apply primitive — wraps `figma.createComponentFromNode`
+  with the #368 instance-child guard and the ADR-023 decision A free-form
+  parent guard. Annotate-fallback on every rejection.
+- `applyReplaceWithInstance` apply primitive — wraps
+  `mainComponent.createInstance()` + `parent.insertChild` + `target.remove()`
+  with an independent swap-site free-form check.
+- `applyGroupComponentize` orchestrator — drives the full loop from a
+  single user `yes` answer; aggregates per-target outcomes into a single
+  Step 4 line.
+- `groupMembers` field on `RuleViolation` and `GotchaSurveyQuestion` —
+  every node id in a Stage 3 fingerprint group surfaces in the survey
+  output so the apply step can iterate the whole group.
+- `RuleContext.analysisRoot` — Stage 3 (and now Stage 1/2) walks the
+  active analysis subtree instead of the full file, fixing a silent scope
+  leak under `--target-node-id` analysis.
+- ADR-023 — Phase 3 design decisions A–E (free-form parent guard, no
+  override threshold, name-collision auto-suffix in Figma's native ` 2`
+  pattern, shared question UI for Forward/Reverse with `mode` field on the
+  answer, silent-skip Code Connect handoff).
+
+### Changed
+
+- Stage 3 `missing-component:structure-repetition` is now **scope-wide**:
+  duplicates spread across different parents within the analysis scope
+  fold into the same fingerprint group instead of being missed by the old
+  sibling-only walk. Message wording updates from `N sibling frame(s)` to
+  `N other frame(s)`.
+- Stage 1 (`unused-component`) and Stage 2 (`name-repetition`) now also
+  honour `analysisRoot` for the frame-name walk — fixes the same
+  silent-skip pattern when `--target-node-id` scopes the run.
+
+### Documentation
+
+- WORKFLOWS.md Workflow 3 promoted to ✅ Available with the new Today's
+  flow, the bundled apply primitives, and two known limits (per-member
+  opt-out, Stage 1 reverse case).
+
+## [0.12.2] - 2026-04-28
+
+### Fixed
+
+- canicode-roundtrip Phase 2 live-verification follow-ups
+  ([#545](https://github.com/let-sunny/canicode/issues/545),
+  [#546](https://github.com/let-sunny/canicode/issues/546),
+  [#547](https://github.com/let-sunny/canicode/issues/547),
+  [#548](https://github.com/let-sunny/canicode/issues/548)) bundled into a
+  single SKILL prose update — one batch per message pacing, output
+  language detection, grade-movement attribution, and Step 1.5 doctor
+  inconclusive handling on screen-scope FRAME URLs.
+
+## [0.12.1] - 2026-04-28
+
+### Added
+
+- `canicode doctor --figma-url <url>` publish-status pre-check
+  ([#532](https://github.com/let-sunny/canicode/issues/532)) — verifies
+  the target Figma component is published in a library before the
+  roundtrip's closing Code Connect mapping step asks the satisfaction
+  prompt. Surfaces inconclusive when `FIGMA_TOKEN` is not configured or
+  the URL has no node-id; failure cases print remediation hints.
+- `unmapped-component` v1.5 — parser-driven main check
+  ([#526](https://github.com/let-sunny/canicode/issues/526)) and
+  acknowledgment-channel opt-out write path
+  ([#543](https://github.com/let-sunny/canicode/issues/543)) so designers
+  can mark a component "intentionally unmapped" and have the rule
+  silently skip it on subsequent roundtrips.
+- ADR-022 — `unmapped-component` opt-out via the existing acknowledgment
+  channel + the REST private-beta annotations field gating that limits
+  standalone analyze visibility.
+
+### Fixed
+
+- Bridge `CanICodeRoundtrip` onto `globalThis` inside `eval`
+  ([#533](https://github.com/let-sunny/canicode/issues/533)) so the
+  bundled IIFE survives Plugin API hosts that wrap the script in a
+  shadowed scope.
+
+### Documentation
+
+- SKILL Step 4 inline-staging guidance + Step 7d single-mapping path
+  ([#531](https://github.com/let-sunny/canicode/issues/531),
+  [#534](https://github.com/let-sunny/canicode/issues/534)).
+
+## [0.12.0] - 2026-04-27
+
+### Added
+
+- **Phase 1 — component-to-code mapping** roundtrip closing step
+  ([#515](https://github.com/let-sunny/canicode/issues/515)): after
+  `figma-implement-design` finishes, the roundtrip prompts for
+  satisfaction and registers a Code Connect mapping
+  (`add_code_connect_map` + `send_code_connect_mappings`) so future
+  roundtrips on screens containing the same component reuse the
+  generated code instead of regenerating markup.
+- `canicode doctor` — verifies `@figma/code-connect` install and
+  `figma.config.json` presence in the user's repo before the roundtrip
+  reaches the mapping step
+  ([#512](https://github.com/let-sunny/canicode/issues/512)).
+- `unmapped-component` analyze rule
+  ([#520](https://github.com/let-sunny/canicode/issues/520)) — flags
+  Figma components that have no Code Connect mapping yet, with the
+  optional Workflow 1 onboarding pointer.
+- New `note` severity tier (zero score impact) for annotation-primary
+  rules whose value is the nudge, not the score
+  ([#519](https://github.com/let-sunny/canicode/issues/519)). Backfills
+  `missing-prototype`, `missing-interaction-state`,
+  `missing-size-constraint`, `unmapped-component`.
+- ADR-021 — handoff carriers and conflict resolution between
+  `canicode-roundtrip` and `figma-implement-design`.
+- WORKFLOWS.md — new 3-phase canicode bootstrap roadmap document
+  ([#511](https://github.com/let-sunny/canicode/issues/511)).
+
+### Changed
+
+- `canicode init` split into interactive setup + a separate
+  `canicode config set-token` subcommand
+  ([#506](https://github.com/let-sunny/canicode/issues/506)). Existing
+  users who relied on the old combined flow should move the token-only
+  step to `config set-token`.
+- Stripped internal issue / ADR refs from user-facing surfaces
+  ([#504](https://github.com/let-sunny/canicode/issues/504)) so the
+  README and SKILL prose read cleanly to a first-time user.
+
+## [0.11.5] - 2026-04-25
+
+### Added
+
+- Claude Code marketplace manifest
+  ([#497](https://github.com/let-sunny/canicode/issues/497)) so canicode
+  appears in Claude Code's plugin/skill catalogue.
+- "Other agents" install guide for non-Claude/Cursor hosts
+  ([#502](https://github.com/let-sunny/canicode/issues/502)) — manual
+  skill copy instructions for hosts that do not auto-discover skills.
+
+### Documentation
+
+- Polished `canicode init` path docs
+  ([#499](https://github.com/let-sunny/canicode/issues/499)) following
+  user-flow testing.
+
+[Unreleased]: https://github.com/let-sunny/canicode/compare/v0.12.3...HEAD
+[0.12.3]: https://github.com/let-sunny/canicode/compare/v0.12.2...v0.12.3
+[0.12.2]: https://github.com/let-sunny/canicode/compare/v0.12.1...v0.12.2
+[0.12.1]: https://github.com/let-sunny/canicode/compare/v0.12.0...v0.12.1
+[0.12.0]: https://github.com/let-sunny/canicode/compare/v0.11.5...v0.12.0
+[0.11.5]: https://github.com/let-sunny/canicode/compare/v0.11.4...v0.11.5

package/README.md

@@ -6,11 +6,12 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/canicode"><img src="https://img.shields.io/npm/v/canicode.svg" alt="npm version"></a>
+  <a href="https://www.figma.com/community/plugin/1617144221046795292/can-i-code"><img src="https://img.shields.io/badge/Figma-Plugin-F24E1E?logo=figma&logoColor=white" alt="Figma Plugin"></a>
   <a href="https://github.com/let-sunny/canicode/actions/workflows/ci.yml"><img src="https://github.com/let-sunny/canicode/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <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>Make your Figma file information-complete — so AI generates code that actually works.</strong></p>
+<p align="center"><strong>Ship your Figma design exactly as you intended — without learning CSS.</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,19 +23,41 @@
 
 ---
 
-## How it works
+## What canicode does
 
-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.
+You designed it in Figma. You know exactly how it should look and behave — but the AI codegen guesses, and half the time it guesses wrong. The cards don't stack on mobile. The hover state disappears. The padding gets normalised. *That's not what I designed.*
 
-![Role diagram: gotchas (memo) vs roundtrip (canvas) vs code-gen](docs/images/roles.svg)
+canicode is the **pre-implementation interview** between your Figma file and AI codegen. It asks the questions a developer would ask before they implement — in plain language you can answer:
 
-### How the analyzer knows what to fix
+> *"The three cards are side-by-side at desktop width — what should happen when the screen is narrow?"*
 
-- **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
-- **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
+You answer in plain words ("좁아지면 한 줄에 하나씩" / "stack them vertically"). canicode translates that into the exact technical spec the codegen needs, and writes it back into your Figma file as a structured annotation so the next run no longer has to guess.
 
-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).
+You stay in Figma. You never type a CSS selector. The intent ships.
+
+→ Full thesis: [docs/POSITIONING.md](docs/POSITIONING.md)
+
+### The three layers
+
+1. **Linter** — 17 rules surface the gaps your craft instinct senses but can't name. *"Something's off with this spacing."* → it finds the one card with 14px padding while the rest are 16px.
+2. **Q&A scaffolding** — for every gap, canicode asks in your vocabulary, not the developer's. You answer, it spec'ifies.
+3. **Roundtrip persistence** — answers live in the Figma file as Dev Mode annotations. Next run, next person, next codegen — they all see the intent.
+
+The linter is deterministic (no LLM tokens consumed for the analysis itself), [ablation-validated](https://github.com/let-sunny/canicode/wiki) at 94% pixel accuracy with 5× fewer tokens than raw JSON, and [calibrated](https://github.com/let-sunny/canicode/wiki/Calibration) against real Figma designs.
+
+---
+
+## Why canicode (vs Claude Design)
+
+[Claude Design](https://www.anthropic.com/news/claude-design) launched in April 2026 and covers the **prompt → app** path beautifully — AI designs from your prompt and hands the result to Claude Code. canicode covers a different workflow:
+
+|  | Claude Design | canicode |
+|---|---|---|
+| Who designs | AI (from a prompt) | The designer (in Figma) |
+
+If you want the AI to design for you, use Claude Design. If you already designed it and want it implemented exactly the way you intended, canicode is for you. The two are not in competition — they assume different things about who owns the design.
+
+See [docs/POSITIONING.md](docs/POSITIONING.md) for the full thesis (target persona, the workflow assumption, and what canicode is **not** for).
 
 ---
 
@@ -42,7 +65,7 @@ Rule scores aren't guesswork. The calibration pipeline converts real Figma desig
 
 **Skills:** **`canicode-gotchas`** = survey answers saved **locally** in SKILL.md only (memo). **`canicode-roundtrip`** = same analysis path plus **writes to Figma** (annotations / properties). Pick gotchas for capture-only; pick roundtrip when the design file should change.
 
-1. **Analyze** — run the 16 rules against the Figma design (report includes grade).
+1. **Analyze** — run the 17 rules against the Figma design (report includes grade).
 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.
@@ -54,71 +77,27 @@ Rule scores aren't guesswork. The calibration pipeline converts real Figma desig
 
 ---
 
-## Getting Started
-
-> **Token safety:** Do **not** paste your Figma token into Claude, Cursor, or other agent chats — session logs can retain it. Use `FIGMA_TOKEN=figd_… npx canicode init`, or run `npx canicode init` and enter the token **only** at the CLI prompt.
+## Try it in 30 seconds
 
-**Quickest way:** **[Open the web app](https://let-sunny.github.io/canicode/)** — paste a Figma URL, get a report.
+1. **[Open the web app](https://let-sunny.github.io/canicode/)** — paste any Figma URL, get a report. No install, no token, no AI cost. This is the linter view (Layer 1) — useful by itself.
+2. Then if you want the full Q&A roundtrip, install the Claude Code skill below.
 
-**Design-to-code in Claude Code (recommended):**
+## Run the full roundtrip (Claude Code)
 
 ```bash
-# 1. Save your Figma token AND install the /canicode-roundtrip skill
-#    Interactive (TTY): npx canicode init        — prompts for the token
-#    Non-interactive:   npx canicode init --token figd_xxxxxxxxxxxxx
-#    (never paste the token into chat — use env var, the prompt, or --token only)
 npx canicode init
+# saves your Figma token + installs /canicode-roundtrip
+# (the prompt asks for the token; never paste it into agent chat)
 
-# 2. Run the roundtrip on a Figma URL
 /canicode-roundtrip https://www.figma.com/design/ABC123/MyDesign?node-id=1-234
+# in your Claude Code session
 ```
 
-> **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.
+The roundtrip calls the **Figma MCP server** to read and write your design — install it once with `claude mcp add -s project -t http figma https://mcp.figma.com/mcp` and restart Claude Code.
 
-> **Optional — Code Connect (for the closing Step 6 mapping):** install `@figma/code-connect` (`pnpm add -D @figma/code-connect` or npm/yarn equivalent) and create `figma.config.json` at your repo root per [Figma's setup guide](https://www.figma.com/code-connect-docs/). Then run `canicode doctor` to confirm both prerequisites are in place. If you skip this, the roundtrip still generates code but will not register a Code Connect mapping — it tells you up front so you can decide.
+> **Cursor / Claude Desktop / other MCP host:** also supported. CLI install path (`npx canicode init --cursor-skills`), bare MCP server install, GitHub Action for CI gates, and other channels are listed in the **Installation** matrix below.
 
-**CanICode in Cursor (no Claude Code required):**
-
-1. Add **canicode** and **Figma** MCPs — [Cursor MCP](docs/CUSTOMIZATION.md#cursor-mcp-canicode) for `npx` → `canicode-mcp` (use **`.cursor/mcp.json`** or **`~/.cursor/mcp.json`** in Cursor, not repo-root `.mcp.json`; [why](docs/CUSTOMIZATION.md#which-mcp-file-affects-which-host)); Figma MCP is required for **`use_figma`** if you run **roundtrip** (design writes), not for analyze-only.
-2. `npx canicode init --token figd_xxxxxxxxxxxxx --cursor-skills` (use `FIGMA_TOKEN=…` or the CLI prompt — not chat) — installs the same three skills as Claude under `.cursor/skills/` (`canicode`, `canicode-gotchas`, `canicode-roundtrip` + `helpers.js`) plus the shared `.claude/skills/canicode-gotchas/SKILL.md` answer file when needed.
-3. In Agent chat, @-mention **canicode-gotchas** (survey) or **canicode-roundtrip** (full roundtrip) and pass a Figma URL — same tool names and JSON as Claude Code (`gotcha-survey`, `analyze`, etc.).
-
-**If you only want analysis (no writes back to Figma):**
-
-```bash
-# CLI — one command
-npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
-
-# MCP Server — works with Claude Code, Cursor, Claude Desktop
-claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
-```
-
-Restart Claude Code or reload MCP (Cursor) so canicode tools (`analyze`, `gotcha-survey`, …) load — same cold-session requirement as the Figma MCP.
-
-**Smoke test (no Figma token needed):**
-
-```bash
-git clone https://github.com/let-sunny/canicode.git
-cd canicode && pnpm install && pnpm build
-canicode analyze ./fixtures/done/desktop-home-page
-```
-
-Loads a bundled fixture (no Figma API call, no token), opens the HTML report in a browser (pass `--no-open` to skip auto-launch). Use any directory under `fixtures/done/` — `desktop-*` are screen-scale, `mobile-*` are mobile viewports.
-
-<details>
-<summary><strong>All channels</strong></summary>
-
-| Channel | Best for |
-|---------|----------|
-| **[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 |
-| **`/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 |
-| **[GitHub Action](https://github.com/marketplace/actions/canicode-action)** | PR gate with score threshold |
-
-</details>
+> **Optional — Code Connect** (for the closing Step 6 mapping): install `@figma/code-connect` and create `figma.config.json` at your repo root per [Figma's setup guide](https://www.figma.com/code-connect-docs/), then run `canicode doctor`. If you skip this, the roundtrip still works — it just does not register the mapping. It warns you up front so you can decide.
 
 ---
 
@@ -128,7 +107,7 @@ Loads a bundled fixture (no Figma API call, no token), opens the HTML report in
 |----------|:-----:|------------------|
 | **Pixel Critical** | 3 | Can AI read the layout? (Auto Layout, absolute positioning, groups) |
 | **Responsive Critical** | 2 | Will it work at different viewports? (fixed sizing, size constraints) |
-| **Code Quality** | 4 | Is the design efficient for AI context? (components, variants, nesting) |
+| **Code Quality** | 5 | Is the design efficient for AI context? (components, variants, nesting, Code Connect coverage) |
 | **Token Management** | 2 | Can AI reproduce exact values? (raw values, spacing grid) |
 | **Interaction** | 2 | Can AI know what happens? (state variants, prototypes) |
 | **Semantic** | 3 | Can AI infer meaning? (semantic names, conventions) |
@@ -139,6 +118,8 @@ Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggest
 
 ## Installation — pick one
 
+> **Token safety:** never paste your Figma token into Claude / Cursor / agent chat — session logs can retain it. Use the CLI prompt (`npx canicode init`), `--token`, or the `FIGMA_TOKEN=…` env var.
+
 Each row below is a **complete** install. Don't run more than one — they cover overlapping use cases.
 
 | If you use… | Install |