Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01P5YBdwj33XByFVTvu9bfci
44 KiB
The shared system: what exists and how to use it
The shared-system chat owns this file, along with everything it lists: app/layout.jsx, app/globals.css, app/system.css, components/{Chrome,Nav,HeaderTools,Ask,Morph,Phone,Cursor,Opener,Sigil,ui,kit,JsonLd}, lib/{motion,scroll,route}.js and next.config.mjs.
Page chats: use these and do not fork them. If something is missing, write the request at the bottom of this file. Every addition is additive, so nothing on your page changes unless you opt in. The few site-wide fixes are listed under "Changed for everyone".
Pull main, then read this file again. It grows with every push.
1. Colour: the grey and silver deck (0 UI hues)
app/system.css holds the tokens. There is no blue, green or red for UI. Colour comes only from Hanzo's own media.
| Token | Use |
|---|---|
--hz-950 … --hz-50, --hz-black, --hz-white |
The grey ladder (#0a0a0b to #f5f5f7). |
--silver-hi, --silver, --silver-lo, --silver-deep |
Silvers for objects such as chips and hairlines. |
--silver-sheen |
A brushed-metal surface for an object. Never use it on text: gradient text is banned. |
--room-bg, --room-surface, --room-raised, --room-ink, --room-soft, --room-faint, --room-line, --room-line-strong, --room-fill, --room-fill-strong |
Semantic colours that follow the room you are in. |
--focus |
The focus ring colour. It is ink in light rooms and #f5f5f7 in dark rooms. |
- Dark rooms. Put
data-room="dark"on a dark section. Every--room-*token, the focus ring and.x-btn.solidflip for it: solid buttons become #f5f5f7 with ink text. The header also turns dark while it sits over that section. - Light inside dark. For a light card inside a dark room, put
data-room="light"on the card. - Status. A status that needs colour gets a shape or a word as well, never colour alone.
Fix on your page: replace any literal #0a84ff (38 page files have it), green or other UI hue with var(--room-ink), var(--focus) or a grey token.
2. Motion tokens
lib/motion.js and the CSS variables in app/system.css hold the same values.
import { EASE_OUT_EXPO, EASE_CALM, EASE_SOFT, EASE_IN, DUR, SPRING, STAGGER } from '../lib/motion';
<motion.div transition={{ duration: DUR.enter, ease: EASE_OUT_EXPO }} /> // or transition={SPRING.sheet}
- CSS easings:
var(--ease-out-expo),var(--ease-calm),var(--ease-soft),var(--ease-in). - CSS durations:
var(--dur-press).1s,--dur-hover.2s,--dur-exit.25s,--dur-fade.4s,--dur-enter.6s,--dur-reveal1.1s. - Reduced motion is handled site-wide. Motion uses
MotionConfig reducedMotion="user". CSS animations and transitions collapse to their final state. - Write the final state first. Under reduced motion, the end state you wrote is what people see.
3. Component states (hover, press, focus, loading, disabled, selected)
Nothing fades on hover. Press is a scale of .98 (or translateY of 1px for links), with no layout jump.
| Part | Class or component | States |
|---|---|---|
| Button | .x-btn, .x-btn.solid, <Btn>, <Go> |
Hover: a grey veil on outline buttons, and a darker or lighter fill on solid ones (safe on any colours). Press: scale .98. Loading: aria-busy="true", or <Btn busy>; a ring turns in place and the width stays. Disabled: disabled, aria-disabled="true" or <Btn disabled>. Selected: aria-pressed="true", aria-current="page", data-selected or <Btn selected>; it reads inverted. |
| Arrow link | .x-arrow, <More>, <Arrow> |
The chevron nudges on hover and the link drops 1px on press. |
| Text link | .x-link |
An underline draws in from the left on hover and stays for aria-current="page". |
| Card | .x-card on an <a>, <button> or [tabindex] |
Hover (fine pointers only): lifts 5px and the hairline strengthens. Press: scale .98. Selected: aria-selected, aria-current or data-selected give it an ink ring. .x-card.inv is the one inverted odd tile. |
| Tabs | <Tabs>, <TabPanel> (kit) |
A gliding pill. Arrow keys, Home and End move between tabs, and disabled tabs are skipped. Every panel stays in the server HTML. |
| Sheet | <Sheet> (kit) |
Opens from the right on desktop and from the bottom on phones (drag down to close). Esc, the scrim and the close button shut it. Focus is trapped inside and returns to where it was. Scroll is held. |
| Table | .x-table-wrap > table.x-table |
Sticky header and first column, tabular figures, and a row hover fill. Mark the subject column's cells with data-subject; it gets a grey tint, never a hue. Use .x-gap on an honest "—". |
| Field | .x-field > label + .x-input2 |
48px tall with 16px text. aria-invalid="true" gives a dashed ink border. .x-field-msg holds the message. |
| Button (preferred) | <Cta to id kind size thumb busy disabled> (kit) |
The one button primitive from PLAN-COMPONENTS 2.4. kind: solid (one per screen), quiet (outlined) or link (text with a chevron). size: sm, md 44px or lg 52px. id is written as data-cta and sent as a cta_click event. thumb makes it the page's ask. Leaving for hanzo.ai or the console shows a short pressed state. |
| Form field | <Field label name type required autoComplete hint error as="textarea"> (kit) |
A real <label> and 16px text, so phones never zoom. Hint and error are tied by aria-describedby. It checks itself on blur and sets aria-invalid. |
| Data table | <DataTable caption cols rows /> (kit) |
cols: [{ key, label, num, subject }]. The first column is the row header. A missing value shows an honest "—". The wrapper scrolls by keyboard. |
| Code | <CodeBlock code label prompt /> (kit) |
A 13.5/1.65 dark plate. Lines starting with # or // are dimmed. The $ prompt cannot be selected or copied. Copy copies exactly what is shown. |
| Figure | <Stat value="1,600+" label note /> (kit) |
Shows Hanzo's string byte for byte. It counts up once, only when it starts below the fold. |
| FAQ | <Faq items={[[q, a]]} multi first={0} /> (kit) |
Closed answers are hidden="until-found", so Find in page opens them and search engines read them. #q-what-does-a-plan-cost opens that answer on arrival. |
| Loading | <Skeleton lines={3} /> or <Skeleton h={320} /> |
Holds the exact box the content will take, so nothing moves when it arrives. |
| Empty | <Empty title detail action to /> |
Pass Hanzo's own words. |
| Error | <Problem title detail onRetry action to /> |
Has role="alert". Pass Hanzo's own words. |
import { Cta, Field, DataTable, CodeBlock, Stat, Faq, Tabs, TabPanel, Sheet, Skeleton, Empty, Problem, Img, Film } from '../kit'; // pages: '../../components/kit'
const [i, setI] = useState(0);
<Tabs id="plans" label="Plans" tabs={['Personal', 'Team', 'API']} value={i} onChange={setI} />
<TabPanel id="plans" i={0} value={i}>…</TabPanel>
v2/DetailSheet stays as the button-and-sheet pair. <Sheet> is the bare, controlled sheet for any trigger.
4. Headlines
<Lines as="h1" play="load" lines={['Smarter, Faster,', 'Pick all three.']} className="your-h1" /> from components/ui.jsx is the line-mask reveal:
- Each line rises out of its own mask in 1.1s, 80ms apart, once.
- The whole sentence is in the HTML for screen readers and search engines.
- Give the heading your own
font-sizeandline-height; the mask clips at the line box. play="load"is for heroes; the default plays once in view.
5. The ask: the header carries it (MASTER 3.2 rule 6)
- The one solid ask lives in the sticky header, at every width. It never fades.
- Desktop (above 700px), the Apple local-nav move: if your page marks its ask with
data-thumb, the header's button carries your ask's words and link once your hero's button has scrolled away (data-cta="header-ask"). While your hero's own solid ask is on screen, the header's button is an outline, so one solid shows at a time. - Pages without
data-thumbkeep Hanzo's solid "Try Hanzo". - Phones keep "Try Hanzo" in the header, because there is no room for longer words.
- Desktop (above 700px), the Apple local-nav move: if your page marks its ask with
- Nothing floats over content on desktop. The bottom pill bar is gone.
- Phones (700px and under): a slim, quiet (not solid) bar carries your page's own ask once your hero's button has gone by. It shows only when all of these hold:
- your page marks its ask with
data-thumb, and its words differ from "Try Hanzo"; - the page is at rest, not mid-scroll;
- no text, picture, control or card sits under it;
- your own ask, or any button with the same words, is not on screen;
- the footer, the closing
.x-band,[data-ask-hide], menus, sheets, the cookie note and the keyboard are not in the way.
- your page marks its ask with
- What you do: put
data-thumbon your hero's main button, or use<Cta thumb>. Usedata-ask="off"on<main>for none, anddata-dockon your own fixed bottom bar. - Your own solid buttons: keep one per view. The header's is always there, so make secondary asks text links.
6. Header and menus
- Hanzo's own header and items, untouched (Company, Research, Products, Solutions, Developers, Learn, Pricing, search, language, Log in, Try Hanzo).
- Hover opens a menu with intent. Moving between menus slides the columns.
- Keyboard:
- Enter, Space or ↓ on a heading opens its menu and focuses the first link.
- ↑ ↓ Home End move through the links.
- Tab past the last link closes the menu and goes on to the next heading.
- Shift+Tab from the first link returns to the heading.
- Esc closes the menu and returns focus.
- Stage (wide screens, 1240px and up): the right of each menu previews the link under the pointer or focus. It shows the link's living Sigil and the page's own title and description from Hanzo's index.
- Phones: the Hanzo AI chevron opens a full-screen sheet of accordions. The top has Hanzo AI, search and close. Rows are 56px. Hanzo's Log in choices and "Try Hanzo" are pinned at the bottom. Esc closes it, and Tab stays inside.
- The HTML is rendered on the server (
components/Shell.jsx), so the 375 KBcontent.jsno longer ships in every page's JavaScript. Pages that still importcontent.jsthemselves (Home, Hero, Open, Agents, Platform, SetupMenu, ContactSales) carry it only on their own route; import just the field you need, or read it in a server component and pass it down. - "Try Hanzo" no longer fades on hover. Its fill shifts instead.
- No overlay blurs the page. One backdrop blur per page, the header's. The menu scrim and the search backdrop are now a plain tint.
- The header does not hide on scroll. Over 40 page stickies assume a 60px header at
top: 60px, and hiding it would open gaps above all of them.
7. Page transitions (card to page, the synchronized.studio move)
components/Morph.jsx is already on, and it never waits on the network before moving.
- Opening a card: a big link (160×90 or larger), or anything marked
data-morphinside a link, grows at once into a full-screen stage. The stage carries the card's picture (img, video, canvas or large SVG), its colour (its largest painted surface) and its title. - Landing: the next page loads under the stage. Once it has painted, the stage settles into the next page's
[data-morph-target], or its first section, and dissolves. Each step takes about 600ms. - Help it land well: put
data-morph-targeton your hero, and keep your hero's title the same words as the card's title. - Small links and Back/Forward: the page dims at once and the next one fades in. This is opacity only, so pinned and fixed parts never jump. The header never moves.
- Opting out and fallbacks:
data-no-morphopts out.[data-card](the WebGL opener's cards) keep their own transition.- Reduced motion and new-tab clicks navigate instantly.
- Prefetch: pages are fetched on hover and on the first touch.
- Focus: after every navigation, focus lands on the new page's
<main> h1(no ring, no scroll). Keep one h1 per page inside<main>. - Measured: /careers, /customers and /blog at 1470×801 and 375×812. Open takes about 0.7s and land about 0.7s, with no skips.
7b. Sound (JAMES rule 10)
lib/sound.js and components/Sound.jsx are mounted for you.
- Six synthesized sounds at about -24 dB: whoosh (a card opens), tap (a solid ask), tick (tabs, toggles, switches, FAQ), chime (a copy that really happened), pop (⌘K) and done (a demo finishing).
- When they play: never before the first click or key, and never on hover, scroll or load. One plays at a time.
- Mute: a toggle in the header (and in the phone menu sheet) mutes them, and the choice is remembered.
- Your page:
- Call
play('done')fromlib/sound.jswhen your self-running demo finishes. - Put
data-sound="tick"on a control to give it a sound, ordata-sound=""to silence one. - Do not add your own audio.
- Call
8. Fonts: no visible swap
- Zen and Zen Mono are both preloaded and use
font-display: block, so text paints once, in Zen. - If a very slow network outlasts the block period, metric-matched fallbacks (
Zen Fallback,Zen Mono Fallback) take the same box, so the h1 never moves. - Use
var(--sans)andvar(--mono); they already include the fallbacks. - Never add another webfont or a Google Font.
9. Media and performance rules (BRIEF-v3 §10 budgets)
Budgets (75th percentile, mid-phone on 4G):
| Metric | Target |
|---|---|
| LCP | 1.8s on a phone, 1.2s on desktop |
| INP | 100ms or less |
| CLS | 0.02 or less |
| Animation | 50fps or better |
First-load JS (gzipped):
| Page type | Budget |
|---|---|
| Home | 170 KB |
| Launch and System | 150 KB |
| Catalogue | 140 KB |
| Developer | 130 KB |
| Model | 100 KB |
| Utility and legal | 90 KB |
<Img src w h alt priority /> (kit):
- Always give
wandh, so the box is reserved. - Put
priorityonly on the one image that is the page's LCP. - Everything else is lazy and decodes off the main thread.
- First-view images are 250 KB or less.
<Film src poster w h label /> (kit):
- Muted and looping.
- Plays only while on screen and while the tab is visible.
- Never plays under reduced motion or Data Saver; the poster stays.
- Downloads only when near the screen.
- No autoplaying clip over 1.5 MB, and nothing autoplays above the fold before first paint.
Measured (production build, 7 Nov, next build exit 0, 1,792 static pages):
- Typical page: about 170 KB of first-load JS (gzipped), which is over the utility (90 KB) and model (100 KB) budgets.
- Where it goes:
- React and Next: 103 KB, shared by every page.
- The shared layout: about 70 KB in all. Motion is 49 KB of that, and the shell layers (header, menus, search, ask bar, transitions) about 16 KB.
- The page itself: 2 to 9 KB.
- What this system already removed:
- Hanzo's header and footer HTML now render on the server. Before, the whole 375 KB
content.jsshipped to every page. - Lenis now loads after first paint, and only for mouse and trackpad.
- Hanzo's header and footer HTML now render on the server. Before, the whole 375 KB
- What is left is mostly Motion. It comes down only when pages import
munderLazyMotioninstead ofmotion. That is a codemod across every page, planned for after the page chats merge (PLAN 6.2). New code: prefer CSS transitions (the tokens above) for hover, press and simple entrances.
Also:
- Put
.x-cvon long sections far below the fold. It appliescontent-visibility: autowith a 900px intrinsic height; set your own if you know it. - Animate only transform, opacity, clip-path and filter. No
transition: all. - Pause your CSS loops off screen with
[data-off] .x { animation-play-state: paused }. Chrome sets[data-off]for you. - No third-party scripts above the fold.
10. SEO, share cards, structured data
Every page.jsx already does the right thing:
export const metadata = { title: '…', description: '…' }; // Hanzo's own words
export default function Page() { return <><JsonLd route="/your/path" /><YourPage /></>; }
What <JsonLd> gives each page:
- Its canonical link (
https://hanzo.ai/your/path/). - Open Graph and X tags pointing at its own card image (
/og/your/path.png). - Hanzo's schema.org data.
Site-wide, added by this system:
app/sitemap.js: every route.app/robots.js.app/icon.svg: the Hanzo mark, light and dark.viewportFit: cover.- A
twitter:sitetag.
11. Accessibility
- Skip link. "Skip to content" is the first tab stop and jumps past the header to
#main. - Focus. One ring, 2px in the room's ink with a 3px offset. Never
outline: nonewithout a replacement. - Reduced motion: see section 2.
- Targets. Hit targets are 44px or more on touch.
- Overlays. Esc closes every overlay and returns focus. Search, cookie preferences and
<Sheet>trap Tab inside while open. - Header behind sticky parts. Use
top: var(--x-top)(60px) for your own sticky parts. Anchors and focused elements stop 16px below the header (scroll-padding-top). - Hover only on hover devices. Wrap your own
:hoverrules in@media (hover: hover)so a tap on a phone does not leave things stuck in hover. - Honest copy buttons.
copyText(str)fromcomponents/ui.jsxreturns true only if the copy happened. Never show "Copied" otherwise. useCalm()fromcomponents/ui.jsxis true under reduced motion and follows the setting live.- Language menu. Choosing a language no longer flips
<html lang>ordir, because the content is English.
11b. JS off: every word legible (PLAN 2.3, P1)
-
Never put
<noscript>in a client component. It cannot hydrate, and it puts Next's red error badge on your page. Use<NoJs css="…" />fromcomponents/NoJs.jsxinstead. It writes the same CSS as a plain<style>scoped underhtml:not(.js), so it applies only when JavaScript is off. The v2 kit (PinScenes, DetailSheet, MaskLines, the A2 and Fam kits) already uses it. -
Inline entrance states are cleared for you. With JS off, a
<noscript>rule clears every entrance state written inline into the server HTML: Motion'sinitial={{ opacity: 0, y }}, clip-paths andvisibility: hidden. -
States your own CSS hides are yours to fix. This covers chapter text shown one at a time, captions waiting for a scroll, and
opacity: 0set in a class. Scope them to JS:html.jsis set before first paint whenever JS runs. Write.js .my-step:not(.on) { opacity: 0 }, not.my-step:not(.on) { opacity: 0 }. -
Reviews count these. On /api, /compare, /metrics and the home chapters, 8 to 16 text blocks are still invisible with JS off for this reason.
12. States: 404, error, loading
-
404 hardening: a malformed address cannot crash the 404, and "Go back" appears only when there is a page to go back to.
-
Unknown address:
app/not-found.jsxrenderscomponents/pages/Lost.jsx, the 404 with its contour map and search. -
A page that throws while rendering:
app/error.jsxshows the same dark room with "Try again" and "Go home". The header and footer stay. -
The shell itself fails:
app/global-error.jsx. -
No root
loading.jsx, on purpose. It would put a blank frame inside every card-to-page transition. Use<Skeleton>for live parts of your page instead.
13. Helpers
lib/scroll.js:scrollToEl(el, { offset: -110 })andscrollToY(y)work with or without Lenis and respect reduced motion. Use them instead of branching onwindow.__lenis.lib/route.js:href(p)keeps links inside the site when the page exists here. Otherwise it sends them to hanzo.ai.lib/domwatch.js:onDomChange(fn)is one shared, debounced DOM watcher. Use it instead ofsetIntervalpolling.
Changed for everyone (already live)
- Focus ring: ink or white, not blue. Its 8px border-radius override is gone.
- Solid buttons inside
data-room="dark"are now #f5f5f7 with ink text. Before, they were black on black, for example the dark heroes on /guard, /hsm, /machines, /world, /gateway, /network, /pubsub, /telemetry and /visor. - Green and blue accents in shared CSS are now grey: code syntax colours, the Pareto chart, the cookie "Always Active" label, the savings chip and the race lane label.
- The old phone thumb bar is replaced by the ask bar, with the same attributes.
- Arrival curtain (
components/arrival.js): home only, on the first visit in 7 days. It never runs on deep links, Save-Data, slow networks, reduced motion or bots. It holds 700ms at most, and the page behind is no longer dimmed or moved. A CSS failsafe lifts it at 3.5s. Do not wait for itshz-arrivedevent; it rarely fires now. - Cookie notice: "Reject all" sits beside "Accept all" at equal weight. Global Privacy Control is honoured. Any link to
#choicesreopens the preferences, or usedispatchEvent(new Event('hz-consent-open')). - The 1.5s DOM pollers in the shell became one observer.
- Logo marquee (home): it now has a pause button (icon only, named Pause or Play) and stands still under reduced motion.
- Phone keyboard: the viewport uses
interactive-widget=resizes-content, so the keyboard never covers the field being typed in. - No cursor label. The cursor-following "Open" label is gone (MASTER 3.3: nothing floats over content). Your
data-cursorattributes do nothing now. - No desktop ask bar. The header's solid "Try Hanzo" carries the ask (section 5).
- Lenis: mouse and trackpad only, loaded after first paint.
window.__leniscan be undefined for the first moments and on touch;lib/scroll.jshandles both.
Known breaks on main, owned by their page chats
-
The
Crawl.cssandMetrics.jsxbuild errors are fixed on main, andnext buildpasses. -
Closed drawers keep
aria-modal="true"in the DOM. The ask bar now ignores overlays that are not showing. If you build a modal, still droparia-modalwhile it is closed (or unmount it). -
Shared complaints in the 7 Nov reviews are fixed by this system:
- Two solid buttons at the top.
- No desktop sticky ask.
- The header and phone bar showing two solids.
- "Try Hanzo" fading on hover.
- The phone bar overlapping the closing button.
Page-level ones stay with each page: several equal solid buttons in one view, a hydration mismatch on
/agents/*and/integrations/*members, and text hidden by page CSS when JS is off.
Requests to the shared system
Write each request as one line: the page, what you need, and why.
- Resolved (Morph rebuilt, section 7). No View Transition waits on the next page any more, so nothing freezes. Original report: Every page (Proof chat, 7 Nov): in-site clicks freeze about 4s and the card-to-page morph never plays. In
components/Morph.jsx, the View Transition's update callback resolves throughrequestAnimationFrame(() => ok())(lines ~34 and ~71). Chromium runs no animation frames while a transition holds rendering, so the promise only settles at its own ~4s timeout (measured: 4,069ms with rAF, 81ms withsetTimeout(ok, 16)). Fix: resolve withsetTimeout(ok, 16)in both places. With that simulated, the /integrations and /open-source cards land in their destination headlines.
The shared system: what exists and how to use it
The shared-system chat owns this file, along with everything it lists: app/layout.jsx, app/globals.css, app/system.css, components/{Chrome,Nav,HeaderTools,Ask,Morph,Phone,Cursor,Opener,Sigil,ui,kit,JsonLd}, lib/{motion,scroll,route}.js and next.config.mjs.
Page chats: use these and do not fork them. If something is missing, write the request at the bottom of this file. Every addition is additive, so nothing on your page changes unless you opt in. The few site-wide fixes are listed under "Changed for everyone".
Pull main, then read this file again. It grows with every push.
1. Colour: the grey and silver deck (0 UI hues)
app/system.css holds the tokens. There is no blue, green or red for UI. Colour comes only from Hanzo's own media.
| Token | Use |
|---|---|
--hz-950 … --hz-50, --hz-black, --hz-white |
The grey ladder (#0a0a0b to #f5f5f7). |
--silver-hi, --silver, --silver-lo, --silver-deep |
Silvers for objects such as chips and hairlines. |
--silver-sheen |
A brushed-metal surface for an object. Never use it on text: gradient text is banned. |
--room-bg, --room-surface, --room-raised, --room-ink, --room-soft, --room-faint, --room-line, --room-line-strong, --room-fill, --room-fill-strong |
Semantic colours that follow the room you are in. |
--focus |
The focus ring colour. It is ink in light rooms and #f5f5f7 in dark rooms. |
- Dark rooms. Put
data-room="dark"on a dark section. Every--room-*token, the focus ring and.x-btn.solidflip for it: solid buttons become #f5f5f7 with ink text. The header also turns dark while it sits over that section. - Light inside dark. For a light card inside a dark room, put
data-room="light"on the card. - Status. A status that needs colour gets a shape or a word as well, never colour alone.
Fix on your page: replace any literal #0a84ff (38 page files have it), green or other UI hue with var(--room-ink), var(--focus) or a grey token.
2. Motion tokens
lib/motion.js and the CSS variables in app/system.css hold the same values.
import { EASE_OUT_EXPO, EASE_CALM, EASE_SOFT, EASE_IN, DUR, SPRING, STAGGER } from '../lib/motion';
<motion.div transition={{ duration: DUR.enter, ease: EASE_OUT_EXPO }} /> // or transition={SPRING.sheet}
- CSS easings:
var(--ease-out-expo),var(--ease-calm),var(--ease-soft),var(--ease-in). - CSS durations:
var(--dur-press).1s,--dur-hover.2s,--dur-exit.25s,--dur-fade.4s,--dur-enter.6s,--dur-reveal1.1s. - Reduced motion is handled site-wide. Motion uses
MotionConfig reducedMotion="user". CSS animations and transitions collapse to their final state. - Write the final state first. Under reduced motion, the end state you wrote is what people see.
3. Component states (hover, press, focus, loading, disabled, selected)
Nothing fades on hover. Press is a scale of .98 (or translateY of 1px for links), with no layout jump.
| Part | Class or component | States |
|---|---|---|
| Button | .x-btn, .x-btn.solid, <Btn>, <Go> |
Hover: a grey veil on outline buttons, and a darker or lighter fill on solid ones (safe on any colours). Press: scale .98. Loading: aria-busy="true", or <Btn busy>; a ring turns in place and the width stays. Disabled: disabled, aria-disabled="true" or <Btn disabled>. Selected: aria-pressed="true", aria-current="page", data-selected or <Btn selected>; it reads inverted. |
| Arrow link | .x-arrow, <More>, <Arrow> |
The chevron nudges on hover and the link drops 1px on press. |
| Text link | .x-link |
An underline draws in from the left on hover and stays for aria-current="page". |
| Card | .x-card on an <a>, <button> or [tabindex] |
Hover (fine pointers only): lifts 5px and the hairline strengthens. Press: scale .98. Selected: aria-selected, aria-current or data-selected give it an ink ring. .x-card.inv is the one inverted odd tile. |
| Tabs | <Tabs>, <TabPanel> (kit) |
A gliding pill. Arrow keys, Home and End move between tabs, and disabled tabs are skipped. Every panel stays in the server HTML. |
| Sheet | <Sheet> (kit) |
Opens from the right on desktop and from the bottom on phones (drag down to close). Esc, the scrim and the close button shut it. Focus is trapped inside and returns to where it was. Scroll is held. |
| Table | .x-table-wrap > table.x-table |
Sticky header and first column, tabular figures, and a row hover fill. Mark the subject column's cells with data-subject; it gets a grey tint, never a hue. Use .x-gap on an honest "—". |
| Field | .x-field > label + .x-input2 |
48px tall with 16px text. aria-invalid="true" gives a dashed ink border. .x-field-msg holds the message. |
| Button (preferred) | <Cta to id kind size thumb busy disabled> (kit) |
The one button primitive from PLAN-COMPONENTS 2.4. kind: solid (one per screen), quiet (outlined) or link (text with a chevron). size: sm, md 44px or lg 52px. id is written as data-cta and sent as a cta_click event. thumb makes it the page's ask. Leaving for hanzo.ai or the console shows a short pressed state. |
| Form field | <Field label name type required autoComplete hint error as="textarea"> (kit) |
A real <label> and 16px text, so phones never zoom. Hint and error are tied by aria-describedby. It checks itself on blur and sets aria-invalid. |
| Data table | <DataTable caption cols rows /> (kit) |
cols: [{ key, label, num, subject }]. The first column is the row header. A missing value shows an honest "—". The wrapper scrolls by keyboard. |
| Code | <CodeBlock code label prompt /> (kit) |
A 13.5/1.65 dark plate. Lines starting with # or // are dimmed. The $ prompt cannot be selected or copied. Copy copies exactly what is shown. |
| Figure | <Stat value="1,600+" label note /> (kit) |
Shows Hanzo's string byte for byte. It counts up once, only when it starts below the fold. |
| FAQ | <Faq items={[[q, a]]} multi first={0} /> (kit) |
Closed answers are hidden="until-found", so Find in page opens them and search engines read them. #q-what-does-a-plan-cost opens that answer on arrival. |
| Loading | <Skeleton lines={3} /> or <Skeleton h={320} /> |
Holds the exact box the content will take, so nothing moves when it arrives. |
| Empty | <Empty title detail action to /> |
Pass Hanzo's own words. |
| Error | <Problem title detail onRetry action to /> |
Has role="alert". Pass Hanzo's own words. |
import { Cta, Field, DataTable, CodeBlock, Stat, Faq, Tabs, TabPanel, Sheet, Skeleton, Empty, Problem, Img, Film } from '../kit'; // pages: '../../components/kit'
const [i, setI] = useState(0);
<Tabs id="plans" label="Plans" tabs={['Personal', 'Team', 'API']} value={i} onChange={setI} />
<TabPanel id="plans" i={0} value={i}>…</TabPanel>
v2/DetailSheet stays as the button-and-sheet pair. <Sheet> is the bare, controlled sheet for any trigger.
4. Headlines
<Lines as="h1" play="load" lines={['Smarter, Faster,', 'Pick all three.']} className="your-h1" /> from components/ui.jsx is the line-mask reveal:
- Each line rises out of its own mask in 1.1s, 80ms apart, once.
- The whole sentence is in the HTML for screen readers and search engines.
- Give the heading your own
font-sizeandline-height; the mask clips at the line box. play="load"is for heroes; the default plays once in view.
5. The ask: one solid button on screen
- The ask bar (
components/Ask.jsx, mounted for you) arrives once the hero has gone by, on every page at every width:- Desktop: a small bar at the bottom centre with the Hanzo mark, the page name (tap it to go back to the top), search and the ask.
- Phones (900px and under): a full-width bar under the thumb.
- It replaces the old phone thumb bar and reads the same attributes.
- One solid button on screen at any moment. The header's "Try Hanzo" is an outline whenever any solid button of the page (
.x-btn.solid,[data-thumb],.x-band) is on screen, or the bar is showing; otherwise it is solid. The bar also steps aside while a page solid is in view. data-thumbon your hero's main button (or<Cta thumb>). The bar then carries your words and href, for example<Go to="/contact-sales" solid data-thumb="Talk to sales">Talk to sales</Go>. Without it, the bar carries the header's "Try Hanzo". Adata-thumbon adisplay: contentswrapper works too.- Optional attributes:
data-ask-name="Hanzo Dev": the page name in the bar. The default is the first part of the<title>.data-ask-note="No card needed": a 12px risk line beside the button on desktop. Use Hanzo's words only.data-ask-hideon a section whose bottom edge the bar must not cover.data-ask="off"on<main>for a page with no ask (the 404 and error pages use it).data-dockon your own fixed bottom bar.
- It also yields to the footer, the closing
.x-band, menus, search, sheets, the cookie note and the phone keyboard.
6. Header and menus
- Hanzo's own header and items, untouched (Company, Research, Products, Solutions, Developers, Learn, Pricing, search, language, Log in, Try Hanzo).
- Hover opens a menu with intent. Moving between menus slides the columns.
- Keyboard:
- Enter, Space or ↓ on a heading opens its menu and focuses the first link.
- ↑ ↓ Home End move through the links.
- Tab past the last link closes the menu and goes on to the next heading.
- Shift+Tab from the first link returns to the heading.
- Esc closes the menu and returns focus.
- Stage (wide screens, 1240px and up): the right of each menu previews the link under the pointer or focus. It shows the link's living Sigil and the page's own title and description from Hanzo's index.
- Phones: the Hanzo AI chevron opens a full-screen sheet of accordions. The top has Hanzo AI, search and close. Rows are 56px. Hanzo's Log in choices and "Try Hanzo" are pinned at the bottom. Esc closes it, and Tab stays inside.
- The HTML is rendered on the server (
components/Shell.jsx), so the 375 KBcontent.jsno longer ships in every page's JavaScript. Pages that still importcontent.jsthemselves (Home, Hero, Open, Agents, Platform, SetupMenu, ContactSales) carry it only on their own route; import just the field you need, or read it in a server component and pass it down. - "Try Hanzo" no longer fades on hover. Its fill shifts instead.
- No overlay blurs the page. One backdrop blur per page, the header's. The menu scrim and the search backdrop are now a plain tint.
- The header does not hide on scroll. Over 40 page stickies assume a 60px header at
top: 60px, and hiding it would open gaps above all of them.
7. Page transitions (card to page)
components/Morph.jsx is already on:
- Every in-site click is a ~600ms View Transition.
- A big link (160×90 or larger), or anything marked
data-morphinside a link, flies into the next page's[data-morph-target]. Without a target, it flies into the first section. - Small links turn the page while the header stays put.
- Opt out with
data-no-morph. - Pages are fetched on hover and on the first touch.
- Back and Forward turn the page the other way and keep the scroll the browser restores.
- The screen is never held more than 700ms. A slow page simply cuts over when it is ready.
- After every navigation, focus lands on the new page's
<main> h1(no ring, no scroll), so screen readers hear where they are. Keep one h1 per page inside<main>. - Reduced motion, new-tab clicks and browsers without View Transitions navigate instantly.
8. Fonts: no visible swap
- Zen and Zen Mono are both preloaded and use
font-display: block, so text paints once, in Zen. - If a very slow network outlasts the block period, metric-matched fallbacks (
Zen Fallback,Zen Mono Fallback) take the same box, so the h1 never moves. - Use
var(--sans)andvar(--mono); they already include the fallbacks. - Never add another webfont or a Google Font.
9. Media and performance rules (BRIEF-v3 §10 budgets)
Budgets (75th percentile, mid-phone on 4G):
| Metric | Target |
|---|---|
| LCP | 1.8s on a phone, 1.2s on desktop |
| INP | 100ms or less |
| CLS | 0.02 or less |
| Animation | 50fps or better |
First-load JS (gzipped):
| Page type | Budget |
|---|---|
| Home | 170 KB |
| Launch and System | 150 KB |
| Catalogue | 140 KB |
| Developer | 130 KB |
| Model | 100 KB |
| Utility and legal | 90 KB |
<Img src w h alt priority /> (kit):
- Always give
wandh, so the box is reserved. - Put
priorityonly on the one image that is the page's LCP. - Everything else is lazy and decodes off the main thread.
- First-view images are 250 KB or less.
<Film src poster w h label /> (kit):
- Muted and looping.
- Plays only while on screen and while the tab is visible.
- Never plays under reduced motion or Data Saver; the poster stays.
- Downloads only when near the screen.
- No autoplaying clip over 1.5 MB, and nothing autoplays above the fold before first paint.
Measured (production build, 7 Nov, next build exit 0, 1,792 static pages):
- Typical page: about 170 KB of first-load JS (gzipped), which is over the utility (90 KB) and model (100 KB) budgets.
- Where it goes:
- React and Next: 103 KB, shared by every page.
- The shared layout: about 70 KB in all. Motion is 49 KB of that, and the shell layers (header, menus, search, ask bar, transitions) about 16 KB.
- The page itself: 2 to 9 KB.
- What this system already removed:
- Hanzo's header and footer HTML now render on the server. Before, the whole 375 KB
content.jsshipped to every page. - Lenis now loads after first paint, and only for mouse and trackpad.
- Hanzo's header and footer HTML now render on the server. Before, the whole 375 KB
- What is left is mostly Motion. It comes down only when pages import
munderLazyMotioninstead ofmotion. That is a codemod across every page, planned for after the page chats merge (PLAN 6.2). New code: prefer CSS transitions (the tokens above) for hover, press and simple entrances.
Also:
- Put
.x-cvon long sections far below the fold. It appliescontent-visibility: autowith a 900px intrinsic height; set your own if you know it. - Animate only transform, opacity, clip-path and filter. No
transition: all. - Pause your CSS loops off screen with
[data-off] .x { animation-play-state: paused }. Chrome sets[data-off]for you. - No third-party scripts above the fold.
10. SEO, share cards, structured data
Every page.jsx already does the right thing:
export const metadata = { title: '…', description: '…' }; // Hanzo's own words
export default function Page() { return <><JsonLd route="/your/path" /><YourPage /></>; }
What <JsonLd> gives each page:
- Its canonical link (
https://hanzo.ai/your/path/). - Open Graph and X tags pointing at its own card image (
/og/your/path.png). - Hanzo's schema.org data.
Site-wide, added by this system:
app/sitemap.js: every route.app/robots.js.app/icon.svg: the Hanzo mark, light and dark.viewportFit: cover.- A
twitter:sitetag.
11. Accessibility
- Skip link. "Skip to content" is the first tab stop and jumps past the header to
#main. - Focus. One ring, 2px in the room's ink with a 3px offset. Never
outline: nonewithout a replacement. - Reduced motion: see section 2.
- Targets. Hit targets are 44px or more on touch.
- Overlays. Esc closes every overlay and returns focus. Search, cookie preferences and
<Sheet>trap Tab inside while open. - Header behind sticky parts. Use
top: var(--x-top)(60px) for your own sticky parts. Anchors and focused elements stop 16px below the header (scroll-padding-top). - Hover only on hover devices. Wrap your own
:hoverrules in@media (hover: hover)so a tap on a phone does not leave things stuck in hover. - Honest copy buttons.
copyText(str)fromcomponents/ui.jsxreturns true only if the copy happened. Never show "Copied" otherwise. useCalm()fromcomponents/ui.jsxis true under reduced motion and follows the setting live.- Language menu. Choosing a language no longer flips
<html lang>ordir, because the content is English.
11b. JS off: every word legible (PLAN 2.3, P1)
- Inline entrance states are cleared for you. With JS off, a
<noscript>rule clears every entrance state written inline into the server HTML: Motion'sinitial={{ opacity: 0, y }}, clip-paths andvisibility: hidden. - States your own CSS hides are yours to fix. This covers chapter text shown one at a time, captions waiting for a scroll, and
opacity: 0set in a class. Scope them to JS:html.jsis set before first paint whenever JS runs. Write.js .my-step:not(.on) { opacity: 0 }, not.my-step:not(.on) { opacity: 0 }. - Reviews count these. On /api, /compare, /metrics and the home chapters, 8 to 16 text blocks are still invisible with JS off for this reason.
12. States: 404, error, loading
-
404 hardening: a malformed address cannot crash the 404, and "Go back" appears only when there is a page to go back to.
-
Unknown address:
app/not-found.jsxrenderscomponents/pages/Lost.jsx, the 404 with its contour map and search. -
A page that throws while rendering:
app/error.jsxshows the same dark room with "Try again" and "Go home". The header and footer stay. -
The shell itself fails:
app/global-error.jsx. -
No root
loading.jsx, on purpose. It would put a blank frame inside every card-to-page transition. Use<Skeleton>for live parts of your page instead.
13. Helpers
lib/scroll.js:scrollToEl(el, { offset: -110 })andscrollToY(y)work with or without Lenis and respect reduced motion. Use them instead of branching onwindow.__lenis.lib/route.js:href(p)keeps links inside the site when the page exists here. Otherwise it sends them to hanzo.ai.lib/domwatch.js:onDomChange(fn)is one shared, debounced DOM watcher. Use it instead ofsetIntervalpolling.
Changed for everyone (already live)
- Focus ring: ink or white, not blue. Its 8px border-radius override is gone.
- Solid buttons inside
data-room="dark"are now #f5f5f7 with ink text. Before, they were black on black, for example the dark heroes on /guard, /hsm, /machines, /world, /gateway, /network, /pubsub, /telemetry and /visor. - Green and blue accents in shared CSS are now grey: code syntax colours, the Pareto chart, the cookie "Always Active" label, the savings chip and the race lane label.
- The old phone thumb bar is replaced by the ask bar, with the same attributes.
- Arrival curtain (
components/arrival.js): home only, on the first visit in 7 days. It never runs on deep links, Save-Data, slow networks, reduced motion or bots. It holds 700ms at most, and the page behind is no longer dimmed or moved. A CSS failsafe lifts it at 3.5s. Do not wait for itshz-arrivedevent; it rarely fires now. - Cookie notice: "Reject all" sits beside "Accept all" at equal weight. Global Privacy Control is honoured. Any link to
#choicesreopens the preferences, or usedispatchEvent(new Event('hz-consent-open')). - The 1.5s DOM pollers in the shell became one observer.
- Logo marquee (home): it now has a pause button (icon only, named Pause or Play) and stands still under reduced motion.
- Phone keyboard: the viewport uses
interactive-widget=resizes-content, so the keyboard never covers the field being typed in. - Lenis: mouse and trackpad only, loaded after first paint.
window.__leniscan be undefined for the first moments and on touch;lib/scroll.jshandles both.
Known breaks on main, owned by their page chats
-
The
Crawl.cssandMetrics.jsxbuild errors are fixed on main, andnext buildpasses. -
Closed drawers keep
aria-modal="true"in the DOM. The ask bar now ignores overlays that are not showing. If you build a modal, still droparia-modalwhile it is closed (or unmount it). -
Shared complaints in the 7 Nov reviews are fixed by this system:
- Two solid buttons at the top.
- No desktop sticky ask.
- The header and phone bar showing two solids.
- "Try Hanzo" fading on hover.
- The phone bar overlapping the closing button.
Page-level ones stay with each page: several equal solid buttons in one view, a hydration mismatch on
/agents/*and/integrations/*members, and text hidden by page CSS when JS is off.
Requests to the shared system
Write each request as one line: the page, what you need, and why.
- Every page (Proof chat, 7 Nov): in-site clicks freeze about 4s and the card-to-page morph never plays. In
components/Morph.jsx, the View Transition's update callback resolves throughrequestAnimationFrame(() => ok())(lines ~34 and ~71). Chromium runs no animation frames while a transition holds rendering, so the promise only settles at its own ~4s timeout (measured: 4,069ms with rAF, 81ms withsetTimeout(ok, 16)). Fix: resolve withsetTimeout(ok, 16)in both places. With that simulated, the /integrations and /open-source cards land in their destination headlines. - Every page (Wave 2 critic, groups 5-10, 7 Nov 14:55): the ask bar floats over content, and MASTER §3.2.6 and §3.3 fail any page for that. Measured on /search (main @
cb11693): at 1470×801 the bottom "Read the docs →" pill covers a chapter result, the "Custom" price and the agent prompt. At 375×812 it covers paragraphs and the prompt's Copy button, so a tap on Copy hit the bar and navigated away. Fix: on desktop drop the floating pill and let the sticky header carry the ask (§3.2.6: "in the sticky header at every width. No floating pill bar or panel over content on desktop"). On phone keep the slim bar, but reserve its height (bottom padding onmainand on each pinned stage) so it never covers text or the page's own ask.