canicode 0.8.9 → 0.9.1

package/.claude/skills/design-to-code/PROMPT.md

@@ -0,0 +1,143 @@
+# Design to Code — Standard Prompt
+
+This prompt is used by all code generation pipelines:
+- Calibration Converter
+- Ablation experiments (API-based)
+- User-facing `canicode implement` command (default prompt)
+
+## Stack
+- HTML + CSS (single file)
+- No frameworks, no build step
+
+## Conventions
+- Semantic HTML elements
+- Flexbox / Grid for layout
+- Always include `* { box-sizing: border-box; margin: 0; padding: 0; }` reset
+
+## CRITICAL: Do NOT Interpret. Reproduce Exactly.
+
+Every pixel in the Figma file is intentional. A designer made each decision deliberately.
+Your job is to translate the Figma data to HTML+CSS — nothing more.
+
+### Priority Order
+1. **Pixel-exact reproduction** — match every dimension, color, spacing, font exactly
+2. **Component reuse** — same component annotation → shared CSS class
+3. **Design tokens** — repeated values → CSS custom properties
+
+Never sacrifice #1 for #2 or #3. Reuse and tokens are structural improvements only — they must not change the visual output.
+
+### Rules
+- Do NOT add any value that isn't in the Figma data (no extra padding, margin, gap, transition)
+- Do NOT add hover effects unless `[hover]:` data is provided in the design tree
+- Do NOT change any value from the Figma data (if it says 160px padding, use 160px)
+- Do NOT "improve" the design — if something looks wrong, reproduce it anyway
+- Do NOT add responsive behavior unless the Figma data explicitly shows it
+- Do NOT use min-height or min-width unless the design tree explicitly includes them — use exact height and width from the data
+- Do NOT add overflow: auto or scroll unless specified
+- Fonts: load via Google Fonts CDN (`<link>` tag). Do NOT use system font fallbacks as primary — the exact font from the data must render.
+
+### Component Reuse
+
+Nodes annotated with `[component: ComponentName]` are instances of the same design component.
+
+- Define a CSS class for each unique component name (e.g., `[component: Review Card]` → `.review-card { ... }`)
+- If the same component appears multiple times, define the shared styles once in the class, then apply it to each instance
+- `component-properties:` lines show variant overrides — use them to differentiate instances (e.g., different text content, sizes) while keeping shared styles in the class
+- Component name → class name: lowercase, spaces to hyphens (e.g., `Review Card` → `.review-card`)
+- Use CSS classes only — no Web Components, no JavaScript templates
+
+### Design Tokens
+
+Extract repeated values into CSS custom properties in `:root { }`.
+
+**Colors**: When the same hex color appears 3+ times, define it as a CSS variable:
+```css
+:root {
+  --color-2C2C2C: #2C2C2C;
+  --color-0066CC: #0066CC;
+}
+```
+Then use `var(--color-2C2C2C)` instead of inline `#2C2C2C`.
+
+Naming: if a `/* var:... */` comment is present next to a color value, it means the designer bound this color to a design token — always extract these as CSS variables.
+
+**Typography**: When `/* text-style: StyleName */` appears in a text node's styles, nodes sharing the same text style name should use a shared CSS class:
+```css
+.text-heading-large { font-family: "Inter"; font-weight: 700; font-size: 32px; line-height: 40px; }
+```
+Style name → class name: lowercase, spaces/slashes to hyphens, prefix with `text-` (e.g., `Heading / Large` → `.text-heading-large`).
+
+### SVG Vectors
+
+When a node's style includes `svg: <svg>...</svg>`, render it as an inline `<svg>` element:
+- Use the SVG markup exactly as provided — do not modify paths or attributes
+- Preserve the node's dimensions (`width` and `height` from the node header)
+- The `<svg>` replaces the node's HTML element (do not wrap it in an extra `<div>` unless the node has other styles like background or border)
+
+### Hover States
+
+When a node includes a `[hover]:` line, generate a `:hover` CSS rule with the provided style changes:
+
+```text
+Button (INSTANCE, 120x40) [component: Button]
+  style: background: #2C2C2C
+  [hover]: background: #1E1E1E; Icon: fill: #FFFFFF
+```
+
+→ generates:
+
+```css
+.button { background: #2C2C2C; }
+.button:hover { background: #1E1E1E; }
+.button:hover .icon { fill: #FFFFFF; }
+```
+
+- Only use hover data that is explicitly provided in `[hover]:` — do not invent hover effects
+- Child styles (e.g., `Icon: fill: #FFFFFF`) use `.parent:hover .child` selector pattern
+
+### Image Assets
+
+The design tree uses two distinct image types:
+
+**`content-image:`** — leaf node, no children → render as `<img>` tag
+- `content-image: url(images/...)` → `<img src="images/..." />`
+- `object-fit: cover` or `object-fit: contain` is provided alongside — use it directly
+
+**`background-image:`** — node has children on top → keep as CSS `background-image`
+- `background-image: url(images/...)` → `background-image: url(images/...)` in CSS
+- `background-size`, `background-position`, `background-repeat` are provided alongside — use as-is
+
+**`[IMAGE]` placeholder** — image asset unavailable → use a placeholder color matching the surrounding design
+
+### If data is missing
+When the Figma data does not specify a value, you MUST list it as an interpretation.
+Do not silently guess — always declare what you assumed.
+
+## Output
+
+### 1. Code
+- Place the entire design inside a single root `<div>` as the first child of `<body>` — do NOT apply design styles directly to `<body>` or `<html>`
+- Output as a code block with filename:
+
+```html
+// filename: index.html
+<!DOCTYPE html>
+...
+```
+
+### 2. Interpretations
+After the code block, list every value you had to guess or assume.
+Keep this list to **only genuine ambiguities** — do not list standard defaults (e.g., `body { margin: 0 }` is always expected, not an interpretation).
+**Maximum 10 items.** If you have more than 10, keep only the highest-impact ones.
+
+```text
+// interpretations:
+- Used placeholder gray (#CCCCCC) for unavailable image asset
+- Chose "Inter" font weight 500 for ambiguous "Medium" style reference
+```
+
+If you did not interpret anything, write:
+
+```text
+// interpretations: none
+```

