Documentation

scrapping.md

Reference Recreation System

Objective

Recreate a user-provided reference image as accurately as possible in working UI code.

Input

The user submits an image, or a website URL and visible text identifying the section they want recreated.

Reference Mode

For an image, follow the visual-analysis and scale-calibration rules below. For a website, locate the exact section from the supplied text, create a fixed capture at the chosen primary viewport, and use browser inspection to observe its rendered structure, computed styles, dimensions, typography, media, and interactions. Use this extra evidence to reduce guessing while following the same recreation process and single-view 90% QA threshold used for images; rebuild within the target design system rather than copying source code or hotlinking assets.

Recreation Rules

Study the reference carefully before implementation. Identify its layout, hierarchy, spacing, typography, colors, borders, shadows, imagery, responsive behavior, and interactive elements.
Recreate the interface with real UI code and reusable components.
When useful, adapt compatible building blocks from trusted registries as structural skeletons instead of rebuilding common patterns from scratch. Prefer this for responsive sections such as navbars, while preserving accessibility and conforming the result to the target design system.
Do not take shortcuts by placing the reference image, a screenshot, or large image slices into the page instead of building the interface.
Treat outer mockup frames, inset presentation cards, and surrounding canvas as presentation chrome unless clearly part of the requested section; do not recreate them.
Text visible in the reference must be implemented as real text, not baked into an image.
Controls and interface elements must be functional where their intended behavior can be inferred.
Image generation may be used for decorative artwork, illustrations, textures, or backgrounds when suitable source assets are unavailable. It must not replace UI structure, controls, or text.
When extracting or recreating a background, illustration, texture, or other image region, provide the original reference image to the image-generation or image-editing tool. Identify the specific region and instruct the tool to extract or recreate the background from that part of the reference. Prefer this reference-guided workflow over attempting to reproduce the asset from a text-only prompt with no visual reference.
Crop or isolate the relevant reference region when useful so the image tool receives the clearest possible visual guidance. Preserve the resulting asset as a separate implementation asset rather than embedding the full reference screenshot.
Preserve the conventions, design system, and technical constraints of the target codebase.
Verify the result at the same viewport size and aspect ratio as the reference whenever those dimensions can be determined.
Give every published page a unique, descriptive URL slug based on what the page contains: its section type, composition, visual treatment, interaction, or another implementation-specific characteristic. Never derive the slug from the reference site's name, product name, brand, domain, source URL, or source section identifier. Reference provenance belongs only in the dedicated source and Referenced Media metadata, never in the public route.

Motion and Interaction Inspection (mandatory)

If the reference contains or suggests animations, transitions, hover effects, disclosures, scrolling effects, or other interactions, investigate them before implementation. A still screenshot does not establish how the interface behaves. When a source website is available, exercise the actual behavior rather than substituting a plausible animation.

Identify and trigger every relevant state: initial appearance, hover, focus, press, opening, closing, switching, scrolling, and timed or looping changes. Repeat interactions, reverse them midway, and switch rapidly to understand interruption and sequencing. Inspect responsive differences and reduced-motion behavior where available.
Observe the complete transition, including how surrounding content moves. Inspect computed CSS transitions/keyframes, the browser animation timeline, or exposed animation properties to determine the animated properties, start/end values, exact duration, delay, easing curve, transform origin, scale, opacity, clipping, layout changes, stagger, overshoot, repetition, and direction. For spring motion, record the spring parameters or measure its displacement and settling behavior; do not replace it with an arbitrary ease.
When the properties alone do not explain the behavior, slow playback or inspect it frame by frame. Capture comparable timestamped frames or recordings from the source and recreation, including the start, intermediate phases, overshoot, and settled state. Measure timing and motion values rather than relying on a memory of the effect.
Recreate the observed motion precisely, including duration and easing curve. Preserve opening and closing choreography, coordinated layout movement, interaction feedback, and behavior during interruption. Do not settle for a generic fade, slide, or spring because the resting screenshot looks correct. Keep the implementation accessible, respect reduced motion, and stop section-owned work when inactive or unmounted.
Verify the recreation against the source using the same trigger, viewport, state, and timeline positions. Record the measured values and any remaining differences. Static visual similarity does not pass the motion requirement. If source behavior cannot be inspected, state what remains unverified and distinguish inferred behavior from measured behavior instead of claiming an exact recreation.

