EDS UI Migrator

Visual migration toolkit for Adobe Edge Delivery Services.

Discover interactive states from a live wrapper, run a structure gate, capture viewport × state screenshots with Playwright, and compare with pixelmatch. Fix CSS from Cursor or Claude Code using the included skill — no org LLM API keys for the default loop.

GitHub: codeandtheory/eds-ui-migrator

---

For UI developers (stay in your EDS repo)

You do not need to open this migrator repo as your main workspace. Keep working in your EDS site (e.g. driv-implementation-).

One-time setup

git clone https://github.com/codeandtheory/eds-ui-migrator.git ~/Documents/eds-ui-migrator
cd ~/Documents/eds-ui-migrator
npm install

Optional (saves typing --repo every time):

export EDS_REPO=/absolute/path/to/your-eds-site
# add that line to ~/.zshrc if you want it permanent

Day-to-day — stay in the EDS repo

1. Open your EDS project in Cursor or Claude Code.
2. Have local preview running (aem up / npm run dev, etc.).
3. In agent chat, paste something like:

Use eds-ui-migrator at ~/Documents/eds-ui-migrator with
--repo set to this EDS repo.

Live: https://www.example.com/your-page
Wrapper: .cards-article-list
Block name: moog/cards-article-list
EDS: http://localhost:3000/your-page

Run discover, review/fix the states contract if needed, then diff.
Fix CSS in this repo from AGENT-BRIEF until all viewports/states pass.

The agent will run the CLI from the migrator clone, write CSS under this site’s blocks/…, and keep reports under the migrator’s .reports/.

You only need to supply:

Input	Example
Live page URL	https://…/page
Wrapper selector	.hero, .cards-article-list
Block name	moog/hero
EDS URL	http://localhost:3000/page

---

Install (tool maintainers)

git clone https://github.com/codeandtheory/eds-ui-migrator.git
cd eds-ui-migrator
npm install

Point at your EDS site

export EDS_REPO=/absolute/path/to/driv-implementation-
# or pass --repo on every command

The migrator writes CSS under $EDS_REPO/blocks/… and keeps reports/contracts in this tool repo.

CLI workflow

# From the eds-ui-migrator clone:

# 1) Draft states from the live wrapper
npm run discover -- \
  --repo "$EDS_REPO" \
  --legacy "https://live.example.com/page" \
  --block ".find-my-part" \
  --name moog/find-my-part \
  --eds "http://localhost:3000/page"

# 2) Review contracts/generated/find-my-part.states.json

# 3) Diff
npm run diff -- \
  --repo "$EDS_REPO" \
  --legacy "https://live.example.com/page" \
  --eds "http://localhost:3000/page" \
  --block ".find-my-part" \
  --name moog/find-my-part \
  --states ./contracts/generated/find-my-part.states.json

# 4) Fix CSS in the EDS repo from .reports/…/AGENT-BRIEF.md, then re-run diff

Skills

Copy into your EDS project (or personal skills) so chat auto-picks them up:

Client	Path in this repo
Cursor	skills/cursor/eds-ui-migrator/SKILL.md → .cursor/skills/eds-ui-migrator/
Claude Code	skills/claude/eds-ui-migrator/SKILL.md → .claude/skills/eds-ui-migrator/
Canonical	SKILL.md

Commands

Script	Purpose
npm run discover	Live DOM → draft states JSON
npm run diff	Diff-only (default, no API key)
npm run until-pass	Optional closed loop (needs API key)

Nested use (optional)

If you copy or submodule this package at your-eds-site/tools/ui-migrator, --repo defaults to the site root (../..) when blocks/ is present. Prefer the separate clone + --repo flow above for most teams.

Docs

Engineering write-up (DRIV Confluence): EDS UI Migrator — Engineering Architecture