Rebuild Reference Site

Rebuild Reference Site

Turn a visual reference into a measured implementation. Prefer evidence from the running reference over aesthetic guesses.

Workflow

1. Define the route, viewport, state, and deployment acceptance matrix before editing.
2. Capture reference top, full-page, section, and interaction-state screenshots.
3. Inventory browser-delivered images, fonts, models, textures, media, CSS, and relevant runtime requests. Localize required assets and record URL, path, MIME type, byte size, and hash.
4. Measure document geometry, section rectangles, typography, colors, borders, and overflow behavior.
5. Inspect 3D models, cameras, named focus nodes, animations, materials, lighting clues, post-processing, and mobile fallbacks when present.
6. Implement structure first, then typography and spacing, then assets and interaction, then motion and post-processing.
7. Compare captures repeatedly. Fix large geometry deltas before small decorative deltas.
8. Exercise every route, viewport, toggle, accordion, navigation state, animation stop, and reduced-motion path.
9. Build and deploy through the repository's configured workflow. Verify the production URL in a fresh browser context.

Evidence layout

Keep generated evidence outside application source when possible:

.replica/
|-- config.json
|-- reference/
|-- local/
|-- assets/
|   `-- manifest.json
|-- metrics/
`-- reports/

Do not commit large generated captures unless the repository explicitly tracks visual fixtures.

Use bundled scripts

• Run scripts/capture-reference.mjs to capture routes at multiple viewports.
• Run scripts/inventory-assets.mjs to record and optionally download browser-delivered assets.
• Run scripts/measure-layout.mjs to export document and section geometry.
• Run scripts/inspect-glb.mjs to inventory nodes, cameras, meshes, materials, and animations in GLB or glTF files.
• Run scripts/compare-screenshots.py to produce visual diffs and numeric image metrics.
• Run scripts/qa-production.mjs after implementation and again against the deployed URL.

Read references/capture-and-measure.md before creating the evidence configuration. Read references/threejs-and-motion.md when the reference uses WebGL, Three.js, R3F, GLB, HDR, shaders, or cinematic motion. Read references/visual-qa.md before final visual and interaction acceptance.

Implementation rules

• Reuse the target repository's framework and conventions unless a rebuild is necessary.
• Check the reference network waterfall before substituting or generating assets.
• Preserve intrinsic image aspect ratios and identify desktop/mobile variants.
• Model responsive layouts as distinct compositions, not a uniformly scaled desktop page.
• Preserve meaningful DOM semantics, keyboard operation, focus state, and reduced-motion behavior.
• Keep WebGL optional on constrained devices when the reference provides or benefits from a fallback.
• Keep reference measurement, implementation, and verification reproducible through configuration and scripts.
• Preserve unrelated user changes in the target repository.

Acceptance contract

Do not call the reconstruction complete until all requested routes and states pass:

• no unexpected horizontal overflow;
• no uncaught browser or console errors;
• required assets load from the intended local or production paths;
• reference and implementation captures exist at every requested viewport;
• controls reach the expected state and expose accessible state where applicable;
• reduced-motion and mobile behavior are verified;
• the production URL returns the expected page rather than a gate, redirect, or error;
• remaining visual differences are recorded rather than silently ignored.