@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/shell/FToolbarActions.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+// A view's own controls, placed at the right-hand end of the section's toolbar.
+//
+//   <FToolbarActions>
+//     <UButton label="Recentre" @click="recentre" />
+//   </FToolbarActions>
+//
+// A console section owns its navigation and renders it once, in the route that owns the section. Its
+// VIEWS own their actions. The two are siblings in that route's template — toolbar beside the router
+// view — so a view cannot fill the toolbar's slots, and provide/inject cannot cross siblings either.
+// What both sit inside is the SHELL, so the shell carries the ref and this teleports into it.
+//
+// These land in the FIRST toolbar to claim the seam, which is not necessarily the nearest bar in the
+// markup: on a section stacking a nav row over a filter row that is the NAV row, and a view writing
+// its own second bar still sends its actions up to the section's.
+//
+// Renders where it was written when no toolbar has claimed the seam. A page whose actions vanished
+// silently is broken in a way nobody notices; controls appearing somewhere odd say so immediately.
+import { computed, inject } from 'vue';
+import { TOOLBAR_SEAT_KEY } from './shell';
+
+const seat = inject(TOOLBAR_SEAT_KEY, null);
+const target = computed(() => seat?.actions.value ?? null);
+</script>
+
+<template>
+  <!-- `disabled` rather than v-if, so the slot still renders with no toolbar above. Teleport wants a
+       valid `to` even when disabled, hence the body fallback. -->
+  <Teleport :to="target ?? 'body'" :disabled="!target">
+    <slot />
+  </Teleport>
+</template>

package/packages/ui/src/shell/index.ts

@@ -0,0 +1,33 @@
+// The Forest app shell — the chrome AROUND a page, and the toolbar seat a page can reach into.
+//
+//   <FAppShell>       sidebar + header + the inset card the page lives in
+//   <FAppSidebar>     the brand mark, the nav and the collapsed rail — the app supplies the list
+//   <FAppNavbar>      the rail control and the crumb — the app supplies the crumb and its actions
+//   <FScrollShadow>   the overflow signal for a column whose scrollbar is hidden — the sidebar's
+//   <FSidePanel>      a column belonging to a CONTAINER rather than the app — settings sub-nav, or a
+//                     filter/list panel over a canvas. Not the app rail; see the component's own note.
+//   <FPageToolbar>   the page's filters, view controls or sub-route nav, flush at the top of the card
+//   <FToolbarActions> a view's own controls, placed at the right of the section's toolbar
+//   TOOLBAR_SEAT_KEY   the injection carrying the toolbar seat; exported for a custom shell
+//   createToolbarClaims the claim ordering behind a seat's actions, for a shell of one's own
+//
+// The look of every region is theme fragments (themes/dashboard-*.ts), not this component — what
+// lives here is the ARRANGEMENT: chrome outside the card, and a way for a page to reach it.
+export { default as FAppShell } from './FAppShell.vue';
+export { default as FAppSidebar } from './FAppSidebar.vue';
+export { default as FAppNavbar } from './FAppNavbar.vue';
+export { default as FScrollShadow } from './FScrollShadow.vue';
+export { default as FSidePanel } from './FSidePanel.vue';
+export {
+  CANVAS_INSET_VAR,
+  SIDE_PANEL_WIDTH,
+  sidePanelInsetPx,
+  type SidePanelBehaviour,
+  type SidePanelSide,
+  type SidePanelSize,
+} from './sidePanel';
+export { createToolbarClaims, TOOLBAR_SEAT_KEY, type ToolbarClaims, type ToolbarSeat } from './shell';
+export type { FNavItem, FNavGroup, FCrumb } from './nav';
+export { default as FPageToolbar } from './FPageToolbar.vue';
+export { type PageToolbarWell } from './pageToolbar';
+export { default as FToolbarActions } from './FToolbarActions.vue';

package/packages/ui/src/shell/nav.ts

