mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
438 lines
44 KiB
HTML
438 lines
44 KiB
HTML
<!doctype html>
|
||
<html lang="en"><head>
|
||
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
||
<title>ui-port</title>
|
||
<meta name="color-scheme" content="dark">
|
||
<style>
|
||
/* Committed to one visual world: a dark instrument panel. No light variant —
|
||
the dot field and the hairline rules only read on black, and a naive
|
||
inversion would wash both out. Every colour is painted explicitly so the page
|
||
never borrows a host background. */
|
||
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
||
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
||
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
||
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
||
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
||
|
||
:root{
|
||
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
||
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
||
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
||
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
||
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
||
--mono:var(--font-zen-mono);
|
||
--sans:var(--font-zen-sans);
|
||
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
||
--r:999px; --r-soft:14px;
|
||
}
|
||
*{box-sizing:border-box}
|
||
html{-webkit-text-size-adjust:100%}
|
||
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
||
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
||
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
||
|
||
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
||
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
||
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
||
would cut off the copy-prompt menu. */
|
||
.hero{position:relative;border-bottom:1px solid var(--line)}
|
||
.hero::before{content:"";position:absolute;inset:0;
|
||
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
||
background-size:7px 7px;
|
||
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
||
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
||
pointer-events:none}
|
||
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
||
|
||
nav{border-bottom:1px solid var(--line)}
|
||
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
||
justify-content:space-between;align-items:center;gap:1rem}
|
||
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
||
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
||
display:inline-flex;align-items:center;gap:.6rem}
|
||
.brand i{font-style:normal;color:var(--faint)}
|
||
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
||
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
||
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
||
nav a.up:hover{color:var(--ink)}
|
||
|
||
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
||
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
||
h1 em{font-style:normal;color:var(--faint)}
|
||
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
||
|
||
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
||
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
||
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
||
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
||
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
||
line-height:1.2;font-weight:400}
|
||
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
||
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
||
.btn.solid:hover{background:#d8d8d4}
|
||
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
||
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
||
|
||
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
||
.copy{position:relative;display:inline-flex}
|
||
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
||
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
||
padding:.4rem;display:flex;flex-direction:column;
|
||
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
||
.menu[hidden]{display:none}
|
||
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
||
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
||
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
||
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
||
white-space:nowrap}
|
||
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
||
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
||
.mi:hover .mark{color:var(--ink)}
|
||
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
||
letter-spacing:.1em;text-transform:uppercase}
|
||
|
||
/* Works-with bar: one scrolling row, name and mark per agent. */
|
||
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
||
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
||
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
||
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
||
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
||
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
||
display:flex;align-items:center}
|
||
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
||
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
||
-webkit-overflow-scrolling:touch;
|
||
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
||
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
||
.bar::-webkit-scrollbar{display:none}
|
||
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
||
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
||
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
||
text-decoration:none;background:var(--ground)}
|
||
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
||
.agent .mark{width:.95rem;height:.95rem}
|
||
|
||
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
||
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
||
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
||
p{margin:0 0 1rem;max-width:70ch}
|
||
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
||
li{margin:.22rem 0}
|
||
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
||
text-decoration-color:var(--line-hi)}
|
||
a:hover{text-decoration-color:var(--ink)}
|
||
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
||
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
||
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
||
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
||
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
||
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
||
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
||
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
||
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
||
display:block;overflow-x:auto}
|
||
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
||
|
||
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
||
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
||
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
||
white-space:pre;line-height:1.9}
|
||
.curl b{color:var(--ink);font-weight:400}
|
||
.curl i{font-style:normal;color:var(--faint)}
|
||
|
||
/* index */
|
||
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
||
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
||
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
||
#q:focus{outline:none;border-color:var(--soft)}
|
||
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
||
text-transform:uppercase;margin:0 0 2rem}
|
||
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
||
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
||
padding-bottom:.45rem}
|
||
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
||
border-radius:var(--r-soft);text-decoration:none}
|
||
.row:hover{background:#0a0a0a}
|
||
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
||
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
||
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
||
color:var(--faint);font-size:.85rem}
|
||
footer a{color:var(--soft)}
|
||
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
||
margin:0 0 2rem;font-size:.85rem}
|
||
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
||
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
||
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
||
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
||
.fmap a:hover{text-decoration:underline}
|
||
.fmap div{color:var(--faint);line-height:1.5}
|
||
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
||
|
||
@media (max-width:640px){
|
||
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
||
.btns{gap:.5rem}
|
||
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
||
.copy,.copy .btn{width:100%;justify-content:center}
|
||
.menu{left:0;right:0;min-width:0}
|
||
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
||
.strip b{border-right:0;padding-right:0}
|
||
.bar{width:100%}
|
||
}
|
||
</style>
|
||
<link rel="alternate" type="text/markdown" href="/ui-port.md">
|
||
|
||
<link rel="icon" href="/favicon.svg">
|
||
<link rel="canonical" href="https://hanzoskills.com/ui-port">
|
||
</head>
|
||
<!-- Reading this with a machine? Every page here is also plain markdown.
|
||
This one: https://hanzoskills.com/ui-port.md
|
||
Index: https://hanzoskills.com/llms.txt
|
||
Corpus: https://hanzoskills.com/all.md
|
||
Append .md to any path for the markdown twin. -->
|
||
<body>
|
||
<nav><div class="in">
|
||
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
||
<a class="up" href="/">All skills</a>
|
||
</div></nav>
|
||
|
||
<div class="wrap">
|
||
<h1>ui-port</h1><p class="lede">Port or migrate a UI from an old/reference implementation to a new system while preserving new-system functionality and achieving high visual parity. Use when comparing reference and target URLs, routes, repos/worktrees, Storybook stories, screenshots, PDFs, DOM/computed-style probes, or any combination; when asked to make a rewrite look like an older UI; when a visual regression is "close" but still reads as a different product; or when agents need a repeatable audit-fix-measure loop for screen-by-screen convergence.</p><h1>UI Port Parity</h1>
|
||
<p>Treat the reference UI as an executable visual contract, not inspiration. Preserve the target system's working business logic, data model, semantics, accessibility, and explicitly approved divergences while making equivalent visible states converge to the reference.</p>
|
||
<h2>Core rule</h2>
|
||
<p>Never begin by polishing individual components. Converge in dependency order:</p>
|
||
<ol><li>capture conditions</li><li>shell geometry</li><li>typography metrics</li><li>spacing and control primitives</li><li>screen topology / information architecture</li><li>compound components</li><li>state families and data-dependent regions</li><li>responsive layouts</li><li>pixel-level cleanup</li></ol>
|
||
<p>A lower-level mismatch invalidates measurements below it. If the shell shifts every child, fix the shell and remeasure. If typography changes wrapping, fix type before vertical spacing. If a screen has the wrong regions or order, do not compensate with margins.</p>
|
||
<h2>Two rules that outrank every heuristic below</h2>
|
||
<p>Both are false positives that let an agent declare victory on a screen a human rejects at a glance. Neither is caught by a CSS check.</p>
|
||
<h3>Never validate only the state that happened to render</h3>
|
||
<p>A screenshot that looks correct because a backend failed is not a pass. An Explore screen scored PASS on five metric tiles, four tabs, no chart cards and one quiet failure line; every one of those was the 404 state. Fixture data restored the chart panels, their headings, and the rows — and the screen was then wrong on three gates.</p>
|
||
<p>So a data-driven screen is scored once per state, and a state nobody exercised reports NOT EVALUATED, never inheriting its neighbour's verdict:</p>
|
||
<pre><code>loading · empty · failure · populated-minimal · populated-realistic</code></pre>
|
||
<p>Only states the reference actually has must match, but each must be entered deliberately, by a deterministic fixture, and served identically to both builds. A populated reference is captured separately — never inferred from the failure state.</p>
|
||
<p>The state goes in the row key, so a screen is not representable as one verdict:</p>
|
||
<pre><code>explore:error:view positions:disconnected:view
|
||
explore:populated:view positions:connected:view
|
||
explore:populated:page buy:default:view
|
||
send:open:view buy:unsupported:view</code></pre>
|
||
<p><code>explore:error:view</code> passing says nothing about <code>explore:populated:view</code>. A key that named only the screen is what let the false green exist.</p>
|
||
<h3>Never equate DOM presence with visual presence</h3>
|
||
<p><code>getBoundingClientRect()</code> is not a definition of visible. A <code>VisuallyHidden</code> heading is clipped to one pixel and its child still reports a box: "Swap" in a 1px parent wraps one letter to a line and returns 21×118. A closed <code><details></code> keeps its contents laid out and paints none of them.</p>
|
||
<p>Ask the question of the text, not the element. Take the Range client rects over the node and require at least one that survives every clipping ancestor:</p>
|
||
<pre><code>visible(node) =
|
||
hasRenderedTextRect(node)
|
||
&& intersectsScope(node)
|
||
&& intersectsAllClippingAncestors(node)
|
||
&& !hiddenByAncestor(node) // display, visibility, ~0 opacity
|
||
&& !insideClosedDetails(node)
|
||
&& !accessibilityOnlyPattern(node)</code></pre>
|
||
<p>And geometric visibility is still not perceptual visibility — black text on a black ground passes every test above. DOM extraction counts semantic material; the screenshot is the final authority. Neither alone is sufficient.</p>
|
||
<h3>Never let a screen converge by hiding</h3>
|
||
<p>Invention has an inverse, and a census cannot tell them apart: material removed from the count because it was suppressed, rather than because the composition was reproduced. Every reviewer asks it directly —</p>
|
||
<blockquote><p>Did this become closer by hiding or clipping material, rather than by reproducing the reference composition?</p></blockquote>
|
||
<p>Fail the screen when material the reference genuinely shows was pushed behind <code>opacity: 0</code>, an offscreen transform, a zero-height or one-pixel clip, an overflow the viewport never reaches, a closed disclosure, or a condition that suppresses it only under the conditions the census runs in. The test is intent-free and mechanical: if the reference paints it and the target does not, that is a gap, whatever moved it out of view.</p>
|
||
<h3>Never measure against a host that now serves the target</h3>
|
||
<p>The reference address is a fact that changes. The moment the port went live at the reference's own domain, every capture compared the target to itself — identical rows, identical strings, 0px, a table reading ten routes at perfect parity — and it took thirteen independent reviewers to notice. Two safeguards, both mechanical:</p>
|
||
<ul><li>the harness refuses two builds whose regions agree on every band's y, x,</li></ul>
|
||
<p> width and height, and names the fix (point the reference at the other build);</p>
|
||
<ul><li>the reference is the other build served from its own source where the</li></ul>
|
||
<p> production host can no longer be trusted, on a hostname that build treats as its own — some SPAs turn their browser router on only for hosts they know and draw the landing for every path elsewhere.</p>
|
||
<h3>The reference's language has three homes, and the exception channel is not one</h3>
|
||
<p>A reference's surface is its string catalog plus whatever its source hardcodes — a standing legal disclosure under every trade card, a screen's own three words — and the second kind is audited exactly as much as the first. Capture it from the rendered reference as leaf sentences (an ancestor's text run together is a sentence nobody paints) and give it one home beside the catalog, keyed by your ids because the runtime needs a key and the reference gave none, held to the capture by a test. The gate then accepts three things and nothing else:</p>
|
||
<pre><code>catalog id the reference's catalog, verbatim
|
||
painted sentences the reference draws outside its catalog, verbatim
|
||
override the owner's own decisions — a handful, each one signed</code></pre>
|
||
<p>The failure mode is letting the override channel become the second catalog: agents register the reference's own words as "overrides" because nothing else would hold them, the channel grows to dozens, and a rewrite hides among the no-ops. Prune it to decisions and the rest either has a captured source or was never the reference's.</p>
|
||
<h2>Scope is part of every assertion</h2>
|
||
<p>Three scopes, three different facts about one page, never compared to each other:</p>
|
||
<p>| scope | what it answers | |---|---| | <code>viewport</code> | the reference screenshot's contract — the first frame, before anyone scrolls | | <code>region</code> | one named part, for matching a single panel's anatomy | | <code>full-page</code> | the whole document, for a port of an entire site |</p>
|
||
<p>A landing page measured 36 words at <code>viewport</code> and 292 at <code>full-page</code>; scored against a reference number taken at the other scope, either reading is nonsense. Record the scope on every row. Below-fold material must not contaminate a viewport score, and a viewport score must not be reported as a page total.</p>
|
||
<p>Two of these are separate deliverables, not two readings of one:</p>
|
||
<p><strong>View parity</strong> is what a person sees in the specified capture. It is what the reference screenshot contracts for and what the anti-invention rule governs.</p>
|
||
<p><strong>Page parity</strong> is the route's complete information architecture.</p>
|
||
<p><code>landing:view</code> converging while <code>landing:page</code> stays far apart is not a contradiction and not a regression. It means the hero port is done and the rest of the route is still its own migration. Say which one a claim is about.</p>
|
||
<h2>Equal counts are not convergence</h2>
|
||
<p>Send reached exactly 42 words against the reference's 42 and was still visibly a different screen: the reference modal is a large sending-value area, a token selector, a destination block and a bottom CTA; the target was a compact amount/recipient form. The same words in a different arrangement.</p>
|
||
<p>So a count never produces a green by itself. Counts detect <em>invention</em> — material present that the reference does not carry. Anatomy detects <em>the port</em>. When the target has fewer words than the reference, the missing material is a region or a component that was not built, and the fix is never to write sentences to close the gap.</p>
|
||
<h2>Semantics are not visual material</h2>
|
||
<p>A census that counts <code>h1</code> counts a fact about markup, not a fact about the screen. Where the reference draws its title in a <code>div</code> and the target draws the same title, in the same place, at the same size, in an <code>h1</code>, the target is visually identical and semantically better. Reporting that as <em>over on h1</em> asks a correct port to delete a correct heading to satisfy a screenshot harness.</p>
|
||
<p>Split them, and never let the second penalise the first:</p>
|
||
<pre><code>VISUAL MATERIAL SEMANTICS
|
||
painted title boxes h1 / h2 / nav / main / table / list
|
||
painted prose landmark roles
|
||
painted controls label associations
|
||
painted cards heading order
|
||
marks and icons</code></pre>
|
||
<p>A difference that is visible scores. A difference that is only in the tag is recorded on a <strong>semantic exemption</strong> channel:</p>
|
||
<pre><code>same visible title, reference div → target h1
|
||
visual material MATCH
|
||
semantics SEMANTIC_IMPROVEMENT — zero visual penalty</code></pre>
|
||
<p>The exemption runs one way. A target that drops to a <code>div</code> where the reference uses a heading is a semantic regression, and that is a finding.</p>
|
||
<h2>Marks are material, and their absence is a failure</h2>
|
||
<p>Token marks, action icons and product illustrations carry much of a dense interface's density, and a census that folds them into "controls" or ignores them reports a screen of bare labels as converged. They get their own gate:</p>
|
||
<pre><code>MARKS reference / target
|
||
token marks
|
||
action icons
|
||
status icons
|
||
decorative product marks</code></pre>
|
||
<p>Automatic failures:</p>
|
||
<ul><li>a known token's mark is absent where the reference draws one</li><li>text is substituted for a control the reference draws as an icon alone</li><li>a generic placeholder stands in where the token metadata names a canonical mark</li><li>the target invents a badge to explain state where the reference draws none</li></ul>
|
||
<p>One component owns the asset control, and screens do not each assemble their own:</p>
|
||
<pre><code>AssetChoice
|
||
├── mark always drawn for a known token
|
||
├── symbol
|
||
├── balance/value optional
|
||
└── chevron
|
||
|
||
known token, mark available → draw the mark
|
||
known token, no mark → the canonical achromatic fallback
|
||
unselected → a generic placeholder, never a fabricated logo
|
||
reference draws a mark → the target may not omit it</code></pre>
|
||
<h2>Implementation leakage</h2>
|
||
<p>A port's characteristic failure is not a missing feature — it is the engineer explaining the new build on the surface of the product. It reads as microcopy, badges, technical qualifiers and state labels the reference never carries.</p>
|
||
<p>Flag any visible string matching, among others:</p>
|
||
<pre><code>projected · derived · decimals · browser · unavailable · endpoint · indexer
|
||
request · failed to fetch · what this does · what we disclose</code></pre>
|
||
<p>None of those words is forbidden. Each is evidence worth checking, and the check is one question:</p>
|
||
<blockquote><p>Is this phrase something a person needs in order to operate the reference interface, or something the author wanted to explain about how the target works?</p></blockquote>
|
||
<p>If the latter it leaves the default state. It does not have to be deleted — a tooltip, a closed disclosure, a settings surface, the result of an interaction, or an accessibility label all keep the information without putting it in a composition the reference draws without it. A required disclosure keeps its access and loses its inline restatement; a required marking can live in an <code>aria-label</code> rather than a visible badge.</p>
|
||
<p>The rule, stated once:</p>
|
||
<pre><code>THE REFERENCE DOES NOT SAY IT
|
||
↓
|
||
THE DEFAULT SCREEN DOES NOT SAY IT</code></pre>
|
||
<h2>A delta needs a region</h2>
|
||
<p>The largest displacement is only useful if it names something worth fixing. A missing 20px help control in a fixed corner will out-measure every real defect on a nearly converged form, and a report whose headline is that number sends the next pass to the wrong place.</p>
|
||
<p>Label each band and report two numbers:</p>
|
||
<pre><code>header · primary · secondary · footer · fixed-affordance · overlay
|
||
|
||
limit:
|
||
largest overall y860 40px fixed-affordance
|
||
largest primary y312 14px sell field</code></pre>
|
||
<p>Fix the fixed-affordance gaps once, globally, precisely because they are cheap and they distort everything measured after them.</p>
|
||
<h2>Supported input modes</h2>
|
||
<p>Use the highest-confidence inputs available. Combine modes when possible.</p>
|
||
<ul><li><strong>Live reference + live target:</strong> inspect routes, DOM, computed styles, screenshots, states.</li><li><strong>Reference repo + target repo/worktree:</strong> run both, inspect implementation and patch target automatically when authorized.</li><li><strong>Storybook/component explorer:</strong> compare equivalent stories and states before page composition.</li><li><strong>Screenshots or PDFs:</strong> perform visual topology and geometry analysis; mark computed-style facts as unmeasured.</li><li><strong>DOM/computed-style probes:</strong> use stable semantic selectors or <code>data-parity-key</code> attributes to compare rectangles and styles.</li><li><strong>Mixed mode:</strong> e.g. reference screenshot + target repo, or reference URL + target Storybook.</li></ul>
|
||
<p>If only screenshots are available, do not invent DOM, CSS, or interaction facts. Produce a visual remediation plan and clearly mark what requires a live probe.</p>
|
||
<h2>Before editing: establish the parity contract</h2>
|
||
<p>Create or update a parity manifest with:</p>
|
||
<ul><li>canonical viewport(s), DPR, browser engine, zoom, theme, locale and fonts</li><li>route/state mapping between reference and target</li><li>deterministic fixture/data requirements</li><li>intentional divergences</li><li>shared defects that should not be copied</li><li>unmeasured states</li></ul>
|
||
<p>Classify every finding as exactly one of:</p>
|
||
<ul><li><code>PARITY</code>: target differs and should converge.</li><li><code>EXEMPT</code>: intentional difference; do not repeatedly "fix" it.</li><li><code>SHARED-BUG</code>: both systems are wrong; fix separately from parity.</li><li><code>UNMEASURED</code>: insufficient rendered state/data; do not guess.</li><li><code>ABSENCE</code>: reference does not render the element/state; absence alone is not proof target should remove semantics or functionality.</li></ul>
|
||
<p>Do not copy accessibility regressions, broken landmarks, unsafe behavior, misleading controls, or shared defects merely because the reference has them.</p>
|
||
<h2>Phase 1: deterministic capture</h2>
|
||
<p>Before comparison, normalize:</p>
|
||
<ul><li>exact viewport and device scale</li><li>browser engine and font loading</li><li>light/dark theme selected explicitly</li><li>locale/timezone/number formatting</li><li>animations/transitions disabled or captured at stable time</li><li>identical scroll positions</li><li>identical route parameters</li><li>identical wallet/account state where possible</li><li>identical market/token/data fixture where possible</li></ul>
|
||
<p>Live market or timestamp noise must not dominate screenshot diffs. Add fixture injection or request interception before judging data-dependent components.</p>
|
||
<p>If the backend is unavailable, continue on static regions and mark data-dependent regions <code>UNMEASURED</code>. Build the fixture injection mechanism now; do not fabricate reference rows or charts.</p>
|
||
<h2>Phase 2 gate: system primitives</h2>
|
||
<p>Do not evaluate page-specific parity until these pass closely enough that descendant measurements are meaningful.</p>
|
||
<h3>Shell</h3>
|
||
<p>Measure page/app root, header, gutters, max-widths, first-content x/y, main content width and major columns. Fix parent geometry before children.</p>
|
||
<h3>Typography</h3>
|
||
<p>Compare rendered metrics, not just CSS names:</p>
|
||
<ul><li>body size</li><li>integer/fractional size ramp</li><li>variable font axes / apparent weight</li><li>line-height strategy</li><li>letter spacing</li><li>x-height/cap-height appearance</li><li>text width and wrapping</li><li>numeric features</li></ul>
|
||
<p>Different font families may be an exemption. If so, tune the target face to visual equivalence rather than forcing equal numeric <code>font-weight</code> values.</p>
|
||
<h3>Spacing</h3>
|
||
<p>Build a histogram of padding, margin and gap values. Detect contamination such as tiny padding plus forced <code>min-height</code>, arbitrary fractional scale multipliers, or one-off compensation values. Fix the generating primitive/token rather than replacing hundreds of local declarations.</p>
|
||
<h3>Controls</h3>
|
||
<p>Compare Button, IconButton, Input, Select, Tabs, Checkbox, Toggle, Badge, Menu, Popover and Modal. Record height, padding, radius, border/elevation, font metrics, icon size, baseline and all visible states.</p>
|
||
<p>Do not pass controls because their outer height matches if inner text/icon geometry still differs.</p>
|
||
<p>Decompose each one. A height is assembled, and only the decomposition says out of what:</p>
|
||
<pre><code>outer height padding-top / bottom
|
||
content-box height border-top / bottom
|
||
font-size min-height
|
||
computed line-height icon box
|
||
text Range height icon baseline offset
|
||
gap
|
||
align-items</code></pre>
|
||
<p>The stop condition is the <strong>same rendered tier</strong>, not the same CSS mechanism. Where the reference lets content size a control — <code>line-height: normal</code>, no minimum, the face's own metrics deciding — that mechanism is not portable: one face at 16px lands on 27 and another does not. Copying the mechanism copies the arithmetic and misses the answer. Name the tier, state the number, and let each build reach it its own way.</p>
|
||
<p>Do not close a control-height gap by moving the global type ramp or setting <code>line-height: 1</code>. If the ramp already agrees with the reference, the remaining difference is local composition, and a global change to fix a local difference breaks every screen that was right.</p>
|
||
<p>A primitive the classifier finds on one build and not on the other is <strong>NOT COMPARABLE</strong>, never DIFFERENT. Reference tabs that are plain anchors and target tabs that carry <code>role="tab"</code> are a markup difference; reporting a gap there reports something nobody measured.</p>
|
||
<p>The frequent cause of a build having fewer tiers than the reference is a control geometry with no single home — the same constant redefined per file, drifting to two or three values, so every control lands on one of them. Give it one home before comparing tiers.</p>
|
||
<p>See <code>references/probe-contract.md</code> for probe fields and semantic selectors.</p>
|
||
<h2>Phase 3 gate: screen topology</h2>
|
||
<p>This gate is mandatory. A screen that contains different primary regions is not visually close even if tokens match.</p>
|
||
<p>For every route/state, create a <strong>screen contract</strong> from top to bottom. Record:</p>
|
||
<ol><li>persistent shell elements</li><li>primary content anchor and width</li><li>ordered visible regions</li><li>each region's role and approximate bounding box</li><li>primary vs secondary information</li><li>overlays/modals vs standalone pages</li><li>empty/error/loading treatment</li><li>footer visibility within the canonical viewport</li></ol>
|
||
<p>Compare reference and target as region sequences. Example:</p>
|
||
<p><code>tabs -> sell card -> buy card -> CTA</code></p>
|
||
<p>is not equivalent to:</p>
|
||
<p><code>tabs -> H1 -> sell card -> buy card -> helper link -> CTA -> disclosure -> footer</code></p>
|
||
<p>Fix the topology before pixel styling.</p>
|
||
<h3>Screen-topology rules</h3>
|
||
<ul><li>Remove redundant page titles if the reference relies on tabs or context instead.</li><li>Do not turn quiet reference states into large cards, dashboards or explanatory blocks.</li><li>Do not preserve target-only primary sections merely because they contain useful information. Move target-only functionality to progressive disclosure, a secondary panel, an advanced section, or a subsequent state when that preserves function without changing the reference geometry.</li><li>Preserve target-only functionality; change its prominence and placement when necessary.</li><li>Do not fake parity with <code>transform</code>, negative margins or absolute-position patches that leave the wrong document flow.</li><li>A reference modal must remain modal in the target parity state; do not replace it with a full page unless explicitly exempted.</li><li>A reference wizard/sidebar layout must remain a wizard/sidebar layout; two equivalent fields in a centered mini-form are not structural parity.</li></ul>
|
||
<p>See <code>references/screen-convergence.md</code> for the required per-screen audit format and <code>references/exchange-example.md</code> for a worked example.</p>
|
||
<h2>Phase 4: compound components</h2>
|
||
<p>Once topology matches, compare compound components in place. Use semantic component identities such as:</p>
|
||
<ul><li>market selector</li><li>trade tabs</li><li>swap/limit/send/buy forms</li><li>metric strip</li><li>order-book rows</li><li>tables</li><li>chart toolbar</li><li>wallet prompt</li><li>position card</li><li>asset picker</li><li>wizard stepper</li></ul>
|
||
<p>Prefer <code>data-parity-key="domain.component"</code> on equivalent nodes. Reuse the same key across reference and target only when the elements are semantically equivalent.</p>
|
||
<p>Fix shared primitives at the highest reusable level. Use page-local CSS only for genuinely page-local geometry.</p>
|
||
<h2>Phase 5: state families</h2>
|
||
<p>A component is not ported until its relevant state family converges. Capture at least:</p>
|
||
<ul><li>default</li><li>hover</li><li>active/pressed</li><li>focus-visible</li><li>disabled</li><li>loading</li><li>selected</li><li>empty</li><li>error</li><li>populated</li></ul>
|
||
<p>For transaction/product flows also capture disconnected/connected wallet, valid/invalid input, menu open, modal open, and successful/blocked states as applicable.</p>
|
||
<p>Target-only safety/compliance behavior is allowed, but it must fit the reference hierarchy and footprint when possible. Never create a fake enabled control to imitate functionality the target intentionally does not provide.</p>
|
||
<h2>Phase 6: visual measurement</h2>
|
||
<p>For matching elements capture at least:</p>
|
||
<ul><li>bounding rect: x, y, width, height</li><li>display, position, overflow, z-index</li><li>flex/grid tracks, alignment and gaps</li><li>padding and margins</li><li>font family, size, weight, line-height, letter spacing</li><li>color and background</li><li>border, radius and shadow</li><li>opacity</li><li>icon box/stroke and text baseline</li><li>wrapping/truncation</li></ul>
|
||
<p>Compare screenshots with overlay and pixel diff, but do not rely on one global percentage. Report the four gates independently, each once per state:</p>
|
||
<p>| gate | question | |---|---| | TOPOLOGY | same kind of screen, same major regions in the same order? | | VISIBLE MATERIAL | same headings, prose, controls, cards, affordances actually painted? | | GEOMETRY | same place, size, alignment, density, rhythm? | | STATE MATRIX | does parity hold in every reference-relevant state? |</p>
|
||
<p>Beneath them, the primitive gates:</p>
|
||
<ul><li>shell geometry</li><li>typography</li><li>primitive spacing</li><li>controls</li><li>screen topology</li><li>screen geometry</li><li>state parity</li><li>data regions</li></ul>
|
||
<p>Large blank regions must not hide a bad header or form in the global score.</p>
|
||
<h2>Phase 7: fix loop</h2>
|
||
<p>For each screen:</p>
|
||
<ol><li>capture reference and target at the same state</li><li>write the screen contract</li><li>classify all extra/missing/reordered regions</li><li>fix topology</li><li>recapture</li><li>compare major bounding boxes</li><li>fix compound components</li><li>recapture</li><li>inspect overlay/diff hotspots</li><li>fix typography/spacing/style residuals</li><li>repeat until the screen gate passes</li></ol>
|
||
<p>After any shared primitive change, recapture all previously passing screens to detect regressions.</p>
|
||
<h2>Automatic failure conditions</h2>
|
||
<p>Fail parity if any of these remain without an explicit exemption:</p>
|
||
<ul><li>equivalent screens use different primary region order</li><li>a reference modal is a target page or vice versa</li><li>target adds a prominent H1/hero/card absent from the reference and shifts the primary workflow</li><li>target uses a different active/default tab</li><li>equivalent controls differ materially in height or typography</li><li>an extra footer/disclosure appears inside a viewport where the reference is still application workspace, unless explicitly required and placed without changing primary geometry</li><li>target uses cards where reference is intentionally flat and the difference materially changes hierarchy</li><li>a parent layout error is compensated in descendants</li><li>screenshot diff is accepted without checking the largest residual regions</li><li>an agent declares "close enough" without a measured screen contract</li><li>a data-driven screen is scored from whichever state happened to render, or a populated state is inferred from a failure state</li><li>visibility is asserted from an element box rather than surviving text rects, so clipped, collapsed or accessibility-only material is counted as shown</li><li>material is moved into a closed disclosure, a visually-hidden wrapper or below the fold to lower a count, where the reference genuinely shows it</li><li>a number measured at one scope is compared against a number measured at another</li><li>word or element counts are reported as convergence without an anatomy comparison</li><li>material the reference paints is suppressed rather than reproduced: <code>opacity: 0</code>, an offscreen transform, a zero-height or one-pixel clip, an overflow the viewport never reaches, or a condition that hides it only under the conditions the census runs in</li><li>a control-height gap is closed by moving the global type ramp or forcing <code>line-height: 1</code></li><li>a primitive present on one build and absent on the other is scored as a difference rather than as not comparable</li><li>a semantic difference with no visual difference (reference <code>div</code>, target <code>h1</code>) is scored as a visual-material failure</li><li>a token mark the reference draws is absent, or a generic placeholder stands in where the metadata names a canonical mark</li><li>explanatory microcopy, a status badge, a technical qualifier or an implementation-state label appears in the default state with no visible counterpart in the reference</li><li>a largest-delta figure is reported without its region, so a fixed affordance outranks the primary content</li></ul>
|
||
<h2>What a converged screen's report looks like</h2>
|
||
<p>Counts are diagnostics. They catch invention and they catch hiding. They stop being the headline the moment a screen's archetype converges — after that the remaining signal is anchor geometry and component anatomy:</p>
|
||
<pre><code>ADD
|
||
topology PASS
|
||
material PASS
|
||
geometry 82%
|
||
states PASS
|
||
largest delta SelectPair width +38px
|
||
|
||
SEND
|
||
topology PASS
|
||
material PARTIAL
|
||
geometry 68%
|
||
states PASS
|
||
largest delta modal anatomy</code></pre>
|
||
<p>A geometry percentage alone is not a report. Pair it with the largest single displacement, because a percentage says how much agrees and never says what does not.</p>
|
||
<h2>Output artifacts</h2>
|
||
<p>Maintain these files in the target repo or parity workspace when possible:</p>
|
||
<ul><li><code>VISUAL_PARITY_MANIFEST.md</code> - environments, route mapping, exemptions, shared bugs</li><li><code>VISUAL_PARITY_AUDIT.md</code> - defect ledger with IDs and statuses</li><li><code>VISUAL_PARITY_SCREENS.md</code> - one contract and convergence checklist per route/state</li><li>deterministic screenshot fixtures and baselines</li><li>a repeatable parity runner such as <code>bin/parity.mjs</code></li></ul>
|
||
<p>The defect ledger should include:</p>
|
||
<p><code>id | screen | region | class | priority | reference | target | root cause | fix location | status | evidence</code></p>
|
||
<p>Use P0 for shell/topology mismatches that invalidate many descendants; P1 for shared primitives and major component geometry; P2 for local styling; P3 for minor residual polish.</p>
|
||
<h2>Definition of done</h2>
|
||
<p>Do not finish at "same design system." Finish when:</p>
|
||
<ul><li>persistent shell geometry converges</li><li>text has equivalent visual density and wrapping</li><li>spacing rhythm and control geometry converge</li><li>each screen has the same primary topology and hierarchy</li><li>target-only functionality remains available without dominating reference geometry</li><li>representative state families converge</li><li>responsive layouts converge at agreed breakpoints</li><li>data-dependent regions are fixture-tested rather than guessed</li><li>intentional divergences are documented and stable</li><li>automated captures reproduce the result</li></ul>
|
||
<p>Use <code>scripts/check_ledger.py</code> as a lightweight completion gate when the audit is represented as JSON.</p>
|
||
<h2>Bundled resources</h2>
|
||
<p><code>scripts/see.mjs</code> is the reference implementation of the visibility rule above: <code>census(scope)</code> runs inside <code>page.evaluate</code> and returns painted headings, words, prose nodes, controls and cards at <code>view</code>, <code>page</code> or a region selector, counting only text whose Range rects survive every clipping ancestor. <code>lines(marks)</code> returns the y of named anchor rows, for matching one composition's rhythm to another.</p>
|
||
<p>Load only what the current parity task needs:</p>
|
||
<ul><li><code>references/modes.md</code> - choose workflow for URLs, repos, Storybook, screenshots/PDFs, DOM dumps or failing backends.</li><li><code>references/ledger.md</code> - defect classes, severity and ledger rules.</li><li><code>references/acceptance.md</code> - phase gates, tolerances and stop conditions.</li><li><code>references/probe-contract.md</code> - stable selectors and computed-style measurement.</li><li><code>references/screen-convergence.md</code> - mandatory per-screen topology contract.</li><li><code>references/exchange-example.md</code> - worked multi-screen example showing page-vs-modal, wizard-vs-mini-form and primary-vs-secondary hierarchy failures.</li><li><code>references/report-template.md</code> - standard report structure.</li><li><code>scripts/probe-page.mjs</code> - optional Playwright DOM/style probe using host-project Playwright.</li><li><code>scripts/diff-probes.mjs</code> - compare two parity probe JSON files.</li><li><code>scripts/image-diff.py</code> - simple equal-size screenshot diff helper.</li><li><code>scripts/check_ledger.py</code> - fail when unresolved blocking parity findings remain.</li></ul>
|
||
<footer>
|
||
<div class="fmap">
|
||
<div><b>Build</b>
|
||
<a href="https://hanzo.app">hanzo.app</a> app builder
|
||
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
||
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
||
<div><b>Run</b>
|
||
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
||
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
||
<div><b>Account</b>
|
||
<a href="https://hanzo.id">hanzo.id</a> sign in
|
||
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
||
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
||
<div><b>Company</b>
|
||
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
||
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
||
</div>
|
||
<div class="fend"><a href="/ui-port.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
||
</footer>
|
||
</div></body></html> |