Reference replication
The eye is good at "something is off" and unreliable at "off by how much". When the brief is "replicate it exactly, no mistakes", measure. Every hour lost to nudging a value was an hour that one extraction script would have ended.
Never trust the screenshot's edges
Screenshots arrive letterboxed, device-framed, or with a rounded browser chrome. Measuring against the file's dimensions then puts every percentage slightly wrong, and the error is invisible because everything is nearly right.
Find the real content box first:
from PIL import Image
import numpy as np
a = np.array(Image.open(src).convert('RGB')).astype(int).sum(axis=2)/3
rows = np.nonzero(a[:, 5] > 200)[0] # a column that is page background
cols = np.nonzero(a[rows.min()+40, :] > 200)[0]
X0, X1, Y0, Y1 = cols.min(), cols.max(), rows.min(), rows.max()
Express every subsequent measurement as a percentage of that box, never of the file.
Extract positions, don't estimate them
def bbox(x0, x1, y0, y1, lo, hi):
reg = a[y0:y1, x0:x1]
ys, xs = np.nonzero((reg >= lo) & (reg <= hi))
return x0+xs.min(), x0+xs.max(), y0+ys.min(), y0+ys.max()
Window each element and threshold on its luminance band — dark UI on light background, or the reverse. Two cautions:
- A result that lands exactly on your window edge is a clipped measurement, not a finding. Widen the window and re-measure.
- Dark text and a dark photograph both pass a "dark" threshold. Choose windows that contain only the element.
Convert to percentages of the content box and build to those. Now "the headline is too big" becomes "the headline is 22.4% of panel width in the reference and 32% in mine".
Verify a claim before you build it
Look for a feature twice before committing. On one build a pair of vertical hairlines was "seen" in a thumbnail and implemented; the reference had none — it was the subject's own silhouette edge. One check would have caught it:
band = a[60:330, :].mean(axis=0) # rows clear of other UI
dips = [i for i in range(200, W-200) if band[i] < 228 - 0.8]
Flat background, no dips, no lines. A 1px rule shows as an isolated single-column dip; a photographic edge shows as a gradual ramp. They are trivial to tell apart numerically and easy to confuse by eye.
Solve image framing, don't nudge it
To reproduce how a photograph is cropped, derive it. Measure the subject's width as a fraction of the photo, and again as a fraction of the panel:
renderScale = subjectWidth_inPanel / subjectWidth_inPhoto # e.g. 1.231
With object-fit: cover scaling by height, scaledW = panelW × renderScale, so
panelAspect = 1 / (renderScale / photoAspect). That gives the panel proportion the
designer used. Then solve object-position from the subject's centre — the formula is in
../landing-page/references/traps.md.
Sanity-check with an independent quantity you did not fit, such as the subject's crown height. If the prediction lands within a pixel or two, the model is right.
Know when a reference cannot be matched
Sometimes the maths says no. If the required object-position falls outside 0–1, no value
places the subject there — the panel aspect or the image has to change.
And if a supplied asset is a regeneration of the original rather than the original, its proportions will differ. Detect it: predict a measurement from the source and compare. Matching to the pixel on four samples means same image; a non-uniform mismatch (203px where 282px is predicted, at one point only) means a different subject.
Say so plainly, state what is matched — layout metrics, framing, placement — and stop chasing the rest. Continuing to "fix" it produces worse output and burns the user's time.
Both viewports, always
A reference is a desktop screenshot and a mobile screenshot. Building desktop-only and inferring mobile reverses the hard part — mobile is where the corrections land. If only one was supplied, ask for the other before starting.
Working loop
- Extract the content box; measure every element into a percentage table.
- Build tokens and layout to those numbers.
- Render at the reference's aspect, scale the reference to your width, stack them vertically with a bright divider. Stacked beats side-by-side — the eye tracks one vertical edge.
- Re-measure your render with the same script. Compare tables, not impressions.
- Repeat per section. Do not move on from a section that is visibly off.
Checklist
- Content box extracted; percentages relative to it, not to the file
- No measurement sitting on its search-window edge
- Every "feature" confirmed numerically before implementing
- Image framing solved, not nudged
- Desktop and mobile references in hand
- Render re-measured with the same script and compared as numbers