@@ -0,0 +1,37 @@
+/**
+ * A navigable destination in the app shell's sidebar.
+ *
+ * Deliberately thin. It carries what a row NEEDS to draw itself and nothing about where the list came
+ * from — an app's own nav tree (routes, a manifest, a permissions filter) maps onto this rather than
+ * the shell prescribing a shape for it.
+ *
+ * `to` is optional on purpose: an entry with no destination renders disabled and badged rather than
+ * being dropped, so a system that is still growing reads as intentional instead of missing.
+ */
+export type FNavItem = {
+  label: string;
+  /** Any icon name the app's icon set resolves. */
+  icon?: string;
+  /** Omit for a destination that does not exist yet — the row renders disabled. */
+  to?: string;
+  /** Flags the row as work in progress; it still links. */
+  wip?: boolean;
+};
+
+/** A labelled section of the sidebar. The label heads the group when expanded. */
+export type FNavGroup = {
+  label: string;
+  items: FNavItem[];
+};
+
+/**
+ * A step in the header's crumb — `group · page`.
+ *
+ * `to` is optional and usually absent: a crumb says where you are, and the group half of `group ·
+ * page` is a section of the nav rather than a route. A step that genuinely is a destination can
+ * carry one.
+ */
+export type FCrumb = {
+  label: string;
+  to?: string;
+};

package/packages/ui/src/shell/pageToolbar.ts

@@ -0,0 +1,69 @@
+/**
+ * Which well rung <FPageToolbar> aligns its controls to.
+ *
+ * A toolbar bleeds to the card's edge so its hairline reads as a rule across the whole card, but its
+ * CONTROLS have to line up with the page content below — on a 1720px card those are 252px apart. The
+ * rung must therefore match the page body's own well, which is why the page states it.
+ *
+ * There is no `flush` rung, and that is a judgement rather than an omission. The body's `.well-flush`
+ * exists so a CANVAS reaches the panel edge, and a canvas has no content start to line up with — so
+ * the alignment this prop is for does not arise. Controls also want their gutter whether or not the
+ * surface beneath them does: a filter jammed against the card's edge reads as broken. A canvas page's
+ * toolbar takes `full` — cap released so it spans the card, gutters kept so the controls can breathe.
+ */
+
+export type PageToolbarWell = 'default' | 'reading' | 'full';
+
+const WELLS: Record<PageToolbarWell, string> = {
+  default: '',
+  reading: 'well-reading',
+  full: 'well-full',
+};
+
+export function pageToolbarWellClass(well: PageToolbarWell): string {
+  return WELLS[well];
+}
+
+/**
+ * How the toolbar draws itself.
+ *
+ * `rule` — full-bleed, a hairline across the whole card, no fill. The default, and what a navigation
+ * row wants: it reads as part of the card's chrome.
+ *
+ * `card` — an inset panel: filled, rounded, and clear of all four edges. What a FILTER row wants,
+ * because a row of applied clauses is state the page is currently in rather than chrome, and it needs
+ * to read as a thing sitting on the surface. Linear's shape, and a page mixes the two — navigation on
+ * a rule, filters on a card beneath it.
+ *
+ * The fill alone does NOT carry this. Measured against the card behind it, `bg-muted` is 0.020
+ * luminance in light against 0.060 in dark — which is why a plain tint was probed for this row once
+ * before and rejected as imperceptible in light. What makes the panel read is the RADIUS and the
+ * INSET, which are geometry and behave the same in both modes; the ring gives it an edge of its own.
+ */
+export type PageToolbarVariant = 'rule' | 'card';
+
+export type PageToolbarSurface = {
+  /** Goes on UDashboardToolbar's root, which is the full-bleed layer. */
+  root: string;
+  /** Goes on the flex row inside the well, which is the layer that becomes the panel. */
+  row: string;
+};
+
+const SURFACES: Record<PageToolbarVariant, PageToolbarSurface> = {
+  rule: { root: '', row: '' },
+  // `border-b-0` cancels stock's rule: a panel with a line under it reads as neither one nor the
+  // other. `py-2` is the inset — the well's own gutter already handles the horizontal.
+  //
+  // The ring is MODE-SPLIT, and measured rather than guessed. Against this panel's own `bg-muted`
+  // fill, `ring-default` is 0.072 luminance apart in light but EXACTLY EQUAL in dark (both 0.1497) —
+  // an edge that simply is not there. `ring-accented` clears it by 0.099. Neither token works in both
+  // modes, which is the same collapse the docs code blocks split their frame for.
+  card: {
+    root: 'border-b-0 py-2',
+    row: 'rounded-md bg-muted ring ring-default dark:ring-accented px-2 py-1.5',
+  },
+};
+
+export function pageToolbarSurface(variant: PageToolbarVariant): PageToolbarSurface {
+  return SURFACES[variant];
+}

