mirror of
https://github.com/hanzoai/site.git
synced 2026-11-20 21:14:28 +00:00
7.6 KiB
7.6 KiB
Dark mode: how to convert your pages (8 Nov)
We use Hanzo's own system, exactly as live hanzo.ai runs it, and build none of our own. Your job is your own page files only:
- The redesign must look right in both modes and match live hanzo.ai in dark.
- Bright mode must not change by a single pixel.
- The copy rule still holds: change no words, and
scripts/copycheck.mjsstays at missing 0.
How it works (the foundation is done; don't change it)
@hanzo/appearance0.2.14 (Hanzo's package, hanzoai/uipkg/appearance).app/layout.jsxputsbootScript({ base: { theme: 'system' } })in<head>. Its output is byte-identical to the script in live hanzo.ai's HTML.- Before the first paint, it replays
localStorage['hanzo.appearance.painted']({ theme, vars }). With nothing saved, it falls back tosystem, which followsprefers-color-scheme. - It sets
light t_lightordark t_darkon<html>, pluscolor-schemeanddata-scheme.
<Appearance />(components/Appearance.jsx) callsuseAppearance({ install: { theme: 'system' } })once at the root, as Hanzo's README says.- After hydration it applies the person's choice: their preference,
localStorage['hanzo.appearance'], which Hanzo IAM keeps across Hanzo sites. - It follows the device while the theme is
system, and re-applies when the choice changes in another tab. - It renders nothing. There is no visible switch, because live shows none.
- After hydration it applies the person's choice: their preference,
- The server HTML says
class="t_dark", as live's does. React never writes these classes (suppressHydrationWarning), so hydration and client navigation keep them. - Colours come from
@hanzo/tokens(itscss, imported inapp/layout.tsx: the ramps, radii, type, spacing and data hues).public/hanzo.cssstates only what the tokens do not: the density, radius and type scales, and the white page of.light.- Dark is Hanzo's default:
:root/:not(.light). Light is.light. - Our tokens in dark are references to Hanzo's (
--ink: var(--foreground)and so on, inapp/globals.cssandapp/system.css), so no dark colour is ours. - Our light values are unchanged.
- Dark is Hanzo's default:
- Already dark-correct: Hanzo's header, menus and footer (through hanzo.css), the cookie banner and preferences, the announcement strip, sign-in buttons, buttons, the search palette and scrims, the menu feature card, sheets, drawers, pause buttons, related cards, every
components/v2/*.css, and the home hero's dot field (it draws in--inkat 17%).
Testing it like live
- Device: emulate
prefers-color-scheme(DevTools › Rendering, or PlaywrightnewContext({ colorScheme: 'dark' })). With nothing saved, the page follows it, including a change while it is open. - A saved choice: run
localStorage.setItem('hanzo.appearance', '{"theme":"dark"}')(or"light"), then reload. It wins over the device, as James's saved "light" does on his dark Mac.hanzo.appearance.paintedis only the first-frame replay. Set on its own, it shows for one frame, thenuseAppearance()re-applies the real preference, as live's<Hanzo>root does.
- Measured on 8 Nov. Every case lands on the right class at first paint and after hydration, with no errors:
- saved dark on a light device → dark;
- saved light on a dark device → light;
- nothing saved → follows the device, and flips live.
The tokens
| Use it for | Token | Light (unchanged) | Dark (Hanzo's token) |
|---|---|---|---|
| Page background | var(--bg) |
#fff |
var(--background) |
| Text, headings, ink fills | var(--ink) |
#0a0a0a |
var(--foreground) |
| Secondary text | var(--soft) |
#6e6e73 |
var(--muted-foreground) |
| Captions, mono labels | var(--faint) |
#86868b |
var(--text-tertiary) |
| Hairlines | var(--line) |
black 8% | var(--border) |
Muted fill (old #f5f5f7) |
var(--x-fill) |
#f5f5f7 |
var(--muted) |
A surface on the page (old #fff card, button, menu) |
var(--x-raised) |
#fff |
var(--card) |
Text on an ink fill (old #fff on #0a0a0a) |
var(--x-on-ink) |
#fff |
var(--primary-foreground) |
Recessed bar (old #fafafa) |
var(--x-sunk) |
#fafafa |
var(--surface-card-quiet) |
| Selected pill in a track | var(--x-knob) |
#fff |
var(--secondary) |
| Stronger borders (old black 10, 12, 15%) | var(--x-e10), var(--x-e12), var(--x-e15) |
black .10, .12, .15 | var(--border), var(--border-control) |
| The open-source band's heat: calendar, legend and bars | var(--x-heat) over var(--x-cell) (the empty cell) |
#0a0a0a over #e8e8ec |
#fff over var(--secondary) |
Rooms ([data-room]) |
var(--room-*) |
as before | Hanzo's tokens; [data-room=light] follows the page into dark |
- Write dark rules with Hanzo's selector,
html:not(.light) .your-thing { … }, neverhtml.dark. That way JS-off renders like live, as dark. - Don't use
var(--card)orvar(--raised)for a new light fill. Hanzo defines those names on inner elements (--cardis#f2f2f2,--raisedis#e4e4e4), so they don't resolve to our light values and bright mode shifts. That is why our new tokens start with--x-. - A one-off grey keeps its exact light value with
light-dark(#ececef, var(--muted)).light-dark()follows the html class:html.lightandhtml:not(.light)setcolor-scheme. - Invent no colours. In dark, use only Hanzo's tokens:
--background,--foreground,--card,--muted,--secondary,--border*,--text-*,--surface-*,--glass*,--primary*.
How to convert a page
- Find what's left. Run
node scripts/darkcheck.mjs /your-pagewith the dev server on :4180 (CHROME=/opt/pw-browsers/chromium-1243/chrome-linux64/chromein the cloud). It lists every bright background and low-contrast text by class, at 1470 and 375. - Replace hard-coded colours in your page CSS:
#fffbackgrounds →var(--x-raised), orvar(--bg)for a full-width section.#0a0a0a/#0a0a0b/#111text →var(--ink).#6e6e73→var(--soft).#86868b→var(--faint).#f5f5f7→var(--x-fill).#fafafa→var(--x-sunk).color: #fffon an ink fill →var(--x-on-ink).rgba(0,0,0,.08)hairlines →var(--line).- Canvas and inline styles: read the colour from CSS (
getComputedStyle(el).colorwithcolor: var(--ink)), and redraw when<html>'s class changes (seeDotsincomponents/Hero.jsx).
- Leave alone anything that is black in both modes:
[data-room=dark]sections, films, Hanzo's media, and white type on a film. - Bright mode is unchanged. Run a server on the code before your change on :4190: a
git worktree,npx next dev -p 4190, with node_modules linked (webpack accepts a link; turbopack doesn't). Then runHZ_OLD=http://localhost:4190 node scripts/lightcheck.mjs /your-page. Done meanslight: OK. - Dark matches live.
darkcheck.mjsshould saydark: OK. Then compare your page and live hanzo.ai side by side in dark at 1470×801 and 375×812, with no console errors, no sideways scroll and no unreadable text. - Copy unchanged. Run
node scripts/copycheck.mjs /your-pageand confirm missing 0.
Setup notes
- React is now 19.2.8, the version
@hanzo/appearancerequires as a peer; Next 15.5.4 accepts it. Runnpm ciafter pulling. npm run buildrefuses stale live figures when hanzo.ai is unreachable, as in the cloud sandbox.HZ_LIVE_OFFLINE=1 npm run buildbuilds from the saved figures on purpose.
Left for the page chats (measured 8 Nov)
/(Home): the platform mock incomponents/pages/Home.css./pricing: the.xpr-*panel, tabs and rail./chat: the.cht-*window, tools and rows.- Every other page: run
darkcheck.mjson it.