@respira/wordpress-mcp-server 7.3.0 → 7.4.0

package/skills/design-system-synthesizer/SKILL.md

@@ -0,0 +1,395 @@
+# Design System Synthesizer
+
+**Version:** 1.2.0
+**Updated:** 2026-06-30
+**Freshly updated:** v1.2.0 makes the synthesis safe and source-traceable end to end. Reads tokens from the actual builder content (`respira_extract_builder_content`) and theme files (`respira_read_theme_file` on style.css / theme.json) rather than guessing. Persists the design_system JSON via `respira_get_option` (diff first) + `respira_update_option`, and takes a `respira_get_snapshot` checkpoint before building the visible style-guide page with `respira_build_page` so the write is explicitly reversible (restore the snapshot, delete the draft). Applying tokens to a builder's global colors and typography is described in plain words since there is no confirmed MCP tool name for that path yet.
+**Category:** intelligence
+**Status:** stable
+**Requires:** Respira for WordPress plugin 7.1+ + MCP server
+
+---
+
+## Description
+
+Read a WordPress site's representative pages, theme files, and media library to extract a complete, reusable **design system** — logo, color palette, typography, spacing scale, component patterns. Persist it to the site so every future content-creation skill references it, and every new page Claude builds matches the existing brand.
+
+This is the foundation for on-brand AI-generated content. Without a design system, the agent guesses at colors, fonts, and spacing — and the result looks like every other AI-generated WordPress page. With a design system, the agent has explicit tokens to use, and new pages snap to the brand.
+
+---
+
+## What it produces
+
+A structured `design_system` artifact stored at the site level. Schema:
+
+```json
+{
+  "version": "1.2.0",
+  "synthesized_at": "2026-05-24T14:30:00Z",
+  "synthesized_from": ["/", "/about/", "/services/web-design/", "/blog/sample-post/", "/contact/"],
+  "brand": {
+    "logo_url": "https://example.com/wp-content/uploads/2025/logo.svg",
+    "logo_dark_url": null,
+    "favicon_url": "https://example.com/favicon.ico",
+    "social_card_url": "https://example.com/wp-content/uploads/2025/og-default.jpg",
+    "wordmark_text": "Acme Studio"
+  },
+  "colors": {
+    "primary": "#2563EB",
+    "secondary": "#0F172A",
+    "accent": "#F59E0B",
+    "neutral_900": "#0F172A",
+    "neutral_700": "#334155",
+    "neutral_500": "#64748B",
+    "neutral_300": "#CBD5E1",
+    "neutral_100": "#F1F5F9",
+    "background": "#FFFFFF",
+    "background_alt": "#F8FAFC",
+    "text_primary": "#0F172A",
+    "text_secondary": "#475569",
+    "link": "#2563EB",
+    "success": "#10B981",
+    "warning": "#F59E0B",
+    "error": "#EF4444"
+  },
+  "typography": {
+    "heading_family": "Söhne, ui-sans-serif, system-ui, sans-serif",
+    "heading_weight": 700,
+    "h1_size": "3.5rem",
+    "h2_size": "2.5rem",
+    "h3_size": "1.875rem",
+    "h4_size": "1.5rem",
+    "h5_size": "1.25rem",
+    "h6_size": "1rem",
+    "body_family": "Söhne, ui-sans-serif, system-ui, sans-serif",
+    "body_weight": 400,
+    "body_size": "1rem",
+    "body_line_height": 1.65,
+    "mono_family": "JetBrains Mono, ui-monospace, monospace",
+    "letter_spacing_heading": "-0.02em",
+    "letter_spacing_body": "0"
+  },
+  "spacing": {
+    "scale_base": 4,
+    "scale_steps": [4, 8, 12, 16, 24, 32, 48, 64, 96, 128],
+    "section_padding_y": "96px",
+    "section_padding_x": "24px",
+    "container_max_width": "1280px"
+  },
+  "components": {
+    "button_primary": {
+      "background": "primary",
+      "color": "#FFFFFF",
+      "padding": "12px 24px",
+      "border_radius": "8px",
+      "font_weight": 600
+    },
+    "button_secondary": { /* ... */ },
+    "card": {
+      "background": "background",
+      "border": "1px solid neutral_300",
+      "border_radius": "12px",
+      "padding": "32px",
+      "shadow": "0 1px 3px rgba(0,0,0,0.05)"
+    },
+    "hero_pattern": "centered_with_kicker_h1_subtitle_2cta",
+    "section_pattern": "wide_two_column_image_left"
+  },
+  "voice_hints": {
+    "person": "we",
+    "formality": "approachable_professional",
+    "sentence_length_avg_words": 14,
+    "avoids": ["exclamation marks", "marketing superlatives"]
+  }
+}
+```
+
+The artifact is stored via `respira_update_option('respira_design_system', ...)` for v7.1. v7.2 may migrate this to a dedicated `respira_intelligence_artifacts` table if cross-site rollup is needed.
+
+---
+
+## When to Use
+
+- First time setting up an AI workflow for an existing site — generate the design system so future content is on-brand
+- Site rebrand — re-synthesize after the new brand lands so the AI catches the new tokens
+- Before running content-creation skills (`build_page`, page generators) so the new pages match the brand
+- Quarterly refresh — re-synthesize to capture brand drift
+
+---
+
+## Trigger Phrases
+
+- "build a design system for my site"
+- "extract my brand"
+- "synthesize a design system"
+- "create my design tokens"
+- "what does my site look like"
+- "capture my brand"
+- "build my style guide"
+- "extract design tokens"
+
+---
+
+## Execution Workflow
+
+### Step 1 — Confirm site
+
+Call `respira_get_active_site` + `respira_get_site_context`. Note WordPress version and active theme — theme.json or customizer settings may already expose some tokens.
+
+### Step 2 — Pick representative pages
+
+Call `respira_list_pages`. From the list, pick 5–10 pages that should represent the brand:
+
+- The homepage (always)
+- The about page (always if present)
+- One typical service or product page
+- One typical blog post
+- The contact page
+- One landing page if any exists
+
+If the site has fewer than 5 pages, use whatever exists. If more than 10, sample by recency and front-page-link weight.
+
+### Step 3 — Extract logo + brand imagery
+
+Call `respira_list_media` filtered for logo-like names (`logo`, `wordmark`, `brand`, `favicon`). Also check site identity via `respira_get_option('site_icon')` for the favicon and `respira_get_option('custom_logo')` for the custom logo URL.
+
+### Step 4 — Read theme stylesheet for CSS variables
+
+Call `respira_read_theme_file('style.css')` and `respira_read_theme_file('theme.json')` if FSE theme. Extract any `:root` CSS custom properties (often the cleanest source of brand tokens).
+
+### Step 5 — Extract each picked page's builder content
+
+For each of the 5–10 picked pages:
+
+1. `respira_extract_builder_content(page_id)` — get the builder-native structure
+2. Note colors used (background, text, buttons, links)
+3. Note typography (heading sizes, families, weights)
+4. Note spacing (section padding, gutters, container widths)
+5. Note component patterns (hero layout, card style, navigation pattern)
+
+### Step 6 — Synthesize
+
+Aggregate the per-page observations into the structured `design_system` schema (see "What it produces" above). When multiple pages disagree on a value, prefer:
+
+- The homepage's choice for hero patterns
+- The most common value across all pages for body typography
+- The CSS custom property value if defined (overrides per-page observation)
+- The theme.json value if FSE theme (overrides CSS custom property)
+
+For colors, identify primary / secondary / accent by frequency-of-use + role (background-of-CTA = primary; link color = link; large-text color = primary if it differs from body). Generate a neutral scale (100 → 900) by sampling backgrounds, borders, text colors.
+
+### Step 7 — Show the synthesized system to the user
+
+Output a human-readable summary:
+
+```markdown
+## Design system synthesized for {site_url}
+
+**Brand**
+- Logo: ![](logo_url)
+- Wordmark: {wordmark_text}
+
+**Colors**
+- Primary: {primary} ▮
+- Secondary: {secondary} ▮
+- Accent: {accent} ▮
+- Neutrals: {neutral_100} → {neutral_900} (9-step scale)
+
+**Typography**
+- Headings: {heading_family} {heading_weight}, H1 {h1_size}
+- Body: {body_family} {body_weight}, {body_size}/{body_line_height}
+
+**Spacing**
+- Base: {scale_base}px, scale: {scale_steps}
+- Section padding: {section_padding_y} vertical, container max {container_max_width}
+
+**Component patterns observed**
+- Hero: {hero_pattern}
+- Section: {section_pattern}
+- Button primary: {button_primary description}
+- Card: {card description}
+```
+
+Ask the user to confirm or correct anything.
+
+### Step 8 — Persist the data
+
+After confirmation, call `respira_update_option('respira_design_system', <json>)`. Confirm with `respira_get_option('respira_design_system')`.
+
+### Step 9 — Generate the visible style-guide page
+
+The JSON in `wp_options` is the machine source of truth, but it's invisible to humans. Step 9 builds a real WordPress page on the site that **renders the synthesized tokens visually** — so the user can see their design system, send a link to teammates, and edit it like any other page.
+
+#### Snapshot before writing (required)
+
+Building the style-guide page is the first write this skill makes to the live site. Take a checkpoint first so it's explicitly reversible:
+
+```
+Tool: respira_get_snapshot
+Note the returned snapshot_id — that's the rollback handle.
+```
+
+If anything looks wrong after the build, roll back cleanly:
+
+- `respira_restore_snapshot(snapshot_id)` to undo site-level changes, and
+- delete the draft style-guide page you created (`respira_delete_page(page_id)`).
+
+The persisted `respira_design_system` option is not destructive (Step 8 already diffed before overwriting), so the snapshot here is about the page build, not the option.
+
+#### Page settings
+
+- **Title:** "Design System" (overridable)
+- **Slug:** `/design-system/` (overridable; check via `respira_list_pages` and append `-2` if conflict)
+- **Status:** `private` by default (visible only to logged-in editors). Ask the user: *"Publish as private (admin-only preview) or public?"* — default to private.
+- **Excluded from sitemap, robots noindex** by default (so even if accidentally published, it doesn't pollute search).
+- **Builder:** the active builder (Bricks / Elementor / Divi / Gutenberg / Oxygen / Breakdance / etc.) — never raw HTML. Use `respira_get_builder_inline_schemas` to confirm available modules before building.
+
+#### Page structure (the section spine)
+
+Build the page with `respira_build_page` using this section spine, mapping each section to the active builder's native modules:
+
+1. **Hero**
+   - Eyebrow: "Design System · synthesized {synthesized_at} from {n} pages"
+   - H1: "{brand.wordmark_text} Design System" (or "Design System" if no wordmark)
+   - Subtitle: "The visual foundation every page generated on this site references."
+   - Logo image (from `brand.logo_url`) prominently displayed
+
+2. **Brand identity**
+   - Logo card with full logo, dimensions, file type
+   - Favicon swatch
+   - Social card preview if `brand.social_card_url`
+   - Wordmark in heading typography if `brand.wordmark_text`
+
+3. **Color palette**
+   - 4 primary swatches (primary / secondary / accent / background) — each a large color block with hex code, role name, and "use for" guidance
+   - 9-step neutral scale — horizontal strip from neutral_100 → neutral_900 with hex codes
+   - Semantic colors row (link / success / warning / error) — smaller swatches
+
+4. **Typography**
+   - **Heading sample:** all six heading levels (H1 → H6) rendered in actual `heading_family` + `heading_weight` + their specified sizes, each labeled with the size value
+   - **Body sample:** a real paragraph in `body_family` + `body_weight` + `body_size` + `body_line_height` so the user can SEE the body reading experience
+   - **Mono sample:** a code block in `mono_family`
+   - Side panel listing the font stacks verbatim (with fallbacks) and font-loading note (Google Fonts / Adobe Fonts / self-hosted)
+
+5. **Spacing scale**
+   - Visual blocks for each step in `scale_steps` — a colored rectangle whose height matches the step value, labeled with the pixel value
+   - "Section padding" block showing actual section padding visually
+   - "Container max-width" line showing the max-width as a horizontal ruler
+
+6. **Components**
+   - Button primary + button secondary rendered in actual styles (background, color, padding, border-radius)
+   - Card example with real content ("Card title", short body, button)
+   - Hero pattern description with a wireframe sketch
+   - Section pattern description with a wireframe sketch
+
+7. **Voice hints** (if synthesized)
+   - Person used
+   - Formality descriptor
+   - Avoided words (the strongest signal)
+   - Cross-link to the Brand Voice Synthesizer skill — *"For the full brand voice including signature phrases, signature openers, and a real paragraph example, run the [Brand Voice Synthesizer](/skills/brand-voice-synthesizer)."*
+
+8. **Footer**
+   - Synthesis metadata: source pages list, synthesized timestamp, version
+   - "Edit this page" link to the builder edit URL
+   - "Re-synthesize" instructions: *"Run the Design System Synthesizer skill again any time to refresh. The artifact will be diffed before overwriting."*
+
+#### Builder mapping
+
+`respira_build_page` accepts a section spine and renders it as native builder modules. For each section above, the page builder picks the closest module:
+
+| Section | Bricks | Elementor | Divi 5 | Gutenberg |
+|---|---|---|---|---|
+| Color swatches | div block grid + heading + text | Inner Section + Heading + Text widgets | Row + Column + Code module | core/columns + core/group blocks |
+| Heading samples | heading element ×6 | Heading widget ×6 | Text module ×6 | core/heading blocks ×6 |
+| Button samples | button element | Button widget | Button module | core/buttons block |
+| Spacing blocks | div block with explicit height | Inner Section with margin | Code module with custom CSS | core/spacer blocks |
+
+Do NOT render with raw HTML even when the builder doesn't have a perfect 1:1 mapping. If a section can't be cleanly built (e.g. the spacing-scale visualization requires inline styles the builder doesn't expose), fall back to a labeled bullet list — never a `<div>` blob.
+
+#### Output
+
+After page creation, output:
+
+```markdown
+## ✓ Design system saved + style-guide page created
+
+**Machine source of truth:** `wp_options.respira_design_system` (queryable via `respira_get_option`)
+
+**Human view:** {page_url} · status: private (editors only)
+
+**Open it now:** [{page_title} in the editor]({builder_edit_url})
+
+**Promote to public:** call `respira_update_page(id={page_id}, status='publish')` if you want this visible on your site as a /design-system/ landing.
+
+**Re-sync any time:** run this skill again. Existing data is diffed and the page is regenerated (with the option to keep customizations).
+
+**Roll back this build:** `respira_restore_snapshot({snapshot_id})` then `respira_delete_page({page_id})`.
+```
+
+---
+
+## How other skills use the design system
+
+Once persisted, future skills (Page Template Library, Brand Voice Synthesizer, future content-generation skills) should call `respira_get_option('respira_design_system')` at the top of their workflow. They use the tokens to:
+
+- Pick colors when generating new sections (use primary, secondary, accent — never invented hex values)
+- Match typography when generating headings (heading_family, heading_weight, sizes)
+- Match spacing when laying out sections (use the spacing scale, not arbitrary pixel values)
+- Match component patterns when generating heros, cards, buttons (reference button_primary etc.)
+
+### Applying tokens to the builder's own global colors / typography
+
+Some builders (Bricks, Elementor, Divi, Oxygen) keep their own global color palette and global typography settings, separate from the page-level styles. Pushing the synthesized tokens into those global settings means future hand-edits in the builder also snap to the brand.
+
+There is **no confirmed MCP tool name** for writing a builder's global palette today, so do not invent one (e.g. do not assume a `respira_*` design-system tool exists). The real path is the plugin's design-token import layer on the WordPress side (`includes/bricks-intelligence/class-design-token-import.php` and the design-system REST handler in `includes/class-respira-bricks-tools.php`), reached through the site, not a named MCP tool. In practice:
+
+- Persist the `respira_design_system` option (Step 8) — that is the canonical, tool-confirmed write.
+- Build the visible style-guide page (Step 9) so the tokens are visible and editable.
+- For pushing tokens into a builder's *global* palette/typography, describe the change to the user in plain words and let them apply it (or trigger the plugin's design-token import). Only reference a builder-token tool by name once you have grepped `includes/` and confirmed the exact registered name.
+
+This is the foundation. Every other content skill stands on it.
+
+---
+
+## Hard rules
+
+- Never invent design tokens. Every color, font, size, and pattern in the artifact must trace to an observation in the source pages, theme files, or media. If a token can't be inferred, leave it null — don't guess.
+- Never overwrite an existing design system silently. If `respira_get_option('respira_design_system')` returns existing data, show the user the diff before overwriting.
+- The logo URL must be an absolute URL. Use `wp_get_attachment_url()` semantics, not a relative path.
+- Color values must be hex (`#RRGGBB`). Convert `rgb()`, `rgba()`, named colors to hex.
+- Font families preserve the full font-stack as written in CSS (with fallbacks), not just the primary family name.
+
+---
+
+## Tooling
+
+**Reading the brand (source of truth)**
+- `respira_get_active_site`
+- `respira_get_site_context`
+- `respira_list_pages`
+- `respira_list_media`
+- `respira_get_option` — read `site_icon` / `custom_logo`, and check for an existing `respira_design_system`
+- `respira_extract_builder_content` — per-page tokens from the builder-native structure
+- `respira_read_theme_file` — `style.css` `:root` custom properties and `theme.json` (FSE)
+
+**Persisting + rendering**
+- `respira_update_option` — write `respira_design_system` (diff first via `respira_get_option`)
+- `respira_get_builder_inline_schemas` — confirm available modules before building
+- `respira_get_snapshot` — checkpoint before the page build (rollback handle)
+- `respira_build_page` — render the visible style-guide page in the active builder
+- `respira_restore_snapshot` + `respira_delete_page` — explicit rollback of the build
+
+Applying tokens to a builder's *global* colors/typography has **no confirmed MCP tool name** — describe it in plain words (see "Applying tokens to the builder's own global colors / typography" above). Never invent a builder-token tool name.
+
+---
+
+## Telemetry
+
+Records: site URL hash, number of pages sampled, builder active, theme name, colors detected count, typography sources used (theme.json / CSS variables / per-page observation), success/failure, total duration. No actual color values, font names, or logo URLs are sent.
+
+Endpoint: `POST https://www.respira.press/api/skills/track-usage`
+
+---
+
+## Future (v7.2)
+
+Storage will migrate from `wp_options` to a dedicated `respira_intelligence_artifacts` table for cross-site rollups and Studio-tier multi-site dashboards. The schema above is stable — the storage layer change is transparent to consuming skills.

package/skills/design-system-synthesizer/metadata.json

@@ -0,0 +1,57 @@
+{
+  "name": "Design System Synthesizer",
+  "slug": "design-system-synthesizer",
+  "icon": "🎨",
+  "category": "intelligence",
+  "description": "Read a WordPress site's representative pages, theme files, and media library to extract a complete reusable design system — logo, color palette, typography, spacing scale, component patterns. Persist it AND generate a visible style-guide page on the site that renders the tokens visually.",
+  "author": "Respira Team",
+  "author_url": "https://respira.press",
+  "trigger": "build a design system for my site",
+  "requires_respira": true,
+  "requires_woocommerce_addon": false,
+  "requires_accessibility_addon": false,
+  "is_read_only": false,
+  "is_duplicate_first": false,
+  "version": "1.1.0",
+  "last_updated": "2026-05-24",
+  "tools_used": [
+    "respira_get_active_site",
+    "respira_get_site_context",
+    "respira_list_pages",
+    "respira_list_media",
+    "respira_get_option",
+    "respira_update_option",
+    "respira_read_theme_file",
+    "respira_extract_builder_content",
+    "respira_get_builder_info",
+    "respira_get_builder_inline_schemas",
+    "respira_build_page",
+    "respira_update_page"
+  ],
+  "detects": [
+    "logo_url",
+    "favicon",
+    "wordmark_text",
+    "primary_color",
+    "secondary_color",
+    "accent_color",
+    "neutral_scale",
+    "heading_typography",
+    "body_typography",
+    "spacing_scale",
+    "section_patterns",
+    "component_patterns",
+    "button_styles",
+    "card_styles"
+  ],
+  "generates": [
+    "design_system_json",
+    "design_system_summary_markdown",
+    "persisted_site_option",
+    "visible_style_guide_page",
+    "color_swatches_rendered",
+    "typography_samples_rendered",
+    "spacing_scale_visualized",
+    "component_previews"
+  ]
+}

package/skills/figma-to-elementor/SKILL.md

@@ -0,0 +1,204 @@
+# Figma to Elementor
+
+Rebuilds a Figma frame as a real, editable Elementor page on your WordPress site. Reads the Figma node tree (layers, auto-layout, text, colors, images), maps each node to its closest Elementor widget or container, generates a build plan for approval, and writes clean Elementor JSON to a draft duplicate so nothing live is touched. Use this skill whenever someone wants to turn a Figma design into an Elementor page, build a Figma mockup in Elementor, or hand a design off to WordPress without rebuilding it by hand.
+
+## What This Skill Does
+
+Figma and Elementor describe a layout in very different ways. Figma stores a tree of nodes (frames, text, shapes, images) with auto-layout, constraints, and design tokens; Elementor stores a nested JSON tree in `_elementor_data` of sections/columns (or flex containers) and widgets. This skill bridges that gap by reading every Figma node, understanding its role, and recreating it as the right Elementor element with matching styling.
+
+**Handles:**
+- Frames and auto-layout → Elementor flex containers (or section/column on older sites): direction, gap, padding, alignment
+- Text nodes → Heading (level inferred from font size) or Text Editor widgets
+- Rectangles/ellipses with image fills → Image widgets; plain shapes → containers; vectors/icons → Image or Icon
+- Lines → Divider widgets
+- Repeated card/list patterns → recognised by layer name + structure: FAQ → Accordion, image rows → Gallery/Carousel, number+label → Counter, icon rows → Social Icons
+- Typography (font family, size, weight, line-height, letter-spacing, transform, alignment)
+- Colors (solid fills with opacity; linear/radial gradients with stops and angle)
+- Spacing (padding, gaps), borders, border-radius (per-corner), box shadows, opacity
+- Image fills downloaded from Figma and sideloaded into the WordPress media library
+- The Figma color palette mapped to Elementor global colors so the design system carries over
+
+**Preserves:**
+- Text content, links, and media
+- Layout structure and nesting (with junk single-child wrappers collapsed)
+- The visual styling listed above, as closely as Elementor's rendering allows
+
+## What This Skill Does NOT Do
+
+- **Pixel-perfect recreation** — Elementor renders with the browser box model, not Figma's canvas. Spacing and alignment land close but expect light manual fine-tuning.
+- **Figma components with overrides / variants** — instances are flattened to inline content; component logic and variant swapping are flagged, not reproduced.
+- **Prototyping and interactions** — Figma's click-throughs, smart-animate, and overlays have no Elementor equivalent and are skipped.
+- **Complex vector art, masks, and blend modes** — exported as flattened images where possible, otherwise flagged.
+- **Auto-generated responsive breakpoints** — the build targets desktop from the frame; tablet/mobile are noted for manual adjustment unless the design provides explicit responsive frames.
+- **Theme builder parts** — headers, footers, archive/single templates are out of scope; this builds page content.
+- **Fetching Figma for you without access** — you must have Figma read access available to your agent (see Requirements).
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- Elementor active on the target site (to write the page)
+- **Figma read access from your agent** — either a connected Figma MCP, or a Figma file/frame URL plus a Figma personal access token you can paste
+- Write access to create a draft duplicate with the new Elementor content
+
+## Trigger Phrase
+
+- "figma to elementor"
+
+## Alternative Triggers
+
+- "build this figma design in elementor"
+- "convert figma to elementor"
+- "turn my figma frame into an elementor page"
+- "rebuild this figma mockup in wordpress with elementor"
+- "import figma into elementor"
+
+## Source: Figma
+
+Figma exposes a design as a tree of nodes. Read it with whatever Figma access the agent has: a connected Figma MCP, or the Figma REST API (`GET /v1/files/:key/nodes?ids=:id` for the selected frame, `GET /v1/files/:key/images` to export image fills) using a personal access token.
+
+Key node shapes to read:
+- `type`: `FRAME`, `GROUP`, `TEXT`, `RECTANGLE`, `ELLIPSE`, `VECTOR`, `LINE`, `COMPONENT`, `INSTANCE`
+- `layoutMode` (`HORIZONTAL`/`VERTICAL`/none), `itemSpacing`, `paddingLeft/Right/Top/Bottom`, `primaryAxisAlignItems`, `counterAxisAlignItems`, `layoutSizingHorizontal/Vertical` (`FILL`/`FIXED`/`HUG`)
+- `style` for text: `fontFamily`, `fontSize`, `fontWeight`, `lineHeightPx`/`lineHeightPercent`, `letterSpacing`, `textAlignHorizontal`, `textCase`, `textDecoration`
+- `fills` (SOLID with `color` + `opacity`; gradients with `gradientStops` + `gradientHandlePositions`), `strokes` + `strokeWeight`, `cornerRadius`/`rectangleCornerRadii`, `effects` (DROP_SHADOW/INNER_SHADOW), `opacity`
+- `characters` (text content), and IMAGE fills (mark for download)
+
+Pick one top-level frame at a time. Each direct child of that frame becomes an independently editable Elementor section/container.
+
+## Target: Elementor
+
+Respira writes Elementor as a simplified tree of `{ type, widget, settings, elements }`, which the plugin normalizes/validates into real `_elementor_data` (v3 sections/columns or v4 atomic flex containers, auto-detected). You never hand-write raw Elementor JSON — you describe the tree and Respira emits the canonical shape.
+
+- Containers: `{ type: "container", settings: {...}, elements: [...] }` (flex) or `section` + `column` on v3 sites
+- Widgets: `{ type: "widget", widget: "heading", settings: { title: "..." } }`, `text-editor` (`editor`), `image`, `button`, `icon`, `divider`, `accordion`, `image-gallery`, `image-carousel`, `counter`, `social-icons`
+- Write with `respira_build_page` (whole frame → page) or `respira_inject_builder_content` (append sections); `respira_convert_html_to_builder` is a fallback bridge; `respira_find_element`/`respira_update_element` for refinement.
+
+## Mapping (Figma → Elementor)
+
+**Node type:**
+- `TEXT` → `heading` if it reads like a heading (large/bold), else `text-editor`. Infer heading level by font size: ≥48 h1, ≥36 h2, ≥28 h3, ≥20 h4, ≥16 h5, else h6.
+- `FRAME`/`GROUP`/auto-layout → `container` (flex). Flatten groups with no fills/strokes/effects; keep groups that carry styling.
+- `RECTANGLE`/`ELLIPSE` with an IMAGE fill → `image`; otherwise → styled `container`.
+- `VECTOR`/shape → `image` (export from Figma) or `icon`; `LINE` → `divider`.
+- `INSTANCE`/`COMPONENT` → treated as a container; flag if it relies on overrides/variants.
+
+**Auto-layout → flex container:**
+- `layoutMode` HORIZONTAL → row, VERTICAL → column
+- `itemSpacing` → gap; `padding*` → padding (per side, linked when equal)
+- `primaryAxisAlignItems` → justify-content, `counterAxisAlignItems` → align-items (MIN→flex-start, CENTER→center, MAX→flex-end, SPACE_BETWEEN→space-between)
+- child `layoutSizing` FILL → flex-grow, FIXED → fixed size, HUG → shrink-to-fit
+
+**Typography → Elementor typography controls:** family, size (px), weight, line-height (px or %), letter-spacing, text-transform, text-decoration, alignment.
+
+**Color:** solid fill → text/background color (+ opacity when <1). Gradient → gradient type (linear/radial), color stops with positions, and an angle computed from `gradientHandlePositions`.
+
+**Box:** `strokes`+`strokeWeight` → border; `cornerRadius`/`rectangleCornerRadii` → border-radius (per-corner when provided); `effects` → box-shadow (offset/blur/spread/color); `opacity` → element opacity.
+
+**Smart widgets (by layer name + structure):** a list whose items each hold a title + body → Accordion; a row that is ≥70% images → Gallery or Carousel (by layer name); a number + label pair → Counter; a row of 2+ icon shapes whose names match platforms → Social Icons. When unsure, fall back to plain containers + widgets.
+
+**Images:** collect IMAGE fills, export from Figma, sideload with `respira_sideload_image`, and set the resulting media on the Elementor image widget/background.
+
+**Design system:** map the frame's distinct fill colors to Elementor global colors (primary/secondary/accent/text) so later edits stay on-brand.
+
+## Execution Workflow
+
+### Phase 1: Read and audit
+1. Verify Respira + MCP via `respira_get_site_context`; confirm Elementor is active via `respira_list_plugins`. If not connected, stop and show setup guidance.
+2. Read the chosen Figma frame's node tree via the agent's Figma access.
+3. Build an inventory: node-type counts, smart-widget candidates, image fills to download, and flagged items (components with overrides, complex vectors/masks, prototyping, gradients beyond linear/radial).
+
+### Phase 2: Build plan
+Present a short plan and get confirmation:
+- Which frame → which new page title
+- Mapping summary table (Figma node → Elementor element, Auto/Manual)
+- Flagged items needing manual attention
+- The global-color palette that will be created
+
+> Ready to build? I'll create a **draft duplicate / new draft page** and write the Elementor version there. Nothing live is touched.
+> 1. Build the whole frame
+> 2. Build section by section (review as we go)
+> 3. Just keep this plan
+
+### Phase 3: Build
+For the approved frame:
+1. Take a snapshot when available (`respira_get_snapshot`) and create a draft target with `respira_create_page_duplicate` (or a new draft page).
+2. Map the Figma tree to the simplified Elementor tree using the mapping above; collapse empty wrappers.
+3. Sideload images (`respira_sideload_image`) and set them on the matching widgets.
+4. Create/align global colors so the palette carries over.
+5. Write with `respira_build_page` (or `respira_inject_builder_content` section by section). Annotate any unmapped node with a clear migration note.
+6. Report status for the frame before moving on.
+
+### Phase 4: Verify
+1. Summarize: sections/widgets built, images imported, items flagged.
+2. Provide the wp-admin/Elementor editor link to the draft.
+3. Give a checklist: open in the Elementor editor, check tablet/mobile, confirm images load, test links/buttons, review flagged items, compare against the Figma frame.
+
+## Safety Model
+
+- Read-only Figma analysis and a full plan before any write
+- Explicit confirmation before building
+- Always writes to a **draft duplicate / new draft** — never an existing live page
+- Never auto-publishes
+- Snapshot before write when available; rollback path is to delete the draft
+- Original Figma file is read-only and never modified
+
+## Honest Disclaimer
+
+This skill rebuilds a Figma frame as an editable Elementor draft page.
+
+It cannot:
+- Guarantee pixel-perfect parity (different rendering engines)
+- Reproduce Figma components/variants, prototyping, or complex masks/effects
+- Auto-generate full responsive breakpoints from a single desktop frame
+- Replace manual QA in the Elementor editor
+
+It can:
+- Turn a clean, auto-layout Figma frame into a structured Elementor page in minutes
+- Preserve text, images, layout, typography, and color
+- Carry the palette into Elementor global colors
+- Flag exactly what needs a human, and keep everything live completely safe
+
+## Tooling
+
+**Figma read** (agent-side): a connected Figma MCP, or the Figma REST API with a personal access token.
+
+**Respira tools**
+- `respira_get_site_context`
+- `respira_list_plugins`
+- `respira_get_builder_info`
+- `respira_create_page_duplicate`
+- `respira_get_snapshot`
+- `respira_sideload_image`
+- `respira_build_page`
+- `respira_inject_builder_content`
+- `respira_convert_html_to_builder`
+- `respira_find_element`
+- `respira_update_element`
+
+## Telemetry
+
+After run completion, send fire-and-forget usage tracking to:
+
+- `POST https://www.respira.press/api/skills/track-usage`
+
+Include:
+- `skill_slug = figma-to-elementor`
+- site/version context
+- duration and success
+- frames built, widgets created, images imported, items flagged counts
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- Design System Synthesizer (turn the imported palette/type into a site-wide system)
+- HTML to Bricks (the same idea for a different target builder)
+- SEO & AEO Amplifier (optimize the new page once it is built)
+- WordPress Site DNA (understand the target site before importing)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/figma-to-elementor