package/packages/ui/src/shell/shell.ts

@@ -0,0 +1,74 @@
+import { computed, ref, type InjectionKey, type Ref } from 'vue';
+
+/**
+ * The seat <FAppShell> hands down to <FPageToolbar>.
+ *
+ * An element, not a selector string. A shipped component cannot own a global id — two shells on one
+ * page would collide, and a page teleporting by selector has to guess a name the shell happens to
+ * render. Injection also gives the "no shell above me" case for free: `inject` returns null and the
+ * toolbar renders where it was written instead.
+ */
+export type ToolbarSeat = {
+  /**
+   * Inside the panel, at the top of the inset card and ABOVE the page's own scrollport, so a toolbar
+   * holds while the page scrolls under it.
+   */
+  toolbar: Ref<HTMLElement | null>;
+  /**
+   * The right-hand end of the FIRST CLAIMANT's well, filled by <FToolbarActions>.
+   *
+   * The SHELL holds this although the TOOLBAR sets it: a section renders its toolbar and its router
+   * view as siblings, so a view's actions cannot inject from the toolbar — provide/inject walks the
+   * component parent chain and cannot cross siblings. Only something above both can carry it.
+   *
+   * Derived from the claimants rather than assigned, so that a section stacking a nav row over a
+   * filter row keeps the nav row's seam while it is there, and PROMOTES the survivor if it goes.
+   * Null only when no toolbar is mounted at all.
+   */
+  actions: Readonly<Ref<HTMLElement | null>>;
+  /** Called by <FPageToolbar> whenever it appears — mounted, or reactivated inside <KeepAlive>. */
+  claimActions: (el: HTMLElement) => void;
+  /**
+   * Called by <FPageToolbar> whenever it goes — unmounted, or deactivated inside <KeepAlive>.
+   * Promotes the next claimant if this one was first.
+   */
+  releaseActions: (el: HTMLElement) => void;
+};
+
+export const TOOLBAR_SEAT_KEY: InjectionKey<ToolbarSeat> = Symbol('forest-toolbar-seat');
+
+/** The claimant list a seat's `actions` is derived from, plus the two functions that move it. */
+export type ToolbarClaims = Pick<ToolbarSeat, 'actions' | 'claimActions' | 'releaseActions'> & {
+  /** Every claimant, in claim order. `actions` is the first of them. */
+  claimants: Ref<HTMLElement[]>;
+};
+
+/**
+ * Builds the claim state behind a seat.
+ *
+ * <FAppShell> provides one of these, and so does the docs preview that stages a toolbar inside a
+ * frame rather than in the real card. Both owe a page the same ordering, so the ordering lives here
+ * and neither restates it.
+ *
+ * Spread the three seat keys alongside a `toolbar` ref to make a {@link ToolbarSeat}; `claimants` is
+ * the list itself, held out so the order can be read directly.
+ *
+ * Both functions are idempotent — claiming a toolbar already in the list changes nothing, and so
+ * does releasing one that is not in it. A toolbar that claims twice for one appearance, or releases
+ * twice for one departure, still leaves the list right.
+ */
+export function createToolbarClaims(): ToolbarClaims {
+  const claimants = ref<HTMLElement[]>([]);
+  const actions = computed(() => claimants.value[0] ?? null);
+
+  const claimActions = (el: HTMLElement) => {
+    if (!claimants.value.includes(el)) claimants.value.push(el);
+  };
+
+  const releaseActions = (el: HTMLElement) => {
+    const i = claimants.value.indexOf(el);
+    if (i !== -1) claimants.value.splice(i, 1);
+  };
+
+  return { claimants, actions, claimActions, releaseActions };
+}

package/packages/ui/src/shell/sidePanel.ts