Recreated Section Editing Rules

When the recreated output is classified as a Section, follow these additional rules:

Catalog placement: Add every new Section to the latest (first) position in its type group in the grid, never the last position.

Font repository law (mandatory): Every font family introduced by a Section must also be available in the shared font library before that Section is complete. Download every used custom font face into public, declare the local files in the Section stylesheet, and register the family, category, source Section, weights, styles, and local URLs in fonts/repository.json. Register system-only families and their usable weights in fonts/system.json. The live font-catalog API merges both registries directly, so registration must automatically make the family available in the Properties font-family picker without adding it to a second dropdown allowlist or waiting for a catalog rebuild; regenerate fonts/catalog.json only to refresh the committed snapshot. Never leave a Section-only font hotlinked, hidden in local component code, or unavailable from the Properties font-family picker.

Editing and theming: Export and register a PreviewCustomizationSchema beside the section. Map its meaningful text styles with scoped typographyControl selectors, and expose editable solid colors and gradients with solidPreviewColor and gradientPreviewColor. Every exposed typography selector must match at least one element in the rendered preview; correct or remove stale and unused mappings instead of presenting inert style controls. Every recreated section must resolve those typography styles to exactly two semantic family values: Heading font family for heading controls and Text font family for every non-heading control, including body copy, navigation, buttons, captions, accents, and route labels. Preserve independent per-style weight, size, spacing, and wrapping values; do not create additional family slots for an original accent or interface font. If a section uses a custom font, download its files locally and register every used face in fonts/repository.json so other sections can reuse it. Theme shows only the named typography-style rows, without separate family rows or Font families/Text styles subheadings. Every named style object in Theme and Edit exposes an editable Font family above Breakpoint, with a visible Lucide Link2 icon and linked-state description; changing it updates every style in the same Heading or Text family. Neither presentation includes a Color property because semantic color controls own text color. Set the correct light or dark mode, assign semantic color roles where applicable, and route editable styling through section-scoped CSS variables with the scraped source values as fallbacks. Theme changes must preserve readable contrast and the intended distinction between backgrounds, surfaces, text, actions, and decorative artwork.

Customizable images are strictly opt-in. Never add an asset property or convert ordinary media into a background merely because a reference contains imagery. Add assets with backgroundImagePreviewControl only when the user explicitly requests interchangeable background artwork and the section has a real, replaceable background-art layer. A normal reference image, scraped source media, extracted artwork, or a general request for color theming does not authorize an Assets group. When the requirement is explicit, store every option locally, preserve intrinsic dimensions and useful alt text, include the intended original/default image, and make the Theme picker and coordinated randomize action operate only on that declared option set.

