Files
zeekay 7649f2ced2 Plex as a third Arabic face; appearance 0.2.13, ui 8.29.32
@hanzo/design 0.5.38 declares IBM Plex Sans Arabic beside the two Noto
companions and the arabic axis gains `plex`. COMPANIONS carries it, so
the appearance panel's Arabic row and the corner's Arabic font list offer
Kufi, Sans and Plex; the panel shows each in its own face, as before.

Corner's Words gains `plex`. A host that writes its own words (hanzo.ai's
help corner) types them as Words, so its typecheck names the new key.

The catalog moves to @hanzo/design 0.5.38. The lockfile is re-resolved
from main's with only that change in the workspace; pnpm also settles
the entries main's lockfile had left behind.

Claude-Session: https://claude.ai/code/session_015XYKLjZtDTJEnMo4eK3AFH
2026-10-30 00:22:12 -07:00

3.1 KiB

@hanzo/appearance

The one appearance panel: theme, text size, scale, density, face, Arabic face, width, corners and accent, stored per person and applied to the whole product.

import { Appearance } from '@hanzo/appearance'

<Appearance />

Add the boot script to <head> so the first paint is already correct — without it the page paints at the defaults and jumps when JS runs:

import { bootScript } from '@hanzo/appearance/state'

<script dangerouslySetInnerHTML={{ __html: bootScript() }} />

<Hanzo> from @hanzo/ui applies the person's choice on mount and hands gui the theme the document shows. A host that mounts its own gui provider calls useAppearance() once at its root and passes useScheme() as defaultTheme.

Knobs, not themes

@hanzo/design publishes --type-scale, --type-ratio, --density, --radius-scale, --font-sans, --font-arabic and the --primary / --accent family, and every ramp in tokens/*.css reads them. A preference sets a few numbers and one colour rather than restating a scale, so rungs added later are covered for free.

Arabic is its own axis (arabic: kufi, sans or plex) because Zen draws no Arabic. It writes --font-arabic, which design's sans, mono and serif stacks all name first, so the companion it names sets every Arabic letter under whichever face was chosen, and Latin never touches it.

An accent is a family: the fill, the ink that reads on it (design's black or white, whichever contrasts more) and the hover that deepens it, all derived from the one colour by vars(). The theme is a class, light / t_light or dark / t_dark, painted on <html> in both vocabularies.

First paint

apply() keeps what it painted under hanzo.appearance.painted, and bootScript() replays exactly that before any bundle runs. It computes nothing, so it cannot fall behind vars(). bootScript({ base }) paints an install default on a device that has never applied anything.

Where a choice lives

Four layers, the narrowest that has an opinion winning axis by axis: install < org < person (everywhere) < person (this org). The person's layers are kept in IAM (/v1/iam/preferences, member appearance) and cached on the device, so a choice made on one Hanzo origin reaches the others.

The composer

How a person's composer behaves is one record, read by every composer (@hanzo/ui/chat's Composer) and written by the panel's last rows:

import { useComposing, writeComposing } from '@hanzo/appearance'

useComposing() // { send?: 'enter' | 'mod', chips?: boolean, model?: boolean, mode?: boolean }
writeComposing({ send: 'mod' }) // ⌘/Ctrl+Enter sends, Enter breaks the line

An axis nobody set is absent, and the surface's own default holds (Chat opens without chips or a mode, Dev with both; the model selector is off until turned on). It is kept on the device under hanzo.composer, announced to the page with a hanzo:composer event, and kept in IAM beside the appearance under the composer member of /v1/iam/preferences, so it crosses a domain. It paints nothing: no document knob, no head script.