- README.md: what this is, how to run and build it, the folder map, how light and dark mode work (@hanzo/appearance, @hanzo/design), where every price and checkout link lives, scripts, and known differences from live - docs/build-notes/: status files, request notes, per-page checklists and reviews, plans - Removed: screenshot galleries, captures of third-party sites used as references, the generated status page and its script, editor config, a personal working-rules file - Code comments point at the new docs paths (no code changes) Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01P5YBdwj33XByFVTvu9bfci
12 KiB
/commerce coverage (MASTER.md part 2, the 18 parts)
Page file: components/pages/apps/Commerce.jsx · gallery: docs/gallery/commerce/ · metric id: docs_click
Open copy questions for James: none new. ("Read the docs" is Hanzo's own hero label and stays the ask until lib/cta.js lands. The cards' "held", "captured", "return", "size · colour · price" and "cart {id}" are labels drawn from Hanzo's own stop sentences; the endpoint counts are counts of Hanzo's list.)
Shared changes requested (docs/build-notes/requests/commerce.md): none.
Forks this page deleted: the raw .x-btn asks and the interim BizAsk (now the kit Cta), the v1 Get block and Rise fade-ups, the hand-rolled endpoint tabs (now five columns plus one BizSheet per group), the data-cursor label, every spring, the three equal integration columns.
Tick what applies. Strike the rest as n/a: reason. Fill each Done here: line with one or two sentences of evidence (a value, a file, a number). A part counts once its Done here: line has text.
1. Strategy and conversion
- Header comment has Persona, Goal, CTA, metric id, Signature, Beyond
- One solid fill per viewport; label and href from
lib/cta.js - One h1; the page is clear in 5 seconds
- No dead or self-looping button; prices from
lib/plans.js(n/a: no prices) - Open copy questions for James listed, none decided
Done here: the top comment carries Persona, Goal, CTA, Metric: docs_click, Signature and Beyond; "Read the docs" differs from the header's "Try Hanzo", so it is the page's one solid fill (hero, then the close); the audit counts 1 page-owned solid button in the first 1470×801 view.
2. Information architecture and navigation
- One
<main id="main">; skip link reaches it (the layout's, untouched) - Every link through
A,Go,Moreorhref(); every card a real link - Breadcrumb at depth 2 or more (n/a: depth 1)
- Link parity: 0 removed, 0 unexpected
Done here: links are A, More and the kit Cta; parity links 7/7; the ten noun cards open panels in place and the four ways in are real links.
3. First impression and page narrative
- Sells in 5 s; something moves within 1 s without input
PageHero; nothing above the h1 (kit equivalent: BizLines h1 + the rail untilPageHeromerges)- JS off: legible; no
opacity:0on the LCP element - One idea per 100svh; no 3 same-height sections in a row
- Ends in proof strip,
Band, footer (the close: one 44px sentence, the ask, a full-width "View on GitHub" row, then the footer about 72px below it) - Card-to-page links use Morph; title lands within 12px (n/a: noun cards open panels in place)
Done here: at 1470×801 the h1 sits at y 267–321 (bottom at 40% of the screen) with the lede beside it at y 194–253, and the full-bleed rail (y 365–725) sits under them, as on the phone (h1 132–174). The order's first move is at 700ms on first view (then every 3.2s), so the t≈1.1s shot already shows stop 02. The journey no longer repeats the hero's cards: each stop is a line drawing that draws itself as its pane lands, with its endpoint rows arriving one by one. Section gaps after the processor switch are about 88px at 1470 (were 160–250px). (8 Nov) The close stands alone: a full section pad (116–188px) now separates it from the ways rows and Get Commerce.
4. Conversion system
<Cta>only; no raw.x-btn- Sticky ask in header after the hero, same label (desktop header swaps to "Read the docs" after the hero; on the phone the header keeps "Try Hanzo" and no bottom bar was seen in the walk, which is shared chrome, not this page's code)
- Copy button copies exactly the displayed text; failure never says Copied (n/a: no copy button)
data-ctaanddata-thumbon every primary
Done here: hero <Cta to={DOCS} id="commerce.hero" thumb>Read the docs</Cta>, close <Cta id="commerce.close">, "API Platform" is <Cta kind="link" id="commerce.platform">. (8 Nov) While the close's solid "Read the docs" is on screen the header ask goes quiet, so one solid fill per viewport.
5. Trust and proof
- No logo without documented permission; no seal; no invented number
- Every figure traces to Hanzo's copy; qualifier beside the number
- Marquees pause, freeze under reduced motion, hide duplicates (n/a: none)
- Privacy link and owner line beside every submit (n/a: no form)
Done here: every path and description is Hanzo's endpoint list (74 endpoints in 5 groups); integrations are Hanzo's names as text, no logos; "MIT or Apache-2.0" and the rest of the spec sheet are Hanzo's words.
6. Content presentation (copy untouched)
- No text under 13px (14px phone) except mono capitals
- Measures held; no orphan word in a heading
- Tables, FAQ, tabs and code use the kit parts (endpoint lists live in
BizOpenpanels andBizSheetdrawers) python3 scripts/parity.py /commerce: 0 missing
Done here: parity 272/272 text, 7/7 links; the phone audit finds 0 text under 14px and 0 targets under 44px.
7. Visual design system
python3 scripts/taste.py <files>passes; no literal hex outside tokens- No label, tag, badge or pill above a headline
- Radii, shadows and sizes from tokens; never box plus shadow
- One icon set; no icon in a rounded box
- Differs from neighbours in hero medium and room order
Done here: taste OK; colours are --bz-* tokens plus #000000, #fafafa, #a3a3a3, #171717; radii 6/8/12/16/24/full; the order card, panes and switch are outlined, tiles are flat fills, nothing is raised; h1 52, headings 26, figures 64 at rest (the find word 44, counts 32). The integrations are rows (label left, names right), not three equal boxes. Hero medium is a full-bleed rail, unlike /payments (a phone) and /captable (a figure).
8. UI component library
- Every control has hover, press, focus-visible, disabled, loading
- Focus ring visible on every stop of a Tab crawl
- Dialogs are native, trap focus and return it (kit BizSheet and BizOpen)
- Inputs 16px or larger; no bare
:hover - Forks this page deleted: listed below
Done here: stops, pause, suggestion chips, Clear, processor pills, index rows, spec rows and chips have a hover fill inside @media (hover: hover), press .97/.98 and a 2px focus ring; the four ways rows fill on hover, nudge their link 4px and press to .98; "View on GitHub" fills, nudges its arrow and presses 1px; "API Platform" underlines and steps its arrow 4px on hover; the ways rows' descriptions all start at x 355 and every hairline runs 159–821; the processor switch is a radiogroup with arrow keys; the find input is 44px (32px phone) with a label.
9. Motion and interaction
- One signature, at most 3 supporting techniques, at most 2 fade-ups
- At least 3 kinds of movement; scroll-linked is half or less
- Something moves without input; every control answers
- Reduced motion shows the final state; no
setInterval - Sound only on the listed moments, through the one kit (n/a: no sound of its own)
Done here: signature (the order rides the rail, idle, first move at 700ms) + the scroll-driven journey (scroll) whose stop drawings draw in with pathLength dashes + BizOpen (state) + line-mask headings; the processor pill glides (state, 300ms ease-emphasis), the endpoints answer as you type (time), and the spec sheet opens one row at a time and lights its part of the install drawing (state). variety.py: 3 techniques (layoutId, useScroll, pathLength). The rider and the tick move with a 500ms ease-in-out tween, no springs; reduced motion lays the journey out still and drops the draw-in; the rail uses setTimeout only.
10. Media
FilmandPiconly; sizes and posters set (n/a: one decorative<img>, Hanzo's zen.webp with width and height)- At most 2 videos playing; pause button on loops over 5 s (no video; the riding order has a 44px pause)
- Budgets met; nothing missing; alt on every image
- No dimmed or filtered photo; 4+ real visuals together where the page has them (n/a: one image)
Done here: /models/zen.webp with alt="" and fixed 104×104, shown once (on the rail's order card only); the five journey stops, the four shape tiles and the install drawing beside the spec sheet are line drawings; the tile art drifts 12px on hover with a fine pointer only (James's art drift).
11. Mobile and responsive
- 375×812 and 1470×801 pass with no overlap
- No horizontal scroll at 320
- Every target 44px or more; every hover has a tap path
- Primary ask above the fold at 375×667
Done here: 375×812 overflow 0; the hero stacks title, line, ask, then the rail (card full width, stops as numbered dots) and the tick under the card walks to the active dot (centre within 1px of it); the journey becomes five stacked steps; endpoint paths break only after "/" (<wbr>), so "/order/{id}/capture" never splits inside a word; the ask sits at about 330px.
12. Accessibility (WCAG 2.2 AA)
- Contrast measured, text at 4.5:1 or better
- Pause control on every moving item
- Forms labelled; first error focused (the search has a label and a Clear button)
- One h1; no heading skips; names start with visible text
- Keyboard reaches every control
Done here: text is #0a0a0a or #525252 on white and room fills, #737373 only on white, #a3a3a3 and white 55% only on black; stops and chips use aria-pressed, the switch role="radio" with aria-checked, the spec rows are buttons with aria-expanded/aria-controls (every answer stays in the HTML, collapsed). Noun panels name an endpoint's group once where a run of it starts, not on every row.
13. Performance and engineering
- h1 and LCP element in server HTML
- JS and CSS inside budget; every image and video sized
- No poller; no third-party request before consent
- Nothing heavy run on James's laptop
Done here: one scroll-linked transform drives the journey; the rail runs only while on screen (useLive); transform and opacity only; filming ran in the cloud container.
14. SEO and machine files
- Title and description match live (or are listed for James)
- Canonical equals og:url equals the live URL
<JsonLd route>parses; no broken URL- Every card is a real link (n/a: noun cards open panels in place)
Done here: app/commerce/page.jsx is unchanged: metadata from content/pages.json and <JsonLd route="/commerce" />.
15. Catalogue and product pages
- Model card matches
SPEC.md(n/a: not a catalogue or model page) - Every card opens by Morph (n/a)
- Every maker and model page linked in the DOM (n/a)
- One price figure everywhere (n/a: no price)
Done here: n/a, a Launch page for one API; the noun index is a page-level disclosure, not a catalogue.
16. Developer experience
- One
CodeBlock; copy equals display (n/a: endpoint paths are shown as text rows, not a code block) - Config blocks parse on their own (n/a)
- Terminal pauses and ends on a static frame (n/a)
- No hand-typed version number
Done here: "Find an endpoint" searches all five groups at once and starts on "refund" (3 across 2 groups); each group's full list is one tap away in its sheet.
17. States and resilience
- Loading, empty, error and offline states designed
- Blocked live data leaves a complete page, no console errors
- A failed submit keeps its values and shows no success (n/a: no form)
- A thrown island does not blank the page
Done here: the finder's no-match state dims the group and shows an em dash; Clear empties it and the columns show every group's count; it reads with JS off because it renders "refund" on the server. Film: no console errors.
18. Measurement and handover
data-ctaon every primary; events only throughlib/track.js(kitCtadispatchescta_click)- Nothing identifier-bearing before consent; no field value in a payload
V2: <score>/10 <one line>in the page file's top comment- Review read:
docs/build-notes/review/commerce.mdverdict 7/10, every listed fix addressed in round 2; awaiting a fresh review
Done here: data-cta="commerce.hero", "commerce.platform", "commerce.close"; gallery desktop.mp4, desktop-hero.jpg, phone-1..3.jpg, plus round 2 desktop-r2.jpg and phone-r2.jpg at 1470×801 and 375×812; errs.js 0 errors, overflow 0 at both sizes.