@@ -0,0 +1,115 @@
+/**
+ * FSidePanel's measures, and the one calculation anything outside it needs.
+ *
+ * ★ WHY THIS IS A MODULE AND NOT TWO NUMBERS IN A COMPONENT. An overlay panel covers a strip of the
+ * surface it floats on, and three separate things have to agree on how wide that strip is:
+ *
+ *   · the panel, which draws it;
+ *   · the map camera, whose `padding` keeps it clear so a flyTo does not centre underneath the panel;
+ *   · the canvas HUD, whose rails on that edge shift over rather than hiding behind it.
+ *
+ * The first two are the ones that drift: the panel is CSS and the camera is JS, so they cannot read one
+ * value unless something like this exists. (The HUD is reached through a custom property instead — see
+ * CANVAS_INSET_VAR.) This module is that one value, and `sidePanelInsetPx` is the only correct way to
+ * turn a size into the camera's number.
+ */
+
+/** The two rungs. A free `width` prop is deliberately not offered — see SIDE_PANEL_WIDTH. */
+export type SidePanelSize = 'md' | 'lg';
+
+/**
+ * Which edge of its container the panel takes, in logical directions.
+ *
+ * `end` is the default: a panel is secondary chrome inside a shell whose own rail already holds the
+ * start edge, so start would stack two columns on one side. `start` is for the case where the panel is
+ * the navigation for its view — a settings sub-nav.
+ */
+export type SidePanelSide = 'start' | 'end';
+
+/**
+ * Does the content beside it move over, or does the panel lie on top of it?
+ *
+ *   push     the panel is a flow item — a settings sub-nav, a dashboard filter column. The page beside
+ *            it is narrower while it is open.
+ *   overlay  the panel is absolutely positioned over the surface — a filter or list panel on a map. The
+ *            canvas keeps its full size and the panel covers a strip of it.
+ */
+export type SidePanelBehaviour = 'push' | 'overlay';
+
+/**
+ * ★ TWO RUNGS, NOT A NUMBER. A panel's width is a system decision, not a per-page one: two panels a
+ * click apart at 320 and 344 read as a bug, and nothing in a usage site can see the other panel to stay
+ * consistent with it.
+ *
+ *   md   17rem — the same measure as the canvas HUD's wide rail (--forest-canvas-rail-top), so a panel
+ *        and a rail card on the same canvas line up rather than nearly lining up.
+ *   lg   22rem — for a list of rows, where md leaves a row's secondary text with nowhere to go.
+ *
+ * Both are also expressed in px because the camera's `padding` is a JS number and rem is not.
+ */
+export const SIDE_PANEL_WIDTH: Record<SidePanelSize, { css: string; px: number }> = {
+  md: { css: '17rem', px: 272 },
+  lg: { css: '22rem', px: 352 },
+};
+
+/**
+ * The gutter an overlay panel floats in, matching the HUD's own chrome gutter (--forest-chrome-gutter,
+ * 1rem). Duplicated here as a number for the same reason the widths are: the camera cannot read a custom
+ * property. The static test asserts the two stay equal.
+ */
+export const SIDE_PANEL_GUTTER_PX = 16;
+
+/**
+ * The strip an OVERLAY panel covers, in px — what `<FMap :padding>` should keep clear on that edge.
+ *
+ *   gutter + panel + gutter
+ *
+ * Both gutters count HERE, and only here: the outer one is the space between the panel and the canvas
+ * edge, the inner one is clearance. A camera inset of just the panel's width parks a marker flush
+ * against the panel's edge, which reads as "hidden behind it" even though it is not. Chrome does not
+ * want that second gutter — it brings its own — so CANVAS_INSET_VAR publishes one gutter fewer.
+ *
+ * Returns 0 when the panel is closed, so a usage site is one expression rather than a branch:
+ *
+ *   :padding="{ right: sidePanelInsetPx('lg', open) }"   // key matches the panel's side
+ */
+export const sidePanelInsetPx = (size: SidePanelSize, open = true): number =>
+  open ? SIDE_PANEL_WIDTH[size].px + SIDE_PANEL_GUTTER_PX * 2 : 0;
+
+/**
+ * The custom property an overlay panel declares on its container so <FCanvasHud> insets its rails on
+ * that edge. The HUD adds it to the safe-area inset it already keeps clear, so a panel and a device
+ * notch compose instead of one overwriting the other.
+ *
+ * ★ ITS VALUE IS NOT `sidePanelInsetPx`, and the difference is deliberate. This publishes the strip the
+ * panel OCCUPIES (outer gutter + width); the camera's number adds a second gutter of clearance. The
+ * HUD's areas already carry the chrome gutter as internal padding, so a trailing gutter here lands
+ * twice — measured, it left a 32px trough between the panel and the first rail item where every other
+ * pair of chrome on that canvas shares 16.
+ *
+ * A property rather than a prop because the HUD and the panel are siblings, not parent and child: the
+ * panel cannot pass anything to the HUD, but it can declare on the ancestor they share.
+ *
+ * ★ PHYSICAL sides, because what they are added to is physical: `env(safe-area-inset-*)` describes a
+ * notch, which does not move under RTL. The panel's own `side` is logical and maps to these here — the
+ * one place that mapping would have to become direction-aware if an RTL surface ever ships.
+ */
+export const CANVAS_INSET_VAR = {
+  start: '--forest-canvas-inset-left',
+  end: '--forest-canvas-inset-right',
+} as const satisfies Record<SidePanelSide, string>;
+
+/**
+ * How long the panel's own travel takes, published alongside the inset.
+ *
+ * ★ THE INSET WITHOUT THE DURATION IS WORSE THAN NEITHER. Everything that follows an open panel — the
+ * HUD's rails, the map's camera — otherwise moves in ONE frame while the panel glides for 240ms: three
+ * things responding to one gesture, only one of them animated. That reads as the panel being smooth and
+ * everything else being broken.
+ *
+ * Published rather than assumed because the panel's travel is ASYMMETRIC (a fast exit, a slower enter),
+ * so a follower that hard-coded one duration would lag on the way out. Written as a resolved time
+ * (`240ms`), not a `var()` reference, because one of the readers is JS: Mapbox's camera takes a number,
+ * and it cannot resolve a token itself.
+ */
+export const CANVAS_INSET_DURATION_VAR = '--forest-canvas-inset-duration';

