Penguin Harness Frontend

Web App frontend conventions

packages/web is React 19 + Vite + Tailwind CSS 4, with no cn/clsx, no tailwind-merge, and no variants library. Classes are composed with template literals, and a component's variants are a Record<Key, string> next to it (button.tsx's variantClass, input.tsx's sizeClass). Match that shape; do not introduce a styling dependency.

This file records the decisions that already exist so they are not re-litigated per PR. Read penguin-harness-dev for the repo-wide contract (verification chain, changelog, two-repo layout).

Status colour: pick a tone, never a palette class

src/lib/tone.ts is the only place a status colour is spelled. Five tones, chosen by meaning:

Three maps, by the shape of the thing being coloured: toneInk (a glyph or a line of status text), toneSurface (a tinted pill with its own text — badges), toneDot (the 6px state dots). A notice that owns a row is the shared UI package's NoticeStrip, which takes the package's tone names (busy → success, link → info, muted → neutral); toasts render through it.

Rules:

• Two states may share a tone. busy and success resolve to the same emerald on purpose. A tone says what a mark means, not which state it belongs to. Where two states share a tone, separate them by shape and motion — that is what the session list's turning hourglass and squeezing compress mark do, and it is legible to a reader who cannot separate hues.
• Never make colour the only carrier. Every status mark also names its state in an accessible name or in adjacent text.
• Contrast is measured, not assumed. The ratios in tone.ts are WCAG 2.x against the four surfaces marks actually sit on — white and gray-50 in light, and the values the default theme overrides for dark (packages/ui/src/themes/github.css: gray-950 is #000000, gray-900 is #0d0d0d, not Tailwind's stock values). Recompute if you change a tone; a graphical mark needs 3:1, and muted is the one tone allowed below it because its meaning is always already in text.
• What is out of scope, and must not be folded in: categorical palettes where colour is an identity rather than a judgement (category-colors.ts, token-colors.ts, the timeline phase bars, per-skill avatar tints); the terminal's chrome, which resolves light/dark in JS because a subtree cannot opt out of the dark: variant (terminal-appearance.ts carries its own success/attention/danger); secondary body text, which is typography; a background-only wash on a card section; and hover-only variants, since a tone token is the resting ink.

Explanatory text: semantics disclose, formatting stays

Two kinds of prose, and the split decides whether it is disclosed.

• Semantics — what a section is, what a field means, what it affects, when a change takes effect. Read once, then in the way forever. It is disclosed on request.
• Formatting — the shape the value must take: "one KEY=value per line", "one argument per line", "leave empty for unlimited", allowed characters, a k/m suffix. Read while typing. It stays on screen, in the field's hint. Hiding it turns a glance into a click and raises the error rate.

A string that mixes both is a string that should be split, not a judgement call. When you cannot split it, keep it visible — a visible sentence is never a bug, a hidden format rule is.

One exception: a rule the control already enforces or already shows goes behind the "?". The Profile nickname's "1–32 characters, blank clears" is the case. maxLength stops the 33rd character, and the placeholder says what blank means, so a visible line would only repeat them (user decision, 2026-10-03).

Already-disclosed text does not move: title= tooltips, OptionMenu row descriptions, confirm dialog bodies (the dialog is the disclosure), toasts, and empty states.

Tooltips: when a mark gets one

A hover hint shows only where its words are not on screen (hintAllowedFor in the UI package's tooltip.tsx): an icon-only control, a wordless mark, an input, or text that is cut off. Three glyphs are read without one — the circled "?" beside a title (InfoPopover, whose hover opens the explanation itself), a close or clear × beside the thing it dismisses, and a fold chevron under the rows it folds — so they carry no data-tooltip unless the hint says something the glyph cannot: a shortcut ("Close (Esc)"), a consequence ("Kill this terminal"), the subject when it is not beside it. That is why DockTabs' close × keeps its hint (the shortcut; on a terminal tab, the consequence) while the password banner's × and a browser tab's × have none. Either way the mark keeps its aria-label; that name is for assistive technology, not a panel. A hint on text that may truncate shows that text whole (plus an id when one helps), never the verb of the click — the underline already says it opens.

Which disclosure — the "?" or the fold

Two forms, and a title decides between them, not taste:

The circled "?" may only appear beside a title. It must never stand alone on its own line. Where it would stand alone, use the fold.

• A title is present → InfoPopover (@prismshadow/penguin-ui). A circled "?" immediately after the section heading, the table column header, or the field label — the last of those via Field/Input/Textarea/PasswordInput/Select's info prop. The "?" is an anchored mark: it reads as help only because it modifies the title it sits against, and it borrows that title's meaning instead of restating it.
• No title on the surface → HelpFold (@prismshadow/penguin-ui). A compact row that names itself and expands its explanation inline underneath. This is the Agent settings tabs: their name lives in the tab bar and the panel does not repeat it, so a "?" at the top of the panel would be a mark modifying nothing. A neighbouring <Button> does not rescue it — a control is not a title.

The fold is not a popover in another shape: it is inline flow, so it takes no portal. Do not reach for usePortalPanel there for symmetry — that hook exists to keep a floating panel clear of an ancestor's overflow and to close it on outside click, Esc or scroll, and a fold does none of those things. It follows the WAI-ARIA disclosure pattern instead: the panel stays in the DOM and is hidden while collapsed, so its aria-controls always resolves.

The "?" opens on hover (owner, 2026-10-03: a help mark that needs a click to say anything is one click too many). InfoPopover takes its behaviour from the UI package's useHoverDisclosure: a mouse resting on the "?" opens the panel after the tooltip's own delay (HOVER_OPEN_DELAY_MS, one hover timing in the app), leaving it closes after a short grace unless the pointer moves into the panel, which stays open while hovered so its text can be selected and a link in it clicked. A click pins it open (a second click, an outside click, Esc or a scroll closes it), which is also the whole story on touch, where pointerType filters hover out. The keyboard toggles with Enter/Space; focus alone opens nothing, or tabbing through a form full of "?" would spray panels. Anything new that reveals a floating panel on hover uses the same hook rather than its own timers — and never a data-tooltip on the trigger, since the panel is the hover content. HelpFold stays a click: it is inline flow, and a fold that opened under a passing pointer would shove the page around.

Both are collapsed by default, both are real <button>s with aria-expanded and aria-controls, and both fold the subject into the accessible name ("More info: Vault") rather than repeating it, so a "?" inside a heading does not make that heading announce its own title twice. The fold's visible text is a prefix of that name, so "label in name" holds.

test/disclosure-anchor.test.ts enforces the rule: it parses the real JSX with the TypeScript parser and fails, naming file and line, on any InfoPopover with no title among its preceding siblings. Extend TITLE_ELEMENTS there if you add a component whose job is to be a title.

The HTML trap this forces. A <button> is a labelable element, and a wrapping <label> names its first labelable descendant — so a "?" nested inside Field's usual <label> would silently retarget the field's title from the input to the button. Field therefore has two layouts: without info it wraps in <label>; with info it splits the title out and associates it by htmlFor, which is why the control needs an id. The UI package's test/field.test.ts guards this.

Icons

One renderer: GlyphIcon from @prismshadow/penguin-ui. A 24×24 path stroked at the theme's --ui-icon-stroke (1.7 in Primer), stroke="currentColor", fill="none" (or filled for an "on" state); pass decor="nav|group|menu|empty" only where a label beside it already says what it says. Do not hand-write an <svg> or a const *_ICON = "M…" for a line icon — the paths live in one registry, ICONS (packages/ui/src/components/icons/icons.ts), keyed by the drawing (robot, alarmClock), and the app's manifests say which drawing stands for what (lib/nav-icons.ts, lib/stat-icons.ts, GROUP_MODE_ICONS). A new glyph is a registry entry; test/icon-registry.test.ts holds the feature files' leftovers to a shrinking list.

A glyph says what the state means, not a metaphor that happens to fit. "Keep this out of the fold" is a favorite: ICONS.star, outline when off, filled when on (nav entries and model groups, owner 2026-10-03, after a lock read as permission or secrecy). A pin is a Session pinned to the top of its list. A lock means access or secrecy and nothing else. A new glyph needs an entry in every theme's set — the line path, an Octicon, a 16×16 pixel grid and a duotone tint — and filled reads each set's filled table, so one key covers both states.

Two marks deliberately live off that grid, because a two-stroke mark aliases when its grid and its render size disagree: ChevronDown (12×12, stroke 1.5) and CloseIcon (14×14, stroke 1.5). Charts, sparklines, the topology view, the ring gauges and the login background draw their own geometry and are outside the family entirely.

Sizes come from ICON_SIZE (packages/ui/src/icon-scale.ts), named by role, not by number — inlineGlyph 13, rowLead 14, iconButton / groupHeaderGlyph 15, navRow / groupHeaderAction 16, groupHeaderAvatar / sectionMark 18, chevron 14 / chevronDense 12, caret 12 / caretDense 10. Pick the rung whose role matches; if none does, the honest move is to add a rung with a sentence saying what it is for, not to type a bare number. An avatar sits one rung above a line glyph in the same slot, because a tile fills its box and a glyph only draws inside it.

Gaps come from ICON_GAP in the same module and track text size: tight (gap-1) for a glyph welded to a number, row (gap-1.5) for a list row, menu (gap-2) for menu/nav rows and banners, card (gap-3) for a card row led by an avatar.

test/icon-scale.test.ts fails on a stroke weight outside the chosen set and on a second copy of the caret, the close cross or the collapse chevron.

Control sizes

One record: sizeTextClass in the UI package's components/forms/input/input.tsx. Two rungs — sm is text-xs, base is text-base — and sizeClass pairs each with its padding. Select's menu rows, OptionMenu's row titles, Textarea and FormPicker all read it, so a rung moves the whole family at once.

The rungs are relative, not the pixel values their names suggest. FONT_SCALE_PX (in @prismshadow/penguin-ui/boot, applied before first paint and by theme.tsx) sets the root font size per tier (16/18/20px, default 18) and no stylesheet overrides a --text-*, so text-xs is 13.5px at the default tier rather than 12px, and every rung tracks the user's setting.

A call site passes size; it never spells a text-* class. The caller's class and the component's own rung are both single-class font-size utilities of equal specificity, so which one wins depends on the order the CSS was generated in, not the order of classes in the string: the built sheet emits .text-base before .text-sm before .text-xs, so a caller's text-sm silently loses to an sm control's text-xs, and a bracket value beats all three. (input.tsx's errorClass meets the same hazard on the border and the focus ring and forces past it with !. A font size has a size prop instead, so it does not need to.)

No text-[Npx] on a control: fixed px opts it out of the user's font-size setting altogether. There is no exception: an OptionMenu row's description at the sm tier shares the text-xs rung with its title (there is no rung below it) and stands apart by its muted ink (rowDescClass).

A form field takes sm: dense forms, dialogs and filter bars, which is near enough the whole app. base is for a standalone page holding two controls and nothing else, and is passed by name — the login card is its only caller, and an unopted base is what four dialog fields had drifted into. Every control defaults to sm so a forgotten prop lands where its neighbours already are (the old base default put it at the roomiest rung in the densest place), but name the rung anyway — all 112 call sites do, and the default is the safety net, not the habit. The two full-height typing surfaces are outside the family entirely: the chat composer is text-base because it holds prose, the file editor font-mono text-xs because it holds code.

A button takes the rung of whatever it stands beside. Button defaults to md (text-sm px-3 py-1.5), the page rung, and that is for an action standing on its own: an empty state's, the login card's submit, a list's "add a custom model". Wherever a button sits next to form controls it takes theirs — sm:

• a Modal footer, on every button, as ConfirmModal always did. Modal owns the footer's wrapper but not the buttons inside it, so this cannot be set in one place.
• a dialog body, next to the fields it belongs with. The settings dialog's pages are separate modules and nothing in one says it renders inside a Modal, which is how four of them kept the md default and stood a rung above their own fields.
• a page header's toolbar that also holds a search box. The Models and Agents headers pair an Input size="sm" with a size="sm" action in the same min-w-0 flex-1 sm:w-56 sm:flex-none shape; a md button beside a sm box reads as a mistake rather than as emphasis.

test/control-size.test.ts parses the JSX and fails, naming file and line, on a font-size class in a className passed to Input / Textarea / Select / OptionMenu / PasswordInput / FormPicker, on a Modal footer Button that does not ask for sm, on a Button in one of the declared dialog-body modules (DIALOG_BODY_MODULES, the settings dialog's pages) that does not ask for sm, and on a font size spelled in a control module outside the two records. Its reach is what a parser sees without types: a footer handed over as a component or built in a variable, and a dialog body outside those declared modules, follow the same rule but are on you. Adding a module to DIALOG_BODY_MODULES is how a new settings page joins the check.