port-page

Files (4)

• SKILL.md
• parity-checklist.md
• plan-template.md
• probe.md

SKILL.md (first lines)

# Port Page

**Faithful port** of one page from a source project into a target project. Source owns *what the page does and how it should feel*; target owns *how it is built*.

Not a redesign. Not a blind copy-paste. Probe → plan → port → parity.

## Inputs

Lock these before probing (ask once if missing):

| Input | Examples |
| --- | --- |
| **Source** | path in another repo, monorepo package, or live URL + route |
| **Target** | repo root (default: cwd) + destination route / page slug |
| **Scope** | one page (default). Multi-page → one page per invocation |

## Process

### 1. Probe both sides

Load [probe.md](./probe.md). Probe **source** and **target** independently, then diff.

Capture at minimum:

- Tech stack (framework, language, package manager, styling system, routing)
- Code conventions (file layout, components, naming, state/data patterns, lint/format)
- Design system signals (tokens, primitives, breakpoints, motion)
- The source page's sections, interactions, and responsive behaviour

**Completion criterion:** both probes filled; gaps and conflicts listed — no code written yet.

### 2. Write the port plan

Create `docs/site/ports/<slug>.md` from [plan-template.md](./plan-template.md) (create `ports/` if needed). If the target has no site-docs layout, write under `.scratch/ports/<slug>.md` instead.

The plan must name:

- Stack/convention mapping (source construct → target idiom)
- Section inventory (nothing invented, nothing dropped without an explicit defer)
- Style mapping (source visual → target tokens/primitives; token additions called out)
- Responsive mapping (source stacking intent → target breakpoints / verification viewports)
- Risks and accepted deltas (things that cannot reach full parity)

Confirm with the user only when a risk would change page job, drop an interaction, or introduce a second styling system.

**Completion criterion:** an agent could port without inventing sections or guessing stack choices.

### 3. Faithful port

Implement in the **target** only:

- Prefer existing target routes, layouts, and primitives
- Map every planned section and interaction
- Extend target tokens when a needed value is missing — do not hardcode source hex/fonts into the target
- Obey target `docs/agents/design-rules.md` / stack conventions when present
- Preserve source **parity** intent: same jobs, same interactive outcomes, same visual hierarchy, same mobile stacking story

Stop and update the port plan if reality diverges (new defer, new token, new risk).

### 4. Parity check

Walk [parity-checklist.md](./parity-checklist.md).

Run **`/responsive-pass`** against the plan's verification viewports (or target page-spec / `TOKENS.md` bands when those exist).

**Completion criterion:** every parity item is pass, explicit defer, or open blocker; responsive failures are concrete; target build/lint for touched files succeeds when tooling exists.

### 5. Close

Summarise: files changed, token additions, accepted deltas, open blockers.

Recommend next:

- Target follows Site Skills main flow → `/visual-qa` (or `/page-spec` first if no page-spec yet and they want the contract persisted)
- More pages remain → another `/port-page` for the next slug
- Unclear → `/ask-site`

From Alfred-Lau/skills, MIT.

More from Alfred-Lau/skills