package/README.md

@@ -8,19 +8,13 @@
   <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://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>
-  <a href="https://let-sunny.github.io/canicode/"><img src="https://img.shields.io/badge/Try_it-GitHub_Pages-blue" alt="GitHub Pages"></a>
-  <a href="https://www.figma.com/community/plugin/1617144221046795292/canicode"><img src="https://img.shields.io/badge/Figma_Plugin-under_review-orange" alt="Figma Plugin"></a>
-  <a href="https://github.com/let-sunny/canicode#mcp-server-claude-code--cursor--claude-desktop"><img src="https://img.shields.io/badge/MCP_Registry-published-green" alt="MCP Registry"></a>
-  <a href="https://github.com/marketplace/actions/canicode-action"><img src="https://img.shields.io/badge/GitHub_Action-Marketplace-2088FF" alt="GitHub Action"></a>
 </p>
 
-<p align="center">The design linter that scores how easily your Figma design can be implemented by AI or developers — before a single line of code is written.</p>
+<p align="center"><strong>Stop explaining your designs. Get scored by AI-calibrated rules.</strong></p>
 
-<p align="center">No AI tokens consumed per analysis. Rules run deterministically — AI only validated the scores during development.</p>
-
-<p align="center"><strong><a href="https://github.com/let-sunny/canicode/discussions/new?category=share-your-figma">Share your Figma design</a></strong> to help improve scoring accuracy.</p>
-
-<p align="center"><strong><a href="https://let-sunny.github.io/canicode/">Try it in your browser</a></strong> — no install needed.</p>
+<p align="center">
+  <strong><a href="https://let-sunny.github.io/canicode/">Try it in your browser</a></strong> — no install needed.
+</p>
 
 <p align="center">
   <img src="docs/images/screenshot.gif" alt="CanICode Report" width="720">
@@ -28,46 +22,78 @@
 
 ---
 
-## How It Works
+## Why CanICode
 
-39 rules. 6 categories. Every node in the Figma tree.
+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.
 
-| Category | Rules | What it checks |
-|----------|-------|----------------|
-| Layout | 11 | Auto-layout usage, responsive behavior, nesting depth |
-| Design Token | 7 | Color/font/shadow tokenization, spacing consistency |
-| Component | 6 | Component reuse, detached instances, variant coverage |
-| Naming | 5 | Semantic names, default names, naming conventions |
-| AI Readability | 5 | Structure clarity, z-index reliance, empty frames |
-| Handoff Risk | 5 | Hardcoded values, truncation handling, placeholder images |
+CanICode solves this:
 
-Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggestion**.
+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
 
-### Rule Scores Validated by AI
+- **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
 
-Rule scores aren't guesswork. They're validated through a 4-agent debate pipeline that converts real Figma nodes to code and measures actual implementation difficulty.
+### Scores You Can Trust
 
-1. **Runner** analyzes the design and flags issues
-2. **Converter** converts the flagged nodes to actual code
-3. **Critic** challenges whether the scores match the real difficulty
-4. **Arbitrator** makes the final call — adjust or keep
+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.
 
-- A node that's hard to implement → rule score goes up
-- A node that's easy to implement despite the flag → rule score goes down
+- Design that's hard to implement accurately → rule score goes **up**
+- Design that's easy despite the flag → rule score goes **down**
 
-The rules themselves run deterministically on every analysis — no tokens consumed. The AI debate validates scores when new fixtures are added, not on every run. See [`docs/CALIBRATION.md`](docs/CALIBRATION.md).
+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).
 
 ---
 
 ## Getting Started
 