A compatible background-image control may opt into gradientMask in its section schema. Keep this capability small and optional: default the mask off, expose only Yes/No, Top/Bottom fade edge, and percentage fade amount, and apply the resulting CSS mask to the isolated artwork layer rather than the section wrapper, copy, controls, or translucent UI above it. Do not declare mask controls for inline content images, logos, screenshots, or any section where the artwork cannot be faded independently.
Font Size units: Font Size defaults to px while allowing px, rem, em, %, vw, vh, cqw, and cqh. Pixel Font Size values are whole numbers; decimals remain valid for non-pixel units. Do not apply this rounding rule to unrelated dimensions, coordinates, shadows, transforms, animations, or other CSS values.
Responsive text flow and type scale: Avoid adding <br> elements merely to force the line wrapping seen in one reference viewport. Unless a break is semantically or compositionally essential, let text reflow using responsive max-width constraints, readable line lengths, fluid type where appropriate, and CSS wrapping such as text-wrap: balance or text-wrap: pretty. Author explicit Desktop, Tablet, and Mobile behavior and treat prominent type as a monotonic scale: Desktop must be greater than or equal to Tablet, and Tablet must be greater than or equal to Mobile. Small labels and already-compact copy may remain unchanged, but a heading or paragraph must not grow merely because the container becomes narrower. Scale line height, text width, surrounding gaps, padding, control dimensions, and nearby media with the type rather than changing font size in isolation. Verify at 1440px desktop, 1024px tablet boundary, 834px tablet, 768px tablet canvas, 520px mobile boundary, and 390px mobile canvas.
Editor-ready layer hierarchy: Build every meaningful visual object as a real, selectable HTML element in the same parent-child hierarchy and sibling order shown in the reference. Use semantic elements where possible and give otherwise ambiguous structural or media wrappers a stable, human-readable aria-label; layer names must not depend on generated class hashes, truncated prose, array indices, or viewport-specific text. Keep decorative implementation details aria-hidden, and do not turn meaningful artwork into a pseudo-element or an undifferentiated background when users should be able to select, move, or delete it.
Reorder-safe structure: DOM order must be the visual order for normal-flow children. Use a parent's authored flex or grid layout, gap, alignment, distribution, and padding to compose its children; avoid CSS order, transform-based placement, duplicated breakpoint-specific DOM, display: contents, portals, and absolute positioning for ordinary structure. A sibling moved up or down in the Layers panel must move visually without requiring a second CSS edit. Use stable semantic React keys where a list is unavoidable, and do not run effects that restore the original child order after an editor mutation.
Composition wrappers and spacing ownership: Use wrapper <div> elements to represent meaningful groups of layers that align, resize, or move together. For example, place a title and subtitle in a copy wrapper and apply their shared max-width to that wrapper instead of repeating the constraint on both text elements; then place that copy wrapper and its button or action group inside a higher-level content wrapper. The parent that owns a relationship must also own its display, direction, alignment, and gap. Use gap for the normal spacing between siblings and padding for spacing inside a container; do not build the primary layout from chains of child margins, one-off offsets, or negative-margin corrections. Give an individual child a margin or constraint only when it intentionally differs from the group. Add a wrapper only when it expresses a real compositional relationship, not merely to increase nesting.
Independent parent and child sizing: A container controls arrangement, not every child's width or height. Preserve a separate width mode and height mode for each selectable layer: Fixed uses an explicit non-percentage length, Relative uses a percentage, Fill participates in the parent's available space through flex growth or cross-axis/grid stretch, and Fit Content remains intrinsic through auto, fit-content, min-content, or max-content as appropriate. Do not use a broad parent selector such as .parent > * { width: 100% } unless the reference truly gives every child that behavior. Changing a parent's size or direction must not silently rewrite a child's authored sizing semantics.
Stack for one dimension; Grid only for two: Author layout on the actual parent that owns the children. Every one-dimensional relationship must use an explicit flex Stack: vertical or horizontal copy groups, navigation and action rows, menus, lists, headers, pricing-card rows, icon centering, and any imported one-column or one-row flow. A one-column/two-row CSS grid is a vertical Stack, and a three-column/single-row CSS grid is a horizontal Stack. Do not use Grid merely to get gap, place-items, equal-width siblings, centering, or a single row/column track. Reserve display: grid for a structure whose children genuinely populate both rows and columns, such as a repeating card matrix or repeated label/value table; declare its tracks and independent row/column gaps explicitly. Prefer simple longhands that the editor can inspect. Do not flatten a coherent stack into margins on each child or simulate a grid with absolute coordinates. For flex children that fill the main axis, use an unambiguous grow/basis model; reserve width: 100% or height: 100% for fill on an applicable cross axis or non-flex parent.
Preserve removable constraints: Record source min-width, max-width, min-height, and max-height as their corresponding authored longhands on the constrained layer, with numeric editor-supported units whenever the source can be represented that way. Omit constraints that are not present instead of inventing fallback limits. Do not bury a removable constraint inside width: min(...), clamp(), grid tracks, a shorthand, or logical-size aliases merely for convenience. If min-width: 0 or min-height: 0 is genuinely needed for flex/grid overflow, treat it as an intentional visible constraint. Adding, editing, or removing any one constraint must not alter the other three or the layer's width/height mode.
Editable text: Keep user-visible copy as real text in a single meaningful text element, with text nodes and only semantically necessary inline markup. Avoid per-word or per-character spans, canvas text, SVG text, and decorative clones. Double-click editing, selection, caret placement, paste, Escape/cancel, and the resulting layer name must remain predictable; interactive form controls retain their native editing behavior.
Scoped assets and styles: Store recreated media locally with the section and render selectable media as <img>, <video>, or a labelled wrapper when appropriate. Do not hotlink source media or leak section rules into app-shell/global styles. Keep component markup, assets, and a CSS module together; scope variables and selectors beneath the section root, preserve intrinsic media aspect ratios, and ensure deleting or reordering one media wrapper cannot restyle unrelated siblings.
Container-responsive implementation: Make the full-size section root an inline-size query container and express section responsiveness with @container rules so resizing the preview, its parent, or a Relative/Fill layer produces the same behavior. Every Section must include an intentional tablet rule covering the 768–1024px range and a narrower mobile rule where the composition needs another reduction; do not let desktop CSS accidentally serve as the tablet design. Disable container behavior only in the catalog's compact thumbnail mode when required by the existing preview contract. Use cqw/cqh only when the value should scale with the nearest query container, not as a substitute for the editor's Fill or Relative sizing modes. Audit computed typography at both sides of every query boundary because an unrestricted clamp() can otherwise make tablet or mobile type larger than desktop.
Editor acceptance testing: In addition to visual QA, test the published Section end to end in layout-edit mode at mobile, tablet, desktop, and XXXL widths. The named-style inspector begins with icon-only Desktop, Tablet, and Mobile segments using Monitor, Tablet, and Smartphone, not L/M/S text. Switching the segment must switch the canvas, measure that breakpoint's native font size, letter spacing, line height, alignment, and wrapping, and preserve independent edits when switching away and back. Verify stable layer names and nesting; canvas-to-tree selection; direct text editing; independent Fixed/Relative/Fill/Fit Content changes on parent and child axes; intelligent Size input where 40% selects Relative, 20px selects Fixed, and a plain number preserves the current mode for Width, Height, and every min/max constraint; stack direction, wrap, align, distribute, gap, and padding controls; genuine two-dimensional grid columns, rows, gaps, and padding; adding each min/max constraint at its 100 / Fixed default, editing it, context-menu removal, and re-adding it; keyboard and context-menu deletion; and moving several first, middle, and last siblings up/down from the Layers panel. Explicitly select every one-dimensional container and confirm the inspector reports Stack with the correct horizontal or vertical Direction; select every retained Grid and confirm its children actually occupy multiple rows and columns. Assert that Layers order and canvas visual order match after every move, that block-flow DOM order follows the move, and that flex/grid visual-order overrides survive a component state update without corrupting React-owned DOM. Refresh between destructive cases, confirm responsive styles still apply, and include at least one text, interactive, media, nested stack, genuine grid, fixed/sticky, and overflow-prone layer in the matrix.
Framer-style inspector boundary: Responsive source CSS may use container queries, cqw, or other appropriate implementation units, but the editor-facing Size and Layout experience must remain abstract. Fixed dimensions, min/max constraints, gap, and padding are presented as whole rendered pixels without unit selectors; Relative, Fill, and Fit Content are expressed through their modes. Size fields may accept px or % while the user is typing solely to infer Fixed or Relative, then normalize back to a unitless value beside the selected mode. Do not require a user to understand display names, grid track strings, logical properties, flex basis, aspect ratio, or child-margin chains to edit the section.