package/packages/ui/src/themes/accordion.ts

@@ -0,0 +1,36 @@
+/**
+ * Forest theme fragment — UAccordion (collapsible sections).
+ *
+ * Forest opinions applied:
+ *   - `trigger`: font-bold on the trigger label (stock is font-medium) — lifts the section heading
+ *     above body copy in the two-weight type system; adds a brand focus ring using the forest-500
+ *     ramp var so tab navigation is clearly visible. Stock's `outline-primary/25` resolves correctly
+ *     but we anchor to the ramp directly for determinism across all consumer surfaces.
+ *   - `item`: the default border-b divider is retained (it reads cleanly); no radius override needed
+ *     at the item level — the root container carries any shell radius from the consumer.
+ *   - `body`: text-sm is stock; we add text-muted so body copy reads at the Forest semantic muted
+ *     level (slightly softer than text-default), keeping content subordinate to the trigger label.
+ *   - `content` / `trailingIcon`: the height animation and the chevron rotate move onto the shared
+ *     motion tokens (stock is a raw 200 ms both). The accordion runs the same keyframe pair as the
+ *     collapsible, so it takes the same timing — --motion-slow for the height travel — and the
+ *     chevron, a small near element, takes --motion-fast.
+ *
+ * Slots touched: trigger, body, content, trailingIcon.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/accordion.ts
+ */
+
+export const accordionTheme = {
+  slots: {
+    // font-bold: clear heading hierarchy; focus ring pinned to forest-500 ramp var for
+    // dark-mode correctness (stock outline-primary resolves correctly but we anchor to the ramp
+    // directly for determinism across all consumer surfaces).
+    trigger: 'font-bold focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-forest-500)]',
+    // text-muted: subordinates body content below the trigger label in the Forest reading hierarchy.
+    body: 'text-muted',
+    // Height travel on --motion-slow, matching the collapsible (same keyframes, same bucket).
+    content:
+      'data-[state=open]:animate-[accordion-down_var(--motion-slow)_var(--motion-ease-out)] data-[state=closed]:animate-[accordion-up_var(--motion-slow)_var(--motion-ease-out)]',
+    // Chevron rotate — a small near element, so --motion-fast.
+    trailingIcon: 'duration-(--motion-fast) ease-(--motion-ease-out)',
+  },
+} as const;

