figma-to-html-pixel-perfect 1.0.0

package/bin/install.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/* Installs the figma-to-html-pixel-perfect skill for Claude Code.
+ *
+ *   npx figma-to-html-pixel-perfect            → ~/.claude/skills/… (personal, all projects)
+ *   npx figma-to-html-pixel-perfect --project  → ./.claude/skills/… (this project only)
+ *
+ * Copies SKILL.md, scripts/ and references/ from this package. No dependencies.
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL = 'figma-to-html-pixel-perfect';
+const SRC = path.join(__dirname, '..');
+const project = process.argv.includes('--project');
+const destRoot = project
+  ? path.join(process.cwd(), '.claude', 'skills')
+  : path.join(os.homedir(), '.claude', 'skills');
+const dest = path.join(destRoot, SKILL);
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    if (['node_modules', '.git', 'bin', 'package.json'].includes(e.name)) continue;
+    const s = path.join(src, e.name), d = path.join(dst, e.name);
+    e.isDirectory() ? copyDir(s, d) : fs.copyFileSync(s, d);
+  }
+}
+
+const existed = fs.existsSync(path.join(dest, 'SKILL.md'));
+copyDir(SRC, dest);
+fs.chmodSync(dest, 0o755);
+
+console.log(`${existed ? 'Updated' : 'Installed'} ${SKILL} → ${dest}
+`);
+console.log(`Next steps:
+  1. Figma token (one-time):
+       echo 'YOUR_TOKEN' > ~/.figma_token && chmod 600 ~/.figma_token
+     (figma.com → Settings → Security → Personal access tokens, scope "File content: Read")
+  2. Restart your Claude Code session — the skill is picked up automatically,
+     or invoke it with /${SKILL}
+  3. Docs: ${dest}/README.md`);

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "figma-to-html-pixel-perfect",
+  "version": "1.0.0",
+  "description": "Claude Code skill: Figma → pixel-perfect HTML/CSS with a self-verifying fidelity pipeline (114 documented failure modes). Running this package installs the skill into ~/.claude/skills.",
+  "bin": {
+    "figma-to-html-pixel-perfect": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "SKILL.md",
+    "README.md",
+    "scripts",
+    "references"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fieldqqq/figma-to-html-perfect-pixel.git"
+  },
+  "keywords": ["claude", "claude-code", "skill", "figma", "html", "css", "pixel-perfect", "design-to-code"],
+  "author": "fieldqqq",
+  "license": "MIT",
+  "engines": { "node": ">=16" }
+}

package/references/accessibility-checklist.md

@@ -0,0 +1,68 @@
+# Accessibility Checklist (WCAG 2.2 AA target)
+
+Verify without changing the approved visual direction. Where a fix would change the
+visible design, flag it as a Usability Issue and request approval.
+
+## Structure & Semantics
+
+- [ ] Landmarks used correctly (`header`, `nav`, `main`, `footer`, `aside`)
+- [ ] One `main` per page
+- [ ] Headings are ordered (no skipped levels; single logical h1)
+- [ ] Lists use `ul`/`ol`/`li`; tables use `th`/`caption` where relevant
+- [ ] Buttons for actions, links for navigation
+- [ ] No duplicate `id` attributes
+
+## Keyboard
+
+- [ ] All interactive elements are reachable by Tab
+- [ ] Focus order is logical and matches visual order
+- [ ] No keyboard traps
+- [ ] Visible focus indicator on every focusable element
+- [ ] Focus outline not removed without an accessible replacement
+- [ ] Custom widgets (menu, tabs, accordion, modal) support expected keys
+- [ ] Modal traps focus and restores it on close; Esc closes
+
+## Names, Roles, Values
+
+- [ ] All form controls have associated `<label>` (or `aria-label`)
+- [ ] Icon-only buttons have accessible names
+- [ ] Images have meaningful `alt`; decorative images use `alt=""`
+- [ ] ARIA used only when native HTML is insufficient
+- [ ] Dynamic updates announced (`aria-live` where appropriate)
+- [ ] Error messages programmatically associated (`aria-describedby`)
+
+## Color & Contrast
+
+- [ ] Body text contrast ≥ 4.5:1
+- [ ] Large text (≥ 24px, or ≥ 19px bold) contrast ≥ 3:1
+- [ ] UI component / graphical object contrast ≥ 3:1
+- [ ] Information is not conveyed by color alone
+- [ ] Focus indicator contrast ≥ 3:1 against adjacent colors
+
+## Target Size & Input (WCAG 2.2)
+
+- [ ] Touch targets ≥ 24×24 px (prefer ≥ 44×44 px)
+- [ ] Adequate spacing between adjacent targets
+- [ ] Dragging actions have a single-pointer alternative
+- [ ] No content relies solely on hover to be accessible
+
+## Motion & Media
+
+- [ ] `prefers-reduced-motion` respected for all non-essential animation
+- [ ] Entrance animation cannot hide content if the script fails (hiding rule is scoped to
+      a class the script adds; never CSS-only `opacity: 0`)
+- [ ] No content flashes more than 3 times per second
+- [ ] Auto-playing/moving content can be paused or stopped
+
+## Forms
+
+- [ ] Required fields indicated in text, not color alone
+- [ ] Inline validation is associated with its field
+- [ ] Error summary provided for longer forms
+- [ ] Success confirmation is announced
+
+## Verification Tools
+
+- [ ] Automated pass (axe / Lighthouse) with issues triaged
+- [ ] Manual keyboard-only walkthrough completed
+- [ ] Screen reader spot-check on key flows

package/references/animation-guidelines.md

@@ -0,0 +1,113 @@
+# Motion Guidelines
+
+There are two kinds of motion, and they are governed by opposite rules.
+
+| | Motion **in** the Figma file | Motion **you would invent** |
+|---|---|---|
+| What it is | Part of the design | An enhancement |
+| Mode | **A — required** | **C — needs approval** (or a standing instruction) |
+| Ask first? | **No. Build it.** | Yes (or confirm the standing instruction) |
+| Label it? | No — it *is* the design | Yes — every value is inferred |
+
+Not implementing motion the file specifies is a fidelity bug, exactly like a wrong colour.
+
+## 1. Read the motion the file already has — first, always
+
+```bash
+grep -l '"interactions"' figma/nodes/*.json    # non-empty => the design specifies motion
+```
+
+Never write "the design has no animation" without having run this.
+
+Per interaction, record:
+
+| Field | Meaning |
+|---|---|
+| `trigger.type` | `ON_HOVER`, `ON_CLICK`, `ON_DRAG`, `AFTER_TIMEOUT` |
+| `trigger.timeout` | autoplay interval, in **seconds** |
+| `actions[].transition.type` | `SMART_ANIMATE`, `DISSOLVE`, `PUSH`, … |
+| `actions[].transition.duration` | **seconds** — multiply by 1000 |
+| `actions[].transition.easing.type` | `GENTLE`, `SLOW`, `LINEAR`, `EASE_*`, `CUSTOM_CUBIC_BEZIER` |
+| `effects[]` | real `DROP_SHADOW` / `BACKGROUND_BLUR` to reproduce |
+
+### Figma easing → CSS
+
+Figma's named easings are springs; CSS has none. Approximate, and say that you did.
+
+| Figma | Character | Reasonable CSS |
+|---|---|---|
+| `GENTLE` | soft settle, slight overshoot | `cubic-bezier(0.34, 1.16, 0.64, 1)` |
+| `SLOW` | long, pure decelerate | `cubic-bezier(0.33, 1, 0.68, 1)` |
+| `EASE_OUT` | standard decelerate | `cubic-bezier(0.16, 1, 0.3, 1)` |
+| `CUSTOM_CUBIC_BEZIER` | exact | copy `easingFunctionCubicBezier` verbatim |
+
+Two traps:
+
+- Spring durations (often 800–1300 ms) are **settle** times, not perceived times. Reproduce
+  the design's number — the design outranks your taste — and note the tension with the
+  microinteraction ranges below.
+- `AFTER_TIMEOUT` implies an autoplaying carousel. Check the file actually contains the
+  other slides. If it has only one, **do not invent them**: implement the timing you can
+  and report the missing slides.
+
+## 2. When the file specifies no motion
+
+Then, and only then, infer it — from the design, not from habit. Read the mood off what the
+file *does* specify:
+
+- **Easings and durations already in use** — if everything is slow and gentle, a snappy
+  200 ms bounce is wrong.
+- **Type and colour** — high-contrast display serif with a muted palette reads editorial
+  and restrained.
+- **Effects** — heavy blur and soft shadows imply soft, layered motion, not snap.
+
+Then pick the smallest motion that serves that mood: fade plus a short rise (12–20 px), a
+generous duration, a decelerating curve, a light stagger. Label every inferred value.
+
+Propose it in this form:
+
+> **Optional enhancement — [section/component]**
+> I recommend `[motion]` because `[specific reason]`.
+> Behaviour: `[trigger, duration, easing, movement]`.
+> This is not in the Figma file. Should I add it?
+
+## 3. Motion must never hide content
+
+Entrance animation that sets `opacity: 0` in CSS is a blank page whenever the script fails,
+JS is off, or the tab is throttled — `IntersectionObserver` callbacks and CSS transitions do
+not run in a hidden tab.
+
+- Scope the hiding rule to a class the script adds: `html.motion [data-reveal] { opacity: 0 }`.
+- Reveal on `IntersectionObserver` **and** a passive `scroll` sweep **and** `visibilitychange`.
+- Never depend on `requestAnimationFrame` for the first pass.
+- Verify by disabling the script: the page must be fully visible.
+
+## 4. Default ranges (only when nothing is specified)
+
+| Category | Duration | Use |
+|---|---|---|
+| Microinteraction | 120–220 ms | hover, press, toggle, focus |
+| Component transition | 180–320 ms | accordion, tab, dropdown |
+| Section entrance | 350–650 ms | hero reveal, scroll-linked reveal |
+
+Defaults, not mandates — and always outranked by a value the file states.
+
+## 5. Quality rules
+
+Motion must reinforce hierarchy or give feedback; stay subtle; never block input; never
+cause layout shift (animate `transform`/`opacity`, not `width`/`top`); avoid heavy parallax
+and long entrance sequences; preserve keyboard use; and respect `prefers-reduced-motion`.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+Prefer targeted handling over the blanket reset for essential state changes (an accordion
+should still open — instantly, not never).

package/references/visual-review-checklist.md

@@ -0,0 +1,121 @@
+# Visual Review Checklist
+
+Use this checklist during **Step 5 — Visual Comparison** and **Step 7 — Final Verification**.
+Compare the implementation against the reference at identical viewport dimensions.
+
+## Build gate (before you look at anything)
+
+- [ ] `figma_lint.py` passes — no `gap`, `font-size` or colour that the design never uses
+- [ ] `<br>` count does not exceed the newlines in `characters`
+- [ ] Type values came from each TEXT node's `style`, not from memory
+- [ ] Spacing came from `itemSpacing` / `padding*`, not from a scale you like
+- [ ] No design value is hidden inside `clamp()` at the design width
+- [ ] Every icon is an exported vector, not an inline `<svg>` drawn from memory
+- [ ] No gradient/box placeholder remains where the design has a photo
+
+## Gate (do this first, per section)
+
+- [ ] A reference image for **this** section exists and I have actually looked at it
+- [ ] The section was screenshot-compared against that reference after being built
+- [ ] I am not relying on matching heights/spacing numbers as proof of visual fidelity
+- [ ] Text case (UPPER/lower), real button labels, and asset→node mapping were checked
+      against the node JSON (`characters`, `textCase`, `visible`) — not assumed
+- [ ] Nodes with `visible:false` **and** nodes whose cumulative ancestor `opacity` is 0
+      were excluded — `visible:true` does not mean "renders"
+- [ ] Per-character overrides (`styleOverrideTable`) were read, not just `style`
+- [ ] Motion the file specifies (`interactions[]`) is implemented, not skipped
+- [ ] The **text audit** for this section was run (`figma_report.py --only <section>`)
+      while building it — not deferred to the end
+- [ ] Opacity/animation assertions were made with transitions disabled — a hidden tab
+      freezes transitions and reports the mid-flight value
+
+## Layout & Structure
+
+- [ ] Max content width matches the reference container
+- [ ] Container gutters / horizontal padding match
+- [ ] Section vertical spacing (top/bottom) matches
+- [ ] Grid column count and gap match
+- [ ] Flex/grid alignment (start/center/end/space-between) matches
+- [ ] Internal component padding matches
+- [ ] Sticky / fixed elements behave as designed
+- [ ] No unintended overflow (horizontal or vertical)
+- [ ] Z-index / stacking order of overlapping elements is correct
+
+## Typography
+
+- [ ] Font family matches (or documented fallback in use)
+- [ ] Font weight matches per text role
+- [ ] Font size matches per breakpoint
+- [ ] Line height matches
+- [ ] Letter spacing matches
+- [ ] Text transform (uppercase/capitalize) matches
+- [ ] Text alignment matches
+- [ ] Text color matches
+- [ ] Heading hierarchy is correct and ordered
+- [ ] Paragraph max-width / measure matches
+- [ ] Text wraps at the same points as the reference
+
+## Color & Surface
+
+- [ ] Background colors match
+- [ ] Surface / card colors match
+- [ ] Accent / brand colors match
+- [ ] Border colors and widths match
+- [ ] Gradients match (direction, stops, colors)
+- [ ] Opacity / transparency values match
+
+## Depth & Shape
+
+- [ ] Border radius matches per element
+- [ ] Shadows match (offset, blur, spread, color)
+- [ ] Blur / backdrop-filter matches
+- [ ] Dividers and separators match
+
+## Imagery & Icons
+
+- [ ] Image dimensions and aspect ratios match
+- [ ] object-fit / crop matches the reference
+- [ ] Focal point of cropped images is preserved
+- [ ] Icons match size, stroke weight, and alignment
+- [ ] SVG vs raster usage is appropriate
+- [ ] Background images position and scale correctly
+- [ ] No missing or placeholder assets remain
+
+## Spacing Precision (spot-check with dev tools)
+
+- [ ] Gaps between repeated cards/items are exact
+- [ ] Button padding matches
+- [ ] Icon-to-text spacing matches
+- [ ] Label-to-field spacing in forms matches
+
+## Cross-Viewport
+
+- [ ] Desktop matches the desktop reference frame
+- [ ] Tablet behaves correctly (if a frame is supplied)
+- [ ] Mobile matches the mobile reference frame
+- [ ] Transitions between breakpoints are clean (no jumps/overlap)
+
+## Coverage — what the report does not prove
+
+- [ ] I told the user that colour/radius/stroke/shadow of non-text elements, z-order,
+      hover and focus states, motion timings, and other viewports are **not** covered
+- [ ] I looked at the difference-blend overlay myself and said what I saw
+
+## Difference Log
+
+Record every remaining discrepancy before declaring completion:
+
+| Area | Difference | Cause | Fix | Status |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+## Icons — the traps that look like success
+
+- [ ] Every icon in the build is an `<img>` pointing at a file extracted from the design.
+- [ ] You **opened the extracted icons and looked at them**, on a background that contrasts
+      with them. White icons on a white contact sheet look like missing files.
+- [ ] No icon is a photo (a shape with an `IMAGE` fill), a carousel dot, or a decorative ring.
+- [ ] No icon is a component's placeholder artwork buried under a photo.
+- [ ] A frame holding several icons was split, not exported as one.
+- [ ] Each icon renders at the size of its node in the design, not the size of its ink.
+- [ ] The fidelity report distinguishes *absent* from *placed wrong*; both are read.

package/scripts/figma_discover.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Discovery: find everything in the file you are about to ignore.
+
+Run this FIRST, before the node dump, before the renders, before a single line of CSS —
+and show the output to the user. It answers four questions that decide the whole job:
+
+  1. how many design widths are in this file?      -> breakpoints you must build, not guess
+  2. is there an icon library?                     -> icons you must export, not draw
+  3. do any interactions point at hover variants?  -> states you must reproduce, not invent
+  4. how many page-sized frames are there?         -> screens you may have been asked for
+
+Missing any of these is not a small error. Guessing a mobile layout that the designer
+already drew, or hand-drawing icons that ship as components in the same file, produces
+work that is wrong on purpose.
+
+Usage:
+    python3 figma_discover.py <fileKey> [--nodes figma/nodes] [--json out.json]
+
+Token: env FIGMA_TOKEN, else ~/.figma_token
+"""
+import argparse, glob, json, os, pathlib, re, sys, urllib.request
+from collections import Counter, defaultdict
+
+API = "https://api.figma.com/v1"
+ICON_MAX = 64          # a frame this small is an icon, not a screen
+SCREEN_MIN_H = 1200    # a screen is tall
+SCREEN_MIN_W, SCREEN_MAX_W = 320, 1920
+# Names that mean "pasted asset", not "screen we must build". Scratch pages are full of
+# them and they otherwise drown the breakpoint list.
+ASSET_RE = re.compile(
+    r"^(image|screencapture|group|rectangle|vector|ellipse|union|mask|isolation_mode|"
+    r"frame \d+|frame \d{6,})", re.I)
+
+
+def token():
+    if os.environ.get("FIGMA_TOKEN"):
+        return os.environ["FIGMA_TOKEN"].strip()
+    p = pathlib.Path.home() / ".figma_token"
+    if p.exists():
+        return p.read_text().strip()
+    sys.exit("No token. See SKILL.md §0.1")
+
+
+CACHE = pathlib.Path("figma/_api_cache")
+
+
+def get(path, tok, required=True):
+    """Cache every response. EVERY REST endpoint shares a rate-limit budget — the render
+    endpoint exhausts first, but /files and /nodes will 429 too. A cached answer is always
+    better than a dead run."""
+    CACHE.mkdir(parents=True, exist_ok=True)
+    key = CACHE / (re.sub(r"[^\w.-]", "_", path)[:120] + ".json")
+    if key.exists():
+        return json.loads(key.read_text())
+    req = urllib.request.Request(API + path, headers={"X-Figma-Token": tok})
+    try:
+        with urllib.request.urlopen(req, timeout=90) as r:
+            data = json.load(r)
+        key.write_text(json.dumps(data))
+        return data
+    except urllib.error.HTTPError as e:
+        body = e.read(200).decode(errors="replace")
+        if e.code == 429:
+            ra = e.headers.get("Retry-After")
+            msg = f"429 rate limited on {path}. Retry-After: {ra}"
+            if required:
+                sys.exit(msg + "\n  Every REST endpoint shares a budget, not just /images.")
+            print(f"  ! {msg} — skipping this part of discovery")
+            return None
+        if e.code == 403 and "not exportable" in body:
+            sys.exit("403 File not exportable — the owner disabled export/copy/share (§0.2).")
+        sys.exit(f"HTTP {e.code}: {body}")
+
+
+def size(n):
+    bb = n.get("absoluteBoundingBox") or {}
+    return round(bb.get("width", 0)), round(bb.get("height", 0))
+
+
+def hover_destinations(nodes_dir):
+    """destinationId of every ON_HOVER action, and whether we already have that node."""
+    dests, have = Counter(), set()
+    for f in glob.glob(os.path.join(nodes_dir, "*.json")):
+        d = json.load(open(f))
+        d = d["document"] if "document" in d else d
+
+        def walk(n):
+            if n.get("visible") is False:
+                return
+            have.add(n.get("id"))
+            for it in n.get("interactions") or []:
+                if (it.get("trigger") or {}).get("type") == "ON_HOVER":
+                    for a in it.get("actions") or []:
+                        if a.get("destinationId"):
+                            dests[a["destinationId"]] += 1
+            for c in n.get("children", []) or []:
+                walk(c)
+
+        walk(d)
+    return dests, have
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("fileKey")
+    ap.add_argument("--nodes", default="figma/nodes",
+                    help="cached node JSON, to find hover destinations (optional)")
+    ap.add_argument("--json", default=None)
+    a = ap.parse_args()
+
+    doc = get(f"/files/{a.fileKey}?depth=2", token())["document"]
+
+    widths = Counter()
+    screens, icons, icon_pages, components, skipped = [], [], [], [], 0
+    for page in doc.get("children", []):
+        pname = page.get("name", "")
+        kids = page.get("children") or []
+        is_icon_page = "icon" in pname.lower() and bool(kids)
+        if is_icon_page:
+            icon_pages.append(pname)
+        for k in kids:
+            w, h = size(k)
+            name = k.get("name", "")
+            entry = {"page": pname, "name": name, "w": w, "h": h, "type": k.get("type")}
+            if k.get("type") in ("COMPONENT", "COMPONENT_SET"):
+                components.append(entry)
+            if 0 < w <= ICON_MAX and 0 < h <= ICON_MAX:
+                icons.append(entry)
+                continue
+            if is_icon_page or ASSET_RE.match(name):
+                skipped += 1
+                continue
+            if (SCREEN_MIN_W <= w <= SCREEN_MAX_W and h >= SCREEN_MIN_H
+                    and h >= w * 1.5):
+                widths[w] += 1
+                screens.append(entry)
+
+    out = {"widths": dict(widths), "screens": screens, "icons": icons,
+           "icon_pages": icon_pages, "components": components}
+
+    print("CANDIDATE DESIGN WIDTHS (a heuristic — confirm with the user which are breakpoints)")
+    print(f"  (ignored {skipped} pasted assets and icon-page frames)")
+    for w, n in widths.most_common():
+        tallest = max((s for s in screens if s["w"] == w), key=lambda s: s["h"])
+        print(f"  {w:>5}px  x{n:<3} tallest: {tallest['name'][:44]!r} ({tallest['h']}px, page {tallest['page']!r})")
+    if len(widths) > 1:
+        print("\n  -> More than one width. Some of these are cards or scratch frames, not")
+        print("     breakpoints. Ask the user which are real, then run the whole loop per")
+        print("     confirmed width. If a mobile frame exists, INFERRING a mobile layout")
+        print("     instead of building that frame is a fabrication.\n")
+    else:
+        print("\n  -> one width only; responsive behaviour is genuinely inferred (label it).\n")
+
+    # An icon page's real components live below depth 2; fetch those pages properly.
+    lib = []
+    for page in doc.get("children", []):
+        if page.get("name") in icon_pages:
+            node = get(f"/files/{a.fileKey}/nodes?ids={page['id']}", token(), required=False)
+            if not node:
+                continue
+            root = node["nodes"][page["id"]]["document"]
+
+            def walk(n):
+                w, h = size(n)
+                # the icons themselves, whatever type the designer used
+                if 0 < w <= ICON_MAX and 0 < h <= ICON_MAX and n.get("name"):
+                    lib.append({"name": n["name"], "id": n["id"], "w": w, "h": h})
+                    return
+                for c in n.get("children", []) or []:
+                    walk(c)
+
+            walk(root)
+    out["icon_library"] = lib
+
+    print(f"ICON LIBRARY: {len(icons)} icon-sized top-level frames"
+          + (f"; icon pages: {icon_pages}" if icon_pages else ""))
+    if lib:
+        names = sorted({i["name"] for i in lib})
+        print(f"  {len(lib)} icons inside those pages ({len(names)} distinct names)")
+        print("  sample: " + ", ".join(names[:8]))
+    if icons or lib:
+        print("  -> export these. Hand-drawing an icon that ships in the file is never acceptable.\n")
+    else:
+        print("  -> none found; icons must still be extracted from the page SVG, not drawn.\n")
+
+    print(f"COMPONENTS / VARIANTS at top level: {len(components)}")
+    if components:
+        print("  -> reuse implies shared CSS components; variants imply states.\n")
+    else:
+        print()
+
+    if os.path.isdir(a.nodes):
+        dests, have = hover_destinations(a.nodes)
+        missing = [d for d in dests if d not in have]
+        print(f"HOVER VARIANTS: {sum(dests.values())} ON_HOVER actions -> {len(dests)} destination nodes")
+        print(f"  not in your cache: {len(missing)}  {missing[:5]}")
+        if missing:
+            print("  -> fetch them and compare your :hover against the real variant (§9.0).\n")
+        out["hover_destinations"] = {"all": list(dests), "missing": missing}
+    else:
+        print("HOVER VARIANTS: no node cache yet; re-run after figma_pull.py\n")
+
+    page_screens = defaultdict(list)
+    for s in screens:
+        page_screens[s["page"]].append(s["name"])
+    print("PAGE-SIZED FRAMES PER FIGMA PAGE (are you being asked for one screen, or a site?)")
+    for p, names in page_screens.items():
+        print(f"  {p!r}: {len(names)}")
+
+    if a.json:
+        pathlib.Path(a.json).write_text(json.dumps(out, indent=2))
+        print(f"\nwrote {a.json}")
+
+    print("\nShow this output to the user before you write any code.")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/figma_fonts.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Report every font the design actually renders, and which ones the user must supply.
+
+Run this once, before writing any CSS, and paste the output to the user (§0.3, §17.A).
+
+It is careful about three things that trip people up:
+  * `characters` styling can be overridden per character -> also read `styleOverrideTable`
+  * `visible: false` subtrees never render -> skipped
+  * a node can be `visible: true` and still render nothing -> effective (cumulative)
+    ancestor `opacity` of 0 is skipped too
+
+Usage:
+    python3 figma_fonts.py figma/nodes/*.json
+"""
+import json, sys
+from collections import Counter
+
+# Common families served free by Google Fonts. Not exhaustive — anything not listed is
+# reported as "verify"; check fonts.google.com before asking the user for it.
+GOOGLE = {
+    "abril fatface", "bodoni moda", "cormorant garamond", "dm sans", "dm serif display",
+    "eb garamond", "figtree", "fraunces", "geist", "ibm plex sans", "inter", "instrument sans",
+    "jost", "karla", "lato", "libre baskerville", "lora", "manrope", "merriweather",
+    "montserrat", "mulish", "nunito", "open sans", "outfit", "playfair display", "poppins",
+    "prata", "public sans", "quicksand", "raleway", "roboto", "rubik", "source sans 3",
+    "space grotesk", "spectral", "syne", "urbanist", "work sans",
+}
+
+
+def collect(paths):
+    faces = Counter()          # postScriptName -> render count
+    families = {}              # postScriptName -> family
+    for p in paths:
+        doc = json.load(open(p))
+        doc = doc["document"] if "document" in doc else doc
+
+        def walk(n, opacity=1.0):
+            if n.get("visible") is False:
+                return
+            opacity *= n.get("opacity", 1)
+            if opacity == 0:                      # renders nothing, needs no font
+                return
+            if n.get("type") == "TEXT":
+                styles = [n.get("style", {})]
+                styles += list((n.get("styleOverrideTable") or {}).values())
+                for st in styles:
+                    ps = st.get("fontPostScriptName")
+                    if not ps:
+                        continue
+                    faces[ps] += 1
+                    families[ps] = st.get("fontFamily") or ps.split("-")[0]
+            for c in n.get("children", []) or []:
+                walk(c, opacity)
+
+        walk(doc)
+    return faces, families
+
+
+def main():
+    paths = sys.argv[1:]
+    if not paths:
+        sys.exit(__doc__)
+    faces, families = collect(paths)
+    if not faces:
+        sys.exit("No TEXT nodes found — wrong files?")
+
+    free, licensed = [], []
+    for ps, n in faces.most_common():
+        (free if (families[ps] or "").lower() in GOOGLE else licensed).append((ps, families[ps], n))
+
+    print("Fonts this design actually renders\n")
+    if licensed:
+        print("LICENSED — the user must supply these (drop into design/fonts/):")
+        for ps, fam, n in licensed:
+            print(f"  {ps}.woff2   (or .otf)   family={fam!r}  used x{n}")
+    if free:
+        print("\nFREE — load these yourself from a CDN, do not ask the user:")
+        for ps, fam, n in free:
+            print(f"  {ps}   family={fam!r}  used x{n}")
+
+    print("\nNotes:")
+    print("  * families not in the built-in Google list are reported as LICENSED —")
+    print("    check fonts.google.com before asking the user for one.")
+    print("  * hidden nodes and nodes with effective opacity 0 were excluded, so this")
+    print("    list is what the page really needs.")
+    print("  * font files cannot be extracted from the REST API or from an SVG export.")
+
+
+if __name__ == "__main__":
+    main()