Scale Calibration

Treat the reference as visual evidence, not a one-to-one CSS measurement. Screenshots may be cropped, resized, zoomed, or captured at a different device-pixel ratio. Match proportional relationships and visual hierarchy within a normalized viewport rather than copying raster dimensions.

Use design tokens and responsive constraints such as clamp(), max-width, aspect-ratio, and container-relative sizing. Keep typography, controls, navigation, media, and spacing within practical interface proportions unless the reference clearly shows intentional exaggeration. When scale is ambiguous, choose the more conservative usable size and record the assumption for QA. Do not introduce fixed sizing rules that override the target design system or the reference's proportions.

Testing Step

After the initial recreation, create a brand-new QA agent for that testing cycle.

Give the QA agent:

The original reference image or fixed primary-view website capture.
A current screenshot of the recreated interface at the matching viewport.
Any relevant context needed to distinguish intentional behavior from visual defects.
For references with motion or interactions, the measured transition properties and comparable source/recreation frames or recordings across the full transition.

Ask the QA agent to return:

A visual similarity score from 1 to 100.
A concise explanation of the score.
A prioritized list of specific changes that would improve similarity.
Concrete observations about layout, spacing, sizing, typography, color, imagery, borders, shadows, alignment, and responsive behavior.
When motion is present, a separate assessment of interaction states, layout movement, timing, easing, sequencing, and intermediate frames. A passing still-image score must not conceal a missing or mismatched transition.

