aiops: site-components - Rebuild a live site's components, patterns and templates in Figma #3992

AI Ops Summary

Rebuild projects need the live site's building blocks in Figma before anyone can design the new version. Today someone redraws buttons, cards, the header, the footer and each page type by hand.

This issue adds a skill, site-to-figma-components, that does it repeatably. It runs after site-to-design-tokens (#3990), which has already created the Figma variables, and its output feeds Pattern mode in figma-to-block-theme (#3989).

1. Inventory: crawl the chosen pages at 390px and 1440px, detect repeated structures by DOM shape and computed style, and classify each one as a component, pattern, template part or template. Record variants and interactive states.
2. Approval report: a Markdown report listing components with their variant properties, patterns, template parts and templates, with source pages, screenshots, the WordPress block each maps to, near duplicates to merge and one-offs to leave out.
3. Figma build, after approval: component sets first, then template parts and patterns from component instances, then one template frame per page type. Every value binds to a semantic variable.
4. Verify: compare each frame with the live page at both widths, and run the design system audit.
5. Hand-off: a manifest (JSON and Markdown) that maps each Figma node ID to its WordPress target.

Build Summary

Create skills/site-to-figma-components/ with one SKILL.md, references/ files and TypeScript helpers with tests: a structure crawler and clusterer, an inventory proposer and report writer, and a manifest writer. It reuses the site-to-design-tokens crawler patterns but imports nothing across skills. The shared contracts are the Figma variables (from #3990) and the manifest that Pattern mode reads (#3989).

Linked Stories/Tasks/PRs/Epic

• Depends on: aiops: site-tokens - Extract design tokens from an existing site for rebuilds #3990 (site-to-design-tokens: the variables every component binds to) and aiops: theme-build-skills - Consolidate the Figma and theme.json build skills into one skill #3989 (figma-to-block-theme: Pattern mode reads the manifest).
• Context: TSP-4 (TSP token extraction and WordPress hand-off). TSP is the pilot and reference project.

Milestones & Timeline

No milestone or dates set.

Problem / Opportunity

• Manual redraws. Each rebuild recreates components and pages by eye, so structure, naming and token use differ between projects.
• Repeats are hard to see. Without counting where a structure appears, it is hard to tell a real component from a one-off.
• The theme build needs a map. Figma frames only become patterns cleanly when each one is named and mapped to its WordPress part.

Approach / Solution

1. Crawl. Puppeteer behind an injectable browser interface, public pages only, one at a time with a pause. Never submit forms or log in. Read states from CSS, and trigger hover and focus where safe.
2. Cluster and classify.
   • Template part: on every page in the same position.
   • Pattern: a repeated section of several elements.
   • Component: a repeated single UI element with states.
   • Template: the page type a page belongs to.
3. Approval report. Zared approves, renames or cuts items. Nothing is written to Figma before approval.
4. Figma build. Follow figma-use, figma-generate-library and figma-generate-design. Component sets with variant properties, Auto Layout, text styles and variable bindings for every fill, stroke, gap, padding, radius, font and effect. Each component description names its WordPress block. Real site content and images. Page structure matches the TSP file dsDojfcCaLQSwLZaYqM0qu.
5. Verify. Screenshot comparison at both widths, and audit-design-system to fix unbound values, local overrides and detached instances.
6. Manifest. Figma node ID to template file, part, pattern slug or block style.
7. Tooling. TypeScript only, run with tsx. Jest tests in __tests__/ beside the scripts, with 80% coverage or more enforced. No .sh files, and no network, files or Figma in tests.

Acceptance Criteria

• AI workflow/agent described
• Problem/opportunity scoped
• Success metric defined: run against TSP, the skill produces an inventory Zared approves, and builds the header, footer, button and card component sets, one hero pattern and the home and single tour templates in the TSP Figma file, all bound to variables, with the audit clean
• Documentation updated
• PR uses correct branch prefix (aiops/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards
• One top-level SKILL.md with reference files and no nested SKILL.md; its description is 1,024 characters or fewer
• Nothing is written to Figma before the inventory is approved
• Every colour, size, space, radius and shadow binds to a variable; values with no token are listed for Zared, never invented
• The manifest maps cleanly into figma-to-block-theme Pattern mode
• Scripts are TypeScript with tests passing at 80% or more coverage, and the type check is clean; no .sh files
• package.json test script, CHANGELOG.md entry and routing references (ai-readiness-agent routing map, the two sibling skills' next-step notes) updated

Additional Context

Branch instructions

• Repository: lightspeedwp/.github
• Branch: aiops/git-2754-site-component-extraction, from develop. aiops: theme-build-skills - Consolidate the Figma and theme.json build skills into one skill #3989 and aiops: site-tokens - Extract design tokens from an existing site for rebuilds #3990 are not merged yet, so read them from their branches; there is no code dependency. Don't use Linear's suggested feature/… name.
• Expected file changes (provisional):
  • Create skills/site-to-figma-components/, containing SKILL.md, references/, agents/openai.yaml, and scripts/ with __tests__/
  • Edit package.json to add a test script
  • Edit CHANGELOG.md
  • Edit the routing references

Rules

• Archive superseded Figma items rather than deleting them, and check prototype link destinations before moving anything.
• No em dashes in Figma copy or document text.

Definition of Ready (DoR)

• AI ops goal described
• Area/action mapped
• Acceptance criteria listed
• Estimate added

Definition of Done (DoD)

• All acceptance criteria met
• Solution/automation verified
• Documentation updated
• PR uses correct branch prefix (aiops/)
• PR uses the correct PR template based on type:aiops PR label or linked issue type or linked issue type:aiops label
• Branch deleted after merge
• Linked issue(s) updated with latest status and closed after merge,
• The related epic should not be closed, instead updated with a comment to reflect the closed issue