-| If you want to... | Use |
-|---|---|
-| Just try it | **[Web App](https://let-sunny.github.io/canicode/)** — paste a URL, no install |
-| Analyze inside Figma | **[Figma Plugin](https://www.figma.com/community/plugin/1617144221046795292/canicode)** (under review) |
-| Use with Claude Code / Cursor | **MCP Server** or **Skill** — see below |
-| Add to CI/CD | **[GitHub Action](https://github.com/marketplace/actions/canicode-action)** |
-| Full control | **CLI** |
+**Quickest way:** **[Open the web app](https://let-sunny.github.io/canicode/)** — paste a Figma URL, get a report.
+
+**For your workflow:**
+
+```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 -y -p canicode canicode-mcp
+```
+
+<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 |
+| **Claude Code Skill** | Lightweight, 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>
+
+---
+
+## What It Checks
+
+| Category | Rules | What it measures |
+|----------|:-----:|------------------|
+| **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) |
+| **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) |
+
+Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggestion**.
+
+---
+
+## Installation
 
 <details>
 <summary><strong>CLI</strong></summary>
@@ -87,7 +113,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 use MCP (no token, separate rate limit pool). 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-fixture` once and analyze locally. [Full details](https://developers.figma.com/docs/rest-api/rate-limits/)
 
 </details>
 
@@ -103,22 +129,38 @@ Then ask: *"Analyze this Figma design: https://www.figma.com/design/..."*
 
 canicode's rule engine analyzes the design data — the AI assistant just orchestrates the calls.
 
-Or with a Figma API token (no Figma MCP needed):
+With a Figma API token:
 ```bash
 claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y -p canicode canicode-mcp
 ```
 
-For Cursor / Claude Desktop config, see [`docs/REFERENCE.md`](docs/REFERENCE.md).
+For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md).
 
-**Figma MCP Rate Limits**
+</details>
 
-| Plan | Limit |
-|------|-------|
-| Starter | 6 tool calls/month |
-| Pro / Org — Full or Dev seat | 200 tool calls/day |
-| Enterprise — Full or Dev seat | 600 tool calls/day |
 
-MCP and CLI use separate rate limit pools — switching to MCP won't affect your CLI quota. [Full details](https://developers.figma.com/docs/figma-mcp-server/plans-access-and-permissions/)
+<details>
+<summary><strong>Design to Code</strong> (prepare implementation package)</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
+```
+
+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)
+
+| 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>
 
@@ -129,7 +171,7 @@ MCP and CLI use separate rate limit pools — switching to MCP won't affect your
 cp -r .claude/skills/canicode /your-project/.claude/skills/
 ```
 
-Requires the official Figma MCP. Then use `/canicode` with a Figma URL.
+Requires FIGMA_TOKEN. Then use `/canicode` with a Figma URL.
 
 </details>
 
@@ -156,11 +198,8 @@ Posts analysis as a PR comment. Fails if score is below threshold. See [**canico
 |------|-----|
 | **Presets** | `--preset relaxed \| dev-friendly \| ai-ready \| strict` |
 | **Config overrides** | `--config ./config.json` — adjust scores, severity, exclude nodes |
-| **Custom rules** | `--custom-rules ./rules.json` — add project-specific checks |
-
-> Ask any LLM *"Write a canicode custom rule that checks X"* — it can generate the JSON for you.
 
-See [`docs/REFERENCE.md`](docs/REFERENCE.md) for the full guide, examples, and all available options.
+See [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md) for the full guide, examples, and all available options.
 
 ---
 
@@ -177,19 +216,11 @@ pnpm test       # run tests
 pnpm lint       # type check
 ```
 
-For architecture details, see [`CLAUDE.md`](CLAUDE.md). For calibration pipeline, see [`docs/CALIBRATION.md`](docs/CALIBRATION.md).
+For architecture details, see [`CLAUDE.md`](CLAUDE.md). For calibration pipeline, see the [Calibration wiki](https://github.com/let-sunny/canicode/wiki/Calibration).
 
-## Roadmap
+## Contributing
 
-- [x] **Phase 1** — 39 rules, density-based scoring, HTML reports, presets, scoped analysis
-- [x] **Phase 2** — 4-agent calibration pipeline, `/calibrate-loop` debate loop
-- [x] **Phase 3** — Config overrides, MCP server, Claude Skills
-- [x] **Phase 4** — Figma comment from report (per-issue "Comment" button in HTML report, posts to Figma node via API)
-- [x] **Phase 5** — Custom rules with pattern matching (node name/type/attribute conditions)
-- [x] **Phase 6** — Screenshot comparison (`visual-compare` CLI: Figma vs AI-generated code, pixel-level diff)
-- [x] **Phase 7** — Calibration pipeline upgrade (visual-compare + Gap Analyzer for objective score validation)
-- [x] **Phase 8** — Rule discovery pipeline (6-agent debate: researcher → designer → implementer → A/B visual validation → evaluator → critic)
-- [ ] **Ongoing** — Rule refinement via calibration + gap analysis on community fixtures
+**[Share your Figma design](https://github.com/let-sunny/canicode/discussions/new?category=share-your-figma)** to help calibrate scores against real-world designs.
 
 ## Support