canicode 0.8.8 → 0.9.0

package/docs/CUSTOMIZATION.md

@@ -0,0 +1,208 @@
+# Customization Guide
+
+CanICode supports two types of customization:
+
+1. **Config overrides** — adjust scores, severity, and node exclusions
+2. **Custom rules** — add project-specific checks
+
+---
+
+## Config Overrides
+
+Override built-in rule scores, severity, and filter settings with a JSON file.
+
+```bash
+canicode analyze <url> --config ./my-config.json
+```
+
+### Full Schema
+
+```json
+{
+  "excludeNodeTypes": ["VECTOR", "BOOLEAN_OPERATION", "SLICE"],
+  "excludeNodeNames": ["chatbot", "ad-banner", "custom-widget"],
+  "gridBase": 2,
+  "rules": {
+    "no-auto-layout": { "score": -15, "severity": "blocking", "enabled": true },
+    "raw-value": { "score": -5 },
+    "non-semantic-name": { "enabled": false }
+  }
+}
+```
+
+### Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `excludeNodeTypes` | `string[]` | `[]` | Figma node types to skip entirely (node + children) |
+| `excludeNodeNames` | `string[]` | `[]` | Name patterns to skip (case-insensitive word match) |
+| `gridBase` | `number` | `2` | Spacing grid unit for `irregular-spacing` |
+| `rules` | `object` | — | Per-rule overrides (see below) |
+
+### Node Exclusions
+
+**`excludeNodeNames`** — Nodes whose name contains any of these words (case-insensitive) will be skipped entirely. The node and all its children are excluded from analysis.
+
+```json
+{
+  "excludeNodeNames": ["chatbot", "floating-cta", "ad-banner", "legacy"]
+}
+```
+
+This matches word boundaries, so `"nav"` matches `"Nav Bar"` and `"bottom-nav"` but not `"unavailable"`.
+
+**Built-in exclusions** (always active for conversion candidates):
+`badge`, `close`, `dismiss`, `overlay`, `float`, `fab`, `dot`, `indicator`, `corner`, `decoration`, `tag`, `status`, `notification`, `icon`, `ico`, `image`, `asset`, `filter`, `dim`, `dimmed`, `bg`, `background`, `logo`, `avatar`, `divider`, `separator`, `nav`, `navigation`, `gnb`, `header`, `footer`, `sidebar`, `toolbar`, `modal`, `dialog`, `popup`, `toast`, `tooltip`, `dropdown`, `menu`, `sticky`, `spinner`, `loader`, `cursor`, `cta`, `chatbot`, `thumb`, `thumbnail`, `tabbar`, `tab-bar`, `statusbar`, `status-bar`
+
+**`excludeNodeTypes`** — Figma node types to skip.
+
+```json
+{
+  "excludeNodeTypes": ["VECTOR", "BOOLEAN_OPERATION", "SLICE", "STICKY"]
+}
+```
+
+Available types: `DOCUMENT`, `CANVAS`, `FRAME`, `GROUP`, `SECTION`, `COMPONENT`, `COMPONENT_SET`, `INSTANCE`, `RECTANGLE`, `ELLIPSE`, `VECTOR`, `TEXT`, `LINE`, `BOOLEAN_OPERATION`, `STAR`, `REGULAR_POLYGON`, `SLICE`, `STICKY`, `TABLE`, `TABLE_CELL`
+
+### Per-Rule Overrides
+
+Override score, severity, or enable/disable individual rules:
+
+```json
+{
+  "rules": {
+    "no-auto-layout": {
+      "score": -15,
+      "severity": "blocking"
+    },
+    "non-semantic-name": {
+      "enabled": false
+    }
+  }
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `score` | `number` (≤ 0) | Penalty score (more negative = harsher) |
+| `severity` | `string` | `"blocking"`, `"risk"`, `"missing-info"`, or `"suggestion"` |
+| `enabled` | `boolean` | Set `false` to disable the rule |
+
+### All Rule IDs
+
+<!-- RULE_TABLE_START — auto-generated by scripts/sync-rule-docs.ts, do not edit manually -->
+**Pixel Critical (3 rules)**
+
+| Rule ID | Default Score | Default Severity |
+|---------|--------------|-----------------|
+| `no-auto-layout` | -10 | blocking |
+| `absolute-position-in-auto-layout` | -7 | blocking |
+| `non-layout-container` | -8 | blocking |
+
+**Responsive Critical (2 rules)**
+
+| Rule ID | Default Score | Default Severity |
+|---------|--------------|-----------------|
+| `fixed-size-in-auto-layout` | -6 | risk |
+| `missing-size-constraint` | -8 | risk |
+
+**Code Quality (4 rules)**
+
+| Rule ID | Default Score | Default Severity |
+|---------|--------------|-----------------|
+| `deep-nesting` | -3 | risk |
+| `missing-component` | -7 | risk |
+| `detached-instance` | -4 | risk |
+| `variant-structure-mismatch` | -6 | risk |
+
+**Token Management (2 rules)**
+
+| Rule ID | Default Score | Default Severity |
+|---------|--------------|-----------------|
+| `raw-value` | -4 | missing-info |
+| `irregular-spacing` | -5 | risk |
+
+**Semantic (3 rules)**
+
+| Rule ID | Default Score | Default Severity |
+|---------|--------------|-----------------|
+| `non-semantic-name` | -4 | risk |
+| `inconsistent-naming-convention` | -1 | suggestion |
+| `non-standard-naming` | -3 | suggestion |
+
+**Interaction (2 rules)**
+
+| Rule ID | Default Score | Default Severity |
+|---------|--------------|-----------------|
+| `missing-interaction-state` | -1 | suggestion |
+| `missing-prototype` *(disabled)* | -3 | missing-info |
+<!-- RULE_TABLE_END -->
+
+### Example Configs
+
+**Strict (for production-ready designs):**
+```json
+{
+  "rules": {
+    "no-auto-layout": { "score": -15 },
+    "raw-value": { "score": -5, "severity": "risk" },
+    "non-semantic-name": { "score": -6, "severity": "blocking" }
+  }
+}
+```
+
+**Relaxed (for early prototypes):**
+```json
+{
+  "excludeNodeNames": ["prototype", "wip", "draft", "temp"],
+  "rules": {
+    "non-semantic-name": { "enabled": false },
+    "missing-component": { "severity": "suggestion" }
+  }
+}
+```
+
+**Mobile-first (focus on structure):**
+
+```json
+{
+  "rules": {
+    "fixed-size-in-auto-layout": { "score": -8, "severity": "blocking" },
+    "no-auto-layout": { "score": -12 }
+  }
+}
+```
+
+
+---
+
+
+## Telemetry
+
+CanICode collects anonymous usage analytics via [PostHog](https://posthog.com) and error tracking via [Sentry](https://sentry.io). This helps improve the tool by understanding which features are used and catching errors early.
+
+### What is tracked
+
+- Event names with `cic_` prefix (e.g. `cic_analysis_completed`, `cic_cli_command`)
+- Aggregate metadata: node count, issue count, grade, duration
+- Error messages (stack traces for debugging)
+
+### What is NOT tracked
+
+- No design data, file contents, or Figma tokens
+- No personally identifiable information
+- No file names or URLs
+
+### How to opt out
+
+```bash
+canicode config --no-telemetry    # disable telemetry
+canicode config --telemetry       # re-enable telemetry
+```
+
+Telemetry is enabled by default. When disabled, all monitoring functions become silent no-ops.
+
+### Implementation
+
+Telemetry uses native `fetch` (Node 18+ / browser) — no external dependencies. API keys are injected at build time. When telemetry is disabled, all capture functions become silent no-ops.
+

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "canicode",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "mcpName": "io.github.let-sunny/canicode",
-  "description": "CLI tool that analyzes Figma design structures for development-friendliness and AI-friendliness scores",
+  "description": "Score your Figma designs with AI-calibrated rules. CLI + MCP server.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -24,11 +24,13 @@
     "test:run": "vitest run",
     "lint": "tsc --noEmit",
     "build:plugin": "bash scripts/build-plugin.sh",
+    "sync-docs": "tsx scripts/sync-rule-docs.ts",
     "clean": "rm -rf dist"
   },
   "files": [
     "dist",
-    "docs/REFERENCE.md"
+    "docs/CUSTOMIZATION.md",
+    ".claude/skills/design-to-code/PROMPT.md"
   ],
   "keywords": [
     "figma",
@@ -49,9 +51,15 @@
   "homepage": "https://github.com/let-sunny/canicode",
   "author": "minseon",
   "license": "MIT",
+  "pnpm": {
+    "overrides": {
+      "picomatch": "4.0.4",
+      "path-to-regexp": "8.4.0"
+    }
+  },
   "packageManager": "pnpm@10.32.1",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
     "@figma/rest-api-spec": "^0.36.0",
@@ -63,11 +71,13 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.80.0",
     "@figma/plugin-typings": "^1.123.0",
     "@types/node": "^25.5.0",
     "@types/pngjs": "^6.0.5",
     "playwright": "^1.58.2",
     "tsup": "^8.5.1",
+    "tsx": "^4.19.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   }