package/packages/ui/src/themes/alert.ts

@@ -0,0 +1,16 @@
+/**
+ * Forest theme fragment — UAlert (inline message banner, all intents).
+ *
+ * Deltas only — the preset APPENDS to stock, so restating stock's layout classes would only invite
+ * drift. One change:
+ *   - `title`: font-bold (over stock font-medium) — clear hierarchy above the description
+ *     without font-bold, which is too heavy for inline copy.
+ * Everything else (root layout/radius, text-sm, description opacity-90, icon/actions/close) is stock.
+ * The bold contexts round the banner corner up to rounded-xl (mobile/marketing).
+ */
+
+export const alertTheme = {
+  slots: {
+    title: 'font-bold',
+  },
+} as const;

package/packages/ui/src/themes/auth-form.ts

@@ -0,0 +1,19 @@
+/**
+ * Forest theme fragment for UAuthForm.
+ *
+ * UAuthForm ships the contents of a sign-in screen — fields, provider buttons, the separator — and
+ * takes its title and description sizes from Tailwind's default scale (`text-xl` and `text-base`)
+ * rather than from Forest's. That is a second type ladder running beside the real one and drifting the
+ * moment the real one moves. Both slots move onto the ladder: `.type-title` and `.type-body`, which
+ * carry size, line-height, tracking and family together.
+ *
+ * Weight was never the problem — `styles/forest.css` remaps `--font-weight-semibold` to 700 in
+ * `@theme`, so stock's `font-semibold` already lands on a cut the brand fonts ship.
+ */
+
+export const authFormTheme = {
+  slots: {
+    title: 'type-title',
+    description: 'type-body',
+  },
+};

package/packages/ui/src/themes/avatar-group.ts

@@ -0,0 +1,9 @@
+/**
+ * Forest theme fragment — UAvatarGroup. No delta: the stock recipe is correct as-is.
+ *
+ *   - The overlap ring is ring-bg (surface-coloured), so it adapts to light/dark and to tinted
+ *     surfaces through the semantic token — nothing to re-point.
+ *   - Shape and sizing ride UAvatar, which carries the Forest opinion in its own fragment.
+ */
+
+export const avatarGroupTheme = {} as const

package/packages/ui/src/themes/avatar.ts

@@ -0,0 +1,18 @@
+/**
+ * Forest theme fragment — Avatar / AvatarGroup
+ *
+ * Deltas only (the preset APPENDS to stock, so this carries just what changes):
+ *   - root:     `font-bold` — confident initials; stock root is unweighted.
+ *   - fallback: `font-bold` — stock is `font-medium`, which reads thin at xs/2xs on the tint fills.
+ *
+ * Everything else is stock and correct: rounded-full shape, the /10 colour-ramp fills
+ * (bg-{color}/10 · text-{color}, wired to the Forest ramps in docs.css), the 3xs–3xl ladder,
+ * `object-cover rounded-[inherit]` images, and the AvatarGroup `ring-bg` separator. AvatarGroup
+ * needs no override.
+ */
+export const avatarTheme = {
+  slots: {
+    root: 'font-bold',
+    fallback: 'font-bold',
+  },
+} as const;

package/packages/ui/src/themes/badge.ts

