house / WordPress Theme to EmDash

---
name: wordpress-theme-to-emdash
description: >-
  Port WordPress themes to EmDash CMS. Use when asked to convert, migrate, or
  port a WordPress theme to EmDash, or when creating an EmDash site that should
  match an existing WordPress site's design. Handles design extraction, template
  conversion, and EmDash-specific features like menus, taxonomies, and widgets.
agents: [claude-code, codex, autojack, cursor]
license: MIT
tags: [wordpress, astro, emdash, cms, migration, themes]
category: web
metadata:
  version: "1.0.0"
capabilities:
  network: true
  filesystem: readwrite
  tools: [Bash, Read, Edit, Write]
requires-secrets: []
resources:
  - path: story.md
    type: file
  - path: phases/1-discovery.md
    type: file
  - path: phases/2-design.md
    type: file
  - path: phases/3-templates.md
    type: file
  - path: phases/4-dynamic.md
    type: file
  - path: phases/5-seed.md
    type: file
  - path: phases/6-verify.md
    type: file
  - path: references/astro-essentials.md
    type: file
  - path: references/concept-mapping.md
    type: file
  - path: references/design-extraction.md
    type: file
  - path: references/emdash-api.md
    type: file
  - path: references/template-patterns.md
    type: file
  - path: scaffold/astro.config.mjs
    type: file
  - path: scaffold/CHECKLIST.md
    type: file
  - path: scaffold/package.json
    type: file
  - path: scaffold/public/favicon.svg
    type: file
  - path: scaffold/README.md
    type: file
  - path: scaffold/src/components/PostCard.astro
    type: file
  - path: scaffold/src/env.d.ts
    type: file
  - path: scaffold/src/layouts/Base.astro
    type: file
  - path: scaffold/src/live.config.ts
    type: file
  - path: scaffold/src/pages/404.astro
    type: file
  - path: 'scaffold/src/pages/categories/[slug].astro'
    type: file
  - path: scaffold/src/pages/index.astro
    type: file
  - path: 'scaffold/src/pages/pages/[slug].astro'
    type: file
  - path: 'scaffold/src/pages/posts/[slug].astro'
    type: file
  - path: scaffold/src/pages/posts/index.astro
    type: file
  - path: 'scaffold/src/pages/tags/[slug].astro'
    type: file
  - path: scaffold/src/styles/global.css
    type: file
  - path: scaffold/tsconfig.json
    type: file
---

WordPress Theme to EmDash

Port WordPress themes to EmDash in six phases. Read the phase file before starting each phase.

Critical Rules

1. Copy scaffold first - Start every theme by copying scaffold/ from this skill
2. Take screenshots of demo - Identify the demo URL and capture all page types using agent-browser before starting work
3. No hard-coded content - Use getSiteSettings() for title/tagline, getMenu() for navigation
4. Server-rendered pages - Never use getStaticPaths() for EmDash content
5. Astro 6 - Use ClientRouter not ViewTransitions, Zod 4 syntax, Node 22+
6. Use emdash Image component - For all images, import Image from "emdash/ui"

Phases

Checklist

Setup

• [ ] Copy scaffold/ to new theme directory. Unless otherwise specified by the user, make this a subdirectory of themes/ and name it after the WordPress theme (e.g., themes/twentytwentyfour/).
• [ ] Rename folder, update package.json
• [ ] Verify build: pnpm build

Phase 1: Discovery

• [ ] Theme source downloaded
• [ ] Demo site identified
• [ ] discovery/ folder created with screenshots/, images/, notes.md
• [ ] All page types screenshotted
• [ ] Sample images downloaded

Phase 2: Design

• [ ] CSS variables in global.css
• [ ] Fonts loading
• [ ] Colors match demo

Phase 3: Templates

• [ ] Homepage, single post, archive, category, tag, page, 404
• [ ] Components extracted (PostCard, etc.)

Phase 4: Dynamic

• [ ] Site settings (title, tagline, logo from CMS)
• [ ] Navigation menus (from CMS, not hard-coded)
• [ ] Taxonomies
• [ ] Widget areas (if applicable)

Phase 5: Seed

• [ ] Seed file created with demo images at .emdash/seed.json (or wired up via package.json#emdash.seed)

Phase 6: Verify

• [ ] Dev server applied seed cleanly on first request (no validation errors in logs)
• [ ] Output screenshots captured
• [ ] Visual comparison done
• [ ] Build succeeds: pnpm build
• [ ] LICENSE file downloaded (GPL-2.0 in most cases)
• [ ] README credits original theme

Reference Documents

• references/astro-essentials.md - Astro 6 patterns
• references/template-patterns.md - PHP → Astro conversion
• references/concept-mapping.md - WP → EmDash concepts
• references/emdash-api.md - Full API reference
• references/design-extraction.md - CSS extraction techniques

Why

Theme migrations go sideways when a pretty homepage hides missing archives, menus, and content behavior.

How

Inventory the original, extract the design system, translate templates, reconnect dynamic CMS surfaces, seed realistic content, and compare the result before calling it done.

Related

Start with Building EmDash Site for a fresh build or EmDash CLI when the content model needs direct work.