# Pixel Port

> Pixel-port an executable Claude Design (or local design-ref HTML/CSS/JS) into a production site using a temple file tree, CSS design tokens, a plan gate, and a pixelmatch visual-diff. Use when the user wants a pixel port, to port a Claude Design page, to run visual-diff on a ported page, or to foundation-port tokens and primitives from a design kit.

- Skill: `akhileshthykkat/pixel-port` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add akhileshthykkat/pixel-port`
- Raw SKILL.md: https://api.skillmd.com/api/skills/akhileshthykkat/pixel-port/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: AkhileshThykkat (https://skillmd.com/u/akhileshthykkat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/akhileshthykkat/pixel-port

---


# Pixel-port

Port one **executable design** (HTML/CSS/JS that can be served statically — Claude Design by default) into a production site. Same **process** every run. Framework and brand are project-local.

**Leading words:** *temple* (anyone walking the tree knows where a thing lives). *Foundation first* (tokens + primitives before pages). *Fail loud* (never silently diff the wrong variant or viewport).

## Inputs

A session needs:

1. A Claude Design share link **or** an existing `design-ref/<slug>/` tree.
2. A page name (slug = kebab-case).
3. A **framework, chosen once.**

If `.pixelport/config.json` exists, read it and never re-ask. Else detect `astro.config.*` / `next.config.*` in the target repo, or ask once, then write config with `npx pixel-port init`. Stop if framework is still unset.

Then read [`adapters/<framework>.md`](adapters/astro.md) (`astro` | `next-static` | `html`).

Optional variants (regions, locales) live in config. Default variant is `default`. Do not invent Transket-style geo unless the project config lists it.

## Two-pass

**Foundation pass** (once per site, or when the design kit changed): extract `_ds/`, `kit/*.css`, `ui/*`, `ui-icons/*` into tokens + chrome + primitives. No marketing page. Done when: token files exist, `SPEC.md` reuse checklist has real paths, layout/smoke page consumes those tokens, visual-diff `--self-test` of the design-ref pipeline is green.

**Page pass** (every page): steps below. Do not re-extract tokens unless the kit changed.

If config is missing, run foundation before any page. If config exists and tokens already sit at `src/styles/tokens/`, skip to page pass.

## Temple (every port)

Read [`structure.md`](structure.md) before writing files. Hard rules:

- One file, one job. A page is a thin route plus `src/sections/<group>/<slug>/*.` — never a giant route file.
- Reuse → extend → compose → promote → create. Check `SPEC.md` before a new primitive.
- ~300 lines is a smell. ~5 helpers on one job earn a `lib/`.
- Refactors **move bytes** (slice by line range, re-hash). Raise tangles; do not turn a page port into an unrequested refactor.

Tokens: read [`tokens.md`](tokens.md). Components consume CSS custom properties. Sections do not invent hex or spacing. Do not rewrite the kit through Tailwind (or any other system) unless the design source already is that system.

## Page-pass steps

Copy and tick. Each step has a completion criterion. Do not start the next step until the current one is done.

```
- [ ] 1 config/adapter
- [ ] 2 foundation (if missing)
- [ ] 3 resolve design
- [ ] 4 implementation-details doc (no code)
- [ ] 5 plan gate
- [ ] 6 implement
- [ ] 7 visual-diff
- [ ] 8 tracker
- [ ] 9 human review (still-frame is not done)
```

### 1. Config / adapter

Write or confirm `.pixelport/config.json` via `npx pixel-port init` (template: [`templates/config.json`](templates/config.json)). Read the matching adapter.

**Done:** config has `framework`, `targetUrl`, `viewports`; adapter file has been read this session.

### 2. Foundation if missing

If `src/styles/tokens/` is empty or `SPEC.md` has no filled reuse checklist: extract kit → primitive then semantic tokens (component tokens only at 3+ stable uses). Port chrome + ui + icons. Fill SPEC from [`templates/SPEC.md`](templates/SPEC.md).

**Done:** tokens on disk, SPEC checklist cites real paths, smoke/layout renders with tokens, `--self-test` once for the pipeline.

### 3. Resolve design

Parse `projectId` + file from the share link. If DesignSync MCP exists: `get_project`, `list_files`, `get_file` (read-only). Else require `design-ref/<slug>/` already on disk. Pull the page loader plus depended `app/*`, `ui/*`, `ui-icons/*`, `kit/*`, `_ds/` into `design-ref/<slug>/` before step 7.

**Done:** the page’s `.html`/content file exists under `design-ref/<slug>/` and tracker `designPath` can be set.

### 4. Implementation-details doc

Create `implementation_details/<slug>.md` from [`templates/implementation-details.md`](templates/implementation-details.md). What: title/description, ordered sections 1:1 with the design’s top-level components, shared vs new. How, per section: target path, design source symbol, which existing primitive to reuse (cite path).

No `.astro`/`.jsx`/code in this step.

**Done:** the doc exists, every top-level design section has a row, no implementation files created this step.

### 5. Plan gate

Run the doc past `advisor`, or an Agent with Opus, before writing code.

**Done:** the stronger-model review has happened; requested plan fixes are in the doc.

### 6. Implement

Follow the adapter: thin route → one file per section → reuse `src/components/{chrome,ui,icons}/`. Interactivity: vanilla `<script>` plus a re-entry guard, unless the adapter explicitly allows a framework island.

**Done:** every section in the doc has a file at the named path; route composes them; no new primitive that already existed on the SPEC checklist.

### 7. Verify

Protocol: [`visual-diff.md`](visual-diff.md). Run the skill script, do not regenerate a one-off.

From the **target repo**:

```bash
npx pixel-port diff <slug> [--self-test] [--variant default] [--budget 5] [--target-url <url>] [--clip]
```

First time on a page: `--self-test` (design vs design, expect ~0%). That does **not** prove the port. Then a real run. Fail loud on variant/marker/zoom mismatch. Default budget 5%. PNGs in `diff-output/<slug>/`. Full-page is the gate; `--clip` only localizes a failure.

**Done:** self-test already green for this slug; real run within budget for every viewport of this variant; or tracker records fail with diff images.

### 8. Track

One JSON file per page: `.pixelport/pages/<slug>.json` (schema: [`templates/page-tracker.schema.json`](templates/page-tracker.schema.json)). Create before step 7 (`designPath` required; `targetRoute` required unless `--self-test`). Step 7 writes `visualDiff`. On `done`, stamp `specHash` of `SPEC.md`.

**Done:** tracker exists, status matches reality, `visualDiff` present after a real run.

### 9. Human review

A passing still-frame is not done. Animations, hover, and anything that moves are invisible to pixelmatch. Put a human on the live page. How they are notified is **project-local** (email, ticket, chat). Do not add SES or deploy-on-push to this skill.

**Done:** the tracker notes that review was requested; status is not `done` until a human has looked or the user explicitly accepts the still-frame risk.

## Out of scope

Unattended queues, skip-permissions, usage-limit sleep, commit/push as approval, Cloudflare adapter injection, Figma-as-source, generating a React/shadcn design system.

## Additional resources

- File tree and promotion: [structure.md](structure.md)
- Token layers and extraction: [tokens.md](tokens.md)
- Diff protocol: [visual-diff.md](visual-diff.md)
- Adapters: [adapters/astro.md](adapters/astro.md), [adapters/next-static.md](adapters/next-static.md), [adapters/html.md](adapters/html.md)