@@ -0,0 +1,51 @@
+/**
+ * Forest theme fragment for UBadge.
+ *
+ * Standard badge is a soft-cornered tag (rounded-sm/8px), not a pill: rectangular enough to
+ * read as a label on a data-dense web surface. Bold, uppercase, wide-tracked lettering is the
+ * Forest opinion at every scale; the bold contexts round it to a full pill (mobile/marketing).
+ *
+ * Stock UBadge sets the corner PER SIZE (rounded-sm on xs/sm, rounded-md on md/lg/xl), and tv
+ * applies the size variant after the base slot — so `rounded-sm` in base alone would lose to
+ * stock's rounded-md at md/lg/xl. Follow stock's shape: override the corner in the size
+ * variants (tv deep-merges variants, tailwind-merge collapses the per-size token). The Forest
+ * ladder tightens toward the small end: xs/sm rounded-xs, md/lg/xl rounded-sm. The base copy
+ * (rounded-sm) is the representative Standard value the derived contexts card reads.
+ */
+
+export const badgeTheme = {
+  slots: { base: 'rounded-sm font-bold uppercase tracking-wide' },
+  variants: {
+    // Per size: the Forest radius override (see comment above) PLUS a `coarse:` touch bump.
+    // Under a coarse primary pointer each size renders as the NEXT SIZE UP — the full bundle
+    // (text, padding, gap, radius, icon), so a touched md badge reads like an lg badge. Unlike
+    // the button this is legibility, not a tap target (a badge is static) — a chip at arm's
+    // length on a phone wants the bigger step. `coarse:` is the custom variant in
+    // styles/forest.css: it fires only on a coarse pointer AND skips `.cut-fixed` elements, so
+    // the mobile cut (which bakes its own increase and stamps cut-fixed) opts out and doesn't
+    // double-promote; marketing has no cut-fixed, so it adapts like standard. xl is the ceiling.
+    size: {
+      xs: { base: 'rounded-xs coarse:text-[10px]/3 coarse:px-1.5 coarse:py-1' },
+      sm: {
+        base: 'rounded-xs coarse:text-xs coarse:px-2 coarse:rounded-sm',
+        leadingIcon: 'coarse:size-4',
+        trailingIcon: 'coarse:size-4',
+      },
+      md: {
+        base: 'rounded-sm coarse:text-sm coarse:gap-1.5',
+        leadingIcon: 'coarse:size-5',
+        trailingIcon: 'coarse:size-5',
+      },
+      lg: {
+        base: 'rounded-sm coarse:text-base coarse:px-2.5',
+        leadingIcon: 'coarse:size-6',
+        trailingIcon: 'coarse:size-6',
+      },
+      xl: { base: 'rounded-sm' },
+    },
+  },
+  // A badge labels something; it does not ask to be pressed. Subtle (tinted fill + inset ring)
+  // rather than stock's solid, which reads as a control. Being ringed, it also carries the bold
+  // contexts' 2px edge.
+  defaultVariants: { variant: 'subtle' },
+} as const

package/packages/ui/src/themes/banner.ts

@@ -0,0 +1,21 @@
+/**
+ * Forest theme fragment — UBanner.
+ *
+ * Deltas only (the preset appends to stock, so nothing stock is restated):
+ *   • title  — steps up to font-bold so the copy holds against every solid brand fill, and
+ *              takes `me-auto` to shove the actions to the far right.
+ *   • layout — Forest reads the strip as title-LEFT / actions-RIGHT. Stock centres the title
+ *              between two flex-1 spacers (left/right) with the actions beside it; we drop those
+ *              spacers (`lg:flex-none`) and let the centre grow (`flex-1`) so the actions land at
+ *              the end of the row, just before the close button.
+ * The banner has no radius by design — it spans the viewport edge to edge.
+ */
+
+export const bannerTheme = {
+  slots: {
+    left: 'lg:flex-none',
+    center: 'flex-1',
+    title: 'font-bold me-auto',
+    right: 'lg:flex-none',
+  },
+} as const;

package/packages/ui/src/themes/breadcrumb.ts

@@ -0,0 +1,10 @@
+/**
+ * Forest theme fragment — UBreadcrumb. No delta: the stock recipe is correct as-is.
+ *
+ *   - Inactive crumb text-muted with hover:text-default, active crumb font-semibold (bold via
+ *     the two-weight re-map), per-colour focus ring, text-muted separator — all right by default.
+ *   - In a two-weight system there is no intermediate label weight to seat, so the crumb ladder
+ *     is regular → bold exactly as stock wires it.
+ */
+
+export const breadcrumbTheme = {} as const