From a32830b73d594c28c9ef5623e4d5707d20446de6 Mon Sep 17 00:00:00 2001
From: Zared Rogers <zared@lightspeedwp.agency>
Date: Thu, 5 Nov 2026 15:17:51 +0200
Subject: [PATCH 1/3] feat(skills): add site-to-figma-components skill (#3992)

Crawl a live site, propose and review a component inventory, build it in Figma against the token library, verify it and write a Figma node to WordPress target manifest.

- crawl-site-structure, propose-inventory and write-manifest TypeScript scripts with 85 Jest tests
- route registered in the ai-readiness-agent routing map
- npm run test:site-to-figma-components

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |    2 +
 .../references/routing-map.yaml               |   16 +
 package.json                                  |    1 +
 skills/site-to-figma-components/SKILL.md      |   98 ++
 .../agents/openai.yaml                        |    4 +
 .../references/classification.md              |   78 +
 .../references/crawling.md                    |   53 +
 .../references/figma-build.md                 |   44 +
 .../references/inventory-review.md            |   55 +
 .../references/manifest.md                    |   66 +
 .../references/verification.md                |   34 +
 .../__tests__/crawl-site-structure.test.ts    |  595 +++++++
 .../scripts/__tests__/fixtures.ts             |  488 ++++++
 .../__tests__/propose-inventory.test.ts       |  659 +++++++
 .../scripts/__tests__/tokens.test.ts          |  111 ++
 .../scripts/__tests__/write-manifest.test.ts  |  212 +++
 .../scripts/crawl-site-structure.ts           | 1122 ++++++++++++
 .../scripts/jest.config.cjs                   |   28 +
 .../scripts/lib/color.ts                      |   93 +
 .../scripts/lib/tokens.ts                     |  274 +++
 .../scripts/propose-inventory.ts              | 1509 +++++++++++++++++
 .../scripts/tsconfig.json                     |    9 +
 .../scripts/write-manifest.ts                 |  312 ++++
 23 files changed, 5863 insertions(+)
 create mode 100644 skills/site-to-figma-components/SKILL.md
 create mode 100644 skills/site-to-figma-components/agents/openai.yaml
 create mode 100644 skills/site-to-figma-components/references/classification.md
 create mode 100644 skills/site-to-figma-components/references/crawling.md
 create mode 100644 skills/site-to-figma-components/references/figma-build.md
 create mode 100644 skills/site-to-figma-components/references/inventory-review.md
 create mode 100644 skills/site-to-figma-components/references/manifest.md
 create mode 100644 skills/site-to-figma-components/references/verification.md
 create mode 100644 skills/site-to-figma-components/scripts/__tests__/crawl-site-structure.test.ts
 create mode 100644 skills/site-to-figma-components/scripts/__tests__/fixtures.ts
 create mode 100644 skills/site-to-figma-components/scripts/__tests__/propose-inventory.test.ts
 create mode 100644 skills/site-to-figma-components/scripts/__tests__/tokens.test.ts
 create mode 100644 skills/site-to-figma-components/scripts/__tests__/write-manifest.test.ts
 create mode 100644 skills/site-to-figma-components/scripts/crawl-site-structure.ts
 create mode 100644 skills/site-to-figma-components/scripts/jest.config.cjs
 create mode 100644 skills/site-to-figma-components/scripts/lib/color.ts
 create mode 100644 skills/site-to-figma-components/scripts/lib/tokens.ts
 create mode 100644 skills/site-to-figma-components/scripts/propose-inventory.ts
 create mode 100644 skills/site-to-figma-components/scripts/tsconfig.json
 create mode 100644 skills/site-to-figma-components/scripts/write-manifest.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 899e8fa394..03645eb49a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Site to Figma Components Skill** — For website rebuilds, after the design tokens: crawls the live site at mobile and desktop widths, finds its repeated components, patterns, template parts and page templates with their variants and states, and writes an approval report that maps each to its WordPress block and proposes a variable for every value with no token. Once the reviewer approves the inventory and the templates to build, it builds them in Figma bound to the tokens, checks them against the live pages, and writes a manifest for `figma-to-block-theme` Pattern mode. ([#3992](https://github.com/lightspeedwp/.github/issues/3992))
+
 - **WordPress Schema Audit Agent** — Checks the structured data a WordPress site publishes against schema.org and Google's rules, then writes a client report and a spreadsheet of fixes. ([PR #3962](https://github.com/lightspeedwp/.github/pull/3962))
 - **Studio Migration Import Choices** — The agent asks about the table prefix, local accounts, tables to skip and the Studio site URL. Wordfence tables are skipped by default. ([PR #3961](https://github.com/lightspeedwp/.github/pull/3961))
 - **WordPress Studio Migration Agent** — Moves sites between Studio and staging or live: fixes exports Studio rejects, checks exports and replaces the site URL safely. ([PR #3959](https://github.com/lightspeedwp/.github/pull/3959))
diff --git a/agents/ai-readiness-agent/skills/lightspeed-project-onboarding/references/routing-map.yaml b/agents/ai-readiness-agent/skills/lightspeed-project-onboarding/references/routing-map.yaml
index 1e588edd54..c5e34db015 100644
--- a/agents/ai-readiness-agent/skills/lightspeed-project-onboarding/references/routing-map.yaml
+++ b/agents/ai-readiness-agent/skills/lightspeed-project-onboarding/references/routing-map.yaml
@@ -407,6 +407,22 @@ routes:
     use_when: Figma variables or codebase tokens need to become WordPress theme.json settings, presets, or style variations.
     prompt_starter: "Use the theme.json extractor orchestrator to route token extraction across palette, typography, spacing, shadows, and style variations."
 
+  - match:
+      intents:
+        - website_rebuild
+        - live_site_to_figma
+        - rebuild_components
+        - rebuild_templates
+    primary_skill: site-to-figma-components
+    related_skills:
+      - site-to-design-tokens
+      - figma-to-block-theme
+      - figma-generate-library
+      - figma-generate-design
+      - audit-design-system
+    use_when: a live website is being rebuilt and its components, patterns, template parts and templates need to exist in Figma, bound to the design tokens, before the theme is built.
+    prompt_starter: "Use site-to-figma-components after site-to-design-tokens: crawl the live site, approve the inventory and build scope, build the approved set in Figma, then hand the manifest to figma-to-block-theme Pattern mode."
+
   - match:
       intents:
         - linear_triage
diff --git a/package.json b/package.json
index 38a866c897..ae45bfbcc0 100644
--- a/package.json
+++ b/package.json
@@ -154,6 +154,7 @@
     "metrics:run": "node metrics/frontmatter-metrics.js",
     "metrics:ci": "node metrics/frontmatter-metrics.js",
     "test:js": "jest --config .jest.config.cjs --coverage --forceExit --detectOpenHandles",
+    "test:site-to-figma-components": "jest --config skills/site-to-figma-components/scripts/jest.config.cjs",
     "test:agent-spec-validation": "node .github/scripts/__tests__/validate-agent-specs.test.js",
     "test:index-generator": "node .github/scripts/__tests__/generate-agent-index.test.js",
     "test:create-agent-spec": "node .github/scripts/__tests__/create-agent-spec.test.js",
diff --git a/skills/site-to-figma-components/SKILL.md b/skills/site-to-figma-components/SKILL.md
new file mode 100644
index 0000000000..9bd294c3a3
--- /dev/null
+++ b/skills/site-to-figma-components/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: site-to-figma-components
+description: Rebuild a live website's building blocks in Figma as a design system for a WordPress rebuild. Use after site-to-design-tokens has created the Figma variables, when a project needs the site's components (buttons, cards, form fields, navigation, accordions, sliders), patterns (heroes, card grids, call-to-action bands), template parts (header, footer, sidebar) and templates (one frame per page type) built in Figma from those variables. Crawls chosen pages at 390px and 1440px, writes an inventory report for approval, then builds component sets, parts, patterns and templates bound to semantic tokens, verifies them against the live pages, and writes a manifest that maps each Figma node to its WordPress target for figma-to-block-theme Pattern mode.
+---
+
+# Site to Figma Components
+
+## Overview
+
+The third step of a rebuild. Tokens come first, then this skill, then the theme.
+
+```text
+site-to-design-tokens → crawl → inventory report → approval → Figma build → verify → manifest → figma-to-block-theme (Pattern mode)
+```
+
+It stops for approval between stages. Nothing is written to Figma before the reviewer approves the inventory.
+
+## Companion skills
+
+- `figma-use`: **required before every `use_figma` call**, read-only ones included.
+- `figma-generate-library`: component sets, variant properties and variable bindings (stage 3).
+- `figma-generate-design`: composing parts, patterns and templates from instances (stage 3).
+- `audit-design-system` and `fix-design-system-finding`: the design system audit (stage 4).
+- `site-to-design-tokens`: must have run first. Its variables export is this skill's `--tokens` input.
+- `figma-to-block-theme`: reads the manifest in Pattern mode. `wp-block-themes` and `wp-patterns` cover the WordPress side.
+
+If a companion skill is missing, say so and stop rather than calling Figma tools directly.
+
+## Stage 1: Inventory
+
+1. **Agree the pages** with the reviewer: one or two public pages per template, from the site's sitemap. See [references/crawling.md](references/crawling.md).
+2. **Crawl** (scratch folder outside the repository):
+
+   ```bash
+   npx tsx ${CLAUDE_SKILL_DIR}/scripts/crawl-site-structure.ts --url https://www.example.com \
+     --pages '/,/tours/example/,/blog/,/?s=safari' --out site-structure.json --shots shots
+   ```
+
+3. **Get the tokens.** Use the `variables.json` from `site-to-design-tokens`, or export the variables from the project's Figma file with the script in `figma-to-block-theme`'s `references/figma-access.md`.
+4. **Propose**, then take one example screenshot per item:
+
+   ```bash
+   npx tsx ${CLAUDE_SKILL_DIR}/scripts/propose-inventory.ts site-structure.json --tokens variables.json \
+     --theme <theme-slug> --out inventory.json --report inventory.md --shots shots
+   npx tsx ${CLAUDE_SKILL_DIR}/scripts/crawl-site-structure.ts --url https://www.example.com \
+     --shoot inventory.json --shots shots
+   ```
+
+## Stage 2: Approval report
+
+Present `inventory.md`: the decisions list first (with a proposal for every value that has no token), then each table. [references/inventory-review.md](references/inventory-review.md) explains the sections. The reviewer approves, renames, merges or cuts items. Record the answers in `decisions.json`, including the **build scope** (`"build"`: the templates and items to import), re-run `propose-inventory.ts` with `--decisions decisions.json`, and repeat until the report says **approved** and lists the build scope. How items are found, named and mapped is in [references/classification.md](references/classification.md).
+
+## Stage 3: Figma build
+
+Confirm the target file and pages, add the variables the reviewer approved, then follow [references/figma-build.md](references/figma-build.md). Build only the approved scope, in this order:
+
+1. **Components**: component sets with variant properties, Auto Layout, text styles and a variable on every fill, stroke, gap, padding, radius, font and effect. Each description names its WordPress block.
+2. **Template parts and patterns**: composed from component instances.
+3. **Templates**: composed from parts and patterns, at 1440px, and at 390px where the report says the layout changes.
+
+Record each built node ID in `figma-nodes.json` as you go.
+
+## Stage 4: Verify
+
+Compare each frame with the live page at both widths, list the differences, and run the design system audit until it is clean. See [references/verification.md](references/verification.md).
+
+## Stage 5: Hand-off
+
+```bash
+npx tsx ${CLAUDE_SKILL_DIR}/scripts/write-manifest.ts inventory.json --nodes figma-nodes.json \
+  --out manifest.json --markdown manifest.md
+```
+
+Add `--partial` while only some items are built. Hand `manifest.json` to `figma-to-block-theme` Pattern mode and post `manifest.md` on the project's Linear issue. See [references/manifest.md](references/manifest.md).
+
+## Rules
+
+- **Approval first.** No Figma writes before the inventory is approved, and confirm the target file and pages before the first write.
+- **Tokens only.** Every colour, size, space, radius and shadow binds to a variable, semantic tokens before primitives. A value with no token gets a proposal for the reviewer: fonts match the live site (an `Alternate` family), colours fit the ramps, sizes get a new ramp step in order, and one-offs become semantically named `custom/*` variables. Nothing is added without approval.
+- **Approved build scope.** The reviewer approves which templates to build before any import.
+- **Public pages only**, one at a time at the default pace. Never log in, submit a form, click or type. Hovering and focusing to read states is allowed.
+- **Archive, don't delete.** Move superseded Figma items to an archive page (`node.remove()` is blocked) and check prototype link destinations before moving anything.
+- **No em dashes** in Figma copy or document text.
+- **Real content.** Use the site's headings, labels and images, uploaded with the Figma image tools.
+
+## Scripts
+
+TypeScript run with `tsx` (`npx tsx <script> --help`). Tests are in `scripts/__tests__/`: run `npm run test:site-to-figma-components` from the repository root.
+
+| Script | Does |
+| --- | --- |
+| `scripts/crawl-site-structure.ts` | Records regions, sections and components with shape, style, states and content, with Puppeteer; `--shoot` takes example screenshots |
+| `scripts/propose-inventory.ts` | Clusters and classifies, maps to WordPress, binds to tokens, writes the inventory and report, applies decisions |
+| `scripts/write-manifest.ts` | Maps built Figma nodes to WordPress targets for Pattern mode |
+| `scripts/lib/tokens.ts`, `scripts/lib/color.ts` | Token matching and colour helpers |
+
+*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
+[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/agents/openai.yaml b/skills/site-to-figma-components/agents/openai.yaml
new file mode 100644
index 0000000000..9b836a7a6b
--- /dev/null
+++ b/skills/site-to-figma-components/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Site to Figma Components"
+  short_description: "Rebuild a live site's components, patterns and templates in Figma"
+  default_prompt: "Use $site-to-figma-components to crawl the live site, propose an inventory of components, patterns, template parts and templates for approval, build the approved set in Figma bound to the design tokens, verify it and write the manifest for figma-to-block-theme."
diff --git a/skills/site-to-figma-components/references/classification.md b/skills/site-to-figma-components/references/classification.md
new file mode 100644
index 0000000000..f5ced99048
--- /dev/null
+++ b/skills/site-to-figma-components/references/classification.md
@@ -0,0 +1,78 @@
+# Classification, naming and WordPress mapping
+
+`propose-inventory.ts` uses the 1440px captures to cluster and name items, and the 390px captures to decide what changes on mobile.
+
+## Kinds
+
+| Kind | Rule | Figma name |
+| --- | --- | --- |
+| Template part | `header` or `footer` on at least 60% of pages; a `sidebar` on two or more | `Template Parts/<Name>` |
+| Pattern | A section shape found more than once. A shape found once is flagged as a one-off | `Patterns/<Name>` |
+| Component | A repeated single element. Families (buttons, inputs, links, navigation and so on) form one set each; cards are grouped by their most distinctive shared class, forms by search or not | `Components/<Group>/<Name>` |
+| Template | One per page type, from WordPress body classes: `{post_type}-template-default` gives `single-<type>`, then `post-type-archive-*`, `tax-*`, `page-template-*`, `home`, `blog`, `search`, `error404` | `Templates/<Name>` |
+
+Pages that share a template are grouped. Its composition (parts and patterns, top to bottom) comes from the first page of the group.
+
+## Pattern names
+
+From the section's content, in order: `Section Heading`, `Hero` (first section with media and a heading), `Testimonials`, `Card Grid` (two or more cards inside), `Form Section`, `Gallery`, `Banner`, `Media and Text` (two columns with an image), `Feature Row` (three or more columns), `Call to Action` (buttons in a short section), else `Content Section`. Repeated names get a number. The reviewer renames them.
+
+## Variant properties
+
+Named as in the TSP file. Only properties with more than one value are kept.
+
+| Property | Values | Used for |
+| --- | --- | --- |
+| `Style` | `Fill`, `Outline`, `Text` (inputs: `Bordered`, `Filled`, `Plain`) | buttons, badges, inputs |
+| `Size` | `Small`, `Medium`, `Large`, by height | buttons |
+| `Icon`, `Has Text` | `True`, `False` | buttons, badges |
+| `Type` | `Text`, `Select`, `Textarea` | inputs |
+| `Mode` | `Light`, `Dark`, `Transparent`, `Image` | sections, parts, navigation |
+| `Region` | `Header`, `Footer` | navigation items outside the content |
+| `Layout` | `A`, `B` … | cards whose inner structure differs |
+| `State` | `Default`, `Hover`, `Focus`, `Active`, `Open`, `Disabled` | anything with states |
+| `Breakpoint` | `Desktop`, `Mobile` | items whose 390px size or columns differ |
+
+## WordPress targets
+
+| Item | Target |
+| --- | --- |
+| Button | `core/button`; non-default styles become block styles (`styles/blocks/button/<slug>.json`) |
+| Text link | `styles.elements.link` in `theme.json` |
+| Navigation item, pagination | `core/navigation-link`, `core/query-pagination` |
+| Accordion | `core/details` (or `core/accordion` where available) |
+| Badge | block style on `core/post-terms` |
+| Search form | `core/search` |
+| Card | an `Inserter: false` pattern used inside `core/post-template` |
+| Form, input, breadcrumbs, tabs, slider | plugin or custom block; noted for the reviewer |
+| Template part | `parts/<slug>.html`, area `header`, `footer` or `uncategorized` |
+| Pattern | `patterns/<slug>.php`, slug `<theme>/<slug>`, main block (`core/cover`, `core/query`, `core/media-text` …) |
+| Template | `templates/<slug>.html` |
+
+These names are what `figma-to-block-theme` Pattern mode expects.
+
+## Token binding
+
+Every styled value of each variant (fill, text, stroke, font family and size, radius, padding, gap, shadow) is matched against the variables export:
+
+- **Colours:** semantic tokens first. Buttons prefer `action/*`; everything else prefers `text/*`, `surface/*` and `border/*`. A match within a small distance is `exact` or `near`. A colour that only matches a primitive is `primitive`. Prototype collections (`Proto - …`) are ignored.
+- **Sizes:** the `Max` mode of the spacing, radius and type size collections, within 2px or 8%.
+- **Shadows:** the first layer, against drop shadow effect styles.
+
+Anything `none` or `primitive` is listed in the report with a **proposal** for the reviewer, following the LightSpeed rules:
+
+| Value | Proposal |
+| --- | --- |
+| A font with no family variable | Fonts always match the live site: add a family variable (`Font-Families/Alternate`, slug `alternate`) |
+| A colour | Fit it into a colour ramp (it replaces the nearest step when it fits, as in `site-to-design-tokens`) or match it to the nearest existing colour, then bind the semantic token for its role. Theme `contrast` matches the live text colour |
+| A size (radius, spacing, type size) | Add a step to the ramp, in order, with valid naming; renumber slugs if needed (TSP added Radius Huge at `600` and moved Round to `700`) |
+| A true one-off | A semantically named custom variable in the semantic collection (`custom/social-twitter`, `custom/scroll-arrow-size`), as `theme.json` `settings.custom` would hold it |
+
+Nothing is added until the reviewer approves. Then add the variables before the build (see [figma-build.md](figma-build.md)).
+
+## Near duplicates and one-offs
+
+Items whose shape signatures share at least 75% of their tokens (50% for items with the same base name) are grouped as look-alikes for the reviewer to merge. Items found once are flagged as one-offs: cut them, or keep them with `promote`.
+
+*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
+[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/crawling.md b/skills/site-to-figma-components/references/crawling.md
new file mode 100644
index 0000000000..572f7482b7
--- /dev/null
+++ b/skills/site-to-figma-components/references/crawling.md
@@ -0,0 +1,53 @@
+# Crawling the live site
+
+## Choosing pages
+
+Pick pages that between them show every template the rebuild needs, and two of each repeated type so patterns can be told from one-offs:
+
+- the home page
+- two singles of each custom post type (tours, destinations, accommodation)
+- each archive and taxonomy page, the blog index and two posts
+- two plain pages, such as About and Contact
+- a search results URL (`/?s=word`) and a missing URL for the 404 template
+
+Take URLs from the sitemap (`/sitemap_index.xml` or `/wp-sitemap.xml`). Quote the page list in the shell, because `?` is a glob character in zsh.
+
+Use the **live** site. Avoid account, cart, checkout and admin pages; the crawler refuses common ones. The default limit is 15 pages (`--max-pages`).
+
+## What is recorded
+
+At each viewport (390px and 1440px), after fixed overlays such as cookie banners and chat widgets are hidden:
+
+| Hint | Found as |
+| --- | --- |
+| `header`, `footer` | `<header>`, `<footer>` or ids and classes such as `masthead`, `footer-widgets` and `colophon`, full width and outside `main`. A footer can have several pieces |
+| `sidebar` | `#secondary`, `.sidebar` or an `<aside>` of widgets, narrower than 45% of the page |
+| `section` | The stacked children of `main` (through single wrappers), at least 60% of the content column wide, plus full-width bands outside `main` such as page banners |
+| `button`, `input`, `link`, `nav-item` | Buttons and links styled as buttons; text inputs and selects; links in running text; links in navigation |
+| `card` | Repeated siblings with an image, a heading and a link |
+| `badge`, `breadcrumbs`, `pagination`, `accordion`, `tabs`, `slider`, `form` | Small labelled pills; ARIA labels, roles and common class names; `<details>`; `<form>` |
+
+For each one it keeps a unique selector, a label (`tag#id.class`), the region it sits in, its box, a **shape signature** (the tag tree to depth 3, with repeats collapsed: `ul(li*)`), the number of columns its children form, computed styles, and real content: up to three headings, button labels and images.
+
+## States
+
+- **From CSS:** same-origin `:hover`, `:focus`, `:focus-visible`, `:active` and `:disabled` rules whose selector names a class, id or attribute. Bare element rules such as `a:hover` are ignored.
+- **In the browser:** one example of each distinct interactive element is hovered and focused (`--states`, default 30 per page), and what changed replaces the CSS guess.
+- **From markup:** `disabled`, `aria-disabled`, `open` and `aria-expanded="true"`.
+
+Nothing is clicked or typed, so open menus, modals and submitted form states are not captured. Note them for the reviewer if the design needs them.
+
+## Redirects and failures
+
+Each capture records its final URL. Pages that redirect to a page already crawled are left out and listed in the report. TSP redirects its tour, accommodation and review archives to the home page, for example. A page that times out is skipped, listed in the report and in the command output, and the crawl continues.
+
+## Screenshots
+
+`--shots` saves a full-page screenshot per page and viewport. After proposing, `--shoot inventory.json` saves one element screenshot per item (`<item-id>-1440.png`), which the report embeds.
+
+## Politeness
+
+One page at a time with a 1.5 second pause (`--delay`), only on the `--url` origin. Puppeteer downloads its browser on first install; if the launch fails, run `npx puppeteer browsers install chrome`.
+
+*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
+[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/figma-build.md b/skills/site-to-figma-components/references/figma-build.md
new file mode 100644
index 0000000000..d9d120825b
--- /dev/null
+++ b/skills/site-to-figma-components/references/figma-build.md
@@ -0,0 +1,44 @@
+# Building in Figma
+
+Load `figma-use` before every `use_figma` call, `figma-generate-library` for components, and `figma-generate-design` for parts, patterns and templates. Follow their rules on sessions, one page per call, returned IDs and fonts. This file covers only what is specific to rebuilding a live site.
+
+## Before the first write
+
+1. **Agree the build scope.** The reviewer chooses which templates (and any extra items) to build, as `"build"` in `decisions.json`. Templates bring their parts and patterns. Build nothing outside `buildScope`.
+2. **Confirm the file and pages.** Match the file's page structure. A test or pilot run goes on one page with a section per kind (Components, Template Parts, Patterns, Templates, Assets). A full build follows the file's groups (`> Components`, `> Template Parts`, `> Patterns`, `> Templates`).
+3. **Add the approved variables first.** Apply the reviewer's answers to the report's proposals (see [classification.md](classification.md)): new font family, colours fitted into the ramps, new ramp steps, `custom/*` variables. If `setValueForMode` fails with "unloaded font", load the fonts the error names and retry; text bound to the variable must re-render.
+4. **Inspect the file once** (read-only): local variables with their IDs, text and effect styles, existing icon components, and the fonts available (`listAvailableFontsAsync`). Keep a state ledger of every ID you create in a scratch file.
+
+## Images
+
+- Download images from the live site: `content.images` in the inventory, plus computed `background-image` on parts and sections. A video background has no image; extract a frame from the video file (`ffmpeg -ss 4 -i video.mp4 -frames:v 1 hero.jpg`) and crop any letterbox.
+- Upload with `upload_assets` (`currentPageId` set), POSTing each file as multipart. Rasters arrive as image frames with an `imageHash`; SVGs arrive as editable vectors.
+- `use_figma` can't fetch images (`createImageAsync` is unsupported). Apply uploaded images by copying `imageHash` into a fill: `{ type: 'IMAGE', imageHash, scaleMode: 'FILL' }`, on main components and as instance overrides.
+- Turn SVG icons into components and bind their fills to the nearest semantic colour. Clear the hidden placeholder fill `createNodeFromSvg` adds. A brand logo keeps its own artwork colours.
+- If the Figma MCP offers `generate_figma_design`, a capture of the live page may be used as a visual reference only, then removed. Never place a screenshot of the page in the deliverable.
+
+## Order and structure
+
+1. **Components** with `figma-generate-library`: one component set per inventory component, named from `figmaName` (`Components/Buttons/Button`), with the inventory's variant properties (`Style`, `Size`, `State`, `Breakpoint` …). Keep matrices at 30 variants or fewer. Expose text as `TEXT` properties and optional icons as `BOOLEAN` properties. After `combineAsVariants`, lay variants out in a grid and set the set's corner radius to 0.
+2. **Template parts and patterns** with `figma-generate-design`: components themselves (sets with `Breakpoint=Desktop|Mobile` where the 390px layout changes), built only from component instances, text and image frames. Expose headings and links as properties so templates can override them.
+3. **Templates**: an Auto Layout frame per page type and width (`Templates/<Name>/1440`, `/390`), whose direct children are only part and pattern instances, in the inventory's composition order. Override content with properties; swap nested card instances where a section uses a different card.
+
+Use real site content throughout: headings, labels, excerpts, meta and images from the crawl.
+
+## Binding rules
+
+- **Every** fill, stroke, padding, gap, radius, width bound to a token, font size and font family binds to a variable; semantic colour tokens for colours (`action/*` for buttons; `text/*`, `surface/*` and `border/*` elsewhere).
+- Text uses text styles. Don't change case, weight or decoration on a styled node: that detaches the style. Create a text style for the role instead (for example `Primary/Button Text/Small Strong`, uppercase, bound to the font family and size variables).
+- Each component and component set gets a `description` naming its source on the live site, its WordPress target and its inventory id.
+- A width or size with no token (such as a 1120px column) uses the nearest layout token and goes on the verification differences list.
+
+## Record node IDs
+
+After each call, add the IDs to `figma-nodes.json`: the component set for components; the set and its `Breakpoint=Mobile` variant (`mobileNodeId`) for parts and patterns; the 1440 frame and the 390 frame for templates. See [manifest.md](manifest.md).
+
+## Archive, never delete
+
+`node.remove()` is blocked. Move superseded items to an archive page, grouped in sections, and check the destinations of prototype links before moving anything.
+
+*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
+[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/inventory-review.md b/skills/site-to-figma-components/references/inventory-review.md
new file mode 100644
index 0000000000..6d972f0603
--- /dev/null
+++ b/skills/site-to-figma-components/references/inventory-review.md
@@ -0,0 +1,55 @@
+# Reviewing the inventory
+
+`inventory.md` is written for the person who approves what gets built. Walk through it in this order.
+
+## Summary
+
+Items per kind, how many are one-offs, and how many styled values bind to a token.
+
+## Decisions for the reviewer
+
+Each line needs an answer before approval:
+
+| Line | Means | Answer with |
+| --- | --- | --- |
+| **Merge?** | Items that look alike | `merge` the pairs to combine, or leave them separate |
+| **Redirected** | A requested page redirected to one already crawled | Choose another page of that type, or accept |
+| **Not captured** | A page timed out | Re-run the crawl for it |
+| **One-off** | Found once | `cut` it, or `promote` it to keep it |
+| **No token** | A live value with no matching variable, with a proposal (new font family, ramp fit, new ramp step or `custom/*` variable) | Approve the proposal or give another; nothing is added without approval |
+| **Primitive only** | A colour that only matches a primitive | Point a semantic role at it, or approve a new semantic token |
+| **Template not crawled** | A common template with no page in the crawl | Add a page and re-crawl, or confirm it isn't needed |
+
+## Tables
+
+- **Template parts:** how many pages each appears on, its pieces and its variant properties.
+- **Components:** Figma name, count, pages, variant properties (including `State`) and WordPress target.
+- **Patterns:** name with its first heading, count, source pages, whether the 390px layout changes, and WordPress target.
+- **Templates:** each template file with its pages, its frames (1440, and 390 where the layout changes) and its composition.
+- **Values with no token:** every value the build can't bind yet, with the items that use it.
+
+Screenshots sit beside each item when `--shoot` has run.
+
+## Recording decisions
+
+Write `decisions.json` and re-run `propose-inventory.ts` with `--decisions decisions.json`. Ids come from the report.
+
+```json
+{
+  "rename": { "pattern:hero-2": "Tour Summary", "component:card": "Post Card" },
+  "merge": [["pattern:media-and-text", "pattern:media-and-text-2"]],
+  "cut": ["component:tabs", "pattern:content-section-9"],
+  "promote": ["pattern:hero"],
+  "build": ["template:front-page", "template:single-tour", "component:button"],
+  "approve": true
+}
+```
+
+Add `"build"` with the templates (and any extra items) to build in Figma. The reviewer must approve this set before any import; templates bring their parts and patterns, and the report lists the resulting **Build scope**.
+
+Merges run first, then cuts, promotions, renames and the build scope. A merged item takes the other's pages, examples and variants, and templates point to it. A cut item stays in the inventory with `status: "cut"`; templates show it as a local section. Set `"approve": true` only when the reviewer has said so. The manifest writer refuses an unapproved inventory.
+
+Post the approved report on the project's Linear issue.
+
+*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
+[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/manifest.md b/skills/site-to-figma-components/references/manifest.md
new file mode 100644
index 0000000000..61d8fb0441
--- /dev/null
+++ b/skills/site-to-figma-components/references/manifest.md
@@ -0,0 +1,66 @@
+# The hand-off manifest
+
+`write-manifest.ts` joins the approved `inventory.json` with the node IDs recorded during the build.
+
+## figma-nodes.json
+
+Assemble it from the IDs each `use_figma` build call returns:
+
+```json
+{
+  "fileKey": "dsDojfcCaLQSwLZaYqM0qu",
+  "nodes": {
+    "component:button": { "nodeId": "14100:200", "page": "> Components" },
+    "part:header": { "nodeId": "14100:310", "mobileNodeId": "14100:340" },
+    "template:single-tour": { "nodeId": "14101:12", "mobileNodeId": "14101:900" }
+  }
+}
+```
+
+Use the component set's ID for components, and the 1440px frame (`nodeId`) and 390px frame (`mobileNodeId`) for parts, patterns and templates.
+
+## manifest.json
+
+```json
+{
+  "manifestVersion": 1,
+  "site": "https://www.example.com",
+  "theme": "tsp-theme",
+  "figmaFileKey": "dsDojfcCaLQSwLZaYqM0qu",
+  "inventoryApprovedAt": "2026-11-06T09:00:00.000Z",
+  "generatedAt": "2026-11-07T09:00:00.000Z",
+  "entries": [
+    {
+      "id": "pattern:hero",
+      "kind": "pattern",
+      "name": "Hero",
+      "figma": { "fileKey": "…", "nodeId": "14100:500", "name": "Patterns/Hero", "url": "https://www.figma.com/design/…?node-id=14100-500" },
+      "wordpress": { "type": "pattern", "block": "core/cover", "slug": "tsp-theme/hero", "file": "patterns/hero.php" },
+      "sourcePages": ["https://www.example.com/"]
+    },
+    {
+      "id": "template:single-tour",
+      "kind": "template",
+      "wordpress": { "type": "template", "slug": "single-tour", "file": "templates/single-tour.html" },
+      "composition": [
+        { "id": "part:header", "target": "template-part", "slug": "header", "file": "parts/header.html" },
+        { "id": "pattern:hero", "target": "pattern", "slug": "tsp-theme/hero", "file": "patterns/hero.php" },
+        { "id": "pattern:map", "target": "local" }
+      ]
+    }
+  ],
+  "skipped": [],
+  "warnings": []
+}
+```
+
+Entries are ordered components, template parts, patterns, then templates, so styles exist before the patterns that use them. `variantProperties` is included for items with variants. A composition entry marked `local` is a section the reviewer cut: build it inline in the template.
+
+The writer refuses an unapproved inventory, a node ID not in the form `123:456`, and (without `--partial`) any item with no node. It warns about nodes for cut or unknown items, and about templates that change at 390px but have no mobile frame.
+
+## How Pattern mode uses it
+
+`figma-to-block-theme` Pattern mode reads `manifest.json` in entry order. For each entry it reads the node with `figma-design-to-code`, writes the file named in `wordpress.file`, and uses `wordpress.slug`, `block` and `styles` as given. Templates are written last, from their `composition`: `<!-- wp:template-part {"slug":"header"} /-->` for parts and `<!-- wp:pattern {"slug":"tsp-theme/hero"} /-->` for patterns.
+
+*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
+[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/verification.md b/skills/site-to-figma-components/references/verification.md
new file mode 100644
index 0000000000..39c8ddcc55
--- /dev/null
+++ b/skills/site-to-figma-components/references/verification.md
@@ -0,0 +1,34 @@
+# Verifying the build
+
+## Compare with the live site
+
+For each template, at 1440px and at 390px where it has a mobile frame:
+
+1. Take one screenshot of the Figma frame (`get_screenshot`).
+2. Open the crawl's full-page screenshot of a source page (`shots/<page>-1440.png`, `-390.png`).
+3. Compare section by section, and list every difference in a table: section, what differs, why (out of scope, no token, content), and whether to fix now.
+
+Fix defects with targeted `use_figma` edits: clipped or overlapping text, wrong variants, placeholder text, missing images, headings that don't wrap at 390px. Then take one more screenshot. Differences that are out of scope or need a decision go in the list for the reviewer.
+
+## Design system audit
+
+Run `audit-design-system` on the build page, or this read-only scan through `use_figma` across the build sections. Skip nodes inside instances (their main components are checked at the source) and the logo artwork.
+
+| Check | Clean when |
+| --- | --- |
+| Solid fills and strokes | Each has `boundVariables.color` (ignore hidden paints, or remove them) |
+| Auto Layout padding and gaps | Each non-zero value has a bound variable |
+| Corner radius | Each non-zero radius is bound (component set containers set to 0) |
+| Text | Every text node has a `textStyleId`; no mixed styles |
+| Effects | Every effect uses an effect style |
+| Detached instances | No frame carries a component's name; every template instance has a `mainComponent` |
+| Templates | Every direct child of a template frame is an instance |
+
+Fix findings with `fix-design-system-finding`, or in a small `use_figma` pass, and re-run the scan until every count is zero. Report anything that comes from the file's existing components (outside the build) rather than overriding it locally.
+
+## Report
+
+Post the differences table and the audit counts on the project's Linear issue with `manifest.md`.
+
+*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
+[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/scripts/__tests__/crawl-site-structure.test.ts b/skills/site-to-figma-components/scripts/__tests__/crawl-site-structure.test.ts
new file mode 100644
index 0000000000..30c63fdc1a
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/__tests__/crawl-site-structure.test.ts
@@ -0,0 +1,595 @@
+/**
+ * @jest-environment jsdom
+ */
+/* global Element, HTMLElement, DOMRect */
+import {
+  BrowserDriver,
+  CollectedStructure,
+  collectPageStructure,
+  hideOverlays,
+  PageHandle,
+  readElementStyle,
+  runCrawlCli,
+  StructureCrawler,
+  StructureNode,
+  StyleSig,
+  styleDiff,
+} from '../crawl-site-structure';
+
+/** jsdom has no layout, so each element's box comes from its data-rect="x,y,w,h". */
+beforeAll(() => {
+  Element.prototype.getBoundingClientRect = function (this: Element) {
+    const value = (this as HTMLElement).dataset?.rect;
+    const [x, y, w, h] = value ? value.split(',').map(Number) : [0, 0, 0, 0];
+    return {
+      left: x,
+      top: y,
+      width: w,
+      height: h,
+      right: x + w,
+      bottom: y + h,
+      x,
+      y,
+      toJSON: () => ({}),
+    } as DOMRect;
+  };
+});
+
+const card = (name: string, x: number) => `
+  <article class="lsx-to-widget-item-wrap lsx-tour" data-rect="${x},700,300,360">
+    <img src="/${name}.jpg" alt="${name}" data-rect="${x},700,300,200">
+    <h3 data-rect="${x},900,300,30">${name}</h3>
+    <a href="#" data-rect="${x},940,60,20">View</a>
+  </article>`;
+
+const PAGE = `
+  <style>
+    .btn:hover { background-color: rgb(0, 0, 0); }
+    a:hover { color: red; }
+    .menu a:focus-visible { text-decoration: underline; }
+    @media (min-width: 1px) { .badge:hover { opacity: 0.8; border-color: rgb(1, 2, 3); box-shadow: 0 0 2px red; } }
+  </style>
+  <div id="page" data-rect="0,0,1024,3000">
+    <header class="site-header" data-rect="0,0,1024,80">
+      <nav class="menu" data-rect="0,0,600,80">
+        <ul data-rect="0,0,600,80">
+          <li data-rect="0,0,80,20"><a href="#" data-rect="0,0,80,20" style="color: rgb(255, 255, 255)">Tours</a></li>
+          <li data-rect="90,0,80,20"><a href="#" data-rect="90,0,80,20">Blog</a></li>
+        </ul>
+      </nav>
+      <a class="btn" href="#" style="background-color: rgb(163, 23, 0); padding-left: 16px; border-radius: 8px" data-rect="900,20,100,40">Enquire</a>
+    </header>
+    <div class="page-banner" style="background-color: rgb(246, 243, 241)" data-rect="0,80,1024,200"><h1 data-rect="0,100,500,60">Banner</h1></div>
+    <main data-rect="0,280,1024,2000">
+      <div class="wrap" data-rect="0,280,1024,2000">
+        <section class="wp-block-cover hero" style="background-image: url(hero.jpg); padding-top: 80px" data-rect="0,280,1024,400">
+          <h2 data-rect="0,300,600,60">Hero title</h2>
+          <div class="wp-block-buttons" data-rect="0,380,300,50">
+            <div class="wp-block-button" data-rect="0,380,120,50"><a class="wp-block-button__link" href="#" style="background-color: rgb(86, 91, 61); box-shadow: rgba(0, 0, 0, 0.2) 0px 2px 4px 0px" data-rect="0,380,120,50">Go <svg></svg></a></div>
+          </div>
+        </section>
+        <section class="cards" data-rect="0,680,1024,400">
+          <h2 data-rect="0,680,600,40">Tours</h2>
+          <div class="grid" style="display: grid; gap: 20px" data-rect="0,700,1024,380">${card('Tour A', 0)}${card('Tour B', 320)}${card('Tour C', 640)}</div>
+        </section>
+        <div class="short" data-rect="0,1080,1024,40"><p data-rect="0,1080,600,20">Read <a href="#" style="color: rgb(141, 98, 31)" data-rect="40,1080,40,20">a link</a> here.</p></div>
+        <form role="search" class="search-form" data-rect="0,1200,500,200">
+          <input type="search" style="border: 1px solid rgb(138, 133, 128)" data-rect="0,1200,300,40">
+          <input type="checkbox" data-rect="0,1250,20,20">
+          <select data-rect="0,1280,200,40"></select>
+          <button disabled data-rect="320,1200,100,40">Search</button>
+        </form>
+        <details open data-rect="0,1420,600,60"><summary data-rect="0,1420,600,30">Question</summary></details>
+        <nav aria-label="Breadcrumb" data-rect="0,1500,400,20"><a href="#" data-rect="0,1500,40,20">Home</a></nav>
+        <div class="pagination" data-rect="0,1530,400,40"><a href="#" data-rect="0,1530,20,20">1</a></div>
+        <div class="swiper" data-rect="0,1580,600,300"></div>
+        <div role="tablist" data-rect="0,1900,600,40"></div>
+        <span class="badge" style="background-color: rgb(255, 255, 255); border-radius: 4px" data-rect="0,1950,60,24">New</span>
+        <div style="display: none" data-rect="0,2000,600,100"><p>Hidden</p></div>
+        <div aria-hidden="true" data-rect="0,2000,600,100"><span class="badge" style="background-color: red; border-radius: 4px" data-rect="0,2000,60,24">x</span></div>
+      </div>
+    </main>
+    <div id="footer-widgets" data-rect="0,2300,1024,300"><aside class="widget" data-rect="0,2300,300,300"><a href="#" data-rect="0,2300,60,20">Widget</a></aside></div>
+    <footer data-rect="0,2600,1024,80"><nav data-rect="0,2600,300,20"><a href="#" data-rect="0,2600,60,20">Terms</a></nav></footer>
+  </div>`;
+
+describe('collectPageStructure', () => {
+  let result: CollectedStructure;
+  const of = (hint: string) => result.nodes.filter((n) => n.hint === hint);
+
+  beforeEach(() => {
+    document.title = 'Home';
+    document.body.className = 'home page';
+    document.body.innerHTML = PAGE;
+    result = collectPageStructure();
+  });
+
+  it('reports the page title, body classes and final URL', () => {
+    expect(result.title).toBe('Home');
+    expect(result.bodyClasses).toEqual(['home', 'page']);
+    expect(result.finalUrl).toBe(window.location.href);
+  });
+
+  it('finds the header and both footer pieces as regions', () => {
+    expect(of('header')).toHaveLength(1);
+    expect(of('footer').map((n) => n.label)).toEqual(['div#footer-widgets', 'footer']);
+    expect(of('sidebar')).toHaveLength(0); // A widget inside the footer is not a sidebar.
+    expect(of('nav-item').map((n) => n.region)).toEqual(['header', 'header', 'footer']);
+  });
+
+  it('finds sections inside main and full-width bands outside it', () => {
+    const sections = of('section');
+    expect(sections.map((n) => n.label)).toEqual([
+      'section.wp-block-cover.hero',
+      'section.cards',
+      'div.page-banner',
+    ]);
+    expect(sections[0].style.backgroundImage).toBe(true);
+    expect(sections[0].style.paddingBlock).toBe(80);
+    expect(sections[1].shape).toContain('article(img,h3,a)*');
+  });
+
+  it('finds repeated cards with their content', () => {
+    const cards = of('card');
+    expect(cards).toHaveLength(3);
+    expect(cards[0]).toMatchObject({
+      headings: ['Tour A'],
+      images: [{ src: '/Tour A.jpg', alt: 'Tour A' }],
+    });
+  });
+
+  it('finds buttons, links, inputs and other components', () => {
+    const buttons = of('button');
+    expect(buttons.map((b) => b.label)).toEqual(['a.btn', 'a.wp-block-button__link', 'button']);
+    expect(buttons[1].icon).toBe(true);
+    expect(buttons[1].style.shadow).toContain('2px 4px');
+    expect(of('link')).toHaveLength(1);
+    expect(of('input').map((n) => n.tag)).toEqual(['input', 'select']);
+    expect(of('input')[0].style.border).toBe('rgb(138, 133, 128)');
+    for (const hint of [
+      'form',
+      'accordion',
+      'breadcrumbs',
+      'pagination',
+      'slider',
+      'tabs',
+      'badge',
+    ]) {
+      expect(of(hint)).toHaveLength(1);
+    }
+    expect(of('accordion')[0].open).toBe(true);
+    expect(result.nodes.some((n) => n.text === 'x')).toBe(false); // aria-hidden content is skipped.
+  });
+
+  it('reads states from CSS rules that name a class, ignoring bare element rules', () => {
+    const enquire = of('button')[0];
+    expect(enquire.states?.hover).toEqual({ background: 'rgb(0, 0, 0)' });
+    expect(of('nav-item')[0].states?.focus).toEqual({ textDecoration: 'underline' });
+    expect(of('link')[0].states).toBeUndefined();
+    expect(of('badge')[0].states?.hover).toMatchObject({ opacity: 0.8, border: 'rgb(1, 2, 3)' });
+    expect(of('button')[2].states?.disabled).toEqual({});
+  });
+
+  it('respects the node cap', () => {
+    expect(collectPageStructure({ maxNodes: 3 }).nodes).toHaveLength(3);
+  });
+
+  it('finds a sidebar beside a narrow main and opens up tall stacked wrappers', () => {
+    document.body.innerHTML = `
+      <main data-rect="0,0,700,3000">
+        <div class="stack" data-rect="0,0,700,3000">
+          <div class="row-a" style="background-color: rgb(1, 1, 1)" data-rect="0,0,700,1500"><p data-rect="0,0,700,20">A</p></div>
+          <div class="row-b" data-rect="0,1500,700,1500"><p data-rect="0,1500,700,20">B</p></div>
+        </div>
+        <div class="other" data-rect="0,3000,700,200"><ul data-rect="0,3000,700,200"><li data-rect="0,3000,10,10">1</li><li data-rect="0,3010,10,10">2</li></ul></div>
+      </main>
+      <aside id="secondary" data-rect="720,0,300,600"><div class="widget" data-rect="720,0,300,100">W</div></aside>`;
+    const nodes = collectPageStructure().nodes;
+    expect(nodes.filter((n) => n.hint === 'sidebar')).toHaveLength(1);
+    expect(nodes.filter((n) => n.hint === 'section').map((n) => n.label)).toEqual([
+      'div.row-a',
+      'div.row-b',
+      'div.other',
+    ]);
+    expect(nodes.find((n) => n.label === 'div.other')!.shape).toBe('div(ul(li*))');
+  });
+
+  it('works without a main element', () => {
+    document.body.innerHTML =
+      '<div class="only" data-rect="0,0,1024,300"><h2 data-rect="0,0,100,20">One</h2><p data-rect="0,40,100,20">Two</p></div>';
+    expect(collectPageStructure().nodes.map((n) => n.hint)).toEqual(['section']);
+  });
+});
+
+describe('hideOverlays', () => {
+  it('hides fixed overlays but keeps a fixed header and top bar', () => {
+    document.body.innerHTML = `
+      <header style="position: fixed" data-rect="0,0,1024,80"><nav>Menu</nav></header>
+      <div class="topbar" style="position: fixed" data-rect="0,0,1024,40">Offer</div>
+      <div class="cookie" style="position: fixed" data-rect="100,700,800,60">Cookies</div>
+      <div class="chat" style="position: fixed" data-rect="800,300,200,400"><button>Ask</button></div>
+      <div class="gone" style="position: fixed; display: none">x</div>
+      <p>Content</p>`;
+    expect(hideOverlays()).toBe(2);
+    expect((document.querySelector('.cookie') as HTMLElement).style.display).toBe('none');
+    expect((document.querySelector('header') as HTMLElement).style.display).toBe('');
+    expect((document.querySelector('.topbar') as HTMLElement).style.display).toBe('');
+  });
+});
+
+describe('readElementStyle and styleDiff', () => {
+  it('reads the style of one element, or null when it is missing', () => {
+    document.body.innerHTML =
+      '<a id="x" style="color: rgb(1, 2, 3); background-color: rgb(4, 5, 6); border: 2px solid rgb(7, 8, 9); box-shadow: 0 0 1px red; text-decoration: underline; opacity: 0.5">x</a>';
+    expect(readElementStyle('#x')).toMatchObject({
+      color: 'rgb(1, 2, 3)',
+      background: 'rgb(4, 5, 6)',
+      border: 'rgb(7, 8, 9)',
+      textDecoration: 'underline',
+      opacity: 0.5,
+    });
+    expect(readElementStyle('#missing')).toBeNull();
+  });
+
+  it('returns only the properties that changed', () => {
+    expect(
+      styleDiff({ color: 'a', background: 'b' }, { color: 'a', background: 'c', shadow: 'd' })
+    ).toEqual({ background: 'c', shadow: 'd' });
+    expect(styleDiff({ color: 'a' }, { color: 'a' })).toBeUndefined();
+  });
+});
+
+const node = (over: Partial<StructureNode>): StructureNode => ({
+  selector: 'body > a:nth-child(1)',
+  label: 'a.btn',
+  hint: 'button',
+  region: 'main',
+  tag: 'a',
+  rect: { x: 0, y: 0, w: 100, h: 40 },
+  shape: 'a',
+  columns: 1,
+  style: {},
+  headings: [],
+  buttons: [],
+  images: [],
+  ...over,
+});
+
+function fakeDriver(
+  options: {
+    nodes?: StructureNode[];
+    styles?: Record<string, StyleSig | null>;
+    failShot?: boolean;
+  } = {}
+) {
+  const opened: string[] = [];
+  const shots: string[] = [];
+  let closed = 0;
+  let browserClosed = false;
+  const page: PageHandle = {
+    collect: async () => ({
+      finalUrl: '',
+      title: 'T',
+      bodyClasses: [],
+      docHeight: 100,
+      nodes: (options.nodes ?? []).map((n) => ({ ...n })),
+    }),
+    styleIn: async (selector, state) =>
+      options.styles ? (options.styles[`${selector}|${state}`] ?? null) : null,
+    screenshot: async (path) => {
+      shots.push(path);
+      return !options.failShot;
+    },
+    close: async () => {
+      closed++;
+    },
+  };
+  const driver: BrowserDriver = {
+    open: async (url, viewport) => {
+      opened.push(`${url}@${viewport}`);
+      return page;
+    },
+    close: async () => {
+      browserClosed = true;
+    },
+  };
+  return { driver, opened, shots, closed: () => closed, browserClosed: () => browserClosed };
+}
+
+describe('StructureCrawler', () => {
+  const now = () => new Date('2026-11-05T10:00:00Z');
+
+  it('visits each page at each viewport with a pause, and takes full-page screenshots', async () => {
+    const fake = fakeDriver();
+    const sleeps: number[] = [];
+    const crawler = new StructureCrawler(fake.driver, async (ms) => void sleeps.push(ms), now);
+    const result = await crawler.crawl({
+      site: 'https://www.example.com',
+      pages: ['/', '/about/'],
+      shotsDir: 'shots',
+    });
+
+    expect(fake.opened).toEqual([
+      'https://www.example.com/@390',
+      'https://www.example.com/@1440',
+      'https://www.example.com/about/@390',
+      'https://www.example.com/about/@1440',
+    ]);
+    expect(sleeps).toEqual([1500, 1500, 1500]);
+    expect(fake.shots).toEqual([
+      'shots/home-390.png',
+      'shots/home-1440.png',
+      'shots/about-390.png',
+      'shots/about-1440.png',
+    ]);
+    expect(result).toMatchObject({
+      site: 'https://www.example.com',
+      capturedAt: '2026-11-05T10:00:00.000Z',
+      viewports: [390, 1440],
+    });
+    expect(result.pages[0].screenshot).toBe('home-390.png');
+    expect(fake.closed()).toBe(4);
+    expect(fake.browserClosed()).toBe(true);
+  });
+
+  it('leaves out screenshots that fail and crawls the home page by default', async () => {
+    const fake = fakeDriver({ failShot: true });
+    const result = await new StructureCrawler(fake.driver, async () => undefined).crawl({
+      site: 'https://www.example.com',
+      pages: [],
+      viewports: [1440],
+      shotsDir: 'shots',
+      maxStateSamples: 0,
+    });
+    expect(result.pages).toHaveLength(1);
+    expect(result.pages[0].screenshot).toBeUndefined();
+  });
+
+  it('records a page that fails and carries on', async () => {
+    const fake = fakeDriver();
+    const open = fake.driver.open;
+    fake.driver.open = async (url, viewport) => {
+      if (url.endsWith('/slow/')) {
+        throw new Error('Navigation timeout');
+      }
+      return open(url, viewport);
+    };
+    const result = await new StructureCrawler(fake.driver, async () => undefined).crawl({
+      site: 'https://www.example.com',
+      pages: ['/slow/', '/'],
+      viewports: [1440],
+      maxStateSamples: 0,
+    });
+    expect(result.pages.map((p) => p.url)).toEqual(['https://www.example.com/']);
+    expect(result.failures).toEqual([
+      { url: 'https://www.example.com/slow/', viewport: 1440, error: 'Navigation timeout' },
+    ]);
+    expect(fake.browserClosed()).toBe(true);
+  });
+
+  it('records triggered hover and focus states, replacing CSS guesses', async () => {
+    const a = node({
+      selector: 'a1',
+      states: { hover: { color: 'css-guess' }, active: { color: 'x' } },
+    });
+    const twin = node({ selector: 'a2' }); // Same label: sampled once.
+    const badge = node({ selector: 'b1', hint: 'badge', label: 'span.badge' });
+    const gone = node({ selector: 'g1', label: 'a.gone' });
+    const section = node({ selector: 's1', hint: 'section', label: 'div' });
+    const styles = {
+      'a1|none': { color: 'black' },
+      'a1|hover': { color: 'red' },
+      'a1|focus': { color: 'black' },
+      'b1|none': { color: 'black' },
+      'b1|hover': null,
+    };
+    const page = fakeDriver({ styles });
+    const crawler = new StructureCrawler(page.driver, async () => undefined);
+    const collected: CollectedStructure = {
+      finalUrl: '',
+      title: '',
+      bodyClasses: [],
+      docHeight: 0,
+      nodes: [a, twin, badge, gone, section],
+    };
+    const handle = await page.driver.open('x', 1);
+    await crawler.triggerStates(handle, collected, 10);
+
+    expect(a.states).toEqual({ hover: { color: 'red' }, active: { color: 'x' } });
+    expect(a.stateSource).toBe('browser');
+    expect(twin.stateSource).toBeUndefined();
+    expect(badge.states).toBeUndefined();
+    expect(badge.stateSource).toBe('browser');
+    expect(gone.stateSource).toBeUndefined();
+
+    const capped = node({ selector: 'a1' });
+    await crawler.triggerStates(handle, { ...collected, nodes: [capped] }, 0);
+    expect(capped.stateSource).toBeUndefined();
+  });
+
+  it('refuses other origins, private pages and too many pages', () => {
+    const crawler = new StructureCrawler(fakeDriver().driver, async () => undefined);
+    const site = new URL('https://www.example.com');
+    expect(() => crawler.resolvePages(site, ['https://other.example.com/'], 10)).toThrow(
+      'Crawl one site at a time'
+    );
+    for (const path of [
+      '/wp-admin/',
+      '/cart/',
+      '/my-account/orders',
+      '/checkout',
+      '/wp-login.php',
+    ]) {
+      expect(() => crawler.resolvePages(site, [path], 10)).toThrow('public pages only');
+    }
+    expect(() => crawler.resolvePages(site, ['/a', '/b'], 1)).toThrow('the limit is 1');
+    expect(crawler.resolvePages(site, ['/a', '/a', '/?s=kenya'], 5)).toEqual([
+      'https://www.example.com/a',
+      'https://www.example.com/?s=kenya',
+    ]);
+    expect(StructureCrawler.slugOf('https://www.example.com/tour/a-b/')).toBe('tour-a-b');
+    expect(StructureCrawler.slugOf('https://www.example.com/?s=kenya')).toBe('s-kenya');
+  });
+
+  it('shoots one example per target, opening each page once', async () => {
+    const fake = fakeDriver();
+    const sleeps: number[] = [];
+    const written = await new StructureCrawler(
+      fake.driver,
+      async (ms) => void sleeps.push(ms)
+    ).shoot(
+      'https://www.example.com',
+      [
+        { id: 'component:button', url: 'https://www.example.com/', viewport: 1440, selector: 'a' },
+        {
+          id: 'pattern:hero',
+          url: 'https://www.example.com/',
+          viewport: 1440,
+          selector: 'section',
+        },
+        {
+          id: 'part:footer',
+          url: 'https://www.example.com/about/',
+          viewport: 1440,
+          selector: 'footer',
+        },
+      ],
+      'shots',
+      10
+    );
+    expect(fake.opened).toEqual([
+      'https://www.example.com/@1440',
+      'https://www.example.com/about/@1440',
+    ]);
+    expect(sleeps).toEqual([10]);
+    expect(written).toEqual([
+      'component-button-1440.png',
+      'pattern-hero-1440.png',
+      'part-footer-1440.png',
+    ]);
+
+    const failing = fakeDriver({ failShot: true });
+    expect(
+      await new StructureCrawler(failing.driver, async () => undefined).shoot(
+        'https://www.example.com',
+        [{ id: 'x', url: 'https://www.example.com/', viewport: 390, selector: 'a' }],
+        'shots'
+      )
+    ).toEqual([]);
+    await expect(
+      new StructureCrawler(fake.driver, async () => undefined).shoot(
+        'https://www.example.com',
+        [{ id: 'x', url: 'https://evil.example.com/', viewport: 390, selector: 'a' }],
+        'shots'
+      )
+    ).rejects.toThrow('one site at a time');
+  });
+});
+
+describe('runCrawlCli', () => {
+  function io(files: Record<string, string> = {}) {
+    const written: Record<string, string> = {};
+    const out: string[] = [];
+    const err: string[] = [];
+    const dirs: string[] = [];
+    const fake = fakeDriver({ nodes: [node({})] });
+    return {
+      deps: {
+        createDriver: async () => fake.driver,
+        sleep: async () => undefined,
+        readFile: (path: string) => files[path],
+        writeFile: (path: string, content: string) => {
+          written[path] = content;
+        },
+        makeDir: (path: string) => void dirs.push(path),
+        stdout: (text: string) => void out.push(text),
+        stderr: (text: string) => void err.push(text),
+      },
+      written,
+      out,
+      err,
+      dirs,
+      fake,
+    };
+  }
+
+  it('prints usage', async () => {
+    const t = io();
+    expect(await runCrawlCli(['--help'], t.deps)).toBe(0);
+    expect(t.out.join('')).toContain('Usage');
+  });
+
+  it('rejects bad arguments', async () => {
+    for (const argv of [['--nope', 'x'], ['stray'], ['--url'], ['--pages', '/']]) {
+      const t = io();
+      expect(await runCrawlCli(argv, t.deps)).toBe(1);
+      expect(t.err.join('')).toMatch(/Unknown argument|needs a value|--url is required/);
+    }
+  });
+
+  it('reports skipped pages on stderr', async () => {
+    const t = io();
+    t.fake.driver.open = async () => {
+      throw new Error('timeout');
+    };
+    expect(
+      await runCrawlCli(['--url', 'https://www.example.com', '--viewports', '1440'], t.deps)
+    ).toBe(0);
+    expect(t.err.join('')).toContain('Skipped https://www.example.com/ at 1440px: timeout');
+  });
+
+  it('crawls and writes the structure', async () => {
+    const t = io();
+    const code = await runCrawlCli(
+      [
+        '--url',
+        'https://www.example.com',
+        '--pages',
+        '/, /about/',
+        '--viewports',
+        '1440',
+        '--out',
+        'o.json',
+        '--shots',
+        'shots',
+        '--states',
+        '0',
+      ],
+      t.deps
+    );
+    expect(code).toBe(0);
+    expect(t.dirs).toEqual(['shots']);
+    expect(JSON.parse(t.written['o.json']).pages).toHaveLength(2);
+    expect(t.out.join('')).toContain('Captured 2 page views and 2 building blocks');
+  });
+
+  it('shoots examples from an inventory, skipping cut items', async () => {
+    const inventory = {
+      items: [
+        {
+          id: 'component:button',
+          examples: [{ url: 'https://www.example.com/', viewport: 1440, selector: 'a' }],
+        },
+        {
+          id: 'pattern:gone',
+          status: 'cut',
+          examples: [{ url: 'https://www.example.com/', viewport: 1440, selector: 'b' }],
+        },
+      ],
+    };
+    const t = io({ 'inv.json': JSON.stringify(inventory) });
+    expect(
+      await runCrawlCli(
+        ['--url', 'https://www.example.com', '--shoot', 'inv.json', '--shots', 'shots'],
+        t.deps
+      )
+    ).toBe(0);
+    expect(t.out.join('')).toContain('Wrote 1 of 1 example screenshots');
+
+    const noShots = io({ 'inv.json': JSON.stringify(inventory) });
+    expect(
+      await runCrawlCli(['--url', 'https://www.example.com', '--shoot', 'inv.json'], noShots.deps)
+    ).toBe(1);
+    expect(noShots.err.join('')).toContain('--shoot needs --shots');
+  });
+});
diff --git a/skills/site-to-figma-components/scripts/__tests__/fixtures.ts b/skills/site-to-figma-components/scripts/__tests__/fixtures.ts
new file mode 100644
index 0000000000..2a637a1980
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/__tests__/fixtures.ts
@@ -0,0 +1,488 @@
+import type { PageStructure, SiteStructure, StructureNode } from '../crawl-site-structure';
+import type { VariablesExport } from '../lib/tokens';
+
+const SITE = 'https://www.example.com';
+
+let seq = 0;
+
+export function node(over: Partial<StructureNode>): StructureNode {
+  return {
+    selector: `body > div:nth-child(${++seq})`,
+    label: 'div',
+    hint: 'section',
+    region: 'main',
+    tag: 'div',
+    rect: { x: 0, y: 0, w: 1440, h: 400 },
+    shape: 'div(h2,p)',
+    columns: 1,
+    style: {},
+    headings: [],
+    buttons: [],
+    images: [],
+    ...over,
+  };
+}
+
+export function page(
+  path: string,
+  viewport: number,
+  bodyClasses: string[],
+  nodes: StructureNode[],
+  over: Partial<PageStructure> = {}
+): PageStructure {
+  return {
+    url: `${SITE}${path}`,
+    viewport,
+    finalUrl: `${SITE}${path}`,
+    title: path,
+    bodyClasses,
+    docHeight: 3000,
+    nodes,
+    ...over,
+  };
+}
+
+const header = (y = 0) =>
+  node({
+    selector: 'body > header',
+    label: 'header.site-header',
+    hint: 'header',
+    region: 'header',
+    rect: { x: 0, y, w: 1440, h: 80 },
+    shape: 'header(nav(ul(li*)))',
+    style: { background: 'rgb(255, 255, 255)' },
+  });
+const footer = () =>
+  node({
+    selector: 'body > footer',
+    label: 'footer',
+    hint: 'footer',
+    region: 'footer',
+    rect: { x: 0, y: 2800, w: 1440, h: 200 },
+    shape: 'footer(div)',
+    style: { background: 'rgb(38, 36, 35)', paddingBlock: 40 },
+  });
+const hero = (selector: string, heading: string) =>
+  node({
+    selector,
+    label: 'div.wp-block-cover.hero',
+    rect: { x: 0, y: 80, w: 1440, h: 600 },
+    shape: 'div(img,div(h1,div(a)))',
+    columns: 1,
+    style: { backgroundImage: true, paddingBlock: 80 },
+    headings: [heading],
+    buttons: ['Enquire'],
+    images: [{ src: `${SITE}/hero.jpg`, alt: 'Hero' }],
+  });
+const button = (selector: string, over: Partial<StructureNode> = {}) =>
+  node({
+    selector,
+    label: 'a.wp-block-button__link',
+    hint: 'button',
+    tag: 'a',
+    rect: { x: 0, y: 300, w: 160, h: 50 },
+    shape: 'a',
+    style: {
+      background: 'rgb(163, 23, 0)',
+      color: 'rgb(255, 255, 255)',
+      fontFamily: 'Moret',
+      fontSize: 16,
+      paddingBlock: 10,
+      paddingInline: 20,
+      radius: 8,
+    },
+    text: 'Enquire',
+    states: { hover: { background: 'rgb(128, 16, 0)' } },
+    stateSource: 'browser',
+    ...over,
+  });
+const cards = (prefix: string, cls: string, y: number, shape = 'article(div(a),div(h4))') =>
+  [0, 1, 2].map((n) =>
+    node({
+      selector: `${prefix} > article:nth-child(${n + 1})`,
+      label: `article.lsx-to-widget-item-wrap.${cls}`,
+      hint: 'card',
+      tag: 'article',
+      rect: { x: n * 400, y, w: 380, h: 400 },
+      shape,
+      style: { background: 'rgb(255, 255, 255)', radius: 8 },
+      headings: [`${cls} ${n}`],
+      images: [{ src: `${SITE}/${cls}-${n}.jpg`, alt: '' }],
+    })
+  );
+
+/** A small site: home, two tours, a destination that redirects to home, a page and a 404. */
+export function site(): SiteStructure {
+  const homeCards = cards('body > main > section:nth-child(2)', 'lsx-tour', 800);
+  const homeD = [
+    header(),
+    hero('body > main > section:nth-child(1)', 'Plan your safari'),
+    node({
+      selector: 'body > main > section:nth-child(2)',
+      label: 'div.tours-posts',
+      rect: { x: 0, y: 700, w: 1440, h: 600 },
+      shape: 'div(h2,div(article*))',
+      headings: ['Top tours'],
+    }),
+    ...homeCards,
+    node({
+      selector: 'body > main > section:nth-child(3)',
+      label: 'div.wp-block-columns.whyus',
+      rect: { x: 0, y: 1300, w: 1440, h: 300 },
+      shape: 'div(div(figure(img),h4,p)*)',
+      columns: 4,
+      headings: ['Why us'],
+      images: [{ src: `${SITE}/icon.png`, alt: '' }],
+    }),
+    node({
+      selector: 'body > main > section:nth-child(4)',
+      label: 'div.cta-home',
+      rect: { x: 0, y: 1600, w: 1440, h: 200 },
+      shape: 'div(h2,a)',
+      style: { background: 'rgb(86, 91, 61)', paddingBlock: 40 },
+      buttons: ['Call us'],
+    }),
+    button('body > main > section:nth-child(1) a'),
+    button('body > header a.btn', {
+      region: 'header',
+      style: {
+        color: 'rgb(141, 98, 31)',
+        border: 'rgb(141, 98, 31)',
+        paddingBlock: 13,
+        radius: 50,
+      },
+      rect: { x: 0, y: 0, w: 120, h: 30 },
+      icon: true,
+      states: undefined,
+      stateSource: undefined,
+    }),
+    node({
+      selector: 'body > header nav a:nth-child(1)',
+      label: 'a',
+      hint: 'nav-item',
+      region: 'header',
+      tag: 'a',
+      shape: 'a',
+      style: { color: 'rgb(38, 36, 35)' },
+      states: { hover: { color: 'rgb(141, 98, 31)' }, focus: { textDecoration: 'underline' } },
+    }),
+    node({
+      selector: 'body > footer nav a:nth-child(1)',
+      label: 'a',
+      hint: 'nav-item',
+      region: 'footer',
+      tag: 'a',
+      shape: 'a',
+      style: { color: 'rgb(255, 255, 255)' },
+    }),
+    node({
+      selector: 'body > main p a',
+      label: 'a',
+      hint: 'link',
+      tag: 'a',
+      shape: 'a',
+      style: { color: 'rgb(141, 98, 31)' },
+    }),
+    node({
+      selector: 'body > main form',
+      label: 'form.search-form',
+      hint: 'form',
+      tag: 'form',
+      shape: 'form(input,button)',
+    }),
+    node({
+      selector: 'body > main form input',
+      label: 'input',
+      hint: 'input',
+      tag: 'input',
+      shape: 'input',
+      style: { border: 'rgb(138, 133, 128)', paddingInline: 14 },
+      states: { focus: { border: 'rgb(141, 98, 31)' } },
+    }),
+    node({
+      selector: 'body > main select',
+      label: 'select',
+      hint: 'input',
+      tag: 'select',
+      shape: 'select',
+      style: {},
+    }),
+    node({
+      selector: 'body > main .badge',
+      label: 'span.badge',
+      hint: 'badge',
+      tag: 'span',
+      shape: 'span',
+      style: { background: 'rgb(245, 246, 240)', radius: 4 },
+      text: 'New',
+    }),
+    node({
+      selector: 'body > main details',
+      label: 'details',
+      hint: 'accordion',
+      tag: 'details',
+      shape: 'details(summary)',
+      open: true,
+    }),
+    footer(),
+  ];
+  const byLabel = (label: string) => homeD.find((n) => n.label === label)!;
+  const mainButton = homeD.find((n) => n.hint === 'button' && n.region === 'main')!;
+  const homeM = [
+    { ...header(), shape: 'header(div(button))' },
+    byLabel('div.wp-block-cover.hero'),
+    { ...byLabel('div.wp-block-columns.whyus'), columns: 1 },
+    { ...mainButton, style: { ...mainButton.style, fontSize: 14, paddingBlock: 6 } },
+    footer(),
+  ];
+  const tour = (path: string, name: string) => [
+    header(),
+    hero(`body > main > section:nth-child(1)`, name),
+    node({
+      selector: 'body > main > section:nth-child(2)',
+      label: 'section.gallery',
+      rect: { x: 0, y: 700, w: 1440, h: 500 },
+      shape: 'section(img*)',
+      images: [1, 2, 3].map((n) => ({ src: `${SITE}${path}${n}.jpg`, alt: '' })),
+    }),
+    node({
+      selector: 'body > main > section:nth-child(3)',
+      label: 'section.reviews',
+      rect: { x: 0, y: 1200, w: 1440, h: 400 },
+      shape: 'section(blockquote*)',
+      headings: ['Reviews'],
+    }),
+    node({
+      selector: 'body > main > section:nth-child(4)',
+      label: 'section.styles',
+      rect: { x: 0, y: 1650, w: 1440, h: 500 },
+      shape: 'section(h2,div(article*))',
+      headings: ['Safari styles'],
+    }),
+    ...cards(
+      'body > main > section:nth-child(4)',
+      'lsx-travel-style',
+      1700,
+      'article(div(a),div(h4,p))'
+    ),
+    node({
+      selector: 'body > main > section:nth-child(5)',
+      label: 'section.more',
+      rect: { x: 0, y: 2150, w: 1440, h: 500 },
+      shape: 'section(h3,div(article*))',
+      headings: ['More styles'],
+    }),
+    ...cards('body > main > section:nth-child(5)', 'lsx-travel-style', 2200),
+    footer(),
+  ];
+  const contact = [
+    header(),
+    node({
+      selector: 'body > main > div:nth-child(1)',
+      label: 'h2.wp-block-heading',
+      rect: { x: 0, y: 80, w: 1440, h: 80 },
+      shape: 'h2',
+    }),
+    node({
+      selector: 'body > main > div:nth-child(2)',
+      label: 'div.wp-block-media-text',
+      rect: { x: 0, y: 160, w: 1440, h: 400 },
+      shape: 'div(figure(img),div(h3,p))',
+      columns: 2,
+      images: [{ src: `${SITE}/team.jpg`, alt: 'Team' }],
+      headings: ['Our history'],
+    }),
+    node({
+      selector: 'body > main > div:nth-child(3)',
+      label: 'div.contact-form',
+      rect: { x: 0, y: 600, w: 1440, h: 400 },
+      shape: 'div(div(form))',
+    }),
+    node({
+      selector: 'body > main > div:nth-child(3) form',
+      label: 'form.gform',
+      hint: 'form',
+      tag: 'form',
+      rect: { x: 0, y: 620, w: 600, h: 300 },
+      shape: 'form(input*,button)',
+    }),
+    node({
+      selector: 'body > main > div:nth-child(4)',
+      label: 'div.plain',
+      rect: { x: 0, y: 1000, w: 1440, h: 600 },
+      shape: 'div(p*)',
+    }),
+    footer(),
+  ];
+  const contactM = contact.map((n) =>
+    n.label === 'div.wp-block-media-text' ? { ...n, columns: 1 } : n
+  );
+  const notFound = [
+    header(),
+    node({
+      selector: 'body > main > div',
+      label: 'div',
+      rect: { x: 0, y: 80, w: 1440, h: 300 },
+      shape: 'div(h1,p)',
+      headings: ['Not found'],
+    }),
+    footer(),
+  ];
+
+  return {
+    site: SITE,
+    capturedAt: '2026-11-05T10:00:00.000Z',
+    viewports: [390, 1440],
+    pages: [
+      page('/', 1440, ['home', 'page'], homeD, { screenshot: 'home-1440.png' }),
+      page('/', 390, ['home', 'page'], homeM),
+      page(
+        '/tour/a/',
+        1440,
+        ['tour-template-default', 'single', 'single-lsx-to-tour'],
+        tour('/tour/a/', 'Tour A')
+      ),
+      page(
+        '/tour/b/',
+        1440,
+        ['tour-template-default', 'single', 'single-lsx-to-tour'],
+        tour('/tour/b/', 'Tour B')
+      ),
+      page('/destinations/', 1440, ['home', 'page'], homeD, { finalUrl: `${SITE}/` }),
+      page('/contact/', 1440, ['page-template-default', 'page'], contact),
+      page('/contact/', 390, ['page-template-default', 'page'], contactM),
+      page('/missing/', 1440, ['error404'], notFound),
+    ],
+  };
+}
+
+export function variables(): VariablesExport {
+  const rgb = (r: number, g: number, b: number, a = 1) => ({
+    r: r / 255,
+    g: g / 255,
+    b: b / 255,
+    a,
+  });
+  const v = (id: string, name: string, type: string, value: unknown, web?: string) => ({
+    id,
+    name,
+    type,
+    codeSyntax: web ? { WEB: web } : undefined,
+    valuesByMode: { m: value },
+  });
+  const sized = (id: string, name: string, max: number, web: string) => ({
+    id,
+    name,
+    type: 'FLOAT',
+    codeSyntax: { WEB: web },
+    valuesByMode: { max, min: max / 2 },
+  });
+  return {
+    collections: [
+      {
+        name: 'Theme - Colour',
+        modes: [{ id: 'm', name: 'Value' }],
+        variables: [
+          v('c1', 'Theme/base', 'COLOR', rgb(255, 255, 255), 'var(--wp--preset--color--base)'),
+          v('c2', 'Theme/contrast', 'COLOR', rgb(38, 36, 35), 'var(--wp--preset--color--contrast)'),
+          v('c3', 'brand/600', 'COLOR', rgb(141, 98, 31), 'var(--wp--preset--color--brand-600)'),
+          v('c4', 'cta/500', 'COLOR', rgb(163, 23, 0), 'var(--wp--preset--color--cta-500)'),
+          v('c5', 'primary/500', 'COLOR', rgb(86, 91, 61), 'var(--wp--preset--color--primary-500)'),
+          v(
+            'c6',
+            'neutral/500',
+            'COLOR',
+            rgb(138, 133, 128),
+            'var(--wp--preset--color--neutral-500)'
+          ),
+          v(
+            'c7',
+            'primary/100',
+            'COLOR',
+            rgb(245, 246, 240),
+            'var(--wp--preset--color--primary-100)'
+          ),
+        ],
+      },
+      {
+        name: 'Theme - Semantic',
+        modes: [{ id: 'm', name: 'Value' }],
+        variables: [
+          v('s1', 'text/default', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'c2' }),
+          v(
+            's2',
+            'text/link',
+            'COLOR',
+            { type: 'VARIABLE_ALIAS', id: 'c3' },
+            'var(--wp--custom--color--text--link)'
+          ),
+          v('s3', 'surface/default', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'c1' }),
+          v('s4', 'action/cta/background', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'c4' }),
+          v('s5', 'action/cta/text', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'c1' }),
+          v('s6', 'action/primary/background', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'c5' }),
+          v('s7', 'border/default', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'c6' }),
+          v('s8', 'surface/inverse', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'c2' }),
+          v('s9', 'text/inverse', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'c1' }),
+          v('s10', 'broken/alias', 'COLOR', { type: 'VARIABLE_ALIAS', id: 'nope' }),
+        ],
+      },
+      {
+        name: 'Theme - Spacing',
+        modes: [
+          { id: 'min', name: 'Min' },
+          { id: 'max', name: 'Max' },
+        ],
+        variables: [10, 20, 40, 80].map((n) =>
+          sized(`p${n}`, `Padding/${n}`, n, `var(--wp--preset--spacing--${n})`)
+        ),
+      },
+      {
+        name: 'Theme - Radius',
+        modes: [{ id: 'm', name: 'Mode 1' }],
+        variables: [v('r1', 'Radius Base', 'FLOAT', 8, 'var(--wp--preset--border-radius--200)')],
+      },
+      {
+        name: 'Theme - Typography',
+        modes: [
+          { id: 'max', name: 'Max' },
+          { id: 'min', name: 'Min' },
+        ],
+        variables: [
+          sized('t1', 'Sizes/xSmall', 16, 'var(--wp--preset--font-size--200)'),
+          {
+            id: 't2',
+            name: 'Font-Families/Primary',
+            type: 'STRING',
+            codeSyntax: { WEB: 'var(--wp--preset--font-family--heading)' },
+            valuesByMode: { max: 'Moret', min: 'Moret' },
+          },
+          {
+            id: 't3',
+            name: 'Weights/H1',
+            type: 'STRING',
+            valuesByMode: { max: 'Bold', min: 'Bold' },
+          },
+          {
+            id: 't4',
+            name: 'Line-Heights/Body',
+            type: 'FLOAT',
+            valuesByMode: { max: 24, min: 20 },
+          },
+        ],
+      },
+      {
+        name: 'Proto - Cards',
+        modes: [{ id: 'm', name: 'Mode 1' }],
+        variables: [v('x1', 'card/bg', 'COLOR', rgb(1, 2, 3))],
+      },
+      { name: 'Library (aliases only)', modes: [], variables: [] },
+    ],
+    effectStyles: [
+      {
+        name: 'LSX/xSmall',
+        effects: [{ type: 'DROP_SHADOW', offset: { x: 0, y: 2 }, radius: 4, spread: 0 }],
+      },
+      { name: 'Blur/4', effects: [{ type: 'LAYER_BLUR', radius: 4 }] },
+    ],
+  };
+}
diff --git a/skills/site-to-figma-components/scripts/__tests__/propose-inventory.test.ts b/skills/site-to-figma-components/scripts/__tests__/propose-inventory.test.ts
new file mode 100644
index 0000000000..eba61329dc
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/__tests__/propose-inventory.test.ts
@@ -0,0 +1,659 @@
+import {
+  DecisionApplier,
+  Inventory,
+  InventoryProposer,
+  InventoryReport,
+  kebab,
+  runProposeCli,
+  StyleBinder,
+  TemplateClassifier,
+} from '../propose-inventory';
+import { TokenIndex } from '../lib/tokens';
+import { node, page, site, variables } from './fixtures';
+
+const propose = (withTokens = true) =>
+  new InventoryProposer(
+    withTokens ? new TokenIndex(variables()) : new TokenIndex(),
+    'tsp-theme'
+  ).propose(site());
+const item = (inv: Inventory, id: string) => inv.items.find((i) => i.id === id)!;
+
+describe('TemplateClassifier', () => {
+  const url = 'https://www.example.com/x/';
+  it.each([
+    [['error404'], '404', '404'],
+    [['search', 'search-results'], 'search', 'Search'],
+    [['home', 'blog'], 'home', 'Blog Home'],
+    [['home', 'page'], 'front-page', 'Front Page'],
+    [['blog'], 'home', 'Blog Home'],
+    [['archive', 'post-type-archive-tour'], 'archive-tour', 'Tour Archive'],
+    [['archive', 'tax-travel-style'], 'taxonomy-travel-style', 'Travel Style Taxonomy'],
+    [['archive', 'category'], 'category', 'Category'],
+    [
+      ['page', 'archive', 'page-template-template-travel-style-php'],
+      'travel-style',
+      'Travel Style',
+    ],
+    [['page', 'page-template-default'], 'page', 'Page'],
+    [['archive', 'date'], 'archive', 'Archive'],
+    [['single', 'tour-template-default', 'single-lsx-to-tour'], 'single-tour', 'Single Tour'],
+    [['single', 'single-post', 'post-template-default'], 'single', 'Single Post'],
+    [['single'], 'single', 'Single Post'],
+  ])('maps %j to %s', (classes, slug, name) => {
+    expect(TemplateClassifier.classify(classes as string[], url)).toEqual({ slug, name });
+  });
+
+  it('falls back to the URL', () => {
+    expect(TemplateClassifier.classify([], 'https://www.example.com/').slug).toBe('front-page');
+    expect(TemplateClassifier.classify([], url).slug).toBe('index');
+  });
+});
+
+describe('InventoryProposer', () => {
+  const inv = propose();
+
+  it('leaves out pages that redirect to a page already crawled', () => {
+    expect(inv.pages.map((p) => new URL(p.url).pathname)).toEqual([
+      '/',
+      '/tour/a/',
+      '/tour/b/',
+      '/contact/',
+      '/missing/',
+    ]);
+    expect(inv.redirects).toEqual([
+      { from: 'https://www.example.com/destinations/', to: 'https://www.example.com/' },
+    ]);
+    expect(inv.pages[0]).toMatchObject({ template: 'front-page', screenshots: ['home-1440.png'] });
+    expect(inv.tokensLoaded).toBe(true);
+    expect(inv.approved).toBe(false);
+  });
+
+  it('proposes the header and footer as template parts', () => {
+    const header = item(inv, 'part:header');
+    expect(header).toMatchObject({
+      kind: 'template-part',
+      count: 5,
+      oneOff: false,
+      mobileLayoutChanges: true,
+      figmaName: 'Template Parts/Header',
+    });
+    expect(header.wordpress).toEqual({
+      type: 'template-part',
+      slug: 'header',
+      area: 'header',
+      file: 'parts/header.html',
+    });
+    expect(header.variantProperties).toEqual({ Breakpoint: ['Desktop', 'Mobile'] });
+    const footer = item(inv, 'part:footer');
+    expect(footer.variants[0].properties).toEqual({ Mode: 'Dark' });
+    expect(footer.variants[0].bindings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ property: 'fill', variable: 'surface/inverse', match: 'exact' }),
+        expect.objectContaining({ property: 'paddingBlock', variable: 'Padding/40' }),
+      ])
+    );
+  });
+
+  it('groups buttons into one set with variant properties and states', () => {
+    const button = item(inv, 'component:button');
+    expect(button.figmaName).toBe('Components/Buttons/Button');
+    expect(button.variantProperties).toEqual({
+      Style: ['Fill', 'Outline'],
+      Icon: ['False', 'True'],
+      Size: ['Medium', 'Small'],
+      State: ['Default', 'Hover'],
+      Breakpoint: ['Desktop', 'Mobile'],
+    });
+    expect(button.wordpress).toMatchObject({
+      type: 'core-block',
+      block: 'core/button',
+      styles: ['outline'],
+    });
+    const fill = button.variants.find((v) => v.properties.Style === 'Fill')!;
+    expect(fill.bindings.find((b) => b.property === 'fill')).toMatchObject({
+      variable: 'action/cta/background',
+      match: 'exact',
+    });
+    expect(fill.bindings.find((b) => b.property === 'fontFamily')).toMatchObject({
+      variable: 'Font-Families/Primary',
+    });
+  });
+
+  it('names cards by their distinctive class and makes layout a variant', () => {
+    expect(item(inv, 'component:tour-card')).toMatchObject({
+      count: 3,
+      aka: 'lsx-tour',
+      figmaName: 'Components/Cards/Tour Card',
+    });
+    const travel = item(inv, 'component:travel-style-card');
+    expect(travel.count).toBe(12);
+    expect(travel.variantProperties.Layout).toEqual(['A', 'B']);
+    expect(travel.wordpress).toMatchObject({
+      type: 'pattern',
+      slug: 'tsp-theme/travel-style-card',
+      file: 'patterns/travel-style-card.php',
+    });
+  });
+
+  it('maps every component family to a WordPress target', () => {
+    const targets = Object.fromEntries(
+      inv.items
+        .filter((i) => i.kind === 'component')
+        .map((i) => [i.id, i.wordpress.type + ':' + (i.wordpress.block ?? '')])
+    );
+    expect(targets).toMatchObject({
+      'component:nav-item': 'core-block:core/navigation-link',
+      'component:text-link': 'element-style:core/paragraph',
+      'component:search-form': 'core-block:core/search',
+      'component:form': 'plugin-block:',
+      'component:input-field': 'plugin-block:',
+      'component:badge': 'block-style:core/post-terms',
+      'component:accordion': 'core-block:core/details',
+    });
+    expect(item(inv, 'component:nav-item').variantProperties).toEqual({
+      Mode: ['Dark', 'Light'],
+      Region: ['Footer', 'Header'],
+      State: ['Default', 'Hover', 'Focus'],
+    });
+    expect(item(inv, 'component:input-field').variantProperties).toEqual({
+      Type: ['Select', 'Text'],
+      Style: ['Bordered', 'Plain'],
+      State: ['Default', 'Focus'],
+    });
+    expect(item(inv, 'component:accordion').variantProperties).toEqual({
+      State: ['Default', 'Open'],
+    });
+    expect(item(inv, 'component:badge').oneOff).toBe(true);
+  });
+
+  it('names patterns from their content and flags one-offs and near duplicates', () => {
+    const names = inv.items.filter((i) => i.kind === 'pattern').map((i) => `${i.id}:${i.count}`);
+    expect(names).toEqual([
+      'pattern:hero:3',
+      'pattern:card-grid:1',
+      'pattern:feature-row:1',
+      'pattern:call-to-action:1',
+      'pattern:gallery:2',
+      'pattern:testimonials:2',
+      'pattern:card-grid-2:2',
+      'pattern:card-grid-3:2',
+      'pattern:section-heading:1',
+      'pattern:media-and-text:1',
+      'pattern:form-section:1',
+      'pattern:content-section:1',
+      'pattern:content-section-2:1',
+    ]);
+    expect(item(inv, 'pattern:hero').wordpress).toEqual({
+      type: 'pattern',
+      block: 'core/cover',
+      slug: 'tsp-theme/hero',
+      file: 'patterns/hero.php',
+    });
+    expect(item(inv, 'pattern:hero').content.images[0].src).toBe(
+      'https://www.example.com/hero.jpg'
+    );
+    expect(item(inv, 'pattern:media-and-text').mobileLayoutChanges).toBe(true);
+    expect(item(inv, 'pattern:card-grid-2').mergeWith).toEqual(['pattern:card-grid-3']);
+    expect(item(inv, 'pattern:feature-row').mobileLayoutChanges).toBe(true);
+    expect(item(inv, 'pattern:call-to-action').variants[0].properties).toEqual({ Mode: 'Dark' });
+  });
+
+  it('composes each template from its parts and patterns, top to bottom', () => {
+    expect(item(inv, 'template:front-page').composition).toEqual([
+      'part:header',
+      'pattern:hero',
+      'pattern:card-grid',
+      'pattern:feature-row',
+      'pattern:call-to-action',
+      'part:footer',
+    ]);
+    expect(item(inv, 'template:single-tour')).toMatchObject({
+      count: 2,
+      figmaName: 'Templates/Single Tour',
+      wordpress: { file: 'templates/single-tour.html' },
+    });
+    expect(item(inv, 'template:page').mobileLayoutChanges).toBe(true);
+    expect(item(inv, 'template:404').composition).toEqual([
+      'part:header',
+      'pattern:content-section-2',
+      'part:footer',
+    ]);
+  });
+
+  it('lists values with no token and values that only match a primitive', () => {
+    const keys = inv.unbound.map((u) => `${u.property} ${u.value} ${u.match}`);
+    expect(keys).toEqual(
+      expect.arrayContaining([
+        'fill #f5f6f0 primitive',
+        'paddingBlock 13px none',
+        'radius 50px none',
+        'paddingInline 14px none',
+      ])
+    );
+  });
+
+  it('binds nothing without a variables export', () => {
+    const bare = propose(false);
+    expect(bare.tokensLoaded).toBe(false);
+    expect(bare.unbound.every((u) => u.match === 'none')).toBe(true);
+  });
+
+  it('handles a crawl with one viewport and a sidebar', () => {
+    const sidebar = node({
+      hint: 'sidebar',
+      region: 'sidebar',
+      label: 'aside#secondary',
+      rect: { x: 1000, y: 100, w: 400, h: 600 },
+    });
+    const structure = {
+      site: 'https://www.example.com',
+      capturedAt: '2026-11-05T10:00:00.000Z',
+      viewports: [1440],
+      pages: [
+        page('/a/', 1440, ['single', 'single-post'], [sidebar]),
+        page('/b/', 1440, ['page'], [{ ...sidebar }]),
+      ],
+    };
+    const result = new InventoryProposer(new TokenIndex(), 'demo').propose(structure);
+    expect(item(result, 'part:sidebar')).toMatchObject({
+      oneOff: false,
+      wordpress: { area: 'uncategorized' },
+      mobileLayoutChanges: false,
+    });
+  });
+});
+
+describe('InventoryProposer helpers', () => {
+  it('reads modes from backgrounds and text colours', () => {
+    expect(InventoryProposer.mode({ backgroundImage: true })).toBe('Image');
+    expect(InventoryProposer.mode({})).toBe('Transparent');
+    expect(InventoryProposer.mode({ background: 'rgba(0, 0, 0, 0.05)' })).toBe('Transparent');
+    expect(InventoryProposer.mode({ background: 'rgb(0, 0, 0)' })).toBe('Dark');
+    expect(InventoryProposer.mode({ background: 'rgb(255, 255, 255)' })).toBe('Light');
+    expect(InventoryProposer.textMode('rgb(255, 255, 255)')).toBe('Dark');
+    expect(InventoryProposer.textMode(undefined)).toBe('Light');
+  });
+
+  it('sizes, truncates shapes and keeps names unique', () => {
+    expect(InventoryProposer.sizeKey(node({ rect: { x: 0, y: 0, w: 10, h: 60 } }))).toBe('Large');
+    expect(InventoryProposer.truncateShape('div(article(div(a),div(h4,p)))*', 2)).toBe(
+      'div(article(div,div))*'
+    );
+    expect(InventoryProposer.truncateShape('div(a)', 0)).toBe('div');
+    expect(InventoryProposer.truncateShape('img', 3)).toBe('img');
+    const taken = new Set(['Hero']);
+    expect(InventoryProposer.unique('Hero', taken)).toBe('Hero 2');
+    expect(InventoryProposer.unique('Hero', taken)).toBe('Hero 3');
+    expect(kebab('Forms & Inputs')).toBe('forms-and-inputs');
+  });
+
+  it('gives remaining hints sensible properties and targets', () => {
+    expect(
+      InventoryProposer.componentProps(
+        node({ hint: 'slider', style: { background: 'rgb(0, 0, 0)' } })
+      )
+    ).toEqual({ Mode: 'Dark' });
+    expect(
+      InventoryProposer.componentProps(
+        node({ hint: 'badge', style: { border: 'red' }, icon: true })
+      )
+    ).toEqual({ Style: 'Outline', Icon: 'True' });
+    expect(
+      InventoryProposer.componentProps(
+        node({ hint: 'input', tag: 'textarea', style: { background: 'red' } })
+      )
+    ).toEqual({ Type: 'Textarea', Style: 'Filled' });
+    expect(
+      InventoryProposer.componentProps(
+        node({ hint: 'button', style: {}, rect: { x: 0, y: 0, w: 1, h: 20 } })
+      )
+    ).toMatchObject({ Style: 'Text', 'Has Text': 'False', Size: 'Small' });
+    expect(
+      InventoryProposer.distinctiveClass(node({ label: 'div.wp-block-group.align-full.hero' }))
+    ).toBe('hero');
+    expect(InventoryProposer.distinctiveClass(node({ label: 'div' }))).toBeUndefined();
+  });
+
+  it('maps pagination, breadcrumbs, tabs and sliders', () => {
+    const structure = {
+      site: 'https://www.example.com',
+      capturedAt: '2026-11-05T10:00:00.000Z',
+      viewports: [1440],
+      pages: [
+        page(
+          '/',
+          1440,
+          ['home'],
+          [
+            node({ hint: 'pagination', label: 'nav.pagination' }),
+            node({ hint: 'breadcrumbs', label: 'nav.breadcrumbs' }),
+            node({ hint: 'tabs', label: 'div.tabs' }),
+            node({ hint: 'slider', label: 'div.swiper' }),
+            node({ hint: 'card', label: 'article.post', shape: 'article(img,h3)' }),
+            node({ hint: 'card', label: 'div', shape: 'div(img,h3)' }),
+          ]
+        ),
+      ],
+    };
+    const result = new InventoryProposer(new TokenIndex(), 'demo').propose(structure);
+    const target = (id: string) => item(result, id).wordpress;
+    expect(target('component:pagination').block).toBe('core/query-pagination');
+    expect(target('component:breadcrumbs').type).toBe('custom-block');
+    expect(target('component:tabs').note).toContain('tabs');
+    expect(target('component:slider').note).toContain('slider');
+    expect(result.items.filter((i) => i.hint === 'card').map((i) => i.name)).toEqual([
+      'Card',
+      'Card 2',
+    ]);
+  });
+});
+
+describe('InventoryProposer.proposal', () => {
+  const base = { value: 'x', match: 'none' as const, items: ['a'] };
+  it('proposes a new variable by kind, following the LightSpeed rules', () => {
+    expect(
+      InventoryProposer.proposal({ ...base, property: 'fontFamily', value: 'argesta' })
+    ).toContain('Font-Families/Alternate');
+    expect(InventoryProposer.proposal({ ...base, property: 'text', value: '#333333' })).toContain(
+      'Fit #333333 into a colour ramp'
+    );
+    expect(InventoryProposer.proposal({ ...base, property: 'text', value: '#333333' })).toContain(
+      'custom/<role>'
+    );
+    expect(
+      InventoryProposer.proposal({
+        ...base,
+        property: 'fill',
+        match: 'primitive',
+        nearest: 'neutral/900',
+        items: ['a', 'b'],
+      })
+    ).toBe(
+      'Matches the primitive neutral/900. Point the semantic role for this fill at it, or add a semantic token.'
+    );
+    expect(InventoryProposer.proposal({ ...base, property: 'effect', items: ['a', 'b'] })).toBe(
+      'Add an effect style for this shadow, or match it to the nearest one.'
+    );
+    expect(
+      InventoryProposer.proposal({ ...base, property: 'radius', items: ['a', 'b'] }, [
+        'Radius xLarge',
+        'Radius Round',
+      ])
+    ).toBe(
+      'Add a radius step between Radius xLarge and Radius Round, keeping the ramp in order and renumbering slugs if needed.'
+    );
+    expect(
+      InventoryProposer.proposal({ ...base, property: 'fontSize', items: ['a', 'b'] }, [])
+    ).toContain('Add a type size step,');
+    expect(InventoryProposer.proposal({ ...base, property: 'gap', items: ['a', 'b'] })).toContain(
+      'Add a spacing step,'
+    );
+  });
+});
+
+describe('StyleBinder', () => {
+  it('skips unparseable colours and reports shadows without a style', () => {
+    const bindings = new StyleBinder(new TokenIndex(variables())).bind(
+      { background: 'var(--x)', shadow: '0 9px 9px red', color: 'rgb(38, 36, 35)' },
+      'component'
+    );
+    expect(bindings).toEqual([
+      {
+        property: 'text',
+        value: '#262423',
+        variable: 'text/default',
+        codeSyntax: undefined,
+        match: 'exact',
+      },
+      { property: 'effect', value: '0 9px 9px red', match: 'none' },
+    ]);
+  });
+});
+
+describe('DecisionApplier', () => {
+  const now = () => new Date('2026-11-06T09:00:00Z');
+
+  it('merges, cuts, promotes, renames and approves', () => {
+    const inv = propose();
+    const out = new DecisionApplier(now).apply(inv, {
+      merge: [['pattern:card-grid-2', 'pattern:card-grid-3']],
+      cut: ['pattern:section-heading', 'pattern:section-heading'],
+      promote: ['pattern:media-and-text'],
+      rename: { 'pattern:gallery': 'Tour Gallery', 'component:tour-card': 'Safari Card' },
+      approve: true,
+    });
+    expect(out.items.find((i) => i.id === 'pattern:card-grid-3')).toBeUndefined();
+    expect(item(out, 'pattern:card-grid-2')).toMatchObject({ count: 4, oneOff: false });
+    expect(item(out, 'template:single-tour').composition).toEqual([
+      'part:header',
+      'pattern:hero',
+      'pattern:gallery',
+      'pattern:testimonials',
+      'pattern:card-grid-2',
+      'pattern:card-grid-2',
+      'part:footer',
+    ]);
+    expect(item(out, 'pattern:section-heading').status).toBe('cut');
+    expect(item(out, 'pattern:media-and-text').oneOff).toBe(false);
+    expect(item(out, 'pattern:gallery')).toMatchObject({
+      name: 'Tour Gallery',
+      figmaName: 'Patterns/Tour Gallery',
+      wordpress: { slug: 'tsp-theme/tour-gallery', file: 'patterns/tour-gallery.php' },
+    });
+    expect(item(out, 'component:tour-card').figmaName).toBe('Components/Cards/Safari Card');
+    expect(out).toMatchObject({ approved: true, approvedAt: '2026-11-06T09:00:00.000Z' });
+    expect(out.decisions).toContain('Merged pattern:card-grid-3 into pattern:card-grid-2.');
+    expect(inv.approved).toBe(false); // The input is not changed.
+  });
+
+  it('records the approved build scope, with what each template is built from', () => {
+    const out = new DecisionApplier(now).apply(propose(), {
+      cut: ['pattern:testimonials'],
+      build: ['template:single-tour', 'component:button'],
+    });
+    expect(out.buildScope).toEqual([
+      'part:header',
+      'part:footer',
+      'component:button',
+      'pattern:hero',
+      'pattern:gallery',
+      'pattern:card-grid-2',
+      'pattern:card-grid-3',
+      'template:single-tour',
+    ]);
+    expect(new InventoryReport().render(out)).toContain(
+      'Approved for the Figma build: part:header'
+    );
+  });
+
+  it('rewrites template compositions after a merge', () => {
+    const out = new DecisionApplier(now).apply(propose(), {
+      merge: [['pattern:gallery', 'pattern:testimonials']],
+    });
+    expect(item(out, 'template:single-tour').composition).toEqual([
+      'part:header',
+      'pattern:hero',
+      'pattern:gallery',
+      'pattern:gallery',
+      'pattern:card-grid-2',
+      'pattern:card-grid-3',
+      'part:footer',
+    ]);
+  });
+
+  it('refuses unknown ids and merges across kinds', () => {
+    expect(() => new DecisionApplier().apply(propose(), { cut: ['pattern:nope'] })).toThrow(
+      'Unknown item ids in decisions: pattern:nope.'
+    );
+    expect(() =>
+      new DecisionApplier().apply(propose(), { merge: [['pattern:hero', 'part:header']] })
+    ).toThrow("Can't merge part:header");
+  });
+
+  it('renames a pattern in an inventory without a theme prefix', () => {
+    const inv = propose();
+    delete item(inv, 'pattern:hero').wordpress.slug;
+    expect(
+      item(
+        new DecisionApplier().apply(inv, { rename: { 'pattern:hero': 'Big Hero' } }),
+        'pattern:hero'
+      ).wordpress.slug
+    ).toBe('tsp-theme/big-hero');
+  });
+});
+
+describe('InventoryReport', () => {
+  it('renders the summary, decisions and every section', () => {
+    const md = new InventoryReport('shots').render(propose());
+    expect(md).toContain('# Component inventory: www.example.com');
+    expect(md).toContain('Token bindings:');
+    expect(md).toContain('**Redirected:** /destinations/ redirects to https://www.example.com/');
+    expect(md).toContain(
+      '**Merge?** These look alike: pattern:card-grid, pattern:card-grid-2, pattern:card-grid-3.'
+    );
+    expect(md).toContain('**One-off:** component:badge appears once (/)');
+    expect(md).toContain(
+      '**Primitive only:** fill #f5f6f0. Proposed: Matches the primitive primary/100.'
+    );
+    expect(md).toContain(
+      '**No token:** radius 50px. Proposed: Add a radius step next to Radius Base'
+    );
+    expect(md).toContain('## Build scope');
+    expect(md).toContain('Not chosen yet.');
+    expect(md).toContain('**Template not crawled:** `search`');
+    expect(md).toContain('![pattern:hero](shots/pattern-hero-1440.png)');
+    expect(md).toContain('### Single Tour (`templates/single-tour.html`)');
+    expect(md).toContain('Frames: 1440 and 390.');
+    expect(md).not.toContain('—'); // No em dashes in document text.
+  });
+
+  it('says when no tokens were loaded, when everything is bound, and lists applied decisions', () => {
+    const bare = propose(false);
+    bare.unbound = [];
+    bare.redirects = [];
+    bare.items = bare.items
+      .filter((i) => i.kind === 'template')
+      .map((i) => ({ ...i, mergeWith: undefined }));
+    bare.items.push({
+      ...bare.items[0],
+      id: 'template:search',
+      wordpress: { type: 'template', slug: 'search' },
+    });
+    bare.items.push({
+      ...bare.items[0],
+      id: 'template:single',
+      wordpress: { type: 'template', slug: 'single' },
+    });
+    bare.items.push({
+      ...bare.items[0],
+      id: 'template:page',
+      wordpress: { type: 'template', slug: 'page' },
+    });
+    bare.decisions = ['Approved by the reviewer.'];
+    bare.approved = true;
+    bare.approvedAt = '2026-11-06T09:00:00.000Z';
+    const md = new InventoryReport().render(bare);
+    expect(md).toContain('No variables export was loaded');
+    expect(md).toContain('Every value binds to a token.');
+    expect(md).toContain('- Nothing to decide.');
+    expect(md).toContain('## Decisions applied');
+    expect(md).toContain('Status: approved 2026-11-06');
+  });
+
+  it('lists pages the crawler could not capture', () => {
+    const inv = propose();
+    inv.failures = [{ url: 'https://www.example.com/slow/', viewport: 390, error: 'timeout' }];
+    expect(new InventoryReport().render(inv)).toContain(
+      '**Not captured:** /slow/ at 390px (timeout).'
+    );
+  });
+
+  it('caps the decisions list for long lists of unbound values', () => {
+    const inv = propose();
+    inv.unbound = Array.from({ length: 30 }, (_, n) => ({
+      property: 'fill',
+      value: `#00000${n}`,
+      match: 'none' as const,
+      items: ['x'],
+      proposal: 'Fit it.',
+    }));
+    expect(new InventoryReport().render(inv)).toContain('5 more values without a token');
+  });
+});
+
+describe('runProposeCli', () => {
+  function io(files: Record<string, string>) {
+    const written: Record<string, string> = {};
+    const out: string[] = [];
+    const err: string[] = [];
+    return {
+      io: {
+        readFile: (p: string) => {
+          if (!(p in files)) {
+            throw new Error(`ENOENT ${p}`);
+          }
+          return files[p];
+        },
+        writeFile: (p: string, c: string) => {
+          written[p] = c;
+        },
+        stdout: (t: string) => void out.push(t),
+        stderr: (t: string) => void err.push(t),
+        now: () => new Date('2026-11-06T09:00:00Z'),
+      },
+      written,
+      out,
+      err,
+    };
+  }
+  const files = {
+    's.json': JSON.stringify(site()),
+    'v.json': JSON.stringify(variables()),
+    'd.json': JSON.stringify({ approve: true }),
+  };
+
+  it('proposes, applies decisions and writes both files', () => {
+    const t = io(files);
+    expect(
+      runProposeCli(
+        [
+          's.json',
+          '--tokens',
+          'v.json',
+          '--theme',
+          'tsp-theme',
+          '--decisions',
+          'd.json',
+          '--out',
+          'i.json',
+          '--report',
+          'i.md',
+          '--shots',
+          'shots',
+        ],
+        t.io
+      )
+    ).toBe(0);
+    expect(JSON.parse(t.written['i.json']).approved).toBe(true);
+    expect(t.written['i.md']).toContain('Status: approved');
+    expect(t.out.join('')).toMatch(
+      /items \(2 template-part, \d+ component, \d+ pattern, 4 template\)/
+    );
+  });
+
+  it('works without tokens and prints usage', () => {
+    const t = io(files);
+    expect(runProposeCli(['s.json'], t.io)).toBe(0);
+    expect(Object.keys(t.written)).toEqual(['inventory.json', 'inventory.md']);
+    expect(runProposeCli(['--help'], t.io)).toBe(0);
+    expect(t.out.join('')).toContain('Usage');
+  });
+
+  it('reports errors', () => {
+    for (const argv of [[], ['s.json', '--nope', 'x'], ['s.json', '--out'], ['missing.json']]) {
+      const t = io(files);
+      expect(runProposeCli(argv, t.io)).toBe(1);
+      expect(t.err.join('')).toMatch(/^propose-inventory: /);
+    }
+  });
+});
diff --git a/skills/site-to-figma-components/scripts/__tests__/tokens.test.ts b/skills/site-to-figma-components/scripts/__tests__/tokens.test.ts
new file mode 100644
index 0000000000..913d754460
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/__tests__/tokens.test.ts
@@ -0,0 +1,111 @@
+import { Colour } from '../lib/color';
+import { TokenIndex } from '../lib/tokens';
+import { variables } from './fixtures';
+
+describe('Colour', () => {
+  it('parses hex, rgb and rgba in comma and space syntax', () => {
+    expect(Colour.hex(Colour.parse('#abc')!)).toBe('#aabbcc');
+    expect(Colour.parse('#11223380')!.a).toBeCloseTo(0.5, 2);
+    expect(Colour.hex(Colour.parse('rgb(141, 98, 31)')!)).toBe('#8d621f');
+    expect(Colour.parse('rgba(0, 0, 0, 0.25)')!.a).toBe(0.25);
+    expect(Colour.parse('rgb(0 0 0 / 50%)')!.a).toBe(0.5);
+    expect(Colour.hex({ r: 0, g: 0, b: 0, a: 0.5 })).toBe('#00000080');
+  });
+
+  it('returns null for anything else', () => {
+    for (const value of [undefined, '', 'red', 'var(--x)', 'rgb(1, 2)', 'rgb(a, b, c)']) {
+      expect(Colour.parse(value)).toBeNull();
+    }
+    expect(Colour.fromFigma(null)).toBeNull();
+    expect(Colour.fromFigma({ r: 1 })).toBeNull();
+    expect(Colour.fromFigma({ r: 1, g: 0, b: 0 })).toEqual({ r: 1, g: 0, b: 0, a: 1 });
+  });
+
+  it('measures distance and luminance', () => {
+    const black = Colour.parse('#000')!;
+    const white = Colour.parse('#fff')!;
+    expect(Colour.distance(black, black)).toBe(0);
+    expect(Colour.distance(black, white)).toBeCloseTo(441.67, 1);
+    expect(Colour.luminance(white)).toBeCloseTo(1);
+    expect(Colour.luminance(black)).toBe(0);
+  });
+});
+
+describe('TokenIndex', () => {
+  const index = new TokenIndex(variables());
+
+  it('prefers semantic colour tokens by role', () => {
+    expect(index.colour('rgb(141, 98, 31)', 'text')).toMatchObject({
+      variable: 'text/link',
+      match: 'exact',
+      semantic: true,
+      codeSyntax: 'var(--wp--custom--color--text--link)',
+    });
+    expect(index.colour('rgb(163, 23, 0)', 'fill')).toMatchObject({
+      variable: 'action/cta/background',
+    });
+    expect(index.colour('rgb(255, 255, 255)', 'text')!.variable).toBe('text/inverse');
+    expect(index.colour('rgb(255, 255, 255)', 'fill')!.variable).toBe('surface/default');
+    expect(index.colour('rgb(138, 133, 128)', 'stroke')!.variable).toBe('border/default');
+  });
+
+  it('marks near matches and primitive-only matches, and skips prototype collections', () => {
+    expect(index.colour('rgb(145, 100, 31)', 'text')!.match).toBe('near');
+    expect(index.colour('rgb(245, 246, 240)', 'fill')).toMatchObject({
+      variable: 'primary/100',
+      semantic: false,
+    });
+    expect(index.colour('rgb(1, 2, 3)', 'fill')).toBeUndefined();
+    expect(index.colour('not a colour', 'fill')).toBeUndefined();
+  });
+
+  it('matches sizes in the Max mode, within a tolerance', () => {
+    expect(index.length(40, 'spacing')).toMatchObject({
+      variable: 'Padding/40',
+      match: 'exact',
+      semantic: true,
+    });
+    expect(index.length(41, 'spacing')!.match).toBe('near');
+    expect(index.length(30, 'spacing')).toBeUndefined();
+    expect(index.length(0, 'spacing')).toBeUndefined();
+    expect(index.length(undefined, 'radius')).toBeUndefined();
+    expect(index.length(8, 'radius')!.variable).toBe('Radius Base');
+    expect(index.length(16, 'font-size')!.codeSyntax).toBe('var(--wp--preset--font-size--200)');
+    expect(new TokenIndex().length(16, 'font-size')).toBeUndefined();
+  });
+
+  it('matches font families by name, loosely', () => {
+    expect(index.font('Moret')).toMatchObject({
+      variable: 'Font-Families/Primary',
+      match: 'exact',
+    });
+    expect(index.font('moret_regular')!.match).toBe('near');
+    expect(index.font('Lora')).toBeUndefined();
+    expect(index.font(undefined)).toBeUndefined();
+  });
+
+  it('matches box shadows to drop shadow effect styles', () => {
+    expect(index.shadow('rgba(0, 0, 0, 0.2) 0px 2px 4px 0px')!.variable).toBe('LSX/xSmall');
+    expect(index.shadow('0px 2px 4px rgba(0, 0, 0, 0.2), 0 0 1px red')!.variable).toBe(
+      'LSX/xSmall'
+    );
+    expect(index.shadow('0px 9px 9px red')).toBeUndefined();
+    expect(index.shadow('none')).toBeUndefined();
+    expect(index.shadow(undefined)).toBeUndefined();
+    expect(TokenIndex.parseShadow('inset red')).toBeNull();
+    expect(TokenIndex.parseShadow('1px 2px')).toEqual({ x: 1, y: 2, blur: 0, spread: 0 });
+  });
+
+  it('counts what it indexed and recognises size families', () => {
+    expect(index.size).toBeGreaterThan(15);
+    expect(new TokenIndex().size).toBe(0);
+    expect(TokenIndex.familyOf('Theme - Typography', 'Line-Heights/Body')).toBeUndefined();
+    expect(TokenIndex.familyOf('Theme - Custom', 'Spacing/Button/Medium/Gap')).toBe('spacing');
+  });
+
+  it('can include collections that are skipped by default', () => {
+    expect(new TokenIndex(variables(), /^none$/).colour('rgb(1, 2, 3)', 'fill')!.variable).toBe(
+      'card/bg'
+    );
+  });
+});
diff --git a/skills/site-to-figma-components/scripts/__tests__/write-manifest.test.ts b/skills/site-to-figma-components/scripts/__tests__/write-manifest.test.ts
new file mode 100644
index 0000000000..48d911cecf
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/__tests__/write-manifest.test.ts
@@ -0,0 +1,212 @@
+import { DecisionApplier, Inventory, InventoryProposer } from '../propose-inventory';
+import { TokenIndex } from '../lib/tokens';
+import { FigmaNodes, ManifestBuilder, runManifestCli } from '../write-manifest';
+import { site, variables } from './fixtures';
+
+const now = () => new Date('2026-11-07T09:00:00Z');
+
+function approved(): Inventory {
+  const inv = new InventoryProposer(new TokenIndex(variables()), 'tsp-theme').propose(site());
+  return new DecisionApplier(() => new Date('2026-11-06T09:00:00Z')).apply(inv, {
+    cut: ['pattern:testimonials'],
+    approve: true,
+  });
+}
+
+function allNodes(inv: Inventory): FigmaNodes {
+  const nodes: FigmaNodes['nodes'] = {};
+  inv.items
+    .filter((i) => i.status !== 'cut')
+    .forEach((i, n) => {
+      nodes[i.id] = { nodeId: `100:${n + 1}`, page: '> Rebuild' };
+      if (i.kind === 'template') {
+        nodes[i.id].mobileNodeId = `200:${n + 1}`;
+      }
+    });
+  return { fileKey: 'abc123', nodes };
+}
+
+describe('ManifestBuilder', () => {
+  it('maps every built node to its WordPress target', () => {
+    const inv = approved();
+    const m = new ManifestBuilder(now).build(inv, allNodes(inv));
+    expect(m).toMatchObject({
+      manifestVersion: 1,
+      theme: 'tsp-theme',
+      figmaFileKey: 'abc123',
+      inventoryApprovedAt: '2026-11-06T09:00:00.000Z',
+      generatedAt: '2026-11-07T09:00:00.000Z',
+      skipped: [],
+      warnings: [],
+    });
+    expect(m.entries.map((e) => e.kind)).toEqual(
+      [...m.entries.map((e) => e.kind)].sort(
+        (a, b) =>
+          ['component', 'template-part', 'pattern', 'template'].indexOf(a) -
+          ['component', 'template-part', 'pattern', 'template'].indexOf(b)
+      )
+    );
+    const button = m.entries.find((e) => e.id === 'component:button')!;
+    expect(button.figma.url).toBe(
+      `https://www.figma.com/design/abc123/?node-id=${button.figma.nodeId.replace(':', '-')}`
+    );
+    expect(button.variantProperties?.Style).toEqual(['Fill', 'Outline']);
+    expect(button.figma.page).toBe('> Rebuild');
+  });
+
+  it('resolves template compositions, with cut sections kept local', () => {
+    const inv = approved();
+    const tour = new ManifestBuilder(now)
+      .build(inv, allNodes(inv))
+      .entries.find((e) => e.id === 'template:single-tour')!;
+    expect(tour.figma.mobileNodeId).toMatch(/^200:/);
+    expect(tour.composition).toEqual([
+      { id: 'part:header', target: 'template-part', slug: 'header', file: 'parts/header.html' },
+      { id: 'pattern:hero', target: 'pattern', slug: 'tsp-theme/hero', file: 'patterns/hero.php' },
+      {
+        id: 'pattern:gallery',
+        target: 'pattern',
+        slug: 'tsp-theme/gallery',
+        file: 'patterns/gallery.php',
+      },
+      { id: 'pattern:testimonials', target: 'local' },
+      {
+        id: 'pattern:card-grid-2',
+        target: 'pattern',
+        slug: 'tsp-theme/card-grid-2',
+        file: 'patterns/card-grid-2.php',
+      },
+      {
+        id: 'pattern:card-grid-3',
+        target: 'pattern',
+        slug: 'tsp-theme/card-grid-3',
+        file: 'patterns/card-grid-3.php',
+      },
+      { id: 'part:footer', target: 'template-part', slug: 'footer', file: 'parts/footer.html' },
+    ]);
+  });
+
+  it('refuses an unapproved inventory, a missing file key, bad node IDs and missing nodes', () => {
+    const inv = approved();
+    const builder = new ManifestBuilder(now);
+    expect(() => builder.build({ ...inv, approved: false }, allNodes(inv))).toThrow('not approved');
+    expect(() => builder.build(inv, { ...allNodes(inv), fileKey: '' })).toThrow('fileKey');
+    const bad = allNodes(inv);
+    bad.nodes['component:button'].nodeId = '12-34';
+    expect(() => builder.build(inv, bad)).toThrow('invalid node ID "12-34"');
+    const missing = allNodes(inv);
+    delete missing.nodes['pattern:hero'];
+    expect(() => builder.build(inv, missing)).toThrow('pattern:hero has no Figma node');
+  });
+
+  it('builds a partial manifest with warnings', () => {
+    const inv = approved();
+    const nodes: FigmaNodes = {
+      fileKey: 'abc123',
+      nodes: {
+        'part:header': { nodeId: '1:1' },
+        'template:front-page': { nodeId: '1:2' },
+        'pattern:testimonials': { nodeId: '1:3' },
+        'pattern:ghost': { nodeId: '1:4' },
+      },
+    };
+    const m = new ManifestBuilder(now).build(inv, nodes, true);
+    expect(m.entries.map((e) => e.id)).toEqual(['part:header', 'template:front-page']);
+    expect(m.skipped.length).toBeGreaterThan(5);
+    expect(m.warnings).toEqual([
+      'pattern:testimonials was cut from the inventory but has a Figma node (1:3). Archive the node or restore the item.',
+      'pattern:ghost is in figma-nodes.json but not in the inventory.',
+      'template:front-page changes layout at 390px but has no mobile frame.',
+    ]);
+    const md = new ManifestBuilder(now).markdown(m);
+    expect(md).toContain('## Not built yet');
+    expect(md).toContain('## Warnings');
+    expect(md).toContain('1. template-part `header`');
+  });
+
+  it('only requires nodes for items in the approved build scope', () => {
+    const inv = new DecisionApplier().apply(approved(), { build: ['component:button'] });
+    const m = new ManifestBuilder(now).build(inv, {
+      fileKey: 'k',
+      nodes: { 'component:button': { nodeId: '1:1' } },
+    });
+    expect(m.entries.map((e) => e.id)).toEqual(['component:button']);
+    expect(m.skipped[0].reason).toBe('Outside the approved build scope.');
+  });
+
+  it('renders the Markdown table and composition', () => {
+    const inv = approved();
+    const builder = new ManifestBuilder(now);
+    const m = builder.build(inv, allNodes(inv));
+    const md = builder.markdown(m);
+    expect(md).toContain('# Figma to WordPress manifest: www.example.com');
+    expect(md).toMatch(
+      /\| component \| Button \| \[100:\d+\]\(https:\/\/www\.figma\.com\/design\/abc123\/\?node-id=100-\d+\) \| core-block, core\/button, styles: outline \| {2}\|/
+    );
+    expect(md).toContain('(mobile 200:');
+    expect(md).toContain('pattern:testimonials (local section, no pattern)');
+    expect(md).not.toContain('## Not built yet');
+    expect(builder.markdown({ ...m, inventoryApprovedAt: undefined, entries: [] })).toContain(
+      'on an unknown date'
+    );
+  });
+});
+
+describe('runManifestCli', () => {
+  function io(files: Record<string, string>) {
+    const written: Record<string, string> = {};
+    const out: string[] = [];
+    const err: string[] = [];
+    return {
+      io: {
+        readFile: (p: string) => files[p],
+        writeFile: (p: string, c: string) => {
+          written[p] = c;
+        },
+        stdout: (t: string) => void out.push(t),
+        stderr: (t: string) => void err.push(t),
+        now,
+      },
+      written,
+      out,
+      err,
+    };
+  }
+  const inv = approved();
+  const files = {
+    'i.json': JSON.stringify(inv),
+    'n.json': JSON.stringify(allNodes(inv)),
+    'p.json': JSON.stringify({ fileKey: 'k', nodes: {} }),
+  };
+
+  it('writes the manifest and its Markdown', () => {
+    const t = io(files);
+    expect(
+      runManifestCli(['i.json', '--nodes', 'n.json', '--out', 'm.json', '--markdown', 'm.md'], t.io)
+    ).toBe(0);
+    expect(JSON.parse(t.written['m.json']).entries.length).toBeGreaterThan(10);
+    expect(t.written['m.md']).toContain('manifest');
+    expect(t.out.join('')).toMatch(/entries, 0 not built, 0 warnings/);
+  });
+
+  it('accepts --partial and prints usage', () => {
+    const t = io(files);
+    expect(runManifestCli(['i.json', '--nodes', 'p.json', '--partial'], t.io)).toBe(0);
+    expect(Object.keys(t.written)).toEqual(['manifest.json', 'manifest.md']);
+    expect(runManifestCli(['-h'], t.io)).toBe(0);
+    expect(t.out.join('')).toContain('Usage');
+  });
+
+  it('reports errors', () => {
+    for (const argv of [
+      ['i.json'],
+      ['i.json', '--nodes'],
+      ['i.json', '--nope', 'x'],
+      ['i.json', '--nodes', 'p.json'],
+    ]) {
+      const t = io(files);
+      expect(runManifestCli(argv, t.io)).toBe(1);
+      expect(t.err.join('')).toMatch(/^write-manifest: /);
+    }
+  });
+});
diff --git a/skills/site-to-figma-components/scripts/crawl-site-structure.ts b/skills/site-to-figma-components/scripts/crawl-site-structure.ts
new file mode 100644
index 0000000000..713bba1432
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/crawl-site-structure.ts
@@ -0,0 +1,1122 @@
+/* global HTMLImageElement */
+/**
+ * Crawls pages of a live site and records its repeated building blocks at the
+ * mobile (390px) and desktop (1440px) frame widths: site-wide regions,
+ * page sections and single UI elements, each with its DOM shape, computed
+ * style, interactive states and real content.
+ *
+ * Reads public pages only, one at a time, with a pause between requests. It
+ * hovers and focuses elements to read their states, but never clicks, types
+ * or submits. The output feeds propose-inventory.ts.
+ *
+ * Usage:
+ *   npx tsx crawl-site-structure.ts --url https://www.example.com \
+ *     --pages /,/tours/,/tours/example/ --out site-structure.json --shots shots
+ *   npx tsx crawl-site-structure.ts --url https://www.example.com \
+ *     --shoot inventory.json --shots shots
+ */
+
+/* global Element, HTMLElement, CSSRuleList, CSSStyleRule, CSSGroupingRule -- collectors run in the browser */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export type Hint =
+  | 'header'
+  | 'footer'
+  | 'sidebar'
+  | 'section'
+  | 'button'
+  | 'link'
+  | 'input'
+  | 'card'
+  | 'badge'
+  | 'nav-item'
+  | 'breadcrumbs'
+  | 'pagination'
+  | 'accordion'
+  | 'tabs'
+  | 'slider'
+  | 'form';
+
+export type Region = 'header' | 'footer' | 'sidebar' | 'main';
+export type State = 'hover' | 'focus' | 'active' | 'disabled';
+
+export interface StyleSig {
+  background?: string;
+  backgroundImage?: boolean;
+  color?: string;
+  border?: string;
+  borderWidth?: number;
+  radius?: number;
+  fontFamily?: string;
+  fontSize?: number;
+  fontWeight?: number;
+  lineHeight?: number;
+  paddingBlock?: number;
+  paddingInline?: number;
+  gap?: number;
+  shadow?: string;
+  textDecoration?: string;
+  textTransform?: string;
+  opacity?: number;
+}
+
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface ImageRef {
+  src: string;
+  alt: string;
+}
+
+export interface StructureNode {
+  /** Unique CSS selector from the body, also used to pair the node across viewports. */
+  selector: string;
+  /** Short human label, such as `a.wp-block-button__link`. */
+  label: string;
+  hint: Hint;
+  region: Region;
+  tag: string;
+  rect: Rect;
+  /** DOM shape signature to depth 3, with repeated siblings collapsed: `ul(li*)`. */
+  shape: string;
+  /** Distinct x positions of the direct children: 1 means stacked. */
+  columns: number;
+  style: StyleSig;
+  states?: Partial<Record<State, StyleSig>>;
+  /** `browser` when hover and focus were triggered on this element; otherwise read from CSS. */
+  stateSource?: 'css' | 'browser';
+  text?: string;
+  headings: string[];
+  buttons: string[];
+  images: ImageRef[];
+  icon?: boolean;
+  open?: boolean;
+}
+
+export interface CollectedStructure {
+  /** Where the page ended up after redirects. */
+  finalUrl: string;
+  title: string;
+  bodyClasses: string[];
+  docHeight: number;
+  nodes: StructureNode[];
+}
+
+export interface PageStructure extends CollectedStructure {
+  url: string;
+  viewport: number;
+  screenshot?: string;
+}
+
+export interface SiteStructure {
+  site: string;
+  capturedAt: string;
+  viewports: number[];
+  pages: PageStructure[];
+  /** Page views that could not be captured, such as timeouts. The rest of the crawl continues. */
+  failures?: { url: string; viewport: number; error: string }[];
+}
+
+export interface CollectOptions {
+  maxNodes?: number;
+  maxRules?: number;
+}
+
+/**
+ * Runs inside the page. Must stay self-contained: no imports or outer
+ * variables, because the browser receives only this function's source.
+ */
+export function collectPageStructure(options: CollectOptions = {}): CollectedStructure {
+  const maxNodes = options.maxNodes ?? 800;
+  const maxRules = options.maxRules ?? 4000;
+  const vw = window.innerWidth;
+  const nodes: StructureNode[] = [];
+  const hinted = new Map<Element, Hint>();
+
+  const px = (value: string) => {
+    const n = parseFloat(value);
+    return Number.isFinite(n) ? n : undefined;
+  };
+  const transparent = (value: string) =>
+    !value || value === 'transparent' || /rgba\([^)]*,\s*0\)$/.test(value.replace(/\s+/g, ''));
+  const classText = (el: Element) => (typeof el.className === 'string' ? el.className : '');
+  const visible = (el: Element) => {
+    const s = window.getComputedStyle(el);
+    return s.display !== 'none' && s.visibility !== 'hidden';
+  };
+  const rectOf = (el: Element): Rect => {
+    const r = el.getBoundingClientRect();
+    return {
+      x: Math.round(r.left + window.scrollX),
+      y: Math.round(r.top + window.scrollY),
+      w: Math.round(r.width),
+      h: Math.round(r.height),
+    };
+  };
+  const selectorOf = (el: Element) => {
+    const parts: string[] = [];
+    let node: Element | null = el;
+    while (node && node !== document.body) {
+      const parent: Element | null = node.parentElement;
+      const index = parent ? Array.prototype.indexOf.call(parent.children, node) + 1 : 1;
+      parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${index})`);
+      node = parent;
+    }
+    return ['body', ...parts].join(' > ');
+  };
+  const noise =
+    /^(wp-container-|wp-elements-|is-layout-|wp-block-group-is-layout|has-[a-z0-9-]+-(color|background-color|font-size)$|elementor-element-[0-9a-f]+|css-|jsx-|js-)|[0-9a-f]{6,}/;
+  const labelOf = (el: Element) => {
+    const classes = classText(el)
+      .split(/\s+/)
+      .filter((c) => c && !noise.test(c))
+      .slice(0, 2);
+    const id = el.id && !noise.test(el.id) ? `#${el.id}` : '';
+    return [el.tagName.toLowerCase() + id, ...classes].join('.');
+  };
+  const textOf = (el: Element, max = 80) =>
+    (el.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+  const shapeOf = (el: Element, depth: number): string => {
+    const tag = el.tagName.toLowerCase();
+    if (depth === 0 || tag === 'svg') {
+      return tag;
+    }
+    const kids: string[] = [];
+    for (let i = 0; i < el.children.length; i++) {
+      const child = el.children[i];
+      if (['SCRIPT', 'STYLE', 'TEMPLATE', 'NOSCRIPT', 'BR'].includes(child.tagName)) {
+        continue;
+      }
+      const shape = shapeOf(child, depth - 1);
+      const last = kids[kids.length - 1];
+      if (last === shape || last === `${shape}*`) {
+        kids[kids.length - 1] = `${shape}*`;
+      } else {
+        kids.push(shape);
+      }
+    }
+    return kids.length ? `${tag}(${kids.join(',')})` : tag;
+  };
+  const columnsOf = (el: Element) => {
+    const xs = new Set<number>();
+    for (let i = 0; i < el.children.length; i++) {
+      const r = el.children[i].getBoundingClientRect();
+      if (r.width > 0 && r.height > 0) {
+        xs.add(Math.round(r.left / 8));
+      }
+    }
+    return Math.max(1, xs.size);
+  };
+  const styleOf = (el: Element): StyleSig => {
+    const s = window.getComputedStyle(el);
+    const sig: StyleSig = {};
+    if (!transparent(s.backgroundColor)) {
+      sig.background = s.backgroundColor;
+    }
+    if (s.backgroundImage && s.backgroundImage !== 'none' && s.backgroundImage.includes('url(')) {
+      sig.backgroundImage = true;
+    }
+    sig.color = s.color;
+    const borderWidth = px(s.borderTopWidth) ?? 0;
+    if (borderWidth > 0 && s.borderTopStyle !== 'none' && !transparent(s.borderTopColor)) {
+      sig.border = s.borderTopColor;
+      sig.borderWidth = borderWidth;
+    }
+    const radius = px(s.borderTopLeftRadius) ?? px(s.borderRadius);
+    if (radius) {
+      sig.radius = radius;
+    }
+    sig.fontFamily = s.fontFamily.split(',')[0].replace(/["']/g, '').trim() || undefined;
+    sig.fontSize = px(s.fontSize);
+    sig.fontWeight = Number(s.fontWeight) || undefined;
+    sig.lineHeight = px(s.lineHeight);
+    sig.paddingBlock = px(s.paddingTop) || undefined;
+    sig.paddingInline = px(s.paddingLeft) || undefined;
+    if (s.display.includes('flex') || s.display.includes('grid')) {
+      sig.gap = px(s.rowGap || s.gap) || px(s.columnGap) || undefined;
+    }
+    if (s.boxShadow && s.boxShadow !== 'none') {
+      sig.shadow = s.boxShadow;
+    }
+    const decoration = s.textDecorationLine || (s.textDecoration ?? '').split(' ')[0];
+    if (decoration && decoration !== 'none') {
+      sig.textDecoration = decoration;
+    }
+    if (s.textTransform && s.textTransform !== 'none') {
+      sig.textTransform = s.textTransform;
+    }
+    return sig;
+  };
+  const imagesOf = (el: Element) => {
+    const out: ImageRef[] = [];
+    const imgs = el.tagName === 'IMG' ? [el] : Array.from(el.querySelectorAll('img'));
+    for (const img of imgs.slice(0, 3)) {
+      const src = (img as HTMLImageElement).currentSrc || img.getAttribute('src') || '';
+      if (src && !src.startsWith('data:')) {
+        out.push({ src, alt: img.getAttribute('alt') ?? '' });
+      }
+    }
+    const withBg = [el, ...Array.from(el.querySelectorAll('*')).slice(0, 30)];
+    for (const node of withBg) {
+      if (out.length >= 3) {
+        break;
+      }
+      const match = window
+        .getComputedStyle(node)
+        .backgroundImage.match(/url\(["']?([^"')]+)["']?\)/);
+      if (match && !match[1].startsWith('data:')) {
+        out.push({ src: match[1], alt: '' });
+      }
+    }
+    return out;
+  };
+
+  const matchesClass = (el: Element, pattern: RegExp) => pattern.test(classText(el));
+  const outermost = (el: Element, hint: Hint) => {
+    for (let up = el.parentElement; up && up !== document.body; up = up.parentElement) {
+      if (hinted.get(up) === hint) {
+        return false;
+      }
+    }
+    return true;
+  };
+  const hasRepeatedSiblings = (el: Element) => {
+    const parent = el.parentElement;
+    if (!parent) {
+      return false;
+    }
+    const shape = shapeOf(el, 2);
+    let same = 0;
+    for (let i = 0; i < parent.children.length; i++) {
+      if (shapeOf(parent.children[i], 2) === shape) {
+        same++;
+      }
+    }
+    return same >= 2;
+  };
+  const regionOf = (el: Element): Region => {
+    for (let up: Element | null = el; up && up !== document.body; up = up.parentElement) {
+      const hint = hinted.get(up);
+      if (hint === 'header' || hint === 'footer' || hint === 'sidebar') {
+        return hint;
+      }
+    }
+    return 'main';
+  };
+
+  const buttonClass = /(^|\s|-)(btn|button)(\s|-|_|$)|wp-block-button__link|wp-element-button/i;
+
+  const hintOf = (el: Element, rect: Rect): Hint | undefined => {
+    const tag = el.tagName;
+    const s = window.getComputedStyle(el);
+    const label = (el.getAttribute('aria-label') ?? '').toLowerCase();
+    const type = (el.getAttribute('type') ?? '').toLowerCase();
+    const ident = `${el.id} ${classText(el)}`;
+    const outside = !el.closest('main, article') && rect.w >= vw * 0.9;
+    if (
+      outside &&
+      (tag === 'HEADER' ||
+        /(^|\s)(site-header|header-wrapper|masthead|top-bar|topbar)(\s|$)/.test(ident))
+    ) {
+      return 'header';
+    }
+    if (
+      outside &&
+      (tag === 'FOOTER' ||
+        /(^|\s)(site-footer|footer-widgets|footer-wrapper|footer-cta|colophon)(\s|$)/.test(ident))
+    ) {
+      return 'footer';
+    }
+    if (
+      rect.w < vw * 0.45 &&
+      rect.h >= 150 &&
+      !['header', 'footer'].includes(regionOf(el)) &&
+      (/(^|\s)(sidebar|secondary|widget-area)(\s|$)/.test(ident) ||
+        (tag === 'ASIDE' && !!el.querySelector('.widget')))
+    ) {
+      return 'sidebar';
+    }
+    if (label.includes('breadcrumb') || matchesClass(el, /breadcrumb/i)) {
+      return 'breadcrumbs';
+    }
+    if (
+      label.includes('pagination') ||
+      matchesClass(el, /(^|\s)(pagination|nav-links|page-numbers|wp-block-query-pagination)(\s|$)/)
+    ) {
+      return tag === 'A' || tag === 'SPAN' ? undefined : 'pagination';
+    }
+    if (
+      el.getAttribute('aria-roledescription') === 'carousel' ||
+      matchesClass(el, /(^|\s|-)(swiper|slick|splide|glide|carousel|slider)(\s|$)/i)
+    ) {
+      return 'slider';
+    }
+    if (
+      el.getAttribute('role') === 'tablist' ||
+      matchesClass(el, /(^|\s)([a-z-]*tabs|tablist)(\s|$)/i)
+    ) {
+      return 'tabs';
+    }
+    if (tag === 'DETAILS' || matchesClass(el, /(^|\s)([a-z-]*accordion)(\s|$)/i)) {
+      return 'accordion';
+    }
+    if (tag === 'FORM') {
+      return 'form';
+    }
+    if (tag === 'BUTTON' || (tag === 'INPUT' && ['submit', 'button'].includes(type))) {
+      return 'button';
+    }
+    if (buttonClass.test(classText(el)) && !el.querySelector('a, button')) {
+      return 'button'; // A wrapper such as div.wp-block-button holds the real button.
+    }
+    if (tag === 'SELECT' || tag === 'TEXTAREA' || tag === 'INPUT') {
+      return ['checkbox', 'radio', 'hidden', 'image', 'submit', 'button'].includes(type)
+        ? undefined
+        : 'input';
+    }
+    if (tag === 'A') {
+      const filled = !transparent(s.backgroundColor) || (px(s.borderTopWidth) ?? 0) > 0;
+      if (filled && (px(s.paddingLeft) ?? 0) >= 8) {
+        return 'button';
+      }
+      if (
+        el.closest('nav') &&
+        !el.closest('[aria-label*="readcrumb"], [class*="breadcrumb"], [class*="pagination"]')
+      ) {
+        return 'nav-item';
+      }
+      if (el.closest('p, td, dd, blockquote, figcaption')) {
+        return 'link';
+      }
+    }
+    const ownText = textOf(el, 40);
+    const childTags = Array.from(el.children).map((c) => c.tagName);
+    if (
+      ['SPAN', 'DIV', 'A', 'LI'].includes(tag) &&
+      ownText.length > 0 &&
+      ownText.length <= 30 &&
+      rect.h > 0 &&
+      rect.h <= 40 &&
+      childTags.every((t) => ['SVG', 'I', 'IMG', 'SPAN'].includes(t)) &&
+      (!transparent(s.backgroundColor) || (px(s.borderTopWidth) ?? 0) > 0) &&
+      (px(s.borderTopLeftRadius) ?? px(s.borderRadius) ?? 0) > 0
+    ) {
+      return 'badge';
+    }
+    if (
+      rect.w >= 160 &&
+      rect.w <= (vw < 600 ? vw : vw * 0.6) &&
+      rect.h >= 120 &&
+      imagesOf(el).length > 0 &&
+      el.querySelector('h2, h3, h4, h5, h6, strong, .title') &&
+      (tag === 'A' || el.querySelector('a')) &&
+      hasRepeatedSiblings(el)
+    ) {
+      return 'card';
+    }
+    return undefined;
+  };
+
+  // States declared in same-origin CSS, keyed by the selector they apply to.
+  const stateRules: { state: State; base: string; style: StyleSig }[] = [];
+  const statePattern = /:(hover|focus-visible|focus-within|focus|active|disabled)\b/g;
+  const readRules = (rules: CSSRuleList) => {
+    for (let r = 0; r < rules.length && stateRules.length < maxRules; r++) {
+      const rule = rules[r] as CSSStyleRule & CSSGroupingRule;
+      if (!rule.selectorText) {
+        if (rule.cssRules) {
+          readRules(rule.cssRules);
+        }
+        continue;
+      }
+      for (const selector of rule.selectorText.split(',')) {
+        const found = selector.match(statePattern);
+        if (!found) {
+          continue;
+        }
+        const name = found[0].slice(1);
+        const state: State = name.startsWith('focus') ? 'focus' : (name as State);
+        const base = selector.replace(statePattern, '').trim();
+        if (!/[.#[]/.test(base)) {
+          continue; // Bare element rules such as a:hover apply everywhere and add only noise.
+        }
+        const decl = rule.style;
+        const style: StyleSig = {};
+        const bg = decl.getPropertyValue('background-color') || decl.getPropertyValue('background');
+        if (bg) {
+          style.background = bg.trim();
+        }
+        if (decl.getPropertyValue('color')) {
+          style.color = decl.getPropertyValue('color').trim();
+        }
+        if (decl.getPropertyValue('border-color')) {
+          style.border = decl.getPropertyValue('border-color').trim();
+        }
+        if (decl.getPropertyValue('box-shadow')) {
+          style.shadow = decl.getPropertyValue('box-shadow').trim();
+        }
+        const decoration =
+          decl.getPropertyValue('text-decoration-line') || decl.getPropertyValue('text-decoration');
+        if (decoration) {
+          style.textDecoration = decoration.trim();
+        }
+        if (decl.getPropertyValue('opacity')) {
+          style.opacity = Number(decl.getPropertyValue('opacity'));
+        }
+        if (Object.keys(style).length) {
+          stateRules.push({ state, base, style });
+        }
+      }
+    }
+  };
+  for (let s = 0; s < document.styleSheets.length; s++) {
+    try {
+      readRules(document.styleSheets[s].cssRules);
+    } catch {
+      continue; // Cross-origin stylesheet.
+    }
+  }
+  const cssStatesOf = (el: Element) => {
+    const states: Partial<Record<State, StyleSig>> = {};
+    for (const rule of stateRules) {
+      try {
+        if (el.matches(rule.base)) {
+          states[rule.state] = { ...states[rule.state], ...rule.style };
+        }
+      } catch {
+        // Selector the browser can't match on its own, such as a bare pseudo-element.
+      }
+    }
+    if (el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true') {
+      states.disabled = { ...states.disabled };
+    }
+    return Object.keys(states).length ? states : undefined;
+  };
+
+  const record = (el: Element, hint: Hint, rect: Rect) => {
+    hinted.set(el, hint);
+    if (nodes.length >= maxNodes) {
+      return;
+    }
+    const node: StructureNode = {
+      selector: selectorOf(el),
+      label: labelOf(el),
+      hint,
+      region: regionOf(el),
+      tag: el.tagName.toLowerCase(),
+      rect,
+      shape: shapeOf(el, 3),
+      columns: columnsOf(el),
+      style: styleOf(el),
+      headings: Array.from(el.querySelectorAll('h1, h2, h3, h4, h5, h6'))
+        .slice(0, 3)
+        .map((h) => textOf(h)),
+      buttons: Array.from(
+        el.querySelectorAll('button, a[class*="button"], a[class*="btn"], .wp-block-button__link')
+      )
+        .slice(0, 3)
+        .map((b) => textOf(b, 40)),
+      images: imagesOf(el),
+    };
+    const text = textOf(el);
+    if (text) {
+      node.text = text;
+    }
+    if (el.querySelector('svg, i[class*="icon"], i[class*="fa-"], [class*="dashicons"]')) {
+      node.icon = true;
+    }
+    if (el.hasAttribute('open') || el.querySelector('[aria-expanded="true"]')) {
+      node.open = true;
+    }
+    if (
+      [
+        'button',
+        'link',
+        'nav-item',
+        'input',
+        'badge',
+        'pagination',
+        'breadcrumbs',
+        'tabs',
+        'accordion',
+      ].includes(hint)
+    ) {
+      const states = cssStatesOf(el);
+      if (states) {
+        node.states = states;
+      }
+    }
+    nodes.push(node);
+  };
+
+  // Pass 1: regions and single UI elements, in document order.
+  const all = document.body ? Array.from(document.body.querySelectorAll('*')) : [];
+  for (const el of all) {
+    if (!visible(el) || el.closest('[hidden], [aria-hidden="true"]')) {
+      continue;
+    }
+    const rect = rectOf(el);
+    if (rect.w < 1 || rect.h < 1) {
+      continue;
+    }
+    const hint = hintOf(el, rect);
+    if (!hint) {
+      continue;
+    }
+    const singular = [
+      'header',
+      'footer',
+      'sidebar',
+      'card',
+      'slider',
+      'tabs',
+      'accordion',
+      'breadcrumbs',
+      'pagination',
+      'form',
+    ];
+    if (singular.includes(hint) && !outermost(el, hint)) {
+      continue;
+    }
+    record(el, hint, rect);
+  }
+
+  // Pass 2: page sections. Descend from main (or the body) through single
+  // wrappers; the stacked children found there are the sections. Widths are
+  // measured against the content column, so sections inside a narrow main
+  // with a sidebar still count. Tall sections that are stacks of substantial
+  // rows are opened up; long articles made of short rows are not.
+  const significant = (el: Element) =>
+    Array.from(el.children).filter((c) => {
+      if (!visible(c) || ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE'].includes(c.tagName)) {
+        return false;
+      }
+      const r = c.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    });
+  const isPart = (el: Element) => ['header', 'footer', 'sidebar'].includes(hinted.get(el) ?? '');
+  const main = document.querySelector('main');
+  const column = main ? main.getBoundingClientRect().width || vw : vw;
+  const qualifies = (el: Element) => {
+    const r = el.getBoundingClientRect();
+    return r.width >= column * 0.6 && r.height >= 80;
+  };
+  let root: Element | null = main ?? document.body;
+  while (root) {
+    const kids: Element[] = significant(root).filter((c) => !isPart(c));
+    // Stop at a single child that is itself the section rather than a wrapper of sections.
+    if (kids.length !== 1 || !significant(kids[0]).some(qualifies)) {
+      break;
+    }
+    root = kids[0];
+  }
+  const viewportHeight = window.innerHeight || 900;
+  const addSections = (parent: Element, level: number) => {
+    for (const child of significant(parent)) {
+      if (isPart(child)) {
+        continue;
+      }
+      const rect = rectOf(child);
+      if (rect.w < column * 0.6 || rect.h < 80) {
+        continue;
+      }
+      const rows = significant(child).filter((c) => {
+        const r = c.getBoundingClientRect();
+        return r.width >= column * 0.6 && r.height >= 150;
+      });
+      if (
+        level < 2 &&
+        rect.h > viewportHeight * 2.5 &&
+        rows.length >= 2 &&
+        columnsOf(child) === 1
+      ) {
+        addSections(child, level + 1);
+        continue;
+      }
+      record(child, 'section', rect);
+    }
+  };
+  if (root) {
+    addSections(root, 0);
+  }
+
+  // Full-width bands outside main, such as a page banner between the header and the content.
+  if (main) {
+    const mainRect = rectOf(main);
+    for (
+      let path: Element = main;
+      path.parentElement && path.parentElement !== document.body;
+      path = path.parentElement
+    ) {
+      for (const sibling of significant(path.parentElement)) {
+        if (
+          sibling === path ||
+          isPart(sibling) ||
+          Array.from(hinted.keys()).some((h) => isPart(h) && sibling.contains(h))
+        ) {
+          continue;
+        }
+        const rect = rectOf(sibling);
+        const outside = rect.y + rect.h <= mainRect.y + 1 || rect.y >= mainRect.y + mainRect.h - 1;
+        if (outside && rect.w >= vw * 0.6 && rect.h >= 80) {
+          record(sibling, 'section', rect);
+        }
+      }
+    }
+  }
+
+  return {
+    finalUrl: window.location.href,
+    title: document.title,
+    bodyClasses: document.body ? Array.from(document.body.classList) : [],
+    docHeight: document.documentElement.scrollHeight,
+    nodes,
+  };
+}
+
+/**
+ * Runs inside the page: hides fixed overlays such as cookie banners, chat
+ * widgets and pop-ups, so they don't count as site components or cover
+ * screenshots. A fixed header (or a full-width bar at the top) is kept.
+ * Returns how many elements were hidden.
+ */
+export function hideOverlays(): number {
+  const vw = window.innerWidth;
+  let hidden = 0;
+  for (const el of Array.from(document.body ? document.body.querySelectorAll('*') : [])) {
+    const style = window.getComputedStyle(el);
+    if (style.position !== 'fixed' || style.display === 'none') {
+      continue;
+    }
+    const rect = el.getBoundingClientRect();
+    const header =
+      el.closest('header') ||
+      el.querySelector('header, nav') ||
+      (rect.top <= 1 && rect.width >= vw * 0.9 && rect.height <= 200);
+    if (!header) {
+      (el as HTMLElement).style.setProperty('display', 'none', 'important');
+      hidden++;
+    }
+  }
+  return hidden;
+}
+
+/** Runs inside the page: the computed style of one element, for state diffs. */
+export function readElementStyle(selector: string): StyleSig | null {
+  const el = document.querySelector(selector);
+  if (!el) {
+    return null;
+  }
+  const s = window.getComputedStyle(el);
+  const sig: StyleSig = { color: s.color };
+  if (s.backgroundColor && s.backgroundColor !== 'rgba(0, 0, 0, 0)') {
+    sig.background = s.backgroundColor;
+  }
+  if (parseFloat(s.borderTopWidth) > 0) {
+    sig.border = s.borderTopColor;
+  }
+  if (s.boxShadow && s.boxShadow !== 'none') {
+    sig.shadow = s.boxShadow;
+  }
+  const decoration = s.textDecorationLine || (s.textDecoration ?? '').split(' ')[0];
+  if (decoration && decoration !== 'none') {
+    sig.textDecoration = decoration;
+  }
+  const opacity = Number(s.opacity);
+  if (Number.isFinite(opacity) && opacity !== 1) {
+    sig.opacity = opacity;
+  }
+  return sig;
+}
+
+/** The properties that changed between two styles, or undefined when none did. */
+export function styleDiff(before: StyleSig, after: StyleSig): StyleSig | undefined {
+  const diff: StyleSig = {};
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]) as Set<keyof StyleSig>;
+  for (const key of keys) {
+    if (before[key] !== after[key] && after[key] !== undefined) {
+      (diff as Record<string, unknown>)[key] = after[key];
+    }
+  }
+  return Object.keys(diff).length ? diff : undefined;
+}
+
+export interface PageHandle {
+  collect: () => Promise<CollectedStructure>;
+  /** Hovers or focuses the element and returns its style; never clicks. */
+  styleIn: (selector: string, state: 'hover' | 'focus' | 'none') => Promise<StyleSig | null>;
+  screenshot: (path: string, selector?: string) => Promise<boolean>;
+  close: () => Promise<void>;
+}
+
+export interface BrowserDriver {
+  open: (url: string, viewport: number) => Promise<PageHandle>;
+  close: () => Promise<void>;
+}
+
+export interface CrawlOptions {
+  site: string;
+  pages: string[];
+  viewports?: number[];
+  delayMs?: number;
+  maxPages?: number;
+  /** Folder for full-page screenshots; none are taken when unset. */
+  shotsDir?: string;
+  /** Distinct components per page whose hover and focus are triggered. 0 turns it off. */
+  maxStateSamples?: number;
+}
+
+export interface ShootTarget {
+  id: string;
+  url: string;
+  viewport: number;
+  selector: string;
+}
+
+const FORBIDDEN_PATH =
+  /\/(wp-admin|wp-login\.php|login|log-in|signin|sign-in|account|my-account|cart|basket|checkout)(\/|$|\?)/i;
+const STATE_HINTS = new Set<Hint>(['button', 'link', 'nav-item', 'input', 'badge']);
+
+export class StructureCrawler {
+  constructor(
+    private readonly driver: BrowserDriver,
+    private readonly sleep: (ms: number) => Promise<void>,
+    private readonly now: () => Date = () => new Date()
+  ) {}
+
+  async crawl(options: CrawlOptions): Promise<SiteStructure> {
+    const site = new URL(options.site);
+    const viewports = options.viewports ?? [390, 1440];
+    const urls = this.resolvePages(site, options.pages, options.maxPages ?? 15);
+    const pages: PageStructure[] = [];
+    const failures: { url: string; viewport: number; error: string }[] = [];
+    let first = true;
+
+    try {
+      for (const url of urls) {
+        for (const viewport of viewports) {
+          if (!first) {
+            await this.sleep(options.delayMs ?? 1500);
+          }
+          first = false;
+          let page: PageHandle | undefined;
+          try {
+            page = await this.driver.open(url, viewport);
+            const collected = await page.collect();
+            await this.triggerStates(page, collected, options.maxStateSamples ?? 30);
+            const capture: PageStructure = { url, viewport, ...collected };
+            if (options.shotsDir) {
+              const file = `${StructureCrawler.slugOf(url)}-${viewport}.png`;
+              if (await page.screenshot(join(options.shotsDir, file))) {
+                capture.screenshot = file;
+              }
+            }
+            pages.push(capture);
+          } catch (error) {
+            failures.push({ url, viewport, error: (error as Error).message });
+          } finally {
+            await page?.close();
+          }
+        }
+      }
+    } finally {
+      await this.driver.close();
+    }
+
+    return {
+      site: site.origin,
+      capturedAt: this.now().toISOString(),
+      viewports,
+      pages,
+      ...(failures.length ? { failures } : {}),
+    };
+  }
+
+  /** Takes one screenshot per target element, grouped so each page opens once. */
+  async shoot(
+    site: string,
+    targets: ShootTarget[],
+    shotsDir: string,
+    delayMs = 1500
+  ): Promise<string[]> {
+    const origin = new URL(site);
+    const written: string[] = [];
+    const groups = new Map<string, ShootTarget[]>();
+    for (const target of targets) {
+      this.resolvePages(origin, [target.url], Number.POSITIVE_INFINITY);
+      const key = `${target.url}@${target.viewport}`;
+      groups.set(key, [...(groups.get(key) ?? []), target]);
+    }
+    let first = true;
+    try {
+      for (const group of groups.values()) {
+        if (!first) {
+          await this.sleep(delayMs);
+        }
+        first = false;
+        const page = await this.driver.open(group[0].url, group[0].viewport);
+        try {
+          for (const target of group) {
+            const file = `${target.id.replace(/[^a-z0-9-]+/gi, '-')}-${target.viewport}.png`;
+            if (await page.screenshot(join(shotsDir, file), target.selector)) {
+              written.push(file);
+            }
+          }
+        } finally {
+          await page.close();
+        }
+      }
+    } finally {
+      await this.driver.close();
+    }
+    return written;
+  }
+
+  /** Hovers and focuses one example of each distinct interactive element and records what changes. */
+  async triggerStates(
+    page: PageHandle,
+    collected: CollectedStructure,
+    limit: number
+  ): Promise<void> {
+    const seen = new Set<string>();
+    for (const node of collected.nodes) {
+      if (seen.size >= limit) {
+        break;
+      }
+      const key = `${node.hint}|${node.label}`;
+      if (!STATE_HINTS.has(node.hint) || seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      const base = await page.styleIn(node.selector, 'none');
+      if (!base) {
+        continue;
+      }
+      for (const state of ['hover', 'focus'] as const) {
+        if (state === 'focus' && node.hint === 'badge') {
+          continue;
+        }
+        // What the browser shows wins over CSS rules, which ignore specificity.
+        const after = await page.styleIn(node.selector, state);
+        const diff = after ? styleDiff(base, after) : undefined;
+        const states = { ...node.states };
+        if (diff) {
+          states[state] = diff;
+        } else {
+          delete states[state];
+        }
+        node.states = Object.keys(states).length ? states : undefined;
+      }
+      node.stateSource = 'browser';
+    }
+  }
+
+  /** Resolves page paths against the site, and refuses other origins and private pages. */
+  resolvePages(site: URL, pages: string[], maxPages: number): string[] {
+    const urls = [...new Set((pages.length ? pages : ['/']).map((p) => new URL(p, site).href))];
+    for (const url of urls) {
+      const parsed = new URL(url);
+      if (parsed.origin !== site.origin) {
+        throw new Error(`${url} is not on ${site.origin}. Crawl one site at a time.`);
+      }
+      if (FORBIDDEN_PATH.test(parsed.pathname + parsed.search)) {
+        throw new Error(
+          `${url} looks like a login, account or checkout page. Crawl public pages only.`
+        );
+      }
+    }
+    if (urls.length > maxPages) {
+      throw new Error(
+        `${urls.length} pages requested; the limit is ${maxPages}. Raise --max-pages if needed.`
+      );
+    }
+    return urls;
+  }
+
+  static slugOf(url: string): string {
+    const parsed = new URL(url);
+    const path = (parsed.pathname + parsed.search).replace(/^\/|\/$/g, '');
+    return path
+      ? path
+          .replace(/[^a-z0-9]+/gi, '-')
+          .replace(/^-|-$/g, '')
+          .toLowerCase()
+      : 'home';
+  }
+}
+
+export interface CrawlCliDeps {
+  createDriver: () => Promise<BrowserDriver>;
+  sleep: (ms: number) => Promise<void>;
+  readFile: (path: string) => string;
+  writeFile: (path: string, content: string) => void;
+  makeDir: (path: string) => void;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+}
+
+const USAGE =
+  'Usage: crawl-site-structure --url https://www.example.com [--pages /,/about] [--out site-structure.json] [--shots shots] [--delay 1500] [--max-pages 15] [--viewports 390,1440] [--states 30]\n' +
+  '       crawl-site-structure --url https://www.example.com --shoot inventory.json --shots shots\n';
+
+export async function runCrawlCli(argv: string[], deps: CrawlCliDeps): Promise<number> {
+  const values: Record<string, string> = {
+    pages: '/',
+    out: 'site-structure.json',
+    delay: '1500',
+    'max-pages': '15',
+    viewports: '390,1440',
+    states: '30',
+  };
+  const optional = ['url', 'shots', 'shoot'];
+
+  try {
+    for (let i = 0; i < argv.length; i++) {
+      const arg = argv[i];
+      if (arg === '--help' || arg === '-h') {
+        deps.stdout(USAGE);
+        return 0;
+      }
+      const key = arg.replace(/^--/, '');
+      if (!arg.startsWith('--') || ![...optional, ...Object.keys(values)].includes(key)) {
+        throw new Error(`Unknown argument ${arg}.`);
+      }
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error(`${arg} needs a value.`);
+      }
+      values[key] = value;
+    }
+    if (!values.url) {
+      throw new Error('--url is required.');
+    }
+    if (values.shots) {
+      deps.makeDir(values.shots);
+    }
+
+    const crawler = new StructureCrawler(await deps.createDriver(), deps.sleep);
+    if (values.shoot) {
+      if (!values.shots) {
+        throw new Error('--shoot needs --shots, the folder to write screenshots to.');
+      }
+      const inventory = JSON.parse(deps.readFile(values.shoot)) as {
+        items: {
+          id: string;
+          status?: string;
+          examples: { url: string; viewport: number; selector: string }[];
+        }[];
+      };
+      const targets: ShootTarget[] = inventory.items
+        .filter((item) => item.status !== 'cut')
+        .flatMap((item) => item.examples.slice(0, 1).map((e) => ({ id: item.id, ...e })));
+      const written = await crawler.shoot(values.url, targets, values.shots, Number(values.delay));
+      deps.stdout(
+        `Wrote ${written.length} of ${targets.length} example screenshots to ${values.shots}\n`
+      );
+      return 0;
+    }
+
+    const result = await crawler.crawl({
+      site: values.url,
+      pages: values.pages
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean),
+      viewports: values.viewports.split(',').map(Number),
+      delayMs: Number(values.delay),
+      maxPages: Number(values['max-pages']),
+      shotsDir: values.shots,
+      maxStateSamples: Number(values.states),
+    });
+    deps.writeFile(values.out, `${JSON.stringify(result, null, 2)}\n`);
+    const count = result.pages.reduce((total, p) => total + p.nodes.length, 0);
+    deps.stdout(
+      `Captured ${result.pages.length} page views and ${count} building blocks into ${values.out}\n`
+    );
+    for (const f of result.failures ?? []) {
+      deps.stderr(`Skipped ${f.url} at ${f.viewport}px: ${f.error}\n`);
+    }
+    return 0;
+  } catch (error) {
+    deps.stderr(`crawl-site-structure: ${(error as Error).message}\n`);
+    return 1;
+  }
+}
+
+/* istanbul ignore next -- Puppeteer driver, exercised by live runs */
+export async function createPuppeteerDriver(): Promise<BrowserDriver> {
+  const puppeteer = (await import('puppeteer')).default;
+  const browser = await puppeteer.launch({ headless: true });
+  return {
+    open: async (url, viewport) => {
+      const page = await browser.newPage();
+      await page.setViewport({ width: viewport, height: 900 });
+      await page.goto(url, { waitUntil: 'load', timeout: 60000 });
+      // Pages with polling or live chat never go idle; give them a short, optional wait.
+      await page.waitForNetworkIdle({ idleTime: 500, timeout: 15000 }).catch(() => undefined);
+      // tsx (esbuild) can add __name() helpers to function source; define it in the page.
+      await page.evaluate('globalThis.__name = (f) => f');
+      await page.evaluate(hideOverlays);
+      const reset = async () => {
+        await page.mouse.move(0, 0);
+        await page.evaluate(() => (document.activeElement as HTMLElement | null)?.blur());
+      };
+      return {
+        collect: () => page.evaluate(collectPageStructure, {}),
+        styleIn: async (selector, state) => {
+          try {
+            await reset();
+            if (state === 'hover') {
+              await page.hover(selector);
+            } else if (state === 'focus') {
+              await page.focus(selector);
+            }
+            return await page.evaluate(readElementStyle, selector);
+          } catch {
+            return null; // Covered, off-screen or detached element.
+          }
+        },
+        screenshot: async (path, selector) => {
+          try {
+            if (selector) {
+              const handle = await page.$(selector);
+              if (!handle) {
+                return false;
+              }
+              await handle.screenshot({ path });
+            } else {
+              await page.screenshot({ path, fullPage: true });
+            }
+            return true;
+          } catch {
+            return false;
+          }
+        },
+        close: () => page.close(),
+      };
+    },
+    close: () => browser.close(),
+  };
+}
+
+/* istanbul ignore next -- thin CLI entry point */
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCrawlCli(process.argv.slice(2), {
+    createDriver: createPuppeteerDriver,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    readFile: (path) => readFileSync(path, 'utf8'),
+    writeFile: (path, content) => writeFileSync(path, content),
+    makeDir: (path) => mkdirSync(path, { recursive: true }),
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+  }).then((code) => {
+    process.exitCode = code;
+  });
+}
diff --git a/skills/site-to-figma-components/scripts/jest.config.cjs b/skills/site-to-figma-components/scripts/jest.config.cjs
new file mode 100644
index 0000000000..dad438f081
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/jest.config.cjs
@@ -0,0 +1,28 @@
+/**
+ * Jest configuration for the site-to-figma-components helper scripts.
+ *
+ * Extends the repository config, scopes the run to this skill and enforces
+ * 80% coverage on every metric. Run from the repository root:
+ *   npm run test:site-to-figma-components
+ */
+const base = require('../../../.jest.config.cjs');
+
+const skillDir = '<rootDir>/skills/site-to-figma-components/scripts';
+
+module.exports = {
+  ...base,
+  rootDir: '../../..',
+  testEnvironment: 'node',
+  testMatch: [`${skillDir}/__tests__/**/*.test.ts`],
+  collectCoverage: true,
+  collectCoverageFrom: [`${skillDir}/**/*.ts`, '!**/__tests__/**'],
+  coverageDirectory: '<rootDir>/coverage/site-to-figma-components',
+  coverageThreshold: {
+    global: {
+      statements: 80,
+      branches: 80,
+      functions: 80,
+      lines: 80,
+    },
+  },
+};
diff --git a/skills/site-to-figma-components/scripts/lib/color.ts b/skills/site-to-figma-components/scripts/lib/color.ts
new file mode 100644
index 0000000000..b8d32fe409
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/lib/color.ts
@@ -0,0 +1,93 @@
+/**
+ * Colour helpers for matching live CSS colours to Figma colour variables.
+ */
+
+export interface Rgba {
+  /** Channels from 0 to 1, as Figma stores them. */
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export class Colour {
+  /** Parses #rgb, #rrggbb, #rrggbbaa, rgb() and rgba(), in comma or space syntax. Returns null otherwise. */
+  static parse(value: string | undefined): Rgba | null {
+    if (!value) {
+      return null;
+    }
+    const text = value.trim().toLowerCase();
+    const hex = text.match(/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/);
+    if (hex) {
+      const digits =
+        hex[1].length === 3
+          ? hex[1]
+              .split('')
+              .map((d) => d + d)
+              .join('')
+          : hex[1];
+      const channel = (i: number) => parseInt(digits.slice(i, i + 2), 16) / 255;
+      return {
+        r: channel(0),
+        g: channel(2),
+        b: channel(4),
+        a: digits.length === 8 ? channel(6) : 1,
+      };
+    }
+    const fn = text.match(/^rgba?\(([^)]+)\)$/);
+    if (!fn) {
+      return null;
+    }
+    const parts = fn[1].split(/[\s,/]+/).filter(Boolean);
+    if (parts.length < 3) {
+      return null;
+    }
+    const [r, g, b] = parts.slice(0, 3).map(Number);
+    const alpha =
+      parts[3] === undefined
+        ? 1
+        : parts[3].endsWith('%')
+          ? parseFloat(parts[3]) / 100
+          : Number(parts[3]);
+    if ([r, g, b, alpha].some((n) => !Number.isFinite(n))) {
+      return null;
+    }
+    return { r: r / 255, g: g / 255, b: b / 255, a: alpha };
+  }
+
+  /** A Figma colour value, or null when the value is not one. */
+  static fromFigma(value: unknown): Rgba | null {
+    if (!value || typeof value !== 'object') {
+      return null;
+    }
+    const v = value as Partial<Rgba>;
+    if (typeof v.r !== 'number' || typeof v.g !== 'number' || typeof v.b !== 'number') {
+      return null;
+    }
+    return { r: v.r, g: v.g, b: v.b, a: typeof v.a === 'number' ? v.a : 1 };
+  }
+
+  static hex(c: Rgba): string {
+    const byte = (n: number) =>
+      Math.round(Math.min(1, Math.max(0, n)) * 255)
+        .toString(16)
+        .padStart(2, '0');
+    return `#${byte(c.r)}${byte(c.g)}${byte(c.b)}${c.a < 1 ? byte(c.a) : ''}`;
+  }
+
+  /** Distance on a 0 to 255 scale per channel, alpha included. */
+  static distance(a: Rgba, b: Rgba): number {
+    return Math.sqrt(
+      ((a.r - b.r) * 255) ** 2 +
+        ((a.g - b.g) * 255) ** 2 +
+        ((a.b - b.b) * 255) ** 2 +
+        ((a.a - b.a) * 255) ** 2
+    );
+  }
+
+  /** WCAG relative luminance, from 0 (black) to 1 (white). */
+  static luminance(c: Rgba): number {
+    const lin = (n: number) => (n <= 0.03928 ? n / 12.92 : ((n + 0.055) / 1.055) ** 2.4);
+    return 0.2126 * lin(c.r) + 0.7152 * lin(c.g) + 0.0722 * lin(c.b);
+  }
+}
diff --git a/skills/site-to-figma-components/scripts/lib/tokens.ts b/skills/site-to-figma-components/scripts/lib/tokens.ts
new file mode 100644
index 0000000000..05f669bd56
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/lib/tokens.ts
@@ -0,0 +1,274 @@
+/**
+ * Indexes a Figma variables export (the shape figma-to-block-theme reads, and
+ * site-to-design-tokens writes) so live values can be bound to variables.
+ *
+ * Semantic tokens win over primitives. A value that only matches a primitive
+ * is returned with `semantic: false`, so the report can list it for review.
+ */
+
+import { Colour, Rgba } from './color';
+
+export interface ExportVariable {
+  id: string;
+  name: string;
+  type: string;
+  codeSyntax?: { WEB?: string };
+  valuesByMode: Record<string, unknown>;
+}
+
+export interface ExportCollection {
+  name: string;
+  modes: { id: string; name: string }[];
+  variables: ExportVariable[];
+}
+
+export interface ExportEffect {
+  type: string;
+  color?: Partial<Rgba>;
+  offset?: { x: number; y: number };
+  radius?: number;
+  spread?: number;
+}
+
+export interface VariablesExport {
+  collections: ExportCollection[];
+  effectStyles?: { name: string; description?: string; effects: ExportEffect[] }[];
+}
+
+export type ColourRole = 'text' | 'fill' | 'stroke';
+export type SizeFamily = 'spacing' | 'radius' | 'font-size';
+
+export interface TokenMatch {
+  variable: string;
+  collection: string;
+  codeSyntax?: string;
+  match: 'exact' | 'near';
+  semantic: boolean;
+}
+
+interface Entry<T> {
+  variable: ExportVariable;
+  collection: string;
+  value: T;
+  semantic: boolean;
+}
+
+const ROLE_PREFIX: Record<ColourRole, RegExp> = {
+  text: /^text\//i,
+  fill: /^surface\//i,
+  stroke: /^border\//i,
+};
+const ACTION_PREFIX: Record<ColourRole, RegExp> = {
+  text: /^action\/[^/]+\/text$/i,
+  fill: /^action\/[^/]+\/background$/i,
+  stroke: /^border\/focus/i,
+};
+
+export class TokenIndex {
+  private readonly colours: Entry<Rgba>[] = [];
+  private readonly sizes: Record<SizeFamily, Entry<number>[]> = {
+    spacing: [],
+    radius: [],
+    'font-size': [],
+  };
+  private readonly fonts: Entry<string>[] = [];
+  private readonly shadows: { name: string; effect: ExportEffect }[] = [];
+
+  /**
+   * @param exclude Collections to ignore, by name. Prototype-only collections are skipped by default.
+   */
+  constructor(data: VariablesExport = { collections: [] }, exclude: RegExp = /^proto(type)?\b/i) {
+    const byId = new Map<string, { variable: ExportVariable; collection: ExportCollection }>();
+    for (const collection of data.collections) {
+      for (const variable of collection.variables) {
+        byId.set(variable.id, { variable, collection });
+      }
+    }
+    const resolve = (
+      variable: ExportVariable,
+      collection: ExportCollection,
+      depth = 0
+    ): unknown => {
+      const mode = collection.modes.find((m) => /^max$/i.test(m.name)) ?? collection.modes[0];
+      const value = mode ? variable.valuesByMode[mode.id] : Object.values(variable.valuesByMode)[0];
+      if (
+        value &&
+        typeof value === 'object' &&
+        (value as { type?: string }).type === 'VARIABLE_ALIAS'
+      ) {
+        const target = byId.get((value as { id: string }).id);
+        return target && depth < 10
+          ? resolve(target.variable, target.collection, depth + 1)
+          : undefined;
+      }
+      return value;
+    };
+
+    for (const collection of data.collections) {
+      if (!collection.modes.length || exclude.test(collection.name)) {
+        continue; // Library alias holders and prototype collections are not bound to.
+      }
+      for (const variable of collection.variables) {
+        const value = resolve(variable, collection);
+        // Only colours have a primitive and a semantic tier.
+        const semantic = variable.type !== 'COLOR' || /semantic/i.test(collection.name);
+        const entry = { variable, collection: collection.name, semantic };
+        if (variable.type === 'COLOR') {
+          const rgba = Colour.fromFigma(value);
+          if (rgba) {
+            this.colours.push({ ...entry, value: rgba });
+          }
+        } else if (variable.type === 'FLOAT' && typeof value === 'number') {
+          const family = TokenIndex.familyOf(collection.name, variable.name);
+          if (family) {
+            this.sizes[family].push({ ...entry, value });
+          }
+        } else if (
+          variable.type === 'STRING' &&
+          typeof value === 'string' &&
+          /famil/i.test(variable.name)
+        ) {
+          this.fonts.push({ ...entry, value });
+        }
+      }
+    }
+    for (const style of data.effectStyles ?? []) {
+      const effect = style.effects.find((e) => e.type === 'DROP_SHADOW');
+      if (effect) {
+        this.shadows.push({ name: style.name, effect });
+      }
+    }
+  }
+
+  static familyOf(collection: string, name: string): SizeFamily | undefined {
+    // Spacing collections, and component spacing kept elsewhere (Spacing/Button/Medium/Gap).
+    if (/spacing/i.test(collection) || /(^|\/)(spacing|padding|gap)(\/|$)/i.test(name)) {
+      return 'spacing';
+    }
+    if (/radius/i.test(collection)) {
+      return 'radius';
+    }
+    if (/typograph/i.test(collection) && /^sizes?\//i.test(name)) {
+      return 'font-size';
+    }
+    return undefined;
+  }
+
+  get size(): number {
+    return (
+      this.colours.length +
+      Object.values(this.sizes).reduce((n, list) => n + list.length, 0) +
+      this.fonts.length
+    );
+  }
+
+  /**
+   * @param action Prefer action tokens (buttons), otherwise text, surface and border tokens come first.
+   */
+  colour(value: string | undefined, role: ColourRole, action = false): TokenMatch | undefined {
+    const rgba = Colour.parse(value);
+    if (!rgba) {
+      return undefined;
+    }
+    const fit = (name: string) => {
+      const plain = ROLE_PREFIX[role].test(name);
+      const act = ACTION_PREFIX[role].test(name);
+      return action ? (act ? 2 : plain ? 1 : 0) : plain ? 2 : act ? 1 : 0;
+    };
+    const ranked = this.colours
+      .map((entry) => ({ entry, distance: Colour.distance(rgba, entry.value) }))
+      .filter((c) => c.distance <= 12)
+      .sort(
+        (a, b) =>
+          Number(b.entry.semantic) - Number(a.entry.semantic) ||
+          Math.round(a.distance / 3) - Math.round(b.distance / 3) ||
+          fit(b.entry.variable.name) - fit(a.entry.variable.name) ||
+          a.distance - b.distance
+      );
+    const best = ranked[0];
+    return best ? this.matchOf(best.entry, best.distance <= 2) : undefined;
+  }
+
+  length(px: number | undefined, family: SizeFamily): TokenMatch | undefined {
+    if (px === undefined || px <= 0) {
+      return undefined;
+    }
+    const best = this.sizes[family]
+      .map((entry) => ({ entry, distance: Math.abs(entry.value - px) }))
+      .sort((a, b) => a.distance - b.distance)[0];
+    if (!best || best.distance > Math.max(2, px * 0.08)) {
+      return undefined;
+    }
+    return this.matchOf(best.entry, best.distance <= 0.5);
+  }
+
+  /** The variables either side of a size with no match, for proposing a new ramp step. */
+  neighbours(px: number, family: SizeFamily): { below?: string; above?: string } {
+    const sorted = [...this.sizes[family]].sort((a, b) => a.value - b.value);
+    return {
+      below: [...sorted].reverse().find((e) => e.value < px)?.variable.name,
+      above: sorted.find((e) => e.value > px)?.variable.name,
+    };
+  }
+
+  font(family: string | undefined): TokenMatch | undefined {
+    if (!family) {
+      return undefined;
+    }
+    const norm = (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+    const target = norm(family);
+    const entry =
+      this.fonts.find((f) => norm(f.value) === target) ??
+      this.fonts.find((f) => target.includes(norm(f.value)) || norm(f.value).includes(target));
+    return entry ? this.matchOf(entry, norm(entry.value) === target) : undefined;
+  }
+
+  /** Matches the first layer of a CSS box-shadow to a drop shadow effect style. */
+  shadow(css: string | undefined): TokenMatch | undefined {
+    const parsed = TokenIndex.parseShadow(css);
+    if (!parsed) {
+      return undefined;
+    }
+    const near = (a = 0, b = 0) => Math.abs(a - b) <= 1;
+    const found = this.shadows.find(
+      ({ effect }) =>
+        near(effect.offset?.x, parsed.x) &&
+        near(effect.offset?.y, parsed.y) &&
+        near(effect.radius, parsed.blur) &&
+        near(effect.spread, parsed.spread)
+    );
+    return found
+      ? { variable: found.name, collection: 'Effect styles', match: 'exact', semantic: true }
+      : undefined;
+  }
+
+  static parseShadow(
+    css: string | undefined
+  ): { x: number; y: number; blur: number; spread: number } | null {
+    if (!css || css === 'none') {
+      return null;
+    }
+    const first = css.split(/,(?![^(]*\))/)[0];
+    const lengths = first
+      .replace(/rgba?\([^)]*\)|#[0-9a-f]+|inset/gi, ' ')
+      .trim()
+      .split(/\s+/)
+      .map((n) => parseFloat(n))
+      .filter((n) => Number.isFinite(n));
+    if (lengths.length < 2) {
+      return null;
+    }
+    const [x, y, blur = 0, spread = 0] = lengths;
+    return { x, y, blur, spread };
+  }
+
+  private matchOf<T>(entry: Entry<T>, exact: boolean): TokenMatch {
+    return {
+      variable: entry.variable.name,
+      collection: entry.collection,
+      codeSyntax: entry.variable.codeSyntax?.WEB,
+      match: exact ? 'exact' : 'near',
+      semantic: entry.semantic,
+    };
+  }
+}
diff --git a/skills/site-to-figma-components/scripts/propose-inventory.ts b/skills/site-to-figma-components/scripts/propose-inventory.ts
new file mode 100644
index 0000000000..c6520f3d8f
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/propose-inventory.ts
@@ -0,0 +1,1509 @@
+/**
+ * Turns a site structure crawl into a component inventory for review:
+ * template parts, patterns, components (with variant properties and states)
+ * and templates, each mapped to its WordPress target and bound to the
+ * project's Figma variables. Writes the inventory JSON and a Markdown
+ * approval report. Reviewer decisions (rename, cut, merge, promote, approve)
+ * are applied from a decisions file on the next run.
+ *
+ * Usage:
+ *   npx tsx propose-inventory.ts site-structure.json --tokens variables.json \
+ *     --theme tsp-theme --out inventory.json --report inventory.md [--decisions decisions.json]
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import type {
+  Hint,
+  PageStructure,
+  SiteStructure,
+  StructureNode,
+  StyleSig,
+} from './crawl-site-structure';
+import { Colour } from './lib/color';
+import { ColourRole, SizeFamily, TokenIndex, TokenMatch, VariablesExport } from './lib/tokens';
+
+export type Kind = 'component' | 'pattern' | 'template-part' | 'template';
+
+export interface Example {
+  url: string;
+  viewport: number;
+  selector: string;
+  label: string;
+}
+
+export interface WpTarget {
+  type:
+    | 'core-block'
+    | 'block-style'
+    | 'element-style'
+    | 'pattern'
+    | 'template-part'
+    | 'template'
+    | 'custom-block'
+    | 'plugin-block';
+  block?: string;
+  slug?: string;
+  file?: string;
+  area?: string;
+  styles?: string[];
+  note?: string;
+}
+
+export interface Binding {
+  property: string;
+  value: string;
+  variable?: string;
+  codeSyntax?: string;
+  match: 'exact' | 'near' | 'primitive' | 'none';
+  /** For a size with no match: the ramp steps either side. */
+  between?: string[];
+}
+
+export interface Variant {
+  name: string;
+  properties: Record<string, string>;
+  count: number;
+  example: Example;
+  style: StyleSig;
+  bindings: Binding[];
+}
+
+export interface Content {
+  headings: string[];
+  buttons: string[];
+  images: { src: string; alt: string }[];
+  text?: string;
+}
+
+export interface InventoryItem {
+  id: string;
+  kind: Kind;
+  name: string;
+  /** Figma layer name, following the TSP file: `Components/Buttons/Button`. */
+  figmaName: string;
+  hint?: Hint;
+  count: number;
+  pages: string[];
+  templates: string[];
+  examples: Example[];
+  variantProperties: Record<string, string[]>;
+  variants: Variant[];
+  wordpress: WpTarget;
+  content: Content;
+  /** The 390px layout differs enough to need its own frame. */
+  mobileLayoutChanges?: boolean;
+  /** Region pieces that make up a template part, top to bottom. */
+  pieces?: string[];
+  /** Item ids for templates: what the template is built from, top to bottom. */
+  composition?: string[];
+  /** Near duplicates the reviewer may merge into this item. */
+  mergeWith?: string[];
+  oneOff?: boolean;
+  status: 'proposed' | 'cut';
+  /** A class name that helps recognise the item on the site. */
+  aka?: string;
+}
+
+export interface UnboundValue {
+  property: string;
+  value: string;
+  match: Binding['match'];
+  nearest?: string;
+  items: string[];
+  /** What to add or change so the value binds, for the reviewer to approve. */
+  proposal: string;
+}
+
+export interface Inventory {
+  site: string;
+  capturedAt: string;
+  theme: string;
+  tokensLoaded: boolean;
+  pages: { url: string; template: string; screenshots: string[] }[];
+  /** Requested pages that redirected to a page already crawled, and were left out. */
+  redirects: { from: string; to: string }[];
+  /** Page views the crawler could not capture. */
+  failures: { url: string; viewport: number; error: string }[];
+  items: InventoryItem[];
+  unbound: UnboundValue[];
+  decisions: string[];
+  approved: boolean;
+  approvedAt?: string;
+  /** Item ids the reviewer approved for the Figma build: chosen items and templates with everything they are built from. */
+  buildScope?: string[];
+}
+
+export interface Decisions {
+  rename?: Record<string, string>;
+  cut?: string[];
+  merge?: [string, string][];
+  promote?: string[];
+  /** Templates and items to build in Figma. Templates bring their parts and patterns with them. */
+  build?: string[];
+  approve?: boolean;
+}
+
+const COMPONENT_HINTS: Hint[] = [
+  'button',
+  'link',
+  'input',
+  'card',
+  'badge',
+  'nav-item',
+  'breadcrumbs',
+  'pagination',
+  'accordion',
+  'tabs',
+  'slider',
+  'form',
+];
+/** Hints that form one component family each; cards and forms cluster by shape instead. */
+const FAMILY_HINTS: Hint[] = [
+  'button',
+  'link',
+  'input',
+  'badge',
+  'nav-item',
+  'breadcrumbs',
+  'pagination',
+  'accordion',
+  'tabs',
+  'slider',
+];
+
+const FAMILY: Record<string, { name: string; group: string }> = {
+  button: { name: 'Button', group: 'Buttons' },
+  link: { name: 'Text Link', group: 'Links' },
+  input: { name: 'Input Field', group: 'Forms & Inputs' },
+  badge: { name: 'Badge', group: 'Badges' },
+  'nav-item': { name: 'Nav Item', group: 'Navigation' },
+  breadcrumbs: { name: 'Breadcrumbs', group: 'Navigation' },
+  pagination: { name: 'Pagination', group: 'Navigation' },
+  accordion: { name: 'Accordion', group: 'Accordions' },
+  tabs: { name: 'Tabs', group: 'Tabs' },
+  slider: { name: 'Slider', group: 'Sliders' },
+  card: { name: 'Card', group: 'Cards' },
+  form: { name: 'Form', group: 'Forms & Inputs' },
+};
+
+const PATTERN_BLOCK: Record<string, string> = {
+  Hero: 'core/cover',
+  Banner: 'core/cover',
+  'Call to Action': 'core/group',
+  'Card Grid': 'core/query',
+  Testimonials: 'core/quote',
+  Gallery: 'core/gallery',
+  'Media and Text': 'core/media-text',
+  'Feature Row': 'core/columns',
+  'Form Section': 'core/group',
+  'Section Heading': 'core/heading',
+  'Content Section': 'core/group',
+};
+
+export const kebab = (text: string): string =>
+  text
+    .toLowerCase()
+    .replace(/&/g, 'and')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+
+const title = (text: string): string =>
+  text
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(' ');
+
+export class TemplateClassifier {
+  /** Maps WordPress body classes (or, failing that, the URL) to a block theme template slug. */
+  static classify(bodyClasses: string[], url: string): { slug: string; name: string } {
+    const has = (c: string) => bodyClasses.includes(c);
+    const find = (prefix: string) =>
+      bodyClasses.find((c) => c.startsWith(prefix))?.slice(prefix.length);
+    let slug: string | undefined;
+    if (has('error404')) {
+      slug = '404';
+    } else if (has('search') || has('search-results') || has('search-no-results')) {
+      slug = 'search';
+    } else if (has('home') && has('blog')) {
+      slug = 'home';
+    } else if (has('home')) {
+      slug = 'front-page';
+    } else if (has('blog')) {
+      slug = 'home';
+    } else if (find('post-type-archive-')) {
+      slug = `archive-${find('post-type-archive-')}`;
+    } else if (find('tax-')) {
+      slug = `taxonomy-${find('tax-')}`;
+    } else if (has('category') || has('tag') || has('author')) {
+      slug = ['category', 'tag', 'author'].find(has)!;
+    } else if (has('page') && find('page-template-') && find('page-template-') !== 'default') {
+      slug = find('page-template-')!
+        .replace(/(-php|-html)$/, '')
+        .replace(/^templates?-/, '');
+    } else if (has('archive')) {
+      slug = 'archive';
+    } else if (has('single') || has('single-post')) {
+      // WordPress adds `{post_type}-template-default`; plugins may add other single-* classes.
+      const type = bodyClasses
+        .map((c) => c.match(/^([a-z0-9_-]+)-template(-default)?$/)?.[1])
+        .find((t) => t && t !== 'page');
+      slug = !type || type === 'post' ? 'single' : `single-${type}`;
+    } else if (has('page')) {
+      slug = 'page';
+    }
+    if (!slug) {
+      const path = new URL(url).pathname;
+      slug = path === '/' ? 'front-page' : 'index';
+    }
+    return { slug, name: TemplateClassifier.nameOf(slug) };
+  }
+
+  static nameOf(slug: string): string {
+    const archive = slug.match(/^archive-(.+)$/);
+    if (archive) {
+      return `${title(archive[1])} Archive`;
+    }
+    const tax = slug.match(/^taxonomy-(.+)$/);
+    if (tax) {
+      return `${title(tax[1])} Taxonomy`;
+    }
+    const single = slug.match(/^single-(.+)$/);
+    if (single) {
+      return `Single ${title(single[1])}`;
+    }
+    return (
+      { 'front-page': 'Front Page', home: 'Blog Home', single: 'Single Post', '404': '404' }[
+        slug
+      ] ?? title(slug)
+    );
+  }
+}
+
+export class StyleBinder {
+  constructor(private readonly tokens: TokenIndex) {}
+
+  /** Binds every styled value of a node to a variable, recording what could not be bound. */
+  bind(style: StyleSig, kind: Kind, hint?: Hint): Binding[] {
+    const out: Binding[] = [];
+    const action = hint === 'button';
+    const colour = (property: string, value: string | undefined, role: ColourRole) => {
+      if (!value || !Colour.parse(value)) {
+        return;
+      }
+      out.push(
+        this.result(
+          property,
+          Colour.hex(Colour.parse(value)!),
+          this.tokens.colour(value, role, action)
+        )
+      );
+    };
+    const length = (property: string, value: number | undefined, family: SizeFamily) => {
+      if (value === undefined || value <= 0) {
+        return;
+      }
+      const binding = this.result(
+        property,
+        `${Math.round(value * 100) / 100}px`,
+        this.tokens.length(value, family)
+      );
+      if (binding.match === 'none') {
+        const { below, above } = this.tokens.neighbours(value, family);
+        binding.between = [below, above].filter((n): n is string => !!n);
+      }
+      out.push(binding);
+    };
+    colour('fill', style.background, 'fill');
+    if (kind !== 'pattern' && kind !== 'template-part') {
+      colour('text', style.color, 'text');
+      if (style.fontFamily) {
+        out.push(this.result('fontFamily', style.fontFamily, this.tokens.font(style.fontFamily)));
+      }
+      length('fontSize', style.fontSize, 'font-size');
+    }
+    colour('stroke', style.border, 'stroke');
+    length('radius', style.radius, 'radius');
+    length('paddingBlock', style.paddingBlock, 'spacing');
+    length('paddingInline', style.paddingInline, 'spacing');
+    length('gap', style.gap, 'spacing');
+    if (style.shadow) {
+      out.push(this.result('effect', style.shadow, this.tokens.shadow(style.shadow)));
+    }
+    return out;
+  }
+
+  private result(property: string, value: string, match: TokenMatch | undefined): Binding {
+    if (!match) {
+      return { property, value, match: 'none' };
+    }
+    return {
+      property,
+      value,
+      variable: match.variable,
+      codeSyntax: match.codeSyntax,
+      match: match.semantic ? match.match : 'primitive',
+    };
+  }
+}
+
+interface Located {
+  page: PageStructure;
+  node: StructureNode;
+}
+
+export class InventoryProposer {
+  private readonly binder: StyleBinder;
+
+  constructor(
+    private readonly tokens: TokenIndex,
+    private readonly theme: string
+  ) {
+    this.binder = new StyleBinder(tokens);
+  }
+
+  propose(structure: SiteStructure): Inventory {
+    const desktopWidth = Math.max(...structure.viewports);
+    const mobileWidth = Math.min(...structure.viewports);
+    const { kept: desktop, redirects } = InventoryProposer.dedupe(
+      structure.pages.filter((p) => p.viewport === desktopWidth)
+    );
+    const mobileByUrl = new Map(
+      structure.pages
+        .filter((p) => p.viewport === mobileWidth && mobileWidth !== desktopWidth)
+        .map((p) => [p.url, p])
+    );
+    const templateOf = new Map(
+      desktop.map((p) => [p.url, TemplateClassifier.classify(p.bodyClasses, p.url)])
+    );
+    const mobileOf = ({ page, node }: Located) =>
+      mobileByUrl.get(page.url)?.nodes.find((n) => n.selector === node.selector);
+
+    const items: InventoryItem[] = [
+      ...this.parts(desktop, templateOf, mobileOf),
+      ...this.components(desktop, templateOf, mobileOf),
+    ];
+    const { patterns, sectionOwner } = this.patterns(desktop, templateOf, mobileOf, items);
+    items.push(...patterns);
+    items.push(...this.templates(desktop, templateOf, sectionOwner, items));
+
+    return {
+      site: structure.site,
+      capturedAt: structure.capturedAt,
+      theme: this.theme,
+      tokensLoaded: this.tokens.size > 0,
+      pages: desktop.map((p) => ({
+        url: p.url,
+        template: templateOf.get(p.url)!.slug,
+        screenshots: structure.pages
+          .filter((q) => q.url === p.url && q.screenshot)
+          .map((q) => q.screenshot!),
+      })),
+      redirects,
+      failures: structure.failures ?? [],
+      items,
+      unbound: InventoryProposer.unbound(items),
+      decisions: [],
+      approved: false,
+    };
+  }
+
+  /** Keeps the first capture of each final URL, so redirects don't count as extra pages. */
+  static dedupe(pages: PageStructure[]): {
+    kept: PageStructure[];
+    redirects: { from: string; to: string }[];
+  } {
+    const norm = (u: string) => u.replace(/#.*$/, '').replace(/\/(\?|$)/, '$1');
+    const keptUrls = new Set(pages.map((p) => norm(p.url)));
+    const kept: PageStructure[] = [];
+    const redirects: { from: string; to: string }[] = [];
+    const finals = new Set<string>();
+    for (const page of pages) {
+      const final = norm(page.finalUrl ?? page.url);
+      const moved = final !== norm(page.url);
+      if (moved && (keptUrls.has(final) || finals.has(final))) {
+        redirects.push({ from: page.url, to: page.finalUrl! });
+        continue;
+      }
+      finals.add(final);
+      kept.push(page);
+    }
+    return { kept, redirects };
+  }
+
+  private parts(
+    pages: PageStructure[],
+    templateOf: Map<string, { slug: string }>,
+    mobileOf: (l: Located) => StructureNode | undefined
+  ): InventoryItem[] {
+    const out: InventoryItem[] = [];
+    for (const hint of ['header', 'footer', 'sidebar'] as Hint[]) {
+      const found = pages
+        .map((page) => ({ page, nodes: page.nodes.filter((n) => n.hint === hint) }))
+        .filter((f) => f.nodes.length);
+      if (!found.length) {
+        continue;
+      }
+      const presence = found.length / pages.length;
+      const name = title(hint);
+      const located = found.map((f) => ({ page: f.page, node: f.nodes[0] }));
+      const modeOf = (l: Located) => InventoryProposer.mode(l.node.style);
+      const variants = this.variantsOf(located, (l) => ({ Mode: modeOf(l) }), 'template-part');
+      const changes = located.some((l) => {
+        const m = mobileOf(l);
+        return !!m && (m.shape !== l.node.shape || m.columns !== l.node.columns);
+      });
+      const properties = InventoryProposer.properties(
+        variants,
+        changes ? { Breakpoint: ['Desktop', 'Mobile'] } : {}
+      );
+      const slug = kebab(hint);
+      out.push({
+        id: `part:${slug}`,
+        kind: 'template-part',
+        name,
+        figmaName: `Template Parts/${name}`,
+        hint,
+        count: found.length,
+        pages: found.map((f) => f.page.url),
+        templates: [...new Set(found.map((f) => templateOf.get(f.page.url)!.slug))],
+        examples: located.slice(0, 3).map((l) => InventoryProposer.example(l)),
+        variantProperties: properties,
+        variants,
+        wordpress: {
+          type: 'template-part',
+          slug,
+          area: hint === 'sidebar' ? 'uncategorized' : hint,
+          file: `parts/${slug}.html`,
+        },
+        content: InventoryProposer.content(found[0].nodes),
+        mobileLayoutChanges: changes,
+        pieces: found[0].nodes.map((n) => n.label),
+        oneOff: hint !== 'sidebar' ? presence < 0.6 : found.length < 2,
+        status: 'proposed',
+      });
+    }
+    return out;
+  }
+
+  private components(
+    pages: PageStructure[],
+    templateOf: Map<string, { slug: string }>,
+    mobileOf: (l: Located) => StructureNode | undefined
+  ): InventoryItem[] {
+    const located: Located[] = pages.flatMap((page) =>
+      page.nodes.filter((n) => COMPONENT_HINTS.includes(n.hint)).map((node) => ({ page, node }))
+    );
+    const cardClass = InventoryProposer.distinctiveClasses(
+      located.filter((l) => l.node.hint === 'card').map((l) => l.node)
+    );
+    const groups = new Map<string, Located[]>();
+    for (const l of located) {
+      const { hint, label } = l.node;
+      const key = FAMILY_HINTS.includes(hint)
+        ? hint
+        : hint === 'card'
+          ? `card:${cardClass.get(l.node) ?? InventoryProposer.truncateShape(l.node.shape, 2)}`
+          : `form:${/search/i.test(label + l.node.shape) ? 'search' : 'form'}`;
+      groups.set(key, [...(groups.get(key) ?? []), l]);
+    }
+
+    const out: InventoryItem[] = [];
+    const taken = new Set<string>();
+    const membersOf = new Map<string, Located[]>();
+    for (const members of groups.values()) {
+      const hint = members[0].node.hint;
+      const family = FAMILY[hint];
+      const aka = hint === 'card' ? cardClass.get(members[0].node) : undefined;
+      let name = family.name;
+      if (hint === 'card' && aka) {
+        const stem = aka
+          .replace(/^(lsx|wp|wc|tour-operator|to)-/, '')
+          .replace(/-?(card|item|wrap|post|slot)s?$/, '');
+        name = stem ? `${title(stem)} Card` : 'Card';
+      } else if (hint === 'form') {
+        name = /search/i.test(members[0].node.label + members[0].node.shape)
+          ? 'Search Form'
+          : 'Form';
+      }
+      name = InventoryProposer.unique(name, taken);
+      const layouts = [
+        ...new Set(members.map((m) => InventoryProposer.truncateShape(m.node.shape, 2))),
+      ];
+      const variants = this.variantsOf(
+        members,
+        (l) => ({
+          ...InventoryProposer.componentProps(l.node),
+          Layout:
+            hint === 'card' && layouts.length > 1
+              ? String.fromCharCode(
+                  65 + layouts.indexOf(InventoryProposer.truncateShape(l.node.shape, 2))
+                )
+              : undefined,
+        }),
+        'component'
+      );
+      const extra: Record<string, string[]> = {};
+      const states = InventoryProposer.states(members.map((m) => m.node));
+      if (states.length > 1) {
+        extra.State = states;
+      }
+      const breakpoint = members.some((l) => {
+        const m = mobileOf(l);
+        const d = (a?: number, b?: number) => Math.abs((a ?? 0) - (b ?? 0)) > 2;
+        return (
+          !!m &&
+          (d(m.style.fontSize, l.node.style.fontSize) ||
+            d(m.style.paddingBlock, l.node.style.paddingBlock) ||
+            m.columns !== l.node.columns)
+        );
+      });
+      if (breakpoint) {
+        extra.Breakpoint = ['Desktop', 'Mobile'];
+      }
+      const id = `component:${kebab(name)}`;
+      membersOf.set(id, members);
+      out.push({
+        id,
+        kind: 'component',
+        name,
+        figmaName: `Components/${family.group}/${name}`,
+        hint,
+        count: members.length,
+        pages: [...new Set(members.map((m) => m.page.url))],
+        templates: [...new Set(members.map((m) => templateOf.get(m.page.url)!.slug))],
+        examples: InventoryProposer.examplesOf(members),
+        variantProperties: InventoryProposer.properties(variants, extra),
+        variants,
+        wordpress: this.componentTarget(hint, name, variants, members[0].node),
+        content: InventoryProposer.content(members.map((m) => m.node)),
+        mobileLayoutChanges: breakpoint,
+        oneOff: members.length === 1,
+        status: 'proposed',
+        aka,
+      });
+    }
+    InventoryProposer.nearDuplicates(
+      out.filter((i) => i.hint === 'card' || i.hint === 'form'),
+      membersOf
+    );
+    return out;
+  }
+
+  private patterns(
+    pages: PageStructure[],
+    templateOf: Map<string, { slug: string }>,
+    mobileOf: (l: Located) => StructureNode | undefined,
+    existing: InventoryItem[]
+  ): { patterns: InventoryItem[]; sectionOwner: Map<string, string> } {
+    const groups = new Map<string, Located[]>();
+    for (const page of pages) {
+      const sections = page.nodes
+        .filter((n) => n.hint === 'section')
+        .sort((a, b) => a.rect.y - b.rect.y);
+      for (const node of sections) {
+        groups.set(node.shape, [...(groups.get(node.shape) ?? []), { page, node }]);
+      }
+    }
+    const taken = new Set(existing.map((i) => i.name));
+    const patterns: InventoryItem[] = [];
+    const sectionOwner = new Map<string, string>();
+    const shapeGroups = new Map<string, Located[]>();
+    for (const members of groups.values()) {
+      const first = members[0];
+      const base = InventoryProposer.patternName(first);
+      const name = InventoryProposer.unique(base, taken);
+      const changes = members.some((l) => {
+        const m = mobileOf(l);
+        return !!m && l.node.columns > 1 && m.columns < l.node.columns;
+      });
+      const variants = this.variantsOf(
+        members,
+        (l) => ({ Mode: InventoryProposer.mode(l.node.style) }),
+        'pattern'
+      );
+      const slug = kebab(name);
+      const id = `pattern:${slug}`;
+      members.forEach((m) => sectionOwner.set(`${m.page.url}|${m.node.selector}`, id));
+      shapeGroups.set(id, members);
+      patterns.push({
+        id,
+        kind: 'pattern',
+        name,
+        figmaName: `Patterns/${name}`,
+        hint: 'section',
+        count: members.length,
+        pages: [...new Set(members.map((m) => m.page.url))],
+        templates: [...new Set(members.map((m) => templateOf.get(m.page.url)!.slug))],
+        examples: InventoryProposer.examplesOf(members),
+        variantProperties: InventoryProposer.properties(
+          variants,
+          changes ? { Breakpoint: ['Desktop', 'Mobile'] } : {}
+        ),
+        variants,
+        wordpress: {
+          type: 'pattern',
+          block: PATTERN_BLOCK[base.replace(/ \d+$/, '')] ?? 'core/group',
+          slug: `${this.theme}/${slug}`,
+          file: `patterns/${slug}.php`,
+        },
+        content: InventoryProposer.content(members.map((m) => m.node)),
+        mobileLayoutChanges: changes,
+        oneOff: members.length === 1,
+        status: 'proposed',
+        aka: InventoryProposer.distinctiveClass(first.node),
+      });
+    }
+    InventoryProposer.nearDuplicates(patterns, shapeGroups);
+    return { patterns, sectionOwner };
+  }
+
+  private templates(
+    pages: PageStructure[],
+    templateOf: Map<string, { slug: string; name: string }>,
+    sectionOwner: Map<string, string>,
+    items: InventoryItem[]
+  ): InventoryItem[] {
+    const bySlug = new Map<string, PageStructure[]>();
+    for (const page of pages) {
+      const slug = templateOf.get(page.url)!.slug;
+      bySlug.set(slug, [...(bySlug.get(slug) ?? []), page]);
+    }
+    const byId = new Map(items.map((i) => [i.id, i]));
+    const out: InventoryItem[] = [];
+    for (const [slug, group] of bySlug) {
+      const page = group[0];
+      const ordered = page.nodes
+        .filter((n) => ['header', 'footer', 'sidebar', 'section'].includes(n.hint))
+        .sort((a, b) => a.rect.y - b.rect.y);
+      const composition: string[] = [];
+      for (const node of ordered) {
+        const id =
+          node.hint === 'section'
+            ? sectionOwner.get(`${page.url}|${node.selector}`)
+            : `part:${node.hint}`;
+        // Repeated sections are separate instances (a home page can stack five card grids); parts appear once.
+        if (id && byId.has(id) && !(id.startsWith('part:') && composition.includes(id))) {
+          composition.push(id);
+        }
+      }
+      const name = templateOf.get(page.url)!.name;
+      out.push({
+        id: `template:${slug}`,
+        kind: 'template',
+        name,
+        figmaName: `Templates/${name}`,
+        count: group.length,
+        pages: group.map((p) => p.url),
+        templates: [slug],
+        examples: [{ url: page.url, viewport: page.viewport, selector: 'body', label: page.title }],
+        variantProperties: {},
+        variants: [],
+        wordpress: { type: 'template', slug, file: `templates/${slug}.html` },
+        content: { headings: [page.title], buttons: [], images: [] },
+        mobileLayoutChanges: composition.some((id) => byId.get(id)?.mobileLayoutChanges),
+        composition,
+        status: 'proposed',
+      });
+    }
+    return out;
+  }
+
+  private componentTarget(
+    hint: Hint,
+    name: string,
+    variants: Variant[],
+    node: StructureNode
+  ): WpTarget {
+    const styles = [
+      ...new Set(variants.map((v) => v.properties.Style).filter((s) => s && s !== 'Fill')),
+    ].map(kebab);
+    switch (hint) {
+      case 'button':
+        return {
+          type: 'core-block',
+          block: 'core/button',
+          styles,
+          note: styles.length
+            ? `Non-default styles become block styles: ${styles.map((s) => `styles/blocks/button/${s}.json`).join(', ')}.`
+            : undefined,
+        };
+      case 'link':
+        return {
+          type: 'element-style',
+          block: 'core/paragraph',
+          note: 'theme.json styles.elements.link, with :hover and :focus.',
+        };
+      case 'input':
+        return {
+          type: 'plugin-block',
+          note: 'Form plugin field. Style it through the plugin or the theme stylesheet; core/search for search inputs.',
+        };
+      case 'form':
+        return /search/i.test(name)
+          ? { type: 'core-block', block: 'core/search' }
+          : { type: 'plugin-block', note: `Form plugin block (${node.label}).` };
+      case 'card':
+        return {
+          type: 'pattern',
+          block: 'core/group',
+          slug: `${this.theme}/${kebab(name)}`,
+          file: `patterns/${kebab(name)}.php`,
+          note: 'Card layout inside core/post-template (Query Loop), as an Inserter: false pattern.',
+        };
+      case 'badge':
+        return {
+          type: 'block-style',
+          block: 'core/post-terms',
+          styles: ['badge'],
+          note: 'styles/blocks/post-terms/badge.json',
+        };
+      case 'nav-item':
+        return { type: 'core-block', block: 'core/navigation-link' };
+      case 'pagination':
+        return { type: 'core-block', block: 'core/query-pagination' };
+      case 'accordion':
+        return {
+          type: 'core-block',
+          block: 'core/details',
+          note: 'Or core/accordion where the WordPress version has it.',
+        };
+      case 'breadcrumbs':
+        return {
+          type: 'custom-block',
+          note: 'No core block: the SEO plugin breadcrumbs block or a custom block.',
+        };
+      default:
+        return { type: 'custom-block', note: `No core ${hint} block: a custom or plugin block.` };
+    }
+  }
+
+  private variantsOf(
+    members: Located[],
+    propsOf: (l: Located) => Record<string, string | undefined>,
+    kind: Kind
+  ): Variant[] {
+    const byName = new Map<string, Variant>();
+    for (const l of members) {
+      const properties = Object.fromEntries(
+        Object.entries(propsOf(l)).filter(([, v]) => v !== undefined)
+      ) as Record<string, string>;
+      const name =
+        Object.entries(properties)
+          .map(([k, v]) => `${k}=${v}`)
+          .join(', ') || 'Default';
+      const found = byName.get(name);
+      if (found) {
+        found.count++;
+        continue;
+      }
+      byName.set(name, {
+        name,
+        properties,
+        count: 1,
+        example: InventoryProposer.example(l),
+        style: l.node.style,
+        bindings: this.binder.bind(l.node.style, kind, l.node.hint),
+      });
+    }
+    return [...byName.values()];
+  }
+
+  static componentProps(node: StructureNode): Record<string, string | undefined> {
+    const s = node.style;
+    const style = s.background ? 'Fill' : s.border ? 'Outline' : 'Text';
+    switch (node.hint) {
+      case 'button':
+        return {
+          Style: style,
+          Icon: node.icon ? 'True' : 'False',
+          'Has Text': node.text ? 'True' : 'False',
+          Size: InventoryProposer.sizeKey(node),
+        };
+      case 'badge':
+        return { Style: style, Icon: node.icon ? 'True' : 'False' };
+      case 'input':
+        return {
+          Type: node.tag === 'select' ? 'Select' : node.tag === 'textarea' ? 'Textarea' : 'Text',
+          Style: s.border ? 'Bordered' : s.background ? 'Filled' : 'Plain',
+        };
+      case 'nav-item':
+      case 'breadcrumbs':
+      case 'pagination':
+        return {
+          Mode: InventoryProposer.textMode(s.color),
+          Region: node.region === 'main' ? undefined : title(node.region),
+        };
+      default:
+        return { Mode: InventoryProposer.mode(s) };
+    }
+  }
+
+  /** A size bucket from the element's height, so close sizes share a variant. */
+  static sizeKey(node: StructureNode): string {
+    const h = node.rect.h;
+    return h < 36 ? 'Small' : h < 52 ? 'Medium' : 'Large';
+  }
+
+  static mode(style: StyleSig): string {
+    if (style.backgroundImage) {
+      return 'Image';
+    }
+    const bg = Colour.parse(style.background);
+    if (!bg || bg.a < 0.1) {
+      return 'Transparent';
+    }
+    return Colour.luminance(bg) < 0.3 ? 'Dark' : 'Light';
+  }
+
+  /** Light text means the element sits on a dark background. */
+  static textMode(color: string | undefined): string {
+    const c = Colour.parse(color);
+    return c && Colour.luminance(c) > 0.5 ? 'Dark' : 'Light';
+  }
+
+  static states(nodes: StructureNode[]): string[] {
+    const found = new Set<string>(['Default']);
+    for (const n of nodes) {
+      for (const state of Object.keys(n.states ?? {})) {
+        found.add(title(state));
+      }
+      if (n.open) {
+        found.add('Open');
+      }
+    }
+    const order = ['Default', 'Hover', 'Focus', 'Active', 'Open', 'Disabled'];
+    return [...found].sort((a, b) => order.indexOf(a) - order.indexOf(b));
+  }
+
+  /** Variant property definitions: only properties with more than one value. */
+  static properties(
+    variants: Variant[],
+    extra: Record<string, string[]>
+  ): Record<string, string[]> {
+    const out: Record<string, string[]> = {};
+    for (const v of variants) {
+      for (const [k, value] of Object.entries(v.properties)) {
+        out[k] = [...new Set([...(out[k] ?? []), value])];
+      }
+    }
+    for (const k of Object.keys(out)) {
+      if (out[k].length < 2) {
+        delete out[k];
+      } else {
+        out[k].sort();
+      }
+    }
+    return { ...out, ...extra };
+  }
+
+  static patternName({ page, node }: Located): string {
+    const shape = node.shape;
+    const classes = node.label;
+    const sections = page.nodes
+      .filter((n) => n.hint === 'section')
+      .sort((a, b) => a.rect.y - b.rect.y);
+    const isFirst = sections[0]?.selector === node.selector;
+    const media =
+      node.style.backgroundImage || /video|img|picture/.test(shape) || node.images.length > 0;
+    const cards = page.nodes.filter(
+      (n) =>
+        n.hint === 'card' &&
+        n.rect.y >= node.rect.y &&
+        n.rect.y + n.rect.h <= node.rect.y + node.rect.h + 1
+    );
+    if (/^h[1-6](\(|$)/.test(shape)) {
+      return 'Section Heading';
+    }
+    if (isFirst && media && (shape.includes('h1') || node.headings.length)) {
+      return 'Hero';
+    }
+    if (/testimonial|review|quote/i.test(classes) || shape.includes('blockquote')) {
+      return 'Testimonials';
+    }
+    if (cards.length >= 2) {
+      return 'Card Grid';
+    }
+    if (
+      shape.includes('form') ||
+      page.nodes.some(
+        (n) => n.hint === 'form' && n.rect.y >= node.rect.y && n.rect.y < node.rect.y + node.rect.h
+      )
+    ) {
+      return 'Form Section';
+    }
+    if (/gallery/i.test(classes) || (node.images.length >= 3 && node.headings.length === 0)) {
+      return 'Gallery';
+    }
+    if ((node.style.backgroundImage || shape.includes('video')) && node.headings.length) {
+      return 'Banner';
+    }
+    if (node.columns === 2 && node.images.length >= 1) {
+      return 'Media and Text';
+    }
+    if (node.columns >= 3) {
+      return 'Feature Row';
+    }
+    if (node.buttons.length && node.rect.h < 420) {
+      return 'Call to Action';
+    }
+    return 'Content Section';
+  }
+
+  /**
+   * For each node, its rarest class that at least two nodes share: the class
+   * that tells one kind of card from another (lsx-tour, not lsx-to-widget-item-wrap).
+   */
+  static distinctiveClasses(nodes: StructureNode[]): Map<StructureNode, string> {
+    const classesOf = (n: StructureNode) =>
+      n.label
+        .split('.')
+        .slice(1)
+        .filter((c) => !/\d{2,}|^(has-|is-|col-|align)/.test(c));
+    const freq = new Map<string, number>();
+    nodes.forEach((n) => classesOf(n).forEach((c) => freq.set(c, (freq.get(c) ?? 0) + 1)));
+    const out = new Map<StructureNode, string>();
+    for (const n of nodes) {
+      const best = classesOf(n)
+        .filter((c) => (freq.get(c) ?? 0) >= 2)
+        .sort((a, b) => freq.get(a)! - freq.get(b)!)[0];
+      if (best) {
+        out.set(n, best);
+      }
+    }
+    return out;
+  }
+
+  /** Cuts a shape signature down to the given depth: `div(article(div(a)))` at 1 is `div(article)`. */
+  static truncateShape(shape: string, depth: number): string {
+    const open = shape.indexOf('(');
+    if (open < 0) {
+      return shape;
+    }
+    const close = shape.lastIndexOf(')');
+    const suffix = shape.slice(close + 1);
+    if (depth <= 0) {
+      return shape.slice(0, open) + suffix;
+    }
+    const parts: string[] = [];
+    let level = 0;
+    let current = '';
+    for (const ch of shape.slice(open + 1, close)) {
+      if (ch === ',' && level === 0) {
+        parts.push(current);
+        current = '';
+        continue;
+      }
+      level += ch === '(' ? 1 : ch === ')' ? -1 : 0;
+      current += ch;
+    }
+    parts.push(current);
+    return `${shape.slice(0, open)}(${parts.map((p) => InventoryProposer.truncateShape(p, depth - 1)).join(',')})${suffix}`;
+  }
+
+  static distinctiveClass(node: StructureNode): string | undefined {
+    return node.label
+      .split('.')
+      .slice(1)
+      .find(
+        (c) =>
+          !/^(wp-block-(group|columns|cover|heading|lsx-blocks-lsx-container)|align|has-|is-|col-|container|row|section|widget)/.test(
+            c
+          )
+      );
+  }
+
+  static unique(name: string, taken: Set<string>): string {
+    let candidate = name;
+    for (let n = 2; taken.has(candidate); n++) {
+      candidate = `${name} ${n}`;
+    }
+    taken.add(candidate);
+    return candidate;
+  }
+
+  static example({ page, node }: Located): Example {
+    return { url: page.url, viewport: page.viewport, selector: node.selector, label: node.label };
+  }
+
+  static examplesOf(members: Located[]): Example[] {
+    const seen = new Set<string>();
+    const out: Example[] = [];
+    for (const m of members) {
+      if (!seen.has(m.page.url) && out.length < 3) {
+        seen.add(m.page.url);
+        out.push(InventoryProposer.example(m));
+      }
+    }
+    return out;
+  }
+
+  static content(nodes: StructureNode[]): Content {
+    const uniq = (list: string[]) => [...new Set(list.filter(Boolean))].slice(0, 5);
+    const images = new Map<string, { src: string; alt: string }>();
+    nodes.flatMap((n) => n.images).forEach((i) => images.size < 5 && images.set(i.src, i));
+    return {
+      headings: uniq(nodes.flatMap((n) => n.headings)),
+      buttons: uniq(nodes.flatMap((n) => n.buttons)),
+      images: [...images.values()],
+      text: nodes.find((n) => n.text)?.text,
+    };
+  }
+
+  /** Flags items whose shapes overlap heavily (Jaccard of shape tokens of 0.75 or more). */
+  static nearDuplicates(items: InventoryItem[], groups: Map<string, Located[]>): void {
+    const tokens = (shape: string) => new Set(shape.split(/[^a-z0-9*]+/).filter(Boolean));
+    const shapeOf = (item: InventoryItem) => groups.get(item.id)?.[0]?.node.shape ?? '';
+    for (let i = 0; i < items.length; i++) {
+      for (let j = i + 1; j < items.length; j++) {
+        const a = tokens(shapeOf(items[i]));
+        const b = tokens(shapeOf(items[j]));
+        const common = [...a].filter((t) => b.has(t)).length;
+        const union = new Set([...a, ...b]).size;
+        const sameBase = items[i].name.replace(/ \d+$/, '') === items[j].name.replace(/ \d+$/, '');
+        if (union && (common / union >= 0.75 || (sameBase && common / union >= 0.5))) {
+          items[i].mergeWith = [...(items[i].mergeWith ?? []), items[j].id];
+        }
+      }
+    }
+  }
+
+  static unbound(items: InventoryItem[]): UnboundValue[] {
+    const map = new Map<string, UnboundValue>();
+    const between = new Map<string, string[] | undefined>();
+    for (const item of items) {
+      for (const v of item.variants) {
+        for (const b of v.bindings) {
+          if (b.match === 'exact' || b.match === 'near') {
+            continue;
+          }
+          const key = `${b.property}|${b.value}|${b.match}`;
+          const entry = map.get(key) ?? {
+            property: b.property,
+            value: b.value,
+            match: b.match,
+            nearest: b.variable,
+            items: [],
+            proposal: '',
+          };
+          if (!entry.items.includes(item.id)) {
+            entry.items.push(item.id);
+          }
+          between.set(key, b.between);
+          map.set(key, entry);
+        }
+      }
+    }
+    for (const [key, entry] of map) {
+      entry.proposal = InventoryProposer.proposal(entry, between.get(key));
+    }
+    return [...map.values()].sort(
+      (a, b) => b.items.length - a.items.length || a.property.localeCompare(b.property)
+    );
+  }
+
+  /**
+   * What to add so a value binds, following the LightSpeed rules: fonts match
+   * the live site, colours fit into the ramps, sizes get a new step in order,
+   * and one-offs become semantically named custom variables.
+   */
+  static proposal(u: Omit<UnboundValue, 'proposal'>, between?: string[]): string {
+    const oneOff =
+      u.items.length === 1
+        ? ' If it is a one-off, add a semantically named custom variable (custom/<role>) to the semantic collection instead.'
+        : '';
+    if (u.property === 'fontFamily') {
+      return `Fonts match the live site: add a family variable for "${u.value}" (Font-Families/Alternate, var(--wp--preset--font-family--alternate)) under its licensed name.`;
+    }
+    if (['fill', 'text', 'stroke'].includes(u.property)) {
+      return u.match === 'primitive'
+        ? `Matches the primitive ${u.nearest}. Point the semantic role for this ${u.property} at it, or add a semantic token.`
+        : `Fit ${u.value} into a colour ramp (it replaces the nearest step when it fits) or match it to the nearest existing colour, then bind the semantic token for its role.${oneOff}`;
+    }
+    if (u.property === 'effect') {
+      return `Add an effect style for this shadow, or match it to the nearest one.${oneOff}`;
+    }
+    const range =
+      between?.length === 2
+        ? ` between ${between[0]} and ${between[1]}`
+        : between?.length === 1
+          ? ` next to ${between[0]}`
+          : '';
+    return `Add a ${u.property === 'radius' ? 'radius' : u.property === 'fontSize' ? 'type size' : 'spacing'} step${range}, keeping the ramp in order and renumbering slugs if needed.${oneOff}`;
+  }
+}
+
+export class DecisionApplier {
+  constructor(private readonly now: () => Date = () => new Date()) {}
+
+  apply(inventory: Inventory, decisions: Decisions): Inventory {
+    const out: Inventory = JSON.parse(JSON.stringify(inventory));
+    const byId = new Map(out.items.map((i) => [i.id, i]));
+    const ids = [
+      ...Object.keys(decisions.rename ?? {}),
+      ...(decisions.cut ?? []),
+      ...(decisions.merge ?? []).flat(),
+      ...(decisions.promote ?? []),
+      ...(decisions.build ?? []),
+    ];
+    const unknown = [...new Set(ids.filter((id) => !byId.has(id)))];
+    if (unknown.length) {
+      throw new Error(`Unknown item ids in decisions: ${unknown.join(', ')}.`);
+    }
+    const log = out.decisions;
+
+    for (const [keep, drop] of decisions.merge ?? []) {
+      const a = byId.get(keep)!;
+      const b = byId.get(drop)!;
+      if (a.kind !== b.kind) {
+        throw new Error(`Can't merge ${drop} (${b.kind}) into ${keep} (${a.kind}).`);
+      }
+      a.count += b.count;
+      a.pages = [...new Set([...a.pages, ...b.pages])];
+      a.templates = [...new Set([...a.templates, ...b.templates])];
+      a.examples = [...a.examples, ...b.examples].slice(0, 3);
+      const names = new Set(a.variants.map((v) => v.name));
+      a.variants.push(...b.variants.filter((v) => !names.has(v.name)));
+      for (const [k, values] of Object.entries(b.variantProperties)) {
+        a.variantProperties[k] = [...new Set([...(a.variantProperties[k] ?? []), ...values])];
+      }
+      a.mobileLayoutChanges = a.mobileLayoutChanges || b.mobileLayoutChanges;
+      a.oneOff = false;
+      a.mergeWith = a.mergeWith?.filter((id) => id !== drop);
+      out.items = out.items.filter((i) => i.id !== drop);
+      byId.delete(drop);
+      for (const item of out.items) {
+        if (item.composition) {
+          item.composition = item.composition.map((id) => (id === drop ? keep : id));
+        }
+        item.mergeWith = item.mergeWith?.filter((id) => id !== drop);
+      }
+      log.push(`Merged ${drop} into ${keep}.`);
+    }
+    for (const id of decisions.cut ?? []) {
+      if (byId.has(id)) {
+        byId.get(id)!.status = 'cut';
+        log.push(`Cut ${id}.`);
+      }
+    }
+    for (const id of decisions.promote ?? []) {
+      byId.get(id)!.oneOff = false;
+      log.push(`Kept ${id} although it appears once.`);
+    }
+    for (const [id, name] of Object.entries(decisions.rename ?? {})) {
+      const item = byId.get(id)!;
+      const prefix = item.figmaName.split('/').slice(0, -1).join('/');
+      item.name = name;
+      item.figmaName = `${prefix}/${name}`;
+      if (item.wordpress.type === 'pattern') {
+        const theme = item.wordpress.slug?.split('/')[0] ?? out.theme;
+        item.wordpress.slug = `${theme}/${kebab(name)}`;
+        item.wordpress.file = `patterns/${kebab(name)}.php`;
+      }
+      log.push(`Renamed ${id} to "${name}".`);
+    }
+    if (decisions.build) {
+      const scope = new Set<string>();
+      for (const id of decisions.build) {
+        const chosen = byId.get(id)!;
+        scope.add(id);
+        (chosen.composition ?? [])
+          .filter((c) => byId.get(c)?.status !== 'cut')
+          .forEach((c) => scope.add(c));
+      }
+      out.buildScope = out.items.map((i) => i.id).filter((id) => scope.has(id));
+      log.push(`Build scope: ${out.buildScope.length} items (${decisions.build.join(', ')}).`);
+    }
+    if (decisions.approve) {
+      out.approved = true;
+      out.approvedAt = this.now().toISOString();
+      log.push('Approved by the reviewer.');
+    }
+    out.unbound = InventoryProposer.unbound(out.items.filter((i) => i.status !== 'cut'));
+    return out;
+  }
+}
+
+export class InventoryReport {
+  constructor(private readonly shotsDir?: string) {}
+
+  /** Connected groups of items flagged as near duplicates, each in inventory order. */
+  static mergeGroups(items: InventoryItem[]): string[][] {
+    const ids = new Set(items.map((i) => i.id));
+    const links = new Map<string, Set<string>>();
+    const link = (a: string, b: string) => links.set(a, (links.get(a) ?? new Set()).add(b));
+    for (const item of items) {
+      for (const other of (item.mergeWith ?? []).filter((id) => ids.has(id))) {
+        link(item.id, other);
+        link(other, item.id);
+      }
+    }
+    const seen = new Set<string>();
+    const groups: string[][] = [];
+    for (const item of items) {
+      if (seen.has(item.id) || !links.has(item.id)) {
+        continue;
+      }
+      const group: string[] = [];
+      const stack = [item.id];
+      while (stack.length) {
+        const id = stack.pop()!;
+        if (!seen.has(id)) {
+          seen.add(id);
+          group.push(id);
+          stack.push(...links.get(id)!);
+        }
+      }
+      groups.push(items.map((i) => i.id).filter((id) => group.includes(id)));
+    }
+    return groups;
+  }
+
+  render(inv: Inventory): string {
+    const live = inv.items.filter((i) => i.status !== 'cut');
+    const of = (kind: Kind) => live.filter((i) => i.kind === kind);
+    const lines: string[] = [];
+    const push = (...l: string[]) => lines.push(...l);
+    const list = (values: string[]) => values.join(', ') || 'none';
+    const pathOf = (u: string) => {
+      const url = new URL(u);
+      return url.pathname + url.search;
+    };
+    const pageList = (urls: string[]) => urls.map(pathOf).join(', ');
+    const shot = (id: string) =>
+      this.shotsDir
+        ? ` ![${id}](${this.shotsDir}/${id.replace(/[^a-z0-9-]+/gi, '-')}-1440.png)`
+        : '';
+    const wp = (t: WpTarget) =>
+      [
+        t.type,
+        t.block,
+        t.slug,
+        t.file,
+        t.styles?.length ? `styles: ${t.styles.join(', ')}` : '',
+        t.note,
+      ]
+        .filter(Boolean)
+        .join('; ');
+    const props = (p: Record<string, string[]>) =>
+      Object.entries(p)
+        .map(([k, v]) => `${k} (${v.join(' | ')})`)
+        .join('; ') || 'none';
+
+    push(`# Component inventory: ${new URL(inv.site).host}`, '');
+    push(
+      `Captured ${inv.capturedAt.slice(0, 10)} from ${inv.pages.length} pages. Theme: \`${inv.theme}\`. Status: ${inv.approved ? `approved ${inv.approvedAt?.slice(0, 10)}` : 'awaiting approval'}.`,
+      ''
+    );
+
+    push('## Summary', '');
+    push('| Kind | Items | One-offs |', '| --- | --- | --- |');
+    for (const kind of ['template-part', 'component', 'pattern', 'template'] as Kind[]) {
+      push(`| ${kind} | ${of(kind).length} | ${of(kind).filter((i) => i.oneOff).length} |`);
+    }
+    push('');
+    const bindings = live.flatMap((i) => i.variants.flatMap((v) => v.bindings));
+    const bound = bindings.filter((b) => b.match === 'exact' || b.match === 'near').length;
+    push(
+      inv.tokensLoaded
+        ? `Token bindings: ${bound} of ${bindings.length} values bind to a semantic token or theme variable.`
+        : 'No variables export was loaded, so nothing is bound yet. Re-run with `--tokens variables.json` from site-to-design-tokens.',
+      ''
+    );
+
+    push('## Decisions for the reviewer', '');
+    const decisions: string[] = [];
+    for (const group of InventoryReport.mergeGroups(live)) {
+      const pairs = group
+        .slice(1)
+        .map((id) => `["${group[0]}", "${id}"]`)
+        .join(', ');
+      decisions.push(
+        `**Merge?** These look alike: ${group.join(', ')}. To merge, add \`"merge": [${pairs}]\`.`
+      );
+    }
+    for (const f of inv.failures ?? []) {
+      decisions.push(
+        `**Not captured:** ${pathOf(f.url)} at ${f.viewport}px (${f.error}). Re-run the crawl for that page, or choose another of the same type.`
+      );
+    }
+    for (const r of inv.redirects) {
+      decisions.push(
+        `**Redirected:** ${pathOf(r.from)} redirects to ${r.to}, so it was left out. Choose another page of that type if one exists.`
+      );
+    }
+    for (const item of live.filter((i) => i.oneOff && i.kind !== 'template')) {
+      decisions.push(
+        `**One-off:** ${item.id} appears once (${pageList(item.pages)}). Leave it out with \`cut\`, or keep it with \`promote\`.`
+      );
+    }
+    for (const u of inv.unbound.slice(0, 25)) {
+      const label = u.match === 'primitive' ? 'Primitive only' : 'No token';
+      decisions.push(
+        `**${label}:** ${u.property} ${u.value}. Proposed: ${u.proposal} Used by ${u.items.join(', ')}.`
+      );
+    }
+    if (inv.unbound.length > 25) {
+      decisions.push(
+        `${inv.unbound.length - 25} more values without a token are listed under "Values with no token".`
+      );
+    }
+    const covered = new Set(of('template').map((t) => t.wordpress.slug));
+    for (const missing of ['404', 'search', 'single', 'page'].filter((s) => !covered.has(s))) {
+      decisions.push(
+        `**Template not crawled:** \`${missing}\`. Add a page of that type to the crawl, or confirm it isn't needed.`
+      );
+    }
+    push(...(decisions.length ? decisions.map((d) => `- ${d}`) : ['- Nothing to decide.']), '');
+
+    push('## Template parts', '');
+    push(
+      '| Id | Name | On pages | Variant properties | Pieces | WordPress |',
+      '| --- | --- | --- | --- | --- | --- |'
+    );
+    for (const i of of('template-part')) {
+      push(
+        `| ${i.id} | ${i.name}${shot(i.id)} | ${i.count} of ${inv.pages.length} | ${props(i.variantProperties)} | ${list(i.pieces ?? [])} | ${wp(i.wordpress)} |`
+      );
+    }
+    push('', '## Components', '');
+    push(
+      '| Id | Figma name | Count | Pages | Variant properties | WordPress |',
+      '| --- | --- | --- | --- | --- | --- |'
+    );
+    for (const i of of('component')) {
+      push(
+        `| ${i.id} | ${i.figmaName}${shot(i.id)} | ${i.count} | ${i.pages.length} | ${props(i.variantProperties)} | ${wp(i.wordpress)} |`
+      );
+    }
+    push('', '## Patterns', '');
+    push(
+      '| Id | Name | Count | Source pages | Mobile layout changes | WordPress |',
+      '| --- | --- | --- | --- | --- | --- |'
+    );
+    for (const i of of('pattern')) {
+      const heading = i.content.headings[0] ? ` ("${i.content.headings[0]}")` : '';
+      push(
+        `| ${i.id} | ${i.name}${heading}${shot(i.id)} | ${i.count} | ${pageList(i.pages)} | ${i.mobileLayoutChanges ? 'yes' : 'no'} | ${wp(i.wordpress)} |`
+      );
+    }
+    push('', '## Templates', '');
+    for (const i of of('template')) {
+      push(`### ${i.name} (\`${i.wordpress.file}\`)`, '');
+      push(
+        `Pages: ${pageList(i.pages)}. Frames: 1440${i.mobileLayoutChanges ? ' and 390' : ''}.`,
+        ''
+      );
+      push(...(i.composition ?? []).map((id, n) => `${n + 1}. ${id}`), '');
+    }
+    push('## Values with no token', '');
+    if (!inv.unbound.length) {
+      push('Every value binds to a token.', '');
+    } else {
+      push('| Property | Value | Nearest | Proposed | Items |', '| --- | --- | --- | --- | --- |');
+      inv.unbound.forEach((u) =>
+        push(
+          `| ${u.property} | ${u.value} | ${u.nearest ?? 'none'} | ${u.proposal} | ${u.items.join(', ')} |`
+        )
+      );
+      push('');
+    }
+    push('## Build scope', '');
+    push(
+      inv.buildScope?.length
+        ? `Approved for the Figma build: ${inv.buildScope.join(', ')}.`
+        : 'Not chosen yet. Before any import, the reviewer approves which templates (and any extra items) to build, with `"build": [...]` in decisions.json.',
+      ''
+    );
+    if (inv.decisions.length) {
+      push('## Decisions applied', '', ...inv.decisions.map((d) => `- ${d}`), '');
+    }
+    push('## Next step', '');
+    push(
+      'Record the answers in `decisions.json` and re-run with `--decisions decisions.json`:',
+      '',
+      '```json',
+      '{ "rename": { "component:card": "Tour Card" }, "cut": ["pattern:content-section-3"], "merge": [["pattern:hero", "pattern:hero-2"]], "promote": [], "build": ["template:front-page", "component:button"], "approve": true }',
+      '```',
+      ''
+    );
+    return `${lines.join('\n')}\n`;
+  }
+}
+
+export interface ProposeCliIo {
+  readFile: (path: string) => string;
+  writeFile: (path: string, content: string) => void;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  now?: () => Date;
+}
+
+export function runProposeCli(argv: string[], io: ProposeCliIo): number {
+  const values: Record<string, string> = {
+    out: 'inventory.json',
+    report: 'inventory.md',
+    theme: 'theme',
+  };
+  const optional = ['tokens', 'decisions', 'shots'];
+  let input: string | undefined;
+  try {
+    for (let i = 0; i < argv.length; i++) {
+      const arg = argv[i];
+      if (arg === '--help' || arg === '-h') {
+        io.stdout(
+          'Usage: propose-inventory site-structure.json [--tokens variables.json] [--theme slug] [--out inventory.json] [--report inventory.md] [--decisions decisions.json] [--shots shots]\n'
+        );
+        return 0;
+      }
+      if (!arg.startsWith('--')) {
+        input = arg;
+        continue;
+      }
+      const key = arg.slice(2);
+      if (![...optional, ...Object.keys(values)].includes(key)) {
+        throw new Error(`Unknown argument ${arg}.`);
+      }
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error(`${arg} needs a value.`);
+      }
+      values[key] = value;
+    }
+    if (!input) {
+      throw new Error('Pass the site-structure.json from crawl-site-structure.');
+    }
+    const structure = JSON.parse(io.readFile(input)) as SiteStructure;
+    const tokens = values.tokens
+      ? new TokenIndex(JSON.parse(io.readFile(values.tokens)) as VariablesExport)
+      : new TokenIndex();
+    let inventory = new InventoryProposer(tokens, values.theme).propose(structure);
+    if (values.decisions) {
+      inventory = new DecisionApplier(io.now).apply(
+        inventory,
+        JSON.parse(io.readFile(values.decisions)) as Decisions
+      );
+    }
+    io.writeFile(values.out, `${JSON.stringify(inventory, null, 2)}\n`);
+    io.writeFile(values.report, new InventoryReport(values.shots).render(inventory));
+    const live = inventory.items.filter((i) => i.status !== 'cut');
+    io.stdout(
+      `${live.length} items (${['template-part', 'component', 'pattern', 'template'].map((k) => `${live.filter((i) => i.kind === k).length} ${k}`).join(', ')}), ${inventory.unbound.length} values with no token. Wrote ${values.out} and ${values.report}.\n`
+    );
+    return 0;
+  } catch (error) {
+    io.stderr(`propose-inventory: ${(error as Error).message}\n`);
+    return 1;
+  }
+}
+
+/* istanbul ignore next -- thin CLI entry point */
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = runProposeCli(process.argv.slice(2), {
+    readFile: (path) => readFileSync(path, 'utf8'),
+    writeFile: (path, content) => writeFileSync(path, content),
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+  });
+}
diff --git a/skills/site-to-figma-components/scripts/tsconfig.json b/skills/site-to-figma-components/scripts/tsconfig.json
new file mode 100644
index 0000000000..82a9dc00aa
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "types": ["node", "jest"],
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["*.ts", "lib/*.ts", "__tests__/*.ts"],
+  "exclude": []
+}
diff --git a/skills/site-to-figma-components/scripts/write-manifest.ts b/skills/site-to-figma-components/scripts/write-manifest.ts
new file mode 100644
index 0000000000..8df1ec089a
--- /dev/null
+++ b/skills/site-to-figma-components/scripts/write-manifest.ts
@@ -0,0 +1,312 @@
+/**
+ * Writes the hand-off manifest that maps each Figma node built from an
+ * approved inventory to its WordPress target: template file, template part,
+ * pattern slug, block or block style. figma-to-block-theme's Pattern mode
+ * reads the JSON; the Markdown is for people.
+ *
+ * Usage:
+ *   npx tsx write-manifest.ts inventory.json --nodes figma-nodes.json \
+ *     --out manifest.json --markdown manifest.md [--partial]
+ *
+ * figma-nodes.json is assembled from the IDs the use_figma build calls return:
+ *   { "fileKey": "abc", "nodes": { "component:button": { "nodeId": "12:34", "page": "> Components" } } }
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import type { Inventory, InventoryItem, Kind, WpTarget } from './propose-inventory';
+
+export interface FigmaNodeRef {
+  nodeId: string;
+  /** The 390px frame, for templates and patterns whose layout changes on mobile. */
+  mobileNodeId?: string;
+  page?: string;
+}
+
+export interface FigmaNodes {
+  fileKey: string;
+  nodes: Record<string, FigmaNodeRef>;
+}
+
+export interface CompositionEntry {
+  id: string;
+  /** `local` when the section was cut from the inventory and lives only inside the template frame. */
+  target: 'template-part' | 'pattern' | 'local';
+  slug?: string;
+  file?: string;
+}
+
+export interface ManifestEntry {
+  id: string;
+  kind: Kind;
+  name: string;
+  figma: {
+    fileKey: string;
+    nodeId: string;
+    mobileNodeId?: string;
+    name: string;
+    page?: string;
+    url: string;
+  };
+  wordpress: WpTarget;
+  variantProperties?: Record<string, string[]>;
+  composition?: CompositionEntry[];
+  sourcePages: string[];
+}
+
+export interface Manifest {
+  manifestVersion: 1;
+  site: string;
+  theme: string;
+  figmaFileKey: string;
+  inventoryApprovedAt?: string;
+  generatedAt: string;
+  entries: ManifestEntry[];
+  skipped: { id: string; reason: string }[];
+  warnings: string[];
+}
+
+const NODE_ID = /^\d+:\d+$/;
+const ORDER: Kind[] = ['component', 'template-part', 'pattern', 'template'];
+
+export class ManifestBuilder {
+  constructor(private readonly now: () => Date = () => new Date()) {}
+
+  build(inventory: Inventory, figma: FigmaNodes, partial = false): Manifest {
+    if (!inventory.approved) {
+      throw new Error(
+        'The inventory is not approved. Apply the reviewer decisions with "approve": true first.'
+      );
+    }
+    if (!figma.fileKey) {
+      throw new Error('figma-nodes.json needs the Figma fileKey.');
+    }
+    const live = inventory.items.filter((i) => i.status !== 'cut');
+    const byId = new Map(inventory.items.map((i) => [i.id, i]));
+    const errors: string[] = [];
+    const warnings: string[] = [];
+    const skipped: { id: string; reason: string }[] = [];
+
+    for (const [id, ref] of Object.entries(figma.nodes)) {
+      if (!byId.has(id)) {
+        warnings.push(`${id} is in figma-nodes.json but not in the inventory.`);
+      } else if (byId.get(id)!.status === 'cut') {
+        warnings.push(
+          `${id} was cut from the inventory but has a Figma node (${ref.nodeId}). Archive the node or restore the item.`
+        );
+      }
+      for (const nodeId of [ref.nodeId, ref.mobileNodeId].filter(
+        (n): n is string => n !== undefined
+      )) {
+        if (!NODE_ID.test(nodeId)) {
+          errors.push(`${id} has an invalid node ID "${nodeId}"; expected the form 123:456.`);
+        }
+      }
+    }
+
+    const entries: ManifestEntry[] = [];
+    const scope = inventory.buildScope ? new Set(inventory.buildScope) : undefined;
+    for (const item of live) {
+      const ref = figma.nodes[item.id];
+      if (!ref && scope && !scope.has(item.id)) {
+        skipped.push({ id: item.id, reason: 'Outside the approved build scope.' });
+        continue;
+      }
+      if (!ref) {
+        if (partial) {
+          skipped.push({ id: item.id, reason: 'Not built in Figma yet.' });
+        } else {
+          errors.push(`${item.id} has no Figma node. Build it, cut it, or pass --partial.`);
+        }
+        continue;
+      }
+      if (item.kind === 'template' && item.mobileLayoutChanges && !ref.mobileNodeId) {
+        warnings.push(`${item.id} changes layout at 390px but has no mobile frame.`);
+      }
+      entries.push(this.entry(item, ref, figma.fileKey, byId));
+    }
+    if (errors.length) {
+      throw new Error(errors.join('\n'));
+    }
+    entries.sort(
+      (a, b) => ORDER.indexOf(a.kind) - ORDER.indexOf(b.kind) || a.name.localeCompare(b.name)
+    );
+
+    return {
+      manifestVersion: 1,
+      site: inventory.site,
+      theme: inventory.theme,
+      figmaFileKey: figma.fileKey,
+      inventoryApprovedAt: inventory.approvedAt,
+      generatedAt: this.now().toISOString(),
+      entries,
+      skipped,
+      warnings,
+    };
+  }
+
+  private entry(
+    item: InventoryItem,
+    ref: FigmaNodeRef,
+    fileKey: string,
+    byId: Map<string, InventoryItem>
+  ): ManifestEntry {
+    const entry: ManifestEntry = {
+      id: item.id,
+      kind: item.kind,
+      name: item.name,
+      figma: {
+        fileKey,
+        nodeId: ref.nodeId,
+        name: item.figmaName,
+        url: `https://www.figma.com/design/${fileKey}/?node-id=${ref.nodeId.replace(':', '-')}`,
+      },
+      wordpress: item.wordpress,
+      sourcePages: item.pages,
+    };
+    if (ref.mobileNodeId) {
+      entry.figma.mobileNodeId = ref.mobileNodeId;
+    }
+    if (ref.page) {
+      entry.figma.page = ref.page;
+    }
+    if (Object.keys(item.variantProperties).length) {
+      entry.variantProperties = item.variantProperties;
+    }
+    if (item.composition) {
+      entry.composition = item.composition.map((id) => {
+        const part = byId.get(id);
+        if (!part || part.status === 'cut') {
+          return { id, target: 'local' };
+        }
+        return {
+          id,
+          target: part.kind === 'template-part' ? 'template-part' : 'pattern',
+          slug: part.wordpress.slug,
+          file: part.wordpress.file,
+        };
+      });
+    }
+    return entry;
+  }
+
+  markdown(m: Manifest): string {
+    const lines = [
+      `# Figma to WordPress manifest: ${new URL(m.site).host}`,
+      '',
+      `Theme \`${m.theme}\`, Figma file \`${m.figmaFileKey}\`. Generated ${m.generatedAt.slice(0, 10)} from the inventory approved ${m.inventoryApprovedAt?.slice(0, 10) ?? 'on an unknown date'}.`,
+      '',
+      '| Kind | Name | Figma node | WordPress target | File |',
+      '| --- | --- | --- | --- | --- |',
+      ...m.entries.map((e) => {
+        const target = [
+          e.wordpress.type,
+          e.wordpress.block,
+          e.wordpress.slug,
+          e.wordpress.styles?.length ? `styles: ${e.wordpress.styles.join(', ')}` : '',
+        ]
+          .filter(Boolean)
+          .join(', ');
+        const node = `[${e.figma.nodeId}](${e.figma.url})${e.figma.mobileNodeId ? ` (mobile ${e.figma.mobileNodeId})` : ''}`;
+        return `| ${e.kind} | ${e.name} | ${node} | ${target} | ${e.wordpress.file ?? ''} |`;
+      }),
+      '',
+    ];
+    const templates = m.entries.filter((e) => e.composition);
+    if (templates.length) {
+      lines.push('## Template composition', '');
+      for (const t of templates) {
+        lines.push(`### ${t.name} (\`${t.wordpress.file}\`)`, '');
+        lines.push(
+          ...t.composition!.map(
+            (c, n) =>
+              `${n + 1}. ${c.target === 'local' ? `${c.id} (local section, no pattern)` : `${c.target} \`${c.slug}\``}`
+          ),
+          ''
+        );
+      }
+    }
+    if (m.skipped.length) {
+      lines.push('## Not built yet', '', ...m.skipped.map((s) => `- ${s.id}: ${s.reason}`), '');
+    }
+    if (m.warnings.length) {
+      lines.push('## Warnings', '', ...m.warnings.map((w) => `- ${w}`), '');
+    }
+    return `${lines.join('\n')}\n`;
+  }
+}
+
+export interface ManifestCliIo {
+  readFile: (path: string) => string;
+  writeFile: (path: string, content: string) => void;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  now?: () => Date;
+}
+
+export function runManifestCli(argv: string[], io: ManifestCliIo): number {
+  const values: Record<string, string> = { out: 'manifest.json', markdown: 'manifest.md' };
+  let input: string | undefined;
+  let nodes: string | undefined;
+  let partial = false;
+  try {
+    for (let i = 0; i < argv.length; i++) {
+      const arg = argv[i];
+      if (arg === '--help' || arg === '-h') {
+        io.stdout(
+          'Usage: write-manifest inventory.json --nodes figma-nodes.json [--out manifest.json] [--markdown manifest.md] [--partial]\n'
+        );
+        return 0;
+      }
+      if (arg === '--partial') {
+        partial = true;
+        continue;
+      }
+      if (!arg.startsWith('--')) {
+        input = arg;
+        continue;
+      }
+      const key = arg.slice(2);
+      if (key !== 'nodes' && !(key in values)) {
+        throw new Error(`Unknown argument ${arg}.`);
+      }
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error(`${arg} needs a value.`);
+      }
+      if (key === 'nodes') {
+        nodes = value;
+      } else {
+        values[key] = value;
+      }
+    }
+    if (!input || !nodes) {
+      throw new Error('Pass the approved inventory.json and --nodes figma-nodes.json.');
+    }
+    const builder = new ManifestBuilder(io.now);
+    const manifest = builder.build(
+      JSON.parse(io.readFile(input)) as Inventory,
+      JSON.parse(io.readFile(nodes)) as FigmaNodes,
+      partial
+    );
+    io.writeFile(values.out, `${JSON.stringify(manifest, null, 2)}\n`);
+    io.writeFile(values.markdown, builder.markdown(manifest));
+    io.stdout(
+      `${manifest.entries.length} entries, ${manifest.skipped.length} not built, ${manifest.warnings.length} warnings. Wrote ${values.out} and ${values.markdown}.\n`
+    );
+    return 0;
+  } catch (error) {
+    io.stderr(`write-manifest: ${(error as Error).message}\n`);
+    return 1;
+  }
+}
+
+/* istanbul ignore next -- thin CLI entry point */
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = runManifestCli(process.argv.slice(2), {
+    readFile: (path) => readFileSync(path, 'utf8'),
+    writeFile: (path, content) => writeFileSync(path, content),
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+  });
+}

From 5b2f0584c4ace1b72838de0e12f6f624971ad6b9 Mon Sep 17 00:00:00 2001
From: Zared Rogers <zared@lightspeedwp.agency>
Date: Thu, 5 Nov 2026 15:40:07 +0200
Subject: [PATCH 2/3] fix(site-to-figma-components): address CodeRabbit review

- Shorten changelog entry to user-facing wording under 250 chars
- Remove footer blocks from skill reference files
- Close the browser when CLI or URL validation fails

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                        |  2 +-
 .../references/classification.md                    |  3 ---
 .../site-to-figma-components/references/crawling.md |  3 ---
 .../references/figma-build.md                       |  3 ---
 .../references/inventory-review.md                  |  3 ---
 .../site-to-figma-components/references/manifest.md |  3 ---
 .../references/verification.md                      |  3 ---
 .../scripts/crawl-site-structure.ts                 | 13 ++++++++-----
 8 files changed, 9 insertions(+), 24 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 03645eb49a..4e3be626ac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Site to Figma Components Skill** — For website rebuilds, after the design tokens: crawls the live site at mobile and desktop widths, finds its repeated components, patterns, template parts and page templates with their variants and states, and writes an approval report that maps each to its WordPress block and proposes a variable for every value with no token. Once the reviewer approves the inventory and the templates to build, it builds them in Figma bound to the tokens, checks them against the live pages, and writes a manifest for `figma-to-block-theme` Pattern mode. ([#3992](https://github.com/lightspeedwp/.github/issues/3992))
+- **Site to Figma Components Skill** — Rebuilds a live site's components, patterns and templates in Figma after the reviewer approves an inventory. ([#3992](https://github.com/lightspeedwp/.github/issues/3992))
 
 - **WordPress Schema Audit Agent** — Checks the structured data a WordPress site publishes against schema.org and Google's rules, then writes a client report and a spreadsheet of fixes. ([PR #3962](https://github.com/lightspeedwp/.github/pull/3962))
 - **Studio Migration Import Choices** — The agent asks about the table prefix, local accounts, tables to skip and the Studio site URL. Wordfence tables are skipped by default. ([PR #3961](https://github.com/lightspeedwp/.github/pull/3961))
diff --git a/skills/site-to-figma-components/references/classification.md b/skills/site-to-figma-components/references/classification.md
index f5ced99048..9d17ac3c32 100644
--- a/skills/site-to-figma-components/references/classification.md
+++ b/skills/site-to-figma-components/references/classification.md
@@ -73,6 +73,3 @@ Nothing is added until the reviewer approves. Then add the variables before the
 ## Near duplicates and one-offs
 
 Items whose shape signatures share at least 75% of their tokens (50% for items with the same base name) are grouped as look-alikes for the reviewer to merge. Items found once are flagged as one-offs: cut them, or keep them with `promote`.
-
-*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
-[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/crawling.md b/skills/site-to-figma-components/references/crawling.md
index 572f7482b7..70e6c4f218 100644
--- a/skills/site-to-figma-components/references/crawling.md
+++ b/skills/site-to-figma-components/references/crawling.md
@@ -48,6 +48,3 @@ Each capture records its final URL. Pages that redirect to a page already crawle
 ## Politeness
 
 One page at a time with a 1.5 second pause (`--delay`), only on the `--url` origin. Puppeteer downloads its browser on first install; if the launch fails, run `npx puppeteer browsers install chrome`.
-
-*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
-[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/figma-build.md b/skills/site-to-figma-components/references/figma-build.md
index d9d120825b..f812257e63 100644
--- a/skills/site-to-figma-components/references/figma-build.md
+++ b/skills/site-to-figma-components/references/figma-build.md
@@ -39,6 +39,3 @@ After each call, add the IDs to `figma-nodes.json`: the component set for compon
 ## Archive, never delete
 
 `node.remove()` is blocked. Move superseded items to an archive page, grouped in sections, and check the destinations of prototype links before moving anything.
-
-*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
-[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/inventory-review.md b/skills/site-to-figma-components/references/inventory-review.md
index 6d972f0603..426714ba83 100644
--- a/skills/site-to-figma-components/references/inventory-review.md
+++ b/skills/site-to-figma-components/references/inventory-review.md
@@ -50,6 +50,3 @@ Add `"build"` with the templates (and any extra items) to build in Figma. The re
 Merges run first, then cuts, promotions, renames and the build scope. A merged item takes the other's pages, examples and variants, and templates point to it. A cut item stays in the inventory with `status: "cut"`; templates show it as a local section. Set `"approve": true` only when the reviewer has said so. The manifest writer refuses an unapproved inventory.
 
 Post the approved report on the project's Linear issue.
-
-*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
-[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/manifest.md b/skills/site-to-figma-components/references/manifest.md
index 61d8fb0441..acaeafe36a 100644
--- a/skills/site-to-figma-components/references/manifest.md
+++ b/skills/site-to-figma-components/references/manifest.md
@@ -61,6 +61,3 @@ The writer refuses an unapproved inventory, a node ID not in the form `123:456`,
 ## How Pattern mode uses it
 
 `figma-to-block-theme` Pattern mode reads `manifest.json` in entry order. For each entry it reads the node with `figma-design-to-code`, writes the file named in `wordpress.file`, and uses `wordpress.slug`, `block` and `styles` as given. Templates are written last, from their `composition`: `<!-- wp:template-part {"slug":"header"} /-->` for parts and `<!-- wp:pattern {"slug":"tsp-theme/hero"} /-->` for patterns.
-
-*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
-[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/references/verification.md b/skills/site-to-figma-components/references/verification.md
index 39c8ddcc55..75160ab144 100644
--- a/skills/site-to-figma-components/references/verification.md
+++ b/skills/site-to-figma-components/references/verification.md
@@ -29,6 +29,3 @@ Fix findings with `fix-design-system-finding`, or in a small `use_figma` pass, a
 ## Report
 
 Post the differences table and the audit counts on the project's Linear issue with `manifest.md`.
-
-*Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!*
-[Contributors](https://github.com/lightspeedwp/.github/graphs/contributors)
diff --git a/skills/site-to-figma-components/scripts/crawl-site-structure.ts b/skills/site-to-figma-components/scripts/crawl-site-structure.ts
index 713bba1432..be24d030f4 100644
--- a/skills/site-to-figma-components/scripts/crawl-site-structure.ts
+++ b/skills/site-to-figma-components/scripts/crawl-site-structure.ts
@@ -792,14 +792,16 @@ export class StructureCrawler {
   ) {}
 
   async crawl(options: CrawlOptions): Promise<SiteStructure> {
-    const site = new URL(options.site);
-    const viewports = options.viewports ?? [390, 1440];
-    const urls = this.resolvePages(site, options.pages, options.maxPages ?? 15);
     const pages: PageStructure[] = [];
     const failures: { url: string; viewport: number; error: string }[] = [];
     let first = true;
+    let origin: string;
+    const viewports = options.viewports ?? [390, 1440];
 
     try {
+      const site = new URL(options.site);
+      origin = site.origin;
+      const urls = this.resolvePages(site, options.pages, options.maxPages ?? 15);
       for (const url of urls) {
         for (const viewport of viewports) {
           if (!first) {
@@ -831,7 +833,7 @@ export class StructureCrawler {
     }
 
     return {
-      site: site.origin,
+      site: origin,
       capturedAt: this.now().toISOString(),
       viewports,
       pages,
@@ -1001,7 +1003,6 @@ export async function runCrawlCli(argv: string[], deps: CrawlCliDeps): Promise<n
       deps.makeDir(values.shots);
     }
 
-    const crawler = new StructureCrawler(await deps.createDriver(), deps.sleep);
     if (values.shoot) {
       if (!values.shots) {
         throw new Error('--shoot needs --shots, the folder to write screenshots to.');
@@ -1016,6 +1017,7 @@ export async function runCrawlCli(argv: string[], deps: CrawlCliDeps): Promise<n
       const targets: ShootTarget[] = inventory.items
         .filter((item) => item.status !== 'cut')
         .flatMap((item) => item.examples.slice(0, 1).map((e) => ({ id: item.id, ...e })));
+      const crawler = new StructureCrawler(await deps.createDriver(), deps.sleep);
       const written = await crawler.shoot(values.url, targets, values.shots, Number(values.delay));
       deps.stdout(
         `Wrote ${written.length} of ${targets.length} example screenshots to ${values.shots}\n`
@@ -1023,6 +1025,7 @@ export async function runCrawlCli(argv: string[], deps: CrawlCliDeps): Promise<n
       return 0;
     }
 
+    const crawler = new StructureCrawler(await deps.createDriver(), deps.sleep);
     const result = await crawler.crawl({
       site: values.url,
       pages: values.pages

From 1b8bf3b3806116712c52b686f4c255a3d462cc56 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Thu, 5 Nov 2026 14:01:04 +0000
Subject: [PATCH 3/3] fix(site-to-figma-components): pin tsx and use the
 repository installation for scratch-folder commands

<!-- coderabbit-ai-generated:v1 -->
---
 package-lock.json                        | 504 +++++++++++++++++++++++
 package.json                             |   1 +
 skills/site-to-figma-components/SKILL.md |  12 +-
 3 files changed, 511 insertions(+), 6 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 99065f5cfd..098920c491 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -62,6 +62,7 @@
         "puppeteer": "^25.11.0",
         "semver": "^7.8.5",
         "smol-toml": "^1.8.0",
+        "tsx": "4.23.15",
         "typescript": "^5.0.0",
         "typescript-eslint": "8.70.0",
         "yaml": "2.9.1",
@@ -6128,6 +6129,448 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
+      "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
+      "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
+      "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
+      "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
+      "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
+      "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
+      "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
+      "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
+      "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
+      "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
+      "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
+      "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
+      "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
+      "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
+      "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
+      "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
+      "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
+      "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
+      "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
+      "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
+      "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
+      "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
+      "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@eslint-community/eslint-utils": {
       "version": "4.10.1",
       "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.10.1.tgz",
@@ -14132,6 +14575,48 @@
         "tests/browser-compat"
       ]
     },
+    "node_modules/esbuild": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
+      "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.2",
+        "@esbuild/android-arm": "0.28.2",
+        "@esbuild/android-arm64": "0.28.2",
+        "@esbuild/android-x64": "0.28.2",
+        "@esbuild/darwin-arm64": "0.28.2",
+        "@esbuild/darwin-x64": "0.28.2",
+        "@esbuild/freebsd-arm64": "0.28.2",
+        "@esbuild/freebsd-x64": "0.28.2",
+        "@esbuild/linux-arm": "0.28.2",
+        "@esbuild/linux-arm64": "0.28.2",
+        "@esbuild/linux-ia32": "0.28.2",
+        "@esbuild/linux-loong64": "0.28.2",
+        "@esbuild/linux-mips64el": "0.28.2",
+        "@esbuild/linux-ppc64": "0.28.2",
+        "@esbuild/linux-riscv64": "0.28.2",
+        "@esbuild/linux-s390x": "0.28.2",
+        "@esbuild/linux-x64": "0.28.2",
+        "@esbuild/netbsd-arm64": "0.28.2",
+        "@esbuild/netbsd-x64": "0.28.2",
+        "@esbuild/openbsd-arm64": "0.28.2",
+        "@esbuild/openbsd-x64": "0.28.2",
+        "@esbuild/openharmony-arm64": "0.28.2",
+        "@esbuild/sunos-x64": "0.28.2",
+        "@esbuild/win32-arm64": "0.28.2",
+        "@esbuild/win32-ia32": "0.28.2",
+        "@esbuild/win32-x64": "0.28.2"
+      }
+    },
     "node_modules/escalade": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
@@ -22859,6 +23344,25 @@
       "dev": true,
       "license": "0BSD"
     },
+    "node_modules/tsx": {
+      "version": "4.23.15",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.15.tgz",
+      "integrity": "sha512-Yiex1Ovn8z2xPpOWckIiysV1SSyRMY9BkLF++q0yKiDxCqRhosKfMg3janKkiLBwZ5c/YryloKwGZcrEmtwxKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.28.0"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
     "node_modules/tunnel": {
       "version": "0.0.6",
       "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
diff --git a/package.json b/package.json
index ae45bfbcc0..00b3cda1bd 100644
--- a/package.json
+++ b/package.json
@@ -224,6 +224,7 @@
     "puppeteer": "^25.11.0",
     "semver": "^7.8.5",
     "smol-toml": "^1.8.0",
+    "tsx": "4.23.15",
     "typescript": "^5.0.0",
     "typescript-eslint": "8.70.0",
     "yaml": "2.9.1",
diff --git a/skills/site-to-figma-components/SKILL.md b/skills/site-to-figma-components/SKILL.md
index 9bd294c3a3..b21a327045 100644
--- a/skills/site-to-figma-components/SKILL.md
+++ b/skills/site-to-figma-components/SKILL.md
@@ -29,10 +29,10 @@ If a companion skill is missing, say so and stop rather than calling Figma tools
 ## Stage 1: Inventory
 
 1. **Agree the pages** with the reviewer: one or two public pages per template, from the site's sitemap. See [references/crawling.md](references/crawling.md).
-2. **Crawl** (scratch folder outside the repository):
+2. **Crawl** (scratch folder outside the repository). Install the repository's dependencies first and set `SITE_TO_FIGMA_REPO_ROOT` to the absolute path of its checkout. The `--prefix` option selects its pinned `tsx` while keeping output in the scratch folder:
 
    ```bash
-   npx tsx ${CLAUDE_SKILL_DIR}/scripts/crawl-site-structure.ts --url https://www.example.com \
+   npx --prefix "$SITE_TO_FIGMA_REPO_ROOT" tsx ${CLAUDE_SKILL_DIR}/scripts/crawl-site-structure.ts --url https://www.example.com \
      --pages '/,/tours/example/,/blog/,/?s=safari' --out site-structure.json --shots shots
    ```
 
@@ -40,9 +40,9 @@ If a companion skill is missing, say so and stop rather than calling Figma tools
 4. **Propose**, then take one example screenshot per item:
 
    ```bash
-   npx tsx ${CLAUDE_SKILL_DIR}/scripts/propose-inventory.ts site-structure.json --tokens variables.json \
+   npx --prefix "$SITE_TO_FIGMA_REPO_ROOT" tsx ${CLAUDE_SKILL_DIR}/scripts/propose-inventory.ts site-structure.json --tokens variables.json \
      --theme <theme-slug> --out inventory.json --report inventory.md --shots shots
-   npx tsx ${CLAUDE_SKILL_DIR}/scripts/crawl-site-structure.ts --url https://www.example.com \
+   npx --prefix "$SITE_TO_FIGMA_REPO_ROOT" tsx ${CLAUDE_SKILL_DIR}/scripts/crawl-site-structure.ts --url https://www.example.com \
      --shoot inventory.json --shots shots
    ```
 
@@ -67,7 +67,7 @@ Compare each frame with the live page at both widths, list the differences, and
 ## Stage 5: Hand-off
 
 ```bash
-npx tsx ${CLAUDE_SKILL_DIR}/scripts/write-manifest.ts inventory.json --nodes figma-nodes.json \
+npx --prefix "$SITE_TO_FIGMA_REPO_ROOT" tsx ${CLAUDE_SKILL_DIR}/scripts/write-manifest.ts inventory.json --nodes figma-nodes.json \
   --out manifest.json --markdown manifest.md
 ```
 
@@ -85,7 +85,7 @@ Add `--partial` while only some items are built. Hand `manifest.json` to `figma-
 
 ## Scripts
 
-TypeScript run with `tsx` (`npx tsx <script> --help`). Tests are in `scripts/__tests__/`: run `npm run test:site-to-figma-components` from the repository root.
+TypeScript run with `tsx` (`npx --prefix "$SITE_TO_FIGMA_REPO_ROOT" tsx <script> --help`). Tests are in `scripts/__tests__/`: run `npm run test:site-to-figma-components` from the repository root.
 
 | Script | Does |
 | --- | --- |