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.
---

# 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

| Phase | File                    | Summary                                         |
| ----- | ----------------------- | ----------------------------------------------- |
| 1     | `phases/1-discovery.md` | Download theme, screenshot demo, capture images |
| 2     | `phases/2-design.md`    | Extract CSS variables, fonts, colors            |
| 3     | `phases/3-templates.md` | Convert PHP templates to Astro                  |
| 4     | `phases/4-dynamic.md`   | Site settings, menus, taxonomies, widgets       |
| 5     | `phases/5-seed.md`      | Create seed file with demo content              |
| 6     | `phases/6-verify.md`    | Screenshot, compare, iterate, build             |

## 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