The QA agent must pass its complete assessment back to the main thread.

Judge scale only after confirming matching viewport, zoom, crop, and page state. Do not recommend enlarging an element solely because it occupies more pixels in the supplied screenshot.

Improvement Loop

The main thread reviews the QA assessment and converts each actionable issue into a clearly scoped task.
Spawn as many implementation agents as are useful, up to 20, to work on independent issues in parallel. Avoid assigning multiple agents to overlapping files or conflicting changes unless their work is explicitly coordinated.
The main thread integrates the fixes, resolves conflicts, and verifies that the app still builds and runs correctly.
Capture a new screenshot at the same viewport used for comparison.
Create a brand-new QA agent and repeat the Testing Step using the original reference and the new screenshot.
Continue this loop until the QA agent reports a similarity score of 90 or higher.

Completion Criteria

The recreation is complete only when:

A brand-new QA agent awards a visual similarity score of at least 90 out of 100.
The final screenshot uses the same viewport and comparable page state as the reference.
The interface is implemented with real UI code rather than screenshot substitution.
Required interactions work, and observed source motion passes the Motion and Interaction Inspection checks, including duration, curve, intermediate states, and interruption behavior.
The project passes its relevant lint, type-check, test, and build checks.

If a score of 90 cannot be reached because the reference is incomplete, required assets are unavailable, or a technical constraint prevents an accurate match, report the blocker clearly instead of claiming completion.

Post-processing

After passing 90%, test the canonical 390px mobile, 768px/834px/1024px tablet, 1440px desktop, and XXXL breakpoints. Correct overflow, wrapping, spacing, media scaling, and responsive text sizes; ensure composed UI such as navbars, bentos, grids, and other components remains usable and visually coherent at each size. Compare computed font sizes and line heights for matching text across widths and reject any Desktop < Tablet or Tablet < Mobile reversal for prominent copy. Confirm that hierarchy remains consistent: headings should not overwhelm their containers, body text must remain readable, controls must remain usable, and media must not exceed its intended layout role.

Verify the source-backed motion and interaction layer after achieving static similarity. This is required recreation work, not an optional post-processing enhancement. Only infer motion when no observable source is available, clearly record that assumption, and keep it coherent with the reference. Motion must preserve the approved composition, remain usable, and respect reduced-motion preferences. The 90% threshold measures static similarity only; completion additionally requires the motion and interaction checks above.

Final Publication Step

After the post-processing checks:

Add the finished recreation to the app library as either a Section or a Component.
Classify it as a Section when it represents a composed page region or multi-element layout. Classify it as a Component when it represents a focused, reusable interface element.
Create the library entry using the same metadata structure and conventions as existing entries.
Include the original reference image or fixed website-section capture as a separate metadata datapoint named Referenced Media. For websites, include the source URL and section identifier with it. Do not merge this field with the implementation preview, generated artwork, thumbnail, or other media fields. Author referencedMedia as an ordered array of { image, sourceUrl?, sectionIdentifier } using the contract in lib/reference-media.ts. Include a separate item for every supplied or used reference when there is more than one; append rather than replacing earlier entries or assets. Preserve all earlier references during restyling and label historical or style-only influences. Omit an unknown source URL instead of inventing it. Mirror the entire list in section-owned metadata and the inert catalog snapshot. The shared ReferencedMedia gallery supports both these arrays and existing single-object entries.
Make the new library entry discoverable from the appropriate navigation, category, and detail view.
Verify the published entry renders correctly and preserves the approved recreation.

The recreation workflow is not finished at the 90% threshold alone. It is finished only after the approved result has been added to the app as a Section or Component with its Referenced Media datapoint included.