mockup-to-code skill pack

A self-contained custom-skill pack for turning static web-design mockups into responsive HTML/CSS with measurable visual-fidelity evidence. The repository contains the parent mockup-to-code skill and every custom specialist it can route to.

Instead of treating a mockup as a screenshot to trace, the skill builds a real web document with flow, Grid, and Flexbox. It combines source-image measurement, manifest-driven implementation, browser rendering, box and pixel comparison, responsive checks, and explicit completion gates.

What it provides

• Pixel-clone, production, and hybrid reconstruction modes
• Source measurement and element-manifest workflows
• Photo/background asset preflight and provenance checks
• Responsive typography, layout, and page-flow validation
• Browser rendering and DOMRect-based box comparison
• Crop-pair, pixel-diff, artifact, and completion evidence
• Regression tests for the executable gates

The complete operating contract is in SKILL.md. Detailed phase guides are under references/.

Requirements

• Python 3.10 or newer
• Node.js 18 or newer
• npm
• Chromium, Google Chrome, or Microsoft Edge

OpenCV, NumPy, and Pillow enable the full image-analysis path. Some operations have a reduced Pillow-based fallback. The setup script reports the capabilities available on the current machine.

Install the complete pack

Clone anywhere, inspect the plan, then install all 12 bundled skills:

git clone https://github.com/mocchalera/mockup-to-code-skill.git
cd mockup-to-code-skill
bash scripts/install-skill-pack.sh --dry-run
bash scripts/install-skill-pack.sh

The default destination is ${CODEX_HOME:-~/.codex}/skills. The installer validates the routing closure and every skill's frontmatter/relative resources, finds a Python interpreter with the modules required by the selected specialists, stages all files, installs the parent Node dependency, then places the staged skill set transactionally, with rollback on caught failures. It reports the selected Python interpreter in the install result and each skill's installation marker. Existing destinations stop the install before any changes. To update an existing installation while keeping recoverable backups:

bash scripts/install-skill-pack.sh --replace

Rollback covers caught installation failures. A process kill or power loss between directory placements cannot be made atomic across 12 separate skill destinations; inspect .skill-pack-stage-* and .skill-pack-backups/ before rerunning if that occurs.

Use --dest ~/.agents/skills for an alternate skill root, or --skip-runtime-deps when dependencies are managed separately. Restart Codex or begin a new turn after installation so skill discovery refreshes. When using a non-default destination, set SKILL_ROOT to the same path for commands that must resolve another installed skill. The bundled LP interaction checker uses the parent skill's installed playwright-core, so a full-pack install does not depend on the target web project having its own copy.

The pack requires Pillow and NumPy for the parent/image-owning workflows, and jsonschema for the typography validator. The installer checks MOCKUP_PYTHON, its own Python, python3, and common Homebrew/system locations without modifying a global Python environment. It also verifies Python 3.10+, Node 18+, and npm before changing the destination. Missing requirements stop the install. If no Python candidate is complete, install the reported packages into your chosen environment and set MOCKUP_PYTHON=/path/to/python before rerunning. The installed mockup-to-code/scripts/skill-pack-python wrapper binds every specialist command to the selected interpreter. --allow-missing-python-deps is an explicit degraded override and does not make the missing capabilities usable.

imagegen is the only non-bundled routed skill. It is an OpenAI system skill and runtime capability, required only when photo art direction actually routes to image generation.

Bundled skills

• mockup-to-code
• visual-device-inventory
• typography
• raster-texture-reconstruction
• photo-art-direction
• design-whitespace
• seamless-section-waves
• design-motion-sequencing
• responsive-image-delivery
• lp-interaction-qa
• visual-qa-pixel-polish
• design-copy-structure

Use

Invoke the skill when asking an agent to implement a supplied design mockup, for example:

Use mockup-to-code to turn these desktop and mobile mockups into a responsive page.

The agent should read SKILL.md, follow the referenced phase documents, keep generated work in an isolated work root, and report the computed completion verdict without promoting a prototype to complete.

Validate the repository

npm ci
python3 scripts/verify_skill_pack.py
npm test
python3 -m json.tool schemas/element_manifest.schema.json >/dev/null
git diff --check

VALIDATION.md records the evolution of the executable contracts and the evidence used to verify them.

Repository layout

• SKILL.md — agent-facing entry point and hard rules
• skill-pack.json — bundled/external skill dependency manifest
• skills/ — every directly routed custom specialist
• references/ — measurement, composition, assets, QA, and fallback guides
• scripts/ — deterministic measurement, pack installation, and verification
• schemas/ — element-manifest JSON Schema
• templates/ — starter manifests, CSS, and review artifacts
• test/ — regression coverage for the executable gates

License

ISC