Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

13.7 KB
Raw Blame
/**
 * The style hooks: the closed list of `ui-*` classes a component may carry so that a theme can
 * give it a treatment tokens cannot express (a backdrop blur, a ruled frame, a stepped animation,
 * a colour field behind the app window, connector rules between nested rows).
 *
 * A hook names a job, never a look. The component carries the class, and each theme file decides
 * in `@layer ui-theme` what the hook does, which may be nothing: Primer's `.ui-glass` and
 * `.ui-shell` are no-ops. The layer sits after Tailwind's `utilities`, so a recipe beats the
 * utilities its host also carries.
 *
 * Only the names below exist. A `ui-*` class outside this list is a decoration without a job, and
 * the package's de-slop guard fails it. Adding a hook is a design change: add it here, give it a
 * recipe (or a documented no-op) in every theme file, and list its allowed hosts.
 *
 * | hook               | the job                                                  | anatomy the recipes rely on                           |
 * | ------------------ | -------------------------------------------------------- | ----------------------------------------------------- |
 * | `ui-glass`         | a transient layer over content: menus, popovers, the     | —                                                     |
 * |                    | modal card, the floating composer and launcher, a sticky |                                                       |
 * |                    | page header                                              |                                                       |
 * |                    | hosts: `ComposerCard` and its `SlashMenu`, `Modal`,      |                                                       |
 * |                    | `Dropdown`, the selects, popovers and tooltips           |                                                       |
 * | `ui-eyebrow`       | a group label naming the items below it (never directly  | —                                                     |
 * |                    | above an `h1`–`h4`); hosts: `Text variant="eyebrow"`,    |                                                       |
 * |                    | the sidebar's and group headers' labels                  |                                                       |
 * | `ui-display`       | the one display title of a page or hero                  | only on an `h1` or `[aria-level="1"]`                 |
 * |                    | hosts: `Heading level={1} display`, `PageHeader`'s title |                                                       |
 * | `ui-live`          | motion for something that is running right now           | `data-live="dot" \| "caret" \| "spinner" \| "bar"`   |
 * |                    | hosts: the Spinner, a pulsing Dot, the streaming caret   |                                                       |
 * | `ui-frame`         | a ruled box with a head, a body, a foot and panes        | children carry `data-slot="head" \| "body" \| "foot" \| "pane"` |
 * |                    | hosts: the transcript's cards, the code block, `Card`,   |                                                       |
 * |                    | a framed `Table`                                         |                                                       |
 * | `ui-underline-nav` | the selected-tab marker of a tab bar (a page's tabs, a   | items `[role="tab"]`, selected by `aria-selected="true"` |
 * |                    | dock's tab strip)                                        |                                                       |
 * | `ui-shell`         | the app window: a navigation column beside a main column | children carry `data-slot="nav" \| "main"` (a right column may carry `"dock"`); the selected nav row is `[aria-current="page"]` |
 * |                    | host: `AppShell`                                         |                                                       |
 * | `ui-icon-decor`    | an icon that says nothing its label does not already say | on the icon itself (or the element holding only it); optional `data-role="nav" \| "group" \| "menu" \| "empty"` |
 * |                    | hosts: the icon renderers' call sites, `NavRow`'s glyph  |                                                       |
 * | `ui-tree`          | a container whose rows nest                              | rows carry `data-depth="0"…"8"`, the last row of a level `data-last="true"`; a row's children may follow it in a `data-branch` element carrying the children's `data-depth` |
 * | `ui-field`         | a labelled control row                                   | children carry `data-slot="label" \| "control"` and optionally `"hint"` |
 * | `ui-activity`      | a step of the agent's work in the transcript: a thinking | `data-kind="thinking" \| "tool"`, `data-state="running" \| "done" \| "error"`; descendants may carry `data-slot="label" \| "detail" \| "progress" \| "mark" \| "toggle" \| "toggle-end"` (the progress slot exists only while running, hidden by the host — a recipe that draws it sets `display` itself; `mark` wraps the leading status icon; `toggle` is the fold's chevron after the words, carried to the far edge by `order-last`; `toggle-end` is a chevron button at a row's end that a theme showing `toggle` hides) |
 * |                    | row, a tool-call row, a work group's header              |                                                       |
 * | `ui-notice`        | a notice: a toast, an inline notice strip                | `data-tone="info" \| "success" \| "warning" \| "danger" \| "neutral"`; children may carry `data-slot="icon" \| "title" \| "body" \| "actions"` |
 * | `ui-chart`         | a chart's root (its `<svg>`)                             | parts carry `data-part="grid" \| "axis" \| "series" \| "area" \| "bar" \| "point" \| "label"`; a series may carry `data-series="<n>"` |
 * | `ui-scrim`         | the dimmed layer behind a dialog, drawer or sheet        | —                                                     |
 * | `ui-stream`        | the body of an assistant reply, which may still be       | `data-state="streaming" \| "done"`; while streaming, the markdown blocks are followed by the stream's edge, a direct child `data-slot="caret"`, and then by anything the host appends |
 * |                    | streaming                                                |                                                       |
 *
 * `ui-shell` is the one place a theme may paint a field of colour: Frost paints the navigation
 * column a soft grey beside a near-white main column, flat (its earlier warm field and floating
 * sheet were retired at the owner's review of 2026-09-29); Console rules the columns off each
 * other with hairlines, full bleed; Primer changes nothing — the window's look is its own
 * classes.
 *
 * The three structure hooks (2026-09-19) are how the themes differ in organisation, not only in
 * colour and radius:
 *
 * - `ui-icon-decor` marks the icons a theme may recolour or drop: a nav row's glyph, a group
 *   header's, a menu row's, an empty state's illustration — never a status mark, a file kind, a
 *   tool glyph or an avatar, which carry information and stay in every theme. Primer keeps them
 *   monochrome; Frost draws them in the muted ink (a menu row's keeps the row's own ink — a
 *   danger row keeps its red); Console hides them, so the eyebrow and the selected row's weight
 *   carry the structure and it shows far fewer icons.
 *   A call site applies it by passing `decor="<role>"` to an icon renderer (`GlyphIcon`,
 *   `Glyph`), which writes the class and `data-role` for it; the hook guard reads the prop on
 *   the call site and holds the enclosing row or header to the host list. A wrapper that holds
 *   only the icon may carry the class itself instead, so a hidden icon leaves no empty box
 *   behind in a flex row.
 * - `ui-tree` marks a list whose rows nest: a file tree, a work group's tool rows under its head,
 *   a plan's sub-steps, the subagent call graph. A host indents its rows itself, by
 *   `calc(var(--ui-tree-inset) + var(--ui-tree-indent) * depth)`, so every theme's connector
 *   rules land on the same columns; rows directly under the container's own head (a work group's
 *   tool rows) are depth 1, a tree's roots depth 0, and depths past 8 draw as 8. Console draws
 *   `├─` / `└─` connector rules in CSS (no box, no glyphs in the markup) and takes the box away
 *   from a frame whose body is a tree; Frost indents against a soft guide rule and keeps its
 *   card; Primer keeps today's bordered box. A branch is a plain block holding one level's rows
 *   right after their parent row (`<li data-depth="1">` then `<div data-branch data-depth="2">`);
 *   the recipes continue the parent's rule alongside it. Rows draw with `::before` / `::after`,
 *   so a tree row carries no pseudo-elements of its own.
 * - `ui-field` marks a labelled control row — a form field or a settings row — so a theme can
 *   lay its parts out its own way: Primer keeps the host's layout (label above in a form, label
 *   left and control right in settings); Frost keeps the host's row and sets it as a band in a
 *   soft-filled group, the block's first and last rows rounded; Console sets a tabular row with
 *   a fixed label column (`--ui-field-label-w`) and the control left-aligned in the next, so a
 *   settings page reads
 *   like a table. The hint (or error) may be its own slot or sit inside the label slot.
 *
 * `ui-activity` (2026-09-29) is how a theme renders work in progress without the component
 * knowing which theme runs. The host writes what it knows — the kind of step, its state, and
 * which descendant is the label, the detail (a path, an argument preview, a duration) and the
 * progress slot — and stays a plain row under Primer. Frost adds nothing around the row — no
 * fill, border, ring or halo, the way Codex and macOS show work in progress — and lets a soft
 * highlight in the accent's hue sweep across the label; at rest nothing is added. Console
 * renders a transcript: the label in the mono face at the small rung, uppercase and tracked,
 * muted once done and full ink while running, the detail muted, no box around the row and no
 * fill that moves between rest, hover, open and stuck (a hover changes the ink alone), and a
 * hatched block bar in the progress slot while the step runs; a step in a work group hangs off
 * the `└` its `ui-tree` row draws. Both recipes go still under reduced motion (a plain label,
 * the bar holding one fill) and read as finished at rest. The host's own status icon stays: the
 * recipes add to it, never replace it.
 *
 * `ui-notice` and `ui-chart` (2026-09-29) let notices and charts differ per theme where their
 * components had one look. A notice names its tone; Primer keeps the host's own strip, Frost
 * floats a soft card on the overlay surface with the tone as one small dot of its ink, Console
 * prints a console status line — a bracketed tone tag (`[INFO]`, `[ OK ]`, `[WARN]`, `[FAIL]`,
 * `[NOTE]`) in the tone's ink and the mono face, the message in the reading face, nothing
 * round it. A chart names its parts;
 * Primer keeps the host's drawing, Frost draws soft low-chroma series, translucent bars with no
 * outline, round joins, caps and points and a fading area, Console draws thin solid
 * bars outlined in the ink, a dashed grid on crisp pixels, axis labels as tracked mono capitals
 * and 1px stepped lines with square joins. Nearly all of that is tokens the chart primitives
 * read (`--ui-chart-*`); a recipe adds only what a token cannot say — dashes, joins and caps,
 * pixel alignment, a fade. A series keeps the colour its host gave it in every theme.
 *
 * `ui-scrim` (2026-09-30) is the backdrop a dialog, drawer or sheet dims the page with: the host
 * paints its dim from `--ui-overlay-backdrop` and carries the hook, whether the scrim is a
 * sibling behind the panel or the full-viewport overlay the panel sits in. Primer and Console
 * leave the dim as it is; Frost blurs the page behind it, the reference's frosted backdrop — a
 * backdrop filter never reaches the element's own descendants, so a panel inside the scrim stays
 * sharp. It moves only with the host's fade, so reduced motion needs nothing from it.
 *
 * `ui-stream` (2026-09-30) is how a theme shows a reply arriving. The host is the reply's body
 * (`AssistantText`): it stays `data-state="streaming"` until its paced reveal
 * (`--ui-stream-reveal` / `--ui-stream-rate`, tokens.ts) has caught up with the stream, and until
 * then renders the stream's edge — the caret slot, `StreamingCaret`, itself a `ui-live` caret —
 * as a direct child right after the markdown blocks; whatever else it holds (a stop reason, a
 * files card) comes after the caret, and the host holds those back until `done`. Primer changes
 * nothing: the host's own pulsing caret glyph stays. Frost hides the caret and lets the trailing
 * lines surface through a soft veil — a gradient from nothing to the page's colour over the last
 * three lines, with a faint glow in the accent's wash behind them — drawn only while the caret is
 * the host's last child, so the veil covers the text and never what the host appends after it;
 * on `done` the veil eases away over the reveal duration instead of snapping off. Console draws
 * the caret as a solid block cursor in the body ink, a mono cell wide, blinking in steps, and
 * runs a last paragraph in so the cursor follows its last character; nothing else moves. Under
 * reduced motion the caret holds still and Frost draws no veil.
 */
export const HOOKS = [
  "ui-glass",
  "ui-eyebrow",
  "ui-display",
  "ui-live",
  "ui-frame",
  "ui-underline-nav",
  "ui-shell",
  "ui-icon-decor",
  "ui-tree",
  "ui-field",
  "ui-activity",
  "ui-notice",
  "ui-chart",
  "ui-scrim",
  "ui-stream",
] as const;

export type HookName = (typeof HOOKS)[number];