WordPress Theme to EmDash

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