CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/stardust

Redesign an existing website to make it better. Built on top of impeccable.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

recreation-procedure.mdskills/replica/reference/

Recreation procedure (clean re-authoring against a live original)

Replica's Phase 3: author one clean prototype per page type that the source-fidelity gate can pass. This is recreation, not redesign — the craft skill's redesign gates (critique, anti-template, divergence, distinctiveness) do not apply and must not be invoked; the gate replaces them. The failure mode this doc exists to prevent is taste leaking in: any "improvement" without an inconsistency-register entry is a fidelity bug.

Authoring order

Per archetype, in this order — the order matters because each step removes a class of guesswork before the next begins:

  1. Content skeleton from the captured page JSON. Lay out the section sequence and every text node verbatim from stardust/current/pages/<slug>.json (headings, body, CTAs with hrefs, alt text, metadata). Content-preservation rules (../../migrate/reference/content-preservation.md) apply from line one — including its paragraph-boundary rule: paragraphs come from the source's block-level nodes, never from splitting captured text on newlines. Reconcile COUNTS before authoring: group the captured components by section and count them (n widget instances, n cards each) against what you are about to author. Vendor-template pages repeat whole widgets verbatim (recorded: the same 20-card widget twice plus a 6-card "wide" variant on one page — the first build authored ONE instance and the gate read a 1559px height deficit as a missing section). A large height delta with matching section ORDER is usually a duplicated instance, not a missing one.
  2. Lift exact values from the source site's own CSS (§ CSS lifting).
  3. Fonts (§ Fonts policy).
  4. Compose against the captured screenshot — the ground truth for everything CSS doesn't name: image crops, composition, stacking, paint effects.
  5. Serve locally and enter the gate loop (source-fidelity-gate.md) — do not eyeball-polish first; the first gate run is the map of what's wrong.

Keep the markup clean: semantic elements, BEM-ish classes, CSS custom properties for the lifted tokens, no JS unless a section's initial state requires computing it (see § Carousels) or the live chrome morphs with scroll (see § Fixed and sticky chrome — the one instrument-induced exception). Adopt the live page's content-root class on the prototype's main wrapper so one --main selector scopes both sides of the diff symmetrically.

Cumulative archetype prototypes

Every archetype keeps its own standalone reference prototype — never skip to direct platform authoring for a new archetype "because the blocks already exist". Field evidence (a financial-services site, 8 pages): the prototyped archetype reached 3.5%/5.6% pixel diff and stayed the quality ceiling for its conversion; pages authored directly on the platform plateaued at 8–16%. Prototypes are cumulative: each new one imports the shared layers earlier prototypes already gated — tokens, chrome, shared module CSS, the interaction spec — and iterates only on its NEW modules. Concretely, split the prototype CSS into a shared canon file plus a per-archetype file; the platform conversion inherits both; and the prototype remains the per-archetype fidelity reference (full gate: ≤10%, Δ≤8px, 0 structural red) that the published page is judged against (source-fidelity-gate.md § The published-origin gate).

Canon chrome is a snapshot — re-verify it against EACH new archetype's live page before iterating page content. Header/footer vary per template family and the live site drifts continuously (recorded: the gated canon header rendered 123px vs 101px live on a second template, and the canon footer still carried pre-drift metrics — the two "trusted" regions consumed the new page's first two hot bands). Open every new archetype's gate with the chrome crop gate (source-fidelity-gate.md § Pass bar, item 5) against the NEW page's live chrome, and flag any page-level compensation for back-port into the canon files so later archetypes don't re-discover it.

Repeated-unit families (#125)

A block that repeats a unit — cards, rail items, list rows, FAQ rows — is declared once in stardust/replica/units.json when it is authored: { "<family>": { "origin": "<live unit selector>", "build": "<block unit selector>", "n": 2, "required": true, "pages": ["<slug>"], "templates": ["<template>"] } }. gate.sh --full, gate-all.mjs and unit-geometry.mjs --families resolve the page's families from it and compare the first N units element by element (Δx/Δy/Δw/Δh within 4 px, hidden where the build clips); required: false makes a family advisory. The pixel gate sees the grid of shapes, not whether the badge sits on the corner or the body starts 30 px low — the workstreams that converged measured exactly this.

CSS lifting — fidelity values come from the original site's CSS, not the eye

(Prior art: an earlier airport-site migration's improvement notes §3.6; re-confirmed in UC1-E1 where per-element computed-style capture "did most of the work".)

Before any screenshot-eyeball tuning:

  1. Fetch the live stylesheets (curl or Playwright response capture — CDN-defended sites 403 direct curl; intercept the page's own responses instead, see § Asset harvest).
  2. Lift the exact values into a tokens file (capture/tokens.json pattern): container max-widths, the full type ramp (family / size / line-height / letter-spacing / weight per level), button specs (border, radius, padding — the whole spec, not just color), section paddings, radii, shadows, hero heights, breakpoint values, box-sizing per container (§ Box model is a lifted value) — and the text-rendering group: text-rendering, -webkit-font-smoothing, font-synthesis, font-variant-numeric, font-kerning. Sites commonly set these globally, and the ramp alone doesn't carry them: a ±1% glyph-width difference from a mismatched rendering mode produces systematic one-line-fewer/more wraps that present as inexplicable per-section height errors at every breakpoint. Diagnostic when wraps disagree at identical computed family/size/width: measure a literal string's rendered width on both sides (canvas.measureText or an offscreen span) — it settles whether the fork is metric or layout.
  3. Replicate the container model, not just the tokens: left-offset vs centered hero content, %-of-viewport heights, grid gutters. The container model is where "looks close but drifts" comes from.
  4. Capture per-element computed styles for the elements the gate will measure (headings, CTAs, section wrappers). Computed styles resolve the cascade the stylesheets only imply.
  5. Repeat 2–4 at EVERY gate breakpoint, not just desktop — the 360 layout is NOT derivable from the 1440 recreation. Mobile is its own authoring pass, not a shrink of desktop: lift the source's mobile @media geometry (container model, hidden/restacked blocks, mobile nav, grid collapse rules) up front and build 360 against it. Capture per-element computed styles at 360 (and any other gate width) BEFORE authoring — the 360 gate map is not the moment to discover the mobile container model. Recorded twice: a design-furniture site's 1440-lifted prototype converged desktop in one iteration but opened mobile at 26.8% (an overflow:hidden whose only layout effect is margin-collapse containment at mobile, a different mobile footer container model, a block hidden at mobile — all sitting in the source CSS, discoverable up front); and a fashion retailer, where an essentially unbuilt 360 layout measured −1600px height delta at 360 vs −169px at 1440 — a desktop-only recreation doesn't degrade gracefully at mobile, it collapses. With per-breakpoint lifting, mobile converges in 1–2 iterations; without it, expect the full iteration cap.

This converts 3–4 guess-and-screenshot loops into one. Eyeballing is for step 4 of the authoring order only — and even then, the gate's instruments outrank the eye.

Every url() in a lifted rule is rehosted. A canon rule carries a url() only when it resolves to a file under stardust/current/assets/ (harvest it — § Asset harvest — and keep its intrinsic size and background-size): a url() pointing at the source host is a gate FAIL, not a pass — it renders in the pixel compare and vanishes on the delivered site; a dropped background-image (icons, flags, decorative marks under the extract size filter) is the same defect (recorded: a language switcher's flag icons transcribed into the canon CSS without their url()s, and the one kept hot-linked the source site, which masked the pixel gate). measure.mjs now lists backgroundImage, so a --against run names the miss.

No foundation text-wrap: balance on headings. The redesign prototype's refined pass prescribes h1–h6 { text-wrap: balance }; live sites almost never use it, and under it multi-line card titles and band headings re-wrap differently from the original at identical width and font — persistent 10–20% band diffs that look like font or width errors (recorded). Replica prototypes and their block CSS leave text-wrap at the source's computed value (initial unless the lift says otherwise); when a heading wraps differently at matched width/font, check text-wrap before anything else.

Two probe classes DOM/style capture misses

Both were caught only by the gate in UC1-E1; check for them proactively:

  • Rendered-face font forks on inner spans. An element computes family X while its inner span renders family Y (and sometimes a different size — 31px span in a 30px heading). Computed-style capture of the element lies; the content-diff width probe catches it. When the gate reports a 🟠 font fork on a heading you "captured correctly", inspect the live node's inner spans before touching your font stack.
  • Overlay scrims — read the FULL background-image layer list first; luminance-fit only when the scrim isn't there. A photo band that resists offset/scale fixes (recorded: 30–40% band diff with position, scale and copy numerically aligned, cross-correlation dy≈0) usually carries its scrim as a gradient layer in the live element's background-image stack (linear-gradient(rgba(0,0,0,.1), rgba(0,0,0,.5)), url(…)) — invisible in crawl JSON and to the eye, one getComputedStyle(el).backgroundImage line to find, and worth 4 pixel points on its own. The CSS lift (step 2) captures every layer (gradients + url + size/position per layer) of any element carrying a photo. Only when a scrim is present in rendered pixels with NO discoverable element, pseudo-element, filter, backdrop-filter, or mask, recover it empirically by per-row luminance fitting: compare per-row luminance of the live capture region vs the decoded raw image, fit the ratio curve to a gradient (UC1-E1's hero fit: linear-gradient(transparent 68%, rgba(0,0,0,.45) 80%, #000 100%)), apply, and let the pixel probe confirm the fit.

Lift the sizing MODEL, not the resolved value (#116)

A computed-style lift records width: 720px from an element whose authored rule is width: 50%; both gate widths render the two the same, so the frozen value ships invisibly and diverges on wider screens (#116, recorded). The same trap applies to DOM: a 1440 layout OUTCOME (a button row wrapped 3+1) captured instead of the layout MODEL (one wrapping flex row).

  • Read the measured cap model first (#124), then lift widths AND heights at two widths. DESIGN.json extensions.breakpoints (extract's cap-probe.mjs run) lists every cap origin: caps[] by kind (shell / content / module, px, authored via), modules[] (capped or full-bleed per section), containerMaxWidth, the derived probeWidth. Encode a wrapper cap as main { max-width }, a module cap on the section column — never a resolved px, never a breakpoint (a cap is not a layout switch; breakpoints are preserve-direction.md § 4's concern). For everything else diff a lift at 1440 against one at probeWidth: a box that scales is FLUID — encode its authored rule (% / vw / max-width model), never the px; a box that holds is fixed. Heights get the same test: a fixed-height hero gated pixel-perfect at 1440 read "10px off" to a reviewer browsing at 1512 because live scaled it with the viewport (recorded); when a height or overlap scales, encode it vw-proportional (px@1440 ÷ 14.4 = vw, or the authored vh/% rule).
  • Layout groups get the same test: if a row's children redistribute between the two widths, the model is a wrapping flex/grid row — author ONE row and let it wrap; never encode the wrap point as structure.
  • The gate-side backstop is the mandatory content-cap row (source-fidelity-gate.md § Pass bar item 6: cap-probe.mjs … --against) — it catches what this rule prevents; lifting the model up front is the cheap half.

Box model is a lifted value (box-sizing per container)

box-sizing is a first-class lifted value: read per container from the computed-style capture (step 4), declared per block in the recreation and in its block CSS — never assumed, never set once for the page. A recorded hands-off run's prototypes all gated at ≤ 0.1 %, and the delivered pages came out with the chrome 9 px narrower and a facts row 106 px shorter at 360: the source laid out its grids content-box, the prototype carried no reset, and the delivery boilerplate's universal *, *::before, *::after { box-sizing: border-box } shrank every padded %-width container after conversion — the agent had to discover the source's box model itself, at the published-origin gate. Rules:

  • Lift it. For every container the gate measures (section wrappers, grids, cards, rows, chrome bars) record boxSizing beside width and padding. measure.mjs lists it in its default props, so a --against run prints boxSizing: content-box → border-box per box — the fork is named before a pixel round.
  • Declare it per block. The block's CSS states the box model its lifted widths were authored under (.block-x, .block-x * { box-sizing: content-box } when the source was content-box), and the canon file header records the source's box model per container family.
  • On a replica the boilerplate reset is SCOPED, never universal. The deploy skill's global border-box reset (#106) is a redesign rule. A replica project declares the reset in styles/styles.css scoped to the blocks whose lift recorded border-box (or to the wrapper classes the source applied it to), states the scope in the canon header and the progress ledger, and leaves everything else at the browser default the source relied on. A universal reset is a design change without a register entry.
  • Read the symptom. A width or height short by exactly a padding sum (2 × padding-x on a width, 2 × padding-y on a row) at one breakpoint is a box-model fork, not a spacing error — re-lift boxSizing, do not nudge the padding. The same fork is one of the recorded causes of horizontal overflow at 360 (source-fidelity-gate.md § Iteration discipline, the HARD assert).

Image renditions per breakpoint (srcset / sizes are lifted values)

The browser picks a rendition per viewport from srcset / sizes. A recorded hands-off run's live page selected the 400 px rendition at 360 while the build served its 1600 px rendition at every width; each rendition rounds its rendered height from its own intrinsic ratio, so every inline image differed by a fraction of a pixel (0.64 px recorded), and summed down the page that was a 2.2 px root-height delta that cost iterations chasing a layout bug that was not there. Rules:

  • Record per image which rendition live selects at EACH gate width. measure.mjs "$LIVE" --against "$PROTO" --selectors "img" --all-matches --width 1440,360 prints img <naturalWidth>×<naturalHeight> …/<file> per match per side and img.naturalWidth: a → b; img.file: a → b on the Δ line when the selection differs (--json: img: { naturalWidth, naturalHeight, currentSrc } per match). Write the per-width table into the capture notes beside the lifted CSS.
  • Author the same srcset / sizes — the same candidate widths and the same sizes expression, on the rehosted files — so the build selects the same rendition at every gate width. On the delivery platform map them onto the pipeline's rendition widths (the /media_<hash>?width=… set the optimizer emits; source-fidelity-gate.md § The published-origin gate: read dimensions from the delivered rendition, not the authored asset).
  • Read the symptom. A sub-3 px root-height delta with equal boxes (every measured section Δh 0 while img.naturalWidth differs) is a rendition-ratio symptom, not a layout bug — fix the rendition, do not touch spacing, and do not spend an iteration on it.

Wrap-junction margins (cards-on-a-canvas sites)

Sites built as "cards on a canvas" — white/tinted wrap sections floating on a page background — tempt the recreation into margin-based boxes, and margins collapse: two adjacent wraps each carrying a section-pad margin lose one pad at every junction (recorded: 96px designed → 48px rendered), a systematic per-junction height error the anchor probe reads as every section top drifting further down the page. Two safe constructions:

  • Transparent padded sections with an inner wrap (padding never collapses): the section keeps the page background and the vertical pad; the visible card is an inner element carrying the surface color/radius. Prefer this — it matches how most such sites are actually built.
  • Explicit junction margins, documented per junction, when the inner wrap can't work. Specificity trap: junction rules must match or exceed the :has()-based wrap rules they override, or the wrap rule silently wins and the junction re-collapses.

The inverse case — the SOURCE's margins do NOT collapse where a clean recreation's would: AEM-classic (and any clearfix-era) components wrap each section in a clearfix, whose block formatting context contains child margins. display: flow-root on the recreated section wrapper reproduces that containment exactly — one rule fixed systematic −48/−20px per-section errors across a whole page in the field.

Fonts policy

Deploy § 4 principle 2 (#80) applies from the first archetype on:

  • Self-host the source's own faces as-is. Extract saves every font response under stardust/current/assets/fonts/; ship those files — the same families, weights and styles — as @font-face in the shared canon CSS (at delivery styles/fonts.css, per deploy § 4).
  • Brand family FIRST in every stack; a metric-matched substitute only as the fallback entry after it — never a calibrated stand-in (no derived font files, no hand-tuned metrics), so a licensed drop-in later wins without a code change.
  • A local() source only for a face the gate's browser has. The gate renders on Linux: a fallback face whose local() names a macOS or Windows platform font resolves to nothing there, the stack falls through to the browser default and every type metric forks. Name the Linux-available metric fallbacks — Liberation Sans / Arimo (Arial class), Liberation Serif / Tinos (Times class), Liberation Mono / Cousine (Courier class) — or self-host the fallback. The capture names every dead face (fontsFailed, source-fidelity-gate.md § Hardening rule 14): fix the stack before the next round.
  • Proprietary faces raise deploy's licensing alert (deploy § 4 principle 2, #80 — the banner, fonts/LICENSING.md, the hand-off line; the remove path is deploy's) plus ONE register entry for all of them (preserve-direction.md § 3).

Asset harvest and the capture-state policy

CDN-defended sites (Akamai/Cloudflare/Demandware) 403 direct asset requests, font files, and even in-page fetch() from a headless client. What works:

  • Harvest by intercepting the page's own responses (Playwright response events) — the page's own requests are authorized; yours are not.
  • Canvas readback (same-origin) for the exact displayed bitmap when the rendition URL itself is refused.
  • Icons and vectors: harvest from the live DOM, never approximate. Before authoring any icon, run one probe on the live page collecting svg.outerHTML (plus <img src$=".svg"> and mask-image urls) near the matched text or aria-label. Six hand-drawn lookalikes (person, globe, bell, clock, swap-arrows, check) passed every block gate and read wrong to the eye; all six were extractable verbatim in one probe (recorded). A hand-drawn icon is the fallback only when no live vector exists — and it is a ledger entry.

Capture-state policy — ground truth is the page as observable by the instrument. Two recurring cases:

  • Lazy images stuck on designed placeholders. Some lazy loaders leave images on base64 placeholder data-URIs that report complete && naturalWidth > 0 (fooling load checks). Do NOT force data-src→src swaps — the CDN 403s the forced renditions and you get broken-image icons, worse than placeholders. Replicate the site's own placeholder assets where the live capture shows placeholders, and log each instance in the progress ledger flagged for the delivery phase (real renditions get wired when authors upload media).
  • Hydration states. Commerce buttons stuck on "Loading …" headless, skeleton screens, etc. Replicate as captured, log, flag for delivery. "Fixing" the hydration state creates a pixel delta against the live capture AND fabricates a state the source never showed this instrument.
  • Nondeterministic live elements — stock tickers, "last updated" dates, view/result counts, personalization slots. The live capture itself varies run-to-run on these (recorded: a ticker populated in one gate capture, empty in the next). Replicate the STRUCTURE, freeze one captured value in the prototype, and log the element as a permanent residual in the ledger — it can never zero out, and chasing it burns iterations on a moving target. This is the one content class where confirm-justify stays legitimate under widget mirroring (§ Granularity parity).
  • Live-data embeds (stock tickers, YouTube/euroland-style iframe widgets) — load the SAME live embed (same src) on both sides so the moving data cancels out in the pixel diff, NOT a frozen snapshot (a same-src player and a share ticker each zeroed out, recorded). A snapshot guarantees a permanent residual the size of the widget; any residual left (frame-timing skew) is logged as permanent. Same src, later mount: a player is created after first paint (../../deploy/SKILL.md #157) — the gates capture a settled page, so pixels are unchanged; when the source loaded it eagerly, note the deferral in the progress ledger.
  • Randomized decorative elements (inline positions/paths regenerated per page load — generative line art, particle fields): the live side never pixel-matches ITSELF across captures, so no prototype can zero it out. Class-level permanent residual: log it with its band and %, don't chase it.
  • Pointer/hover state. Pointer position is part of capture state: a :hover-styled element under the resting cursor is a false-measurement trap (recorded: a consent click left the cursor over a hero whose a.box-hover:hover img{opacity:.4} shipped the entire live capture with the hero dimmed). Instrument hardening includes parking the pointer — stitch-shot.mjs does it after consent dismissal; mirror it in any ad-hoc capture that clicks anything.
  • Pre-settle height is fake on entrance-animated sites. Live scrollHeight differs before vs after the settle pass (recorded: 3183 vs 3093 at 360 — entrance translate3d(0,90px,0) transforms inflate the document until elements go inview). stitch-shot's settle handles it; any ad-hoc probe that reads document height — the diagnosis probes this skill encourages included — must settle first too.

Granularity parity (the #87 JOIN/SPLIT policy)

Zeroing content-diff against a live page requires mirroring the live DOM's node granularity, which is in tension with clean re-authoring. Policy — mirror these classes rather than fighting per-page false-reds:

  • Span-in-heading splits: live headings that wrap text in inner spans classify the fragments differently; mirror the split.
  • Hidden DOM that counts as content: mega-menu markup inside <main>, carousel clone slides, hidden tab-panel links, sr-only labels ("Old price"), even server-truncated strings. Content parity means DOM parity, not visible-text parity — reproduce them hidden, exactly as captured.
  • AEM-classic richtext byte patterns are load-bearing (general to the source-CMS class, not one site): an empty spacer paragraph is <p><br>\r\n </p> and renders TWO line boxes (the <br> plus the still- collapsible space); headings lead with <br> (<h1><br>\r\nTitle); a trailing &nbsp; after an inline close is a REAL extra line. Approximating these as clean <p><br></p> measures 20–36px short per instance. Mirror the byte patterns as captured; when a wrap-count mismatch survives width parity, diff innerHTML — the byte-level difference is usually the cause.
  • Alternatively, where mirroring would be genuinely absurd, treat the specific JOIN/SPLIT reds as confirmed-justified per diff SKILL.md's #87 guidance (verify the fragments concatenate into a matched EXTRA before justifying) and record each in the gate log. Mirroring is the default; justification is the exception, because every justified red is a manual re-verification on every subsequent gate run.

Widgets are implemented, not justified away. Mirroring is the default for widget content, hidden or not — and beyond mirroring the DOM, widgets must WORK wherever the live site's do: a live carousel becomes a working carousel, a live select carries its real option list, tabs switch, accordions open. Justifying a whole widget away as a class-level residual is not acceptable; confirm-justify stays reserved for genuinely unreachable or nondeterministic content (ticker values, personalization — § Asset harvest, capture-state policy); § Interaction parity is what makes this affordable. On EDS the delivery form of an app-like component with no authored content is a widget (widgets/<path>/<name>, mounted as one link — ../../stardust/reference/data-attributes.md), not a block with empty rows, and the fidelity gate measures the rendered DOM the same way.

Role parity (mirror the look; semantics may improve)

content-diff classifies every string by DOM wrapping + computed style, never by text alone: a string inside an <a> is a CTA, an uppercase small-type node an eyebrow, an <h*> a heading. Severity follows visibility (../../diff/SKILL.md § Reading content-diff), so mirror the live look and every link per string; improve the semantics where the look holds. When iteration 1 opens with a wall of ROLE SWAP / MISSING-CTA-plus-EXTRA pairs (a link where the live page has a span, or the reverse), fix those first and re-run before touching geometry — they are cheap, and clearing them un-buries the real reds.

Carousels and animated sections

  • Deterministic initial offsets (centering math, first-slide-at-rest): compute the offset and reproduce it statically — stable across runs (UC1-E1: both mid-page carousels were centered tracks, reproduced at their computed offsets with zero JS).
  • Autoplaying carousels / marquees / muted loop videos: freeze policy FOR THE CAPTURE ONLY — stitch-shot's animation freeze, timer clear and video seek to t=0 keep both sides stable, so the recreation reproduces slide 1 / frame 0 as its INITIAL state. The freeze is capture state, never the deliverable: every freeze or mask the gate needs is one captureState entry in progress.json whose restoreAtDelivery names the live behaviour as observed (autoplay muted loop, rotates every 5 s, marquee 40 px/s), and C-deliver implements that list before the page counts as delivered (source-fidelity-gate.md § Residual logging format). "Poster + paused video" or "static first slide" is a capture artefact, not a spec — a recorded run passed 26/26 parity rows while nothing played because the freeze had quietly become the brief.
  • Loop clones are presentational: when Splide/Swiper geometry needs 2×perView clones before and after the track, clones carry no text nodes, alt="", no href, no role/aria-* (aria-hidden/inert do not help — readability checkers read textContent). A faithful clone of the canon's DOM turns a 5-card rail into 17 cards of text and halves the page's AI-readability score (deploy/reference/ai-readability.md).
  • Style-injection ordering: inject any freeze CSS only AFTER the lazyload settle pass — injecting before it breaks some loaders' swap logic (recorded UC1-E1 failure mode). stitch-shot.mjs already orders this correctly; mirror the ordering in any ad-hoc probe.

Interaction parity (after the static gate — observed, never inferred)

The gate measures static pixels at t=0 only: every scroll-entrance animation, header scroll-morph, hover transition, and secondary carousel is invisible to all four probes — and users notice them immediately on first manual review. After the static gate passes (never before — interaction work on unconverged geometry is rework), run the interaction-parity pass. It is a REQUIRED per-archetype gate output (SKILL.md Phase 4 — the motion inventory), not an optional post-pass: in the field it was skipped on 5 of 7 archetypes, including under parallel sub-agent briefs, and every skipped archetype shipped visibly static. Any parallel archetype fan-out brief must carry this section's evidence rule and instrument invocation verbatim — this is precisely the step agents skip when unprompted.

The evidence rule: motion is OBSERVED at runtime, never inferred from static classes or CSS rules. Run ../scripts/motion-observe.mjs ONCE per archetype live URL (full down+up scroll traversal; --click each carousel/widget control; --hover each distinct card/teaser/button family; reuse the JSON — observation costs live hits like any probe). Implement ONLY behaviors that measurably fired, with the recorded trigger mechanism, durations, and thresholds. Static source CSS is then the authority for the exact keyframe/easing VALUES of those fired animations. A behavior implemented without a runtime trace naming it is a fidelity bug — same severity as an unregistered design change. Timer-driven media IS a fired behavior even though the capture instruments stop it: autoplay / loop on a <video>, a currentTime that advances between two samples, a slide index that changes with no interaction — the observe JSON's media block records them before any freeze. "Dead" means never fired on live, never "stopped by the freeze"; a video or carousel the freeze paused is implemented and listed in captureState[].restoreAtDelivery.

Static lifting INVENTS motion three distinct ways (all field-recorded, all caught in user review — this is why the evidence rule exists):

  1. Dead animation classes. Sites — component CMSs especially — stamp animation classes on many elements; the runtime JS adds the trigger class (.animate etc.) to only SOME of them (recorded: of ~8 caption-class families carrying an entrance class, 2 ever fired; 3 whole page types had ZERO firing entrances despite fully classed markup). Tagging from static classes animates elements the real site never animates. A live-classed-but-dead behavior is recorded as NOT implemented — that is the correct replica of a dead class.
  2. Hover rules whose scope never matches. A plausible, syntactically applicable :hover rule can be dead at runtime (scoping condition, specificity loser, wrong variant) — and the inverse: the fired hover may move a different element than the rule suggests (recorded: media-card hover scaled the caption, not the card). Only a measured hover diff justifies a hover rule in the prototype.
  3. Approximated mechanisms create impossible states. Reproducing a header scroll-morph as a cloned fixed overlay bar looked equivalent but allowed bar + original header visible simultaneously — a state that cannot exist on live, which morphs its SINGLE header in place. Users see a double-rendered header. Mechanism cloning rule: scroll-chrome and widgets are reproduced as the SAME state machine observed live (same element morphing, same class-state transitions, same restore thresholds — the observe JSON's headerTimeline and classMutations name them) — never as a different mechanism with a similar look.
  4. The header is a contract, not a look. Menus, drawers, search and their reachability are recorded and gated by chrome-explore / chrome-compare (../../diff/SKILL.md § The header contract).

The two probe patterns the instrument wraps (both cheap, generic, no source JS needed): hover diff (--hover) — computed background/color/shadow/transform on the element + key sub-elements, before vs after a real pointer hover, plus transition-*; overlays dismissed first (an overlay intercepts the pointer and the probe reads no change), mouse parked between probes; the changed-property list translates directly to :hover CSS. Behavior diff (--click) — click the control, sample the animated property mid-flight and settled (transform/scrollLeft + computed transition-*): pitch, easing, duration. Map observed elements to prototype counterparts by the TEXT SNIPPET in the event log, never by class names (prototype classes are clean re-authored names).

Swiper-lock semantics (the dominant carousel library): Swiper hides its controls and disables dragging when the content fits the viewport (swiper-lock/watch-overflow), so per-breakpoint the same widget is sometimes a carousel, sometimes a static row. A scroll-based replica reproduces the entire behavior with no DOM restructuring: arrows drive scrollTo on the already-overflow:hidden track, position count = round((scrollWidth − clientWidth) / pitch) + 1, and controls hide when scrollWidth <= clientWidth — which auto-degrades to the static case exactly where the live widget locks. Late re-renders (e.g. re-check at 400/1200/3000ms and window load) are needed when the platform decorates DOM after the widget initializes — the overflow measurement taken at decorate time is stale by first interaction.

Implementation pattern — ONE shared motion layer per project, never per-page forks: css/motion.css (lifted keyframes verbatim; trigger rules reusing the LIVE class names — that keeps the capture instruments symmetric, since stitch-shot's animation handling already keys on the live conventions; hover rules hover-diff-verified only; chrome-morph classes; indicator transitions) + js/motion.js (an IntersectionObserver adding the live trigger class — threshold as measured, typically ~0.15, once — to a tagging map of runtime-FIRED selectors only; the chrome state machine on scroll with the measured direction + thresholds; widget drivers mirroring observed mechanics). Gate-safety is by construction: entrance animations only run once the trigger class is added — verify the live site has no pre-animate hidden state (if it does, stitch-shot's entrance-state forcing covers it); chrome morph is inert at y=0; hovers need a pointer; stitch-shot clears timers so autoplay stays at t=0. Widget DOM stays fully mirrored so content-diff holds at zero structural red (§ Granularity parity — widgets are implemented, not justified away).

Verification protocol, both directions: (1) no pixel regression — re-run pixel-compare per touched archetype at the gate breakpoints; the number must return to (± noise of) the gated value (recorded: 1.01% gated → 1.06% with invented motion → 1.01% exact after the evidence-only rewrite). The drift itself is the smell test: motion code that changes t=0 is wrong. (2) behavior match — a headless run against the PROTOTYPE asserting, per page: tagged-element count == live fired count; zero pageerrors; the header's scroll states are chrome-compare's.

Pitfalls (each field-recorded):

  • Observation needs the same live-session hardening + pacing as the gate captures (bot walls, 429 bursts): ONE observation run per page, reuse the JSON.
  • Autoplay widgets may pause off-viewport — poke them explicitly with --click rather than waiting for autoplay events.
  • Indicator "magic dots": the live mechanism may animate left/transform where an equivalent rendered effect in the recreation animates width/height — equivalence of the RENDERED effect is the bar, but the duration/easing must be the measured ones.
  • Wobble/stagger patterns: delays may be child-order dependent (recorded: 2nd child first, 0.5s steps, 1st child last) — read them from the CSS rules of the FIRED animation; they are not guessable.
  • prefers-reduced-motion: mirror the live site's handling — do not "improve" by adding it where live has none; that's an inconsistency-register item, not a freebie.

Log each implemented interaction in the progress ledger the way a CSS portation is logged.

Fixed and sticky chrome (headers, floating tabs × stitched capture)

stitch-shot captures position: fixed/sticky layers once: chunk 1 shows the top of the page as a visitor sees it; from chunk 2 a fixed layer — and a sticky one while it is stuck — is transparent, so the seams it covered neither repeat it nor hide the content under it. The scan re-runs after every chunk's scroll: a header that turns fixed on a scroll class, or a widget injected later, is hidden from the chunk where it appears (a stderr WARNING names it), so its scrolled state does not reach the capture either.

What it does not cover:

  • a backdrop — a fixed layer with a negative z-index or covering ≥ 90 % of the viewport (a background image or video, a full-screen modal) — stays in every chunk by design; an undismissed full-screen modal with consent / sign-up copy is a WARNING, any other one is not;
  • fixed elements inside a shadow root, an iframe's own document, or a ::before / ::after pseudo-element are not seen and still repeat;
  • a layer that turns fixed on scroll is in the flow in the chunks before that, as on the page — chunk 1's geometry is the page's, not a clean top.

Replicate fixed chrome AS fixed all the same (never flattened to static/in-flow — that moves chunk 1's geometry), with its scroll-state morph: the header contract (chrome-compare) measures the scrolled state. Minimal prototype JS for that morph is the one sanctioned exception to the "no JS unless a section's initial state requires computing it" rule: a few lines toggling the same class at the same scroll threshold as the live site (lift both from the source JS/CSS — never guess them), no frameworks, no other behavior; log it in the progress ledger like a CSS portation.

Reading the diff: fix any height delta first — hot bands below the first one are offset contamination, not chrome bugs.

CSS-portation fallback (per-section, never page-level)

Re-authoring is the mainline — validated as sufficient for every section type on a strict design-system site. Porting the source's own CSS rules is the reserve, admissible for a SECTION only when it hits one of:

  1. Paint-level effects not recoverable from computed styles — and only when the effect IS in the source CSS (when it isn't, luminance fitting above is the tool).
  2. JS-hydrated commerce/PDP widgets whose "current state" is a moving target across captures.
  3. Video/animated heroes where a static recreation can't express the captured state.

Rules when it fires: port the minimal rule set for that section, tree-shaken to used rules, scoped under the section's class; record the portation (and why) in the progress ledger. Never page-level — page-level portation carries the source's CSS debt into the blocks, defeats "better implementation of key pages", and is fragile under block-class scoping. A page that would need page-level portation is a page that should be flagged to the user as a snowflake-overlay candidate (byte-preservation escape hatch, outside this skill).

skills

README.md

tile.json