visual-reference-calibration

Visual reference calibration

Use when a supplied reference should contribute a particular visual quality. ADS owns the task and review loop; this helper clarifies what to borrow. A screenshot that only marks a bug belongs in the ordinary review path.

Recover before asking

Read the user's request, prior calibration answers, current product decisions and the actual reference. Reuse settled choices. Record a short internal reference contract for substantial reference-led work:

• Source and the property to preserve
• What not to borrow, including incidental demo content
• Fidelity target: close match, same spirit, or loose cue
• Existing surface, hierarchy, tokens and content that must stay
• What observable comparison will establish the intended effect

An uncertain optional detail is not a reason to stop. Ask only when a missing decision materially changes the result and cannot be recovered or reasonably inferred. For example: is the desired property the shared hover field or each card's surface? Do not repeat a whole calibration questionnaire.

Separate the contributing layers

Distinguish composition, material/color, border/shadow/glow, typography/density, motion, content metaphor and system behavior. Preserve only the intended layers. A technically similar mechanism is insufficient if the reference's visible quality is lost.

For nuanced unresolved direction, create the smallest useful visual target or interactive prototype, then compare it with the reference before expensive implementation. An already-specific reference and clear task can proceed directly through authorized local implementation. A tiny reference-led correction does not need another mockup or approval ceremony.

Inspect in product context

• Compare the same relevant state and scale side by side.
• Check whether the effect holds without explaining how the code works.
• Remove fake menus, initials, icons or demo chrome that do not belong in the product.
• Preserve existing content and hierarchy unless changing them is within the user's scope.
• For interaction references, verify actual behavior, keyboard/focus equivalents, reduced motion and target mobile browser behavior. Stills do not establish motion fidelity.
• If the effect is system-level, verify the shared behavior rather than substituting unrelated local hover polish.

Use the existing task review and delivery path. Local implementation authority does not imply deployment or publication authority.

When a pass misses

Read the exact correction against the last artifact and prior contract. Preserve what worked; identify the failed assumption. Continue a supported repair within the task's existing budget, ordinarily one implementation pass plus one repair. Do not automatically reset the project, discard work, or ask the same questions after two rejections. If a material decision or resource still blocks convergence, return the concrete artifact and that one blocker. Switching techniques does not renew the budget.

Jhey card lesson

The documented https://codepen.io/jh3y/pen/WbwZaNa lesson concerns a shared proximity field, thick chromatic borders, saturated blurred material and glow affecting neighboring cards. It is not a template for adding fake app chrome or overflow menus. Preserve the visual system, not incidental demo content; this historical lesson does not prescribe that aesthetic for another task.