--- name: wordpress-theme-to-astro description: Rebuild a WordPress theme as an Astro/EmDash theme for Cloudflare-native migrations. Use when converting an existing WordPress site's visual layout, theme assets, PHP templates, menus, widgets, custom CSS, or screenshots into source-visible Astro components. Covers theme-source audit, design-token extraction, component mapping, unsupported plugin handling, and visual parity verification. --- # WordPress Theme to Astro Use this skill after or alongside WordPress content migration when the target site must look like the source site. The goal is a **source-inspired or parity-focused Astro rebuild**, not running WordPress PHP on Cloudflare. ## Promise Boundary Say: > We rebuild the WordPress theme as clean Astro + EmDash components and verify it against captured source pages. Do not say: > We automatically convert every WordPress theme/plugin 1:1. WordPress PHP, hooks, page builders, and plugin-rendered widgets are reference material. The target is Astro code with EmDash content bindings. ## Required Inputs Minimum: - Public source URL. - EmDash Exporter probe/export artifact or verified REST probe report. - Active `theme.zip` from the WordPress site. - `.migration/theme-analysis.json` generated by the template CLI. - List of pages that must visually match. Recommended: - Child theme ZIP, if active. - Full `wp-content/` backup or uploads backup. - Plugin list and active theme name. - Customizer CSS/export. - Menu/widget export or REST access. - Top URLs from sitemap/Search Console. - Source screenshots for homepage, post page, content page, archive page, and mobile nav. - WXR export as fallback when EmDash Exporter is unavailable. Do not request secrets in chat. Application Passwords may be used for read-only discovery through the template CLI with `--password-prompt` or `--password-stdin`. Theme source should come from the operator as `theme.zip`; do not expect an Application Password to download theme files. ## Workflow 1. **Read local contracts**: `README.agent.md`, `docs/llms.txt`, `microservices.template.json`, `docs/api-boundary.md`, `.migration/theme-analysis.json`, `.migration/theme-conversion.json`, and existing `src/theme`/layout files if present. 2. **Classify the goal**: - `source-inspired`: match brand, typography, layout structure, and key components. - `parity-focused`: match selected pages closely with screenshot diff gates. - `redesign-with-continuity`: preserve brand signals but improve UX. 3. **Inventory source theme**: - classic templates: `index.php`, `front-page.php`, `home.php`, `single.php`, `page.php`, `archive.php`, `header.php`, `footer.php`, `functions.php` - block theme files: `theme.json`, `templates/*.html`, `parts/*.html`, `block.json`, `build/blocks/*/render.php` - assets: CSS, JS, fonts, icons, images - menus/widgets/customizer CSS - plugin/page-builder dependencies 4. **Capture reference pages** at fixed widths: `390`, `768`, and `1440`. Store under `migration-reports/screenshots/source/`. If browser capture fails, record a blocked-capture note in `migration-reports/theme-parity.json` and continue with manual visual review. 5. **Extract design tokens** into `src/theme/tokens.css`: - colors, fonts, font sizes, line heights - container widths, spacing scale, radii, borders - button/link/card/image styles - header/footer/nav dimensions and breakpoints 6. **Map WordPress templates to Astro components**: - `header.php` -> `src/theme/Header.astro` - `footer.php` -> `src/theme/Footer.astro` - `single.php` -> `src/theme/PostLayout.astro` - `page.php` -> `src/theme/PageLayout.astro` - `archive.php`/`home.php` -> `src/theme/ArchiveLayout.astro` - `templates/front-page.html` -> homepage route/composition - `templates/single.html` -> post layout - `templates/page.html` -> page layout - `parts/header.html`/`parts/footer.html` -> header/footer components - `theme.json` -> token defaults for colors, fonts, spacing, and layout widths - `block.json` and `render.php` -> rebuild visible block output as Astro components - repeated loops/cards -> `src/theme/BlogCard.astro` - shortcode/raw HTML fallback -> `src/theme/WpHtmlBlock.astro` 7. **Connect EmDash content** through the template's established content helpers. Keep route handlers thin and avoid bypassing EmDash ownership of CMS/import/admin APIs. 8. **Handle unsupported surfaces explicitly**: - WooCommerce/cart/checkout/orders/customers: exclude unless using a separate commerce template. - Elementor/Divi/Beaver Builder: rebuild visible output, do not port builder runtime. - plugin widgets/forms: replace with Astro components or microservices.sh modules only after approval. 9. **Verify visually**: - Run `npm run microservices -- wp capture --rebuilt http://localhost:4321 --run`. - Run `npm run microservices -- wp diff-theme`. - Compare source and rebuilt screenshots under `migration-reports/screenshots/`. - Check mobile nav, header/footer, typography, content order, image ratios, and top URLs. 10. **Document gaps** in `docs/layout-rebuild.md` and `migration-reports/theme-parity.json`: intentional differences, unsupported widgets, plugin replacements, missing assets, screenshot blockers, and manual review items. Fill the manual metric sections in `theme-parity.json`; automated screenshot diff alone is intentionally not enough for launch. ## Component Rules - Prefer semantic Astro components and CSS tokens over copied WordPress CSS sprawl. - Reuse source assets only when licensing/ownership is clear and paths are stable. - Keep PHP logic out of the target. Translate behavior into explicit Astro/TypeScript code. - Preserve visible content order and navigational structure before improving internals. - Avoid adding client JavaScript unless source behavior requires it. - Keep commerce/payment/auth/provider behavior behind explicit approval gates. ## Parity Gates For each selected reference page: - Content order matches. - Header/nav/footer are present and structurally equivalent. - Typography and spacing are close at mobile and desktop widths. - Images render with stable dimensions and correct crop behavior. - Links point to migrated routes or documented exclusions. - Unsupported plugin/page-builder areas are either rebuilt, replaced, or reported. Use pixel diff as a guide, not the only gate. Brand feel, responsive behavior, and content correctness still need human review. ## Result Metrics Score each rebuild out of 100. Launch only when the total is at least 85 and no critical gate fails. | Area | Points | Validation | | --- | ---: | --- | | Visual parity | 30 | Screenshot diff/SSIM at `390`, `768`, `1440`; compare full page plus header, footer, hero, content card, and article body regions. | | Layout geometry | 15 | Bounding boxes for landmarks/components stay within agreed tolerance: header height, nav position, content width, image ratios, card spacing. | | Content/route parity | 15 | Required pages render, content order matches, migrated links resolve, redirects/canonicals/RSS/sitemap are correct. | | Design tokens | 10 | Fonts, colors, line heights, spacing, buttons, borders, and image treatments are extracted into maintainable tokens/components. | | Responsive behavior | 10 | Mobile nav, tablet layout, desktop layout, wrapping, and overflow pass fixed-width checks. | | Interaction parity | 5 | Menus, dropdowns, accordions, forms, and non-commerce UI behaviors match or are documented as replacements. | | Accessibility/performance | 10 | Semantic landmarks, focus states, alt text, no major Lighthouse/a11y regressions, stable image dimensions, low JS. | | Unsupported-surface reporting | 5 | WooCommerce, page builders, widgets, shortcodes, forms, and plugin behavior are rebuilt, replaced, or explicitly reported. | Critical gates: - No missing required reference page. - No silent loss of content, navigation, or top URLs. - No copied PHP runtime logic in the Astro target. - No secrets or production data committed. - Commerce/payment/auth behavior is not rebuilt without explicit approval. Record scores in `migration-reports/theme-parity.json` and summarize human review items in `docs/layout-rebuild.md`. Use `wp diff-theme` to generate the automated screenshot score, then fill manual metric sections before validation. Validate the score with: ```bash npm run microservices -- wp validate-theme ``` The CLI must report launch-ready before deploy/cutover. ## Finish Report Report: - Source theme files and assets inspected. - Target Astro components created/changed. - Design tokens extracted. - Unsupported WordPress/plugin surfaces and how they were handled. - Screenshots captured and visual parity result. - Checks run and remaining manual review items.