# Skin system — design

**Issue #23. Status (2026-09-25): Signal + BAY shipped. LEDGER and NIGHTWATCH are not
built — the skeleton was proven flexible instead (P7's drill, see "Skeleton flexibility").**
The exploration comps (three static-HTML theme directions + the full research) live
locally on the dev box under `docs/dev/theme-designs/` (git-ignored by policy) and are the
**spec** for anything skin-visible: a conformance question is settled by the comp and by
measurement, not by taste. The phase record is local too (`docs/dev/ui-refactor/`); the
code is the authority and `apps/web/src/skins/registry.test.tsx` holds the promises below
as assertions.

> The rules a skin rides *under* — the shell skeleton, the content language, the
> interaction language — are in [`design-ui-system.md`](design-ui-system.md). This page is
> the second axis on top of them: what a skin may change, and what it may never touch.

## What this is

A multi-skin architecture for the web console: the shipped **Signal** system stays the
default and gains the ability to host additional skins (BAY shipped, LEDGER / NIGHTWATCH
later). A skin is **a token override sheet + a scoped style package + a manifest** — it
never restructures the app shell, and it can never alter a status value, only its
rendering.

Decisions (2026-09-23, amended after P7/P8 and the shell round of 2026-09-25):

| # | Decision |
|---|---|
| 1 | Architecture = token contract + scoped skin packages + topology-renderer registry. **Layout skeleton never changes.** Fidelity is reached through two controlled extension points: (a) `data-*` annotations and the base's empty `Region` slots, (b) the topology registry. ~~manifest-declared widgets~~ — the `widgets` field was **deleted** in P7: the regions the skins-of-record want (`marginalia`, `watchbar`, and the mobile strip region — `baystrip` then, `navstrip` now) are base slots that render nothing while empty, so a skin never needs a manifest field to own DOM. |
| 2 | Ship order: BAY shipped (P7). NIGHTWATCH / LEDGER deferred — but the skeleton they need was proven by a placeholder skin that ran a real browser walk (P7 §Skeleton flexibility), not by a document. |
| 3 | Topology style is locked to the skin (constellation / engraved plate / radar); not a standalone user option. All three keys are real renderers. |
| 4 | Skin preference = `localStorage['hnx.skin']` (same family as `hnx.lang`). No server-side user field. |
| 5 | Visual snapshot rig (`scripts/ui-snap.mjs`) ships as a local/manual tool; CI adoption deferred. |
| 6 | The hexagonal brand mark's **shape is frozen**; `--brand-bright/mid/deep` are per-skin overrides. Wordmark + auth-page banner material follow the skin. |

## The two axes

- **Mode axis** (light/dark) — `next-themes`, class on `<html>`, storage key `theme`,
  `system` default.
- **Skin axis** — `<html data-skin="signal|bay|…">`, set pre-paint by an inline script in
  `apps/web/index.html` (which also closes the pre-existing theme-flash window),
  persisted as `hnx.skin`, driven by `SkinProvider`
  (`src/components/skin-provider.tsx`) + `src/skins/registry.ts`.

A manifest declares `modes: ['light']` etc. A **single-mode skin HIDES the theme toggle**
(#41 — `ThemeToggle` returns null; it used to render a `disabled` icon, which on touch
devices is a dead target whose slipped taps hit the neighbor: the star link in the
corner, the skin picker in the drawer) and switching onto it forces the mode it ships.
The rig does not mirror this: it asks the document which mode it resolved to
and skips the shot when the skin locked the other one (§Snapshot rig).

## Manifest (the contract every skin declares)

```ts
interface SkinManifest {
  id: SkinId;                    // 'signal' | 'bay' | 'ledger' | 'nightwatch'
  nameKey: `app.skin${Capitalize<SkinId>}`; // i18n; product names untranslated
  modes: SkinMode[];             // locks the light/dark toggle when length 1
  statusStyle: 'dot' | 'led' | 'lamp' | 'word';
  topology: 'constellation' | 'plate' | 'radar';
  load: () => Promise<unknown>;  // runtime-injects tokens.css / skin.css / fonts
}
```

`signal` is the zero-package baseline (`load` is a no-op); every other skin is pure
addition under `apps/web/src/skins/<id>/` (`index.ts`, `tokens.css`, `skin.css`,
`fonts.ts`). Skin CSS may use exactly two selector prefixes: `:root[data-skin='<id>']`
(tokens) and `[data-skin='<id>']` (signature surfaces). Nothing else — no bare classes,
no `!important` wars with utilities.

Every manifest field must have a consumer; the registry test fails on a field nothing
reads, which is how `widgets` was caught.

## Token contract

Frozen: every variable in `apps/web/src/index.css` (surfaces, text, borders, `--signal`,
`--ok/--warn/--danger`, `--brand-*`, `--sidebar-*`, `--radius`, …). Components reference
**names only**; skins override **values only**. The set that carries the skin system:

| Token | Role |
|---|---|
| `--scrim` | overlay base color (alpha at use site: `bg-scrim/50` replaced the last hardcoded `bg-black/50` in shadcn primitives) |
| `--surface-inverted` / `-ink` / `-dim` | the "well": a surface darker than the page for terminal/code/diff readouts. `-dim` is that window's **secondary ink** — and, by consequence, the only correct tone for depth *inside* a well (§Material) |
| `--tray` / `--tray-ink` | the neutral step between card and muted (table headers, list feet, row hover, group strips). `--tray-ink` exists because a skin that rebinds ink **inside** a well cannot reach the chip that sits on the tray |
| `--app-font-sans` / `-mono` / `-display` / `-label` | runtime font hooks — the `@theme inline` layer maps `--font-*` onto them, so a skin swaps families by overriding a variable |
| `--spine-w`, `--bay-h` | the rack: the spine column's width and the floor height of one bay (§Addresses) |
| `--panel-pad(-wide)`, `--panel-head-h`, `--table-head-h`, `--row-h`, `--control-h(-sm/-lg)`, `--row-ctl-h`, `--gap(-tight)`, `--touch` | density contract: panel chrome, table headers, rows, and every control's height (§The control scale) |
| `--radius-panel` / `--radius-well`, `--shadow-panel`, `--press-shift` / `--shadow-press` | material contract. `--press-shift`/`--shadow-press` are **read** by `[data-slot='button']:active`; Signal sets them to zero (no displacement), BAY to 2px (a key that goes down) |
| `--lamp-ok/warn/fail/off`, `--state-ok/warn/fail-ink` | status device colours: the lamp body (tones) and the *ink* the state word is printed in |
| `--marginalia-w` | the folio column's width (the slot is the base's; the width is the skin's) |
| `--label-size(-sm)`, `--data-size(-sm)`, `--readout-size*` | type scale for the three roles (`.role-label`, `.role-data`, `.role-readout`) |
| `--motion-seat` (180ms) / `--motion-breath` (2.4s) | the two sanctioned motions: a panel seating, a lamp breathing (both zeroed by the global reduced-motion block) |

### The control scale

Heights are a closed set, and **the scale is only real if every control reads it**:
`ui/button` did from P7, while `ui/input` (`h-9`) and `ui/select` (`h-9`/`h-8`) kept
literals until #23 — which is how BAY's inputs came out a tier taller than its own buttons
(36 vs 30px) and its densest toolbar (the chat Sender) 7px too tall. A literal is
invisible to a skin; a token is the skin's only handle on density.

- **A token fixes WHO decides a size, not WHETHER it fits.** Replacing a row's `h-8` with
  `--control-h-sm` made BAY's rows right and left Signal's flush against the cell rules:
  Signal's small control is 32px and its row is 30px. The constraint therefore belongs in
  the token — `--row-ctl-h: min(var(--control-h-sm), calc(var(--row-h) - 4px))`, "the
  skin's small control, never taller than the row that holds it" (Signal 26, BAY 25 — the
  cap never bites there, because BAY's own small control is smaller). Every row-level
  control reads it: the list pages' row menus and the MCP connect/disconnect buttons.
- **The fingertip is `--touch` (40px)**, and it arrives as an AREA, not as a bigger box.
  A control inside a table row or a Well is behind a pinned/opaque overlay, so expanding
  `min-width/min-height` under `(pointer: coarse)` inflated the well (242×50), its row
  (33 → 51px) and pushed the affordance under the pinned column. The extra area is an
  `::after` overlay (`inset: 50%` + `min-*: 2.5rem` + `translate(-50%,-50%)`); the visuals
  stay at their designed size. Where a control IS the phone's primary action (the Sender's
  send/stop) the token is taken directly instead.

### Material

- **A Well hugs its value.** In a flex container an inline-flex well stretches (a black bar
  across a card in BAY); `self-start` at the call site or a block parent restores the
  comps' behaviour. Table cells use the chip scale for protocol values — the comps'
  `wchip wide` carries whole session ids — while `well` belongs to kv rows and labelled
  fields.
- **A shadow is only a plate if it is a different tone.** BAY's figure shadow started as
  the aluminium `--bezel` (#c3cad4) — but the figures sit inside inverted wells, whose ink
  is already light (#c8d4e0): 20 lightness units apart is not depth, it is the same word
  printed twice. It is `--surface-inverted-dim` now (#7b8899 against ink 200,212,224) — the
  ASK is a shadow, so the property is tone, and the tone has to come from the window the
  thing sits in.

## Hook vocabulary — the only things a skin may depend on

A device a skin cannot see does not exist. Every kit device therefore carries a stable
socket, and the sockets are the frozen half of the contract (components own them; skins
read them):

| Hook | Carried by | Meaning |
|---|---|---|
| `data-skin` | `<html>` | the skin anchor; every skin rule is scoped by it |
| `data-region` | shell | `chrome`, `spine`, `brand`, `nav`, `plate`, `header`, `main`, `signed-in`, `navstrip`, `marginalia`, `watchbar` — empty slots cost 0. The composer's controls are a `data-slot` device (`composer-tools`), not a region: the region list is exactly what the shell renders |
| `data-nav-group` / `data-nav-heading` | nav items + plate headings | which address an item belongs to (spine bays, plate headings, strip items) |
| `data-bay-number` | spine + strip items | the bay's number, **rendered from data** — CSS `content:` injection is forbidden |
| `data-surface` | kit | `panel`, `table`, `tray`, `well`, `readout`, `mesh` — the material class of a block |
| `data-slot` | kit + shadcn primitives | the device: `panel-header`/`panel-title`/`panel-body`, `table-*`, `lamp`/`lamp-body`/`lamp-word`, `switch`/`switch-thumb`, `select-trigger`/`select-value`/`select-chevron`, `composer-tools`, `page-actions`, `chip`, `meter`/`meter-fill`, `meter-ring`/`meter-ring-track`/`meter-ring-fill`, `copy`, … |
| `data-state` | status devices + controls | the status truth (18 states) and control state (`checked`, …) — styling never rewrites it |
| `data-tone` | kit | the accent intent, typed per device (`chip`: `default`/`muted`/`live`; `panel`: `default`/`live`; `note`: the status family). A skin that withdraws the accent (LEDGER) maps `live` onto ink — the hook stays, the colour changes |
| `data-variant` | kit | a material variant **the base intends** (`Button`: `ghost`/`link`/`outline`; `SelectTrigger`: `bare`) — the skin hands back |
| `data-density` | tables | `default` / `compact` |
| `data-live` | shell | the single live thing (a running session, the current bay) — a skin may spend the accent on it |

- **When the base must opt out of a skin, the opt-out is a variant.** Skin rules are
  unlayered, so no Tailwind utility can out-vote one: the chat Sender's config selects
  carried `border-none bg-transparent shadow-none` and BAY still painted them as inverted
  LCD windows. `SelectTrigger variant="bare"` (`data-variant="bare"`) is the socket — the
  skin scopes its window rule with `:not([data-variant='bare'])`, and any future bare
  select gets the exemption by asking for it.
- **A skin that moves something must know which property the base moves it with.** Tailwind
  v4 compiles `translate-x-*` into the standalone `translate:` property, which does NOT
  overwrite `transform:`. BAY's switch thumb was placed with `transform: translateX(22px)`
  while the base animated `translate: calc(100% - 2px)` — the ON knob landed at the SUM
  (34px) of a 38px track and poked out of the switch. The comp positions `.sw i` with
  `left`; the skin does the same and resets `translate: none`. Same family as the
  unlayered-rule lesson: the layer that owns the mechanism is the layer that defines it.

## Status truth is data, never style

One device, two call shapes (P8 closed this — D-13):

- **`Lamp`** (`components/kit/lamp.tsx`) — the status *readout*: wrapper +
  `data-slot="lamp-body"` + an optional word/label. Its shape follows
  `manifest.statusStyle` (dot / LED / phosphor lamp / printed word).
- **`StateSignal`** (`components/state-signal.tsx`) — the inline *mark*: the same
  `data-slot="lamp-body"` element carrying the same `data-state`, with no wrapper and no
  word channel, so it fits a 2px gutter or a tool row.

Both carry `data-state="<semantic state>"`; `SIGNAL_TONE` maps the 18 states onto five
tones and both devices read it, so a new state cannot be added without choosing a tone,
and a skin writes **one** rule family (`[data-skin='x'] [data-slot='lamp-body'][data-state=…]`)
instead of one per device. Before P8 they were two element shapes: BAY carried every LED
rule twice, and a word-style skin could only neutralize one of them.

A skin that replaces colour with a printed word (`statusStyle: 'word'`) gets no lamp body
from `Lamp`, and hides the mark itself —
`[data-skin='ledger'] [data-slot='lamp-body'] { display: none }` — because only the skin
knows whether a word can be printed where the mark sits. The word strings live in i18n.

`SIGNAL_FILL_CLASS` remains the SVG equivalent (the mesh topology fills nodes from the
same map).

## Addresses & navigation (the rack, the strip, the action)

**A nav group is an address engraved on a rack, not prose.** `nav.ts` carries `number`
(`01`…`05`) + `label` (`NAV MESH ASSET ACCESS ADMIN`) for every group; the label is
English and uppercase in **both locales** — translating it is how one section ends up with
two names. The manifest keeps `label` (the engraving, constant) beside `labelKey` (the
section as a LINK in the page trail, translated) — the same split as wire values that stay
English. One source (`nav.ts`) feeds every surface that names a section — spine bays, the
plate heading, the strip's number prefix — so they cannot disagree; `01-skeleton.md §6`
drew the group strip as `NAV MESH ASSET ACCES ADMIN` from the start.

**The spine runs a 30px column with its name down** (`--spine-w`,
`writing-mode: vertical-rl` on `.role-label-vertical`): the comp's 72px was mostly air
once the name turned sideways. Bays keep a `--bay-h` (72px) floor so the rack still reads
as units; the active bay carries a 3px accent edge.

**A piloted bay never moves its address.** The live bay's lamp sits in the module's top
corner (`absolute`), not in the number's row: a lamp beside the address pushed the address
sideways on the one bay the eye is on. Same rule as the hit areas — a marker may not
re-lay-out the thing it marks.

**`navstrip` — the phone's jump bar (`<900px`).** Every **destination**, not one entry per
section: a section-only strip lands every tap on that section's first page, so switching
between interior pages is a drawer trip — and a caret menu beside the page title is not
the answer, it duplicates the drawer button without adding destinations. The strip keeps
the bay strip's dress (each item led by its bay number, hairline separated, the current
item underlined 2px in the accent, one horizontal scroller with its own scrollbar hidden,
the current item scrolled into view on arrival, `2.5rem` minimum height under
`(pointer: coarse)`) and reads `03 技能 │ 03 子代理` for two pages of the same section. The
drawer stays: it is the only surface that also carries the account block.

**A topbar action shrinks to its icon on a phone** (`shell/page-action.tsx`): the bar is
48px tall and already holds the drawer button, the identity and three toggles. Icon + label
from `sm` up, the icon alone below with the name in `aria-label`/`title`. It is one
component because "uniform" has to be a property of the code, not a habit — two pages had
grown their own `hidden sm:inline` span and six had not.

`marginalia` is a base slot **outside** the content frame: empty it is `display: none` and
costs nothing; a page fills it with `<PageSlot slot="margin">`. That is how LEDGER's folio
column arrives without touching the skeleton.

## Devices: bands, rows and lists are composed, never hand-rolled

A page's bands and lists are devices — panel nameplates, tray strips, wells, lamps, the
label/data roles — and a band built out of raw `div`s with literal type sizes reads as
foreign no matter which skin is on, because it is the one element on screen that no skin
can reach. Two worked examples from the shell round (2026-09-25):

- **The chat session rail** was hand-rolled: a group header printing a directory's
  basename with the path in a `title`, and one-line rows with a rounded hover block. The
  comp has `.sgroup-h` (tray strip + `LabelText` + the directory as a **Well**, copyable)
  and `.sess` (lamp + title over a mono meta line `when · short-id`, hairline separators,
  active row on the tray with heavier ink). Rebuilt on the comp's devices, both skins read
  as the same product (measured: tray 233,236,241 = the comp's `#e9ecf1`).
- **The Sender's toolbar sits on its baseline, not on its centre.** `items-end`: the config
  words line up with the Send control beside them; centring them against a taller button
  floats them above the card's edge. The row's height comes from the control scale
  (`--control-h`, not a one-off 36px circle), the shape from the skin's radius (a rounded
  square, not a circle the comps never had), and on a phone the primary action takes
  `--touch` while the config controls trade their values for icons: the value is read in
  the picker, which is also where it is set, so the strip never spends horizontal room on
  a word that is one tap away — icon alone at phone width, icon + value from `sm` up.

**BAY's switch is a device too** (`data-slot="switch"` + `switch-thumb`): a rectangular
slot with a machined knob and a green pilot lamp on the left when it is on (the comp's
`.sw`). Shape is the skin's business — which is why the slot exists at all.

## Skin CSS rules (the two hard rules, plus what a skin must read)

A skin may not:

1. **inject text with `content:`** — text is data the CSS cannot know (the bay numbers
   were injected that way and could never follow the manifest);
2. **tear a component open with negative margins** — the remedy is a base hook, not
   surgery.

Both are asserted by the registry test over every `skins/*/skin.css` (comments stripped),
so a new skin cannot break them by accident. Beyond them, the two positive rules: a skin
**reads the property the base moves with** (§Hook vocabulary) and a skin that needs a
structural difference means the base is missing a hook — add the hook, do not reach over
it.

## Topology registry

`components/topology.tsx` maps the manifest's `topology` onto a renderer:
`constellation` (the SVG fan-in/out, the product's signature), `plate` (the same mesh as
a two-column list; also what `constellation` degrades to on narrow screens) and `radar`
(an instrument sweep, built in P7). All three are real; `radar` has no shipped consumer —
kept because the key is part of the frozen contract and a third skin gets it by editing
its manifest alone.

## Skeleton flexibility (how the deferred skins are still safe)

P7 proved the skeleton can host NIGHTWATCH / LEDGER **without structural change** by
running a placeholder skin in a real browser, one line of the promise at a time: region
slots (the folio column appeared and moved `main` without breaking it), `statusStyle:
'word'`, the via-token topology swap, no light-mode assumptions in structure, the accent
withdrawn to ink (with "current" still carried by position and weight), and density/fonts
entirely through tokens. Two real gaps surfaced that way — the missing folio mount and
the two status devices — and both were fixed rather than documented.

## Snapshot rig

`scripts/ui-snap.mjs` boots the server (memory driver) + web dev server, seeds honest
data over the API, and captures **route × skin × mode × viewport** (desktop 1440×900,
mobile 390×844 via CDP device emulation — headless Chrome clamps raw windows at 500px,
so raw `--window-size=390` screenshots lie). `--update` refreshes the baseline
(`docs/dev/ui-baselines/`, machine-local by gitignore policy) and prunes entries the
matrix no longer produces; without it the rig compares with pixelmatch and fails on real
drift. Run it before merging skin-visible changes.

Determinism is enforced where it can be: reduced motion + frozen clock, an injected mask
for timestamps/ids, `document.fonts` gated on the active skin's families, and a settle
gate that waits for network-quiet *and* two byte-identical frames (socket.io long-polls
forever, so `networkidle` never fires). Single-mode skins are not mirrored in the rig —
the capture reads the resolved mode off the document and skips the duplicate shot
(measured before P8: 22 of 88 baselines were byte-identical pairs).

Companion instruments: `scripts/test-touch-targets.mjs` (a CDP `hasTouch` probe for the
coarse-pointer rules — `set device` in agent-browser does not make `(pointer: coarse)`
true, so the rig has to emulate touch itself).

## Non-goals / future

- No layout-variant mechanism, no per-skin component code.
- NIGHTWATCH / LEDGER themselves: product decisions, deferred. Their contract slots
  (`statusStyle: 'word' | 'lamp'`, `marginalia`, the topology keys) are in place and
  exercised by tests.
- Server-side per-user skin preference — explicitly not built (localStorage only).
- Font subsetting is per-package (`latin-*.css` from Fontsource); the CJK chain in
  `--font-sans` stays system fonts, and extended-Latin characters beyond the shipped
  subset fall back to the system stack.
- Sections carry two names **on purpose**: the breadcrumb's crumb is the translated
  `labelKey` (`资产 / 技能`) because it sits in a sentence-like page trail, while the spine,
  the plate heading and the strip's number use the engraved `label`. Where both are on
  screen at once, each reads as what it is — a reference in the reader's language, next to
  an address that never moves.