@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/themes/command-palette.ts

@@ -0,0 +1,37 @@
+/**
+ * Forest theme fragment — UCommandPalette (searchable command list).
+ *
+ * Deltas only (the preset appends to stock Nuxt UI):
+ *   - root  — rounded-xl: a soft card boundary at the palette container; stock has no radius
+ *             (flat edges, since the palette usually lives inside a modal/drawer).
+ *   - label — font-bold + tracking-wide: group headings get brand confidence; stock is
+ *             font-semibold with no tracking.
+ *
+ * The `item` hover/active slab is stock before:rounded-md (12px) — the same shape the sidebar's nav
+ * rows carry, since UNavigationMenu's `link` takes no Forest radius delta either. A row is a row on
+ * both surfaces.
+ *
+ * Everything else (density ladder, match-mark highlight [&>mark]:text-primary, focus, close/back
+ * icons, transitions) is stock on the Forest ramps. Slot names sourced from:
+ * apps/docs/node_modules/.nuxt-ui/ui/command-palette.ts
+ */
+
+export const commandPaletteTheme = {
+  slots: {
+    root: 'rounded-xl',
+    label: 'font-bold tracking-wide',
+  },
+
+  // Touch: each result row promotes ONE size up under a coarse pointer (borrows the next size's
+  // padding / gap / type / icon) — same ladder as the menu family. The search `input` slot already
+  // ships explicit h-12+ heights so it needs no bump. xl is the ceiling; deltas only. `coarse:`
+  // carries the :not(.cut-fixed) escape so a baked mobile cut opts out.
+  variants: {
+    size: {
+      xs: { item: 'coarse:p-1.5 coarse:gap-1.5', label: 'coarse:p-1.5 coarse:gap-1.5' },
+      sm: { item: 'coarse:text-sm', label: 'coarse:text-xs', itemLeadingIcon: 'coarse:size-5', itemTrailingIcon: 'coarse:size-5', itemTrailingHighlightedIcon: 'coarse:size-5' },
+      md: { item: 'coarse:p-2 coarse:gap-2', label: 'coarse:p-2 coarse:gap-2' },
+      lg: { item: 'coarse:text-base', label: 'coarse:text-sm', itemLeadingIcon: 'coarse:size-6', itemTrailingIcon: 'coarse:size-6', itemTrailingHighlightedIcon: 'coarse:size-6' },
+    },
+  },
+} as const;

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

@@ -0,0 +1,14 @@
+/**
+ * Forest theme fragment for UContainer — deliberately EMPTY.
+ *
+ * UContainer is the WELL: the only thing in the system that caps page width. Stock's recipe is
+ * already correct for Forest — `max-w-(--ui-container) mx-auto px-4 sm:px-6 lg:px-8`, where the cap
+ * rides the `--ui-container` lever (80rem) and the gutters land on 2rem at `lg`, which is what the
+ * docs shell was already hand-typing. So there is no delta to record, only a review.
+ *
+ * The three well modes are NOT variants here: UContainer exposes no `width` prop, so a Tailwind
+ * Variants variant would have nothing to drive it. They ship instead as utilities that re-point
+ * `--ui-container` in scope — `well-reading` / `well-full` / `well-flush` in styles/forest.css.
+ */
+
+export const containerTheme = {} as const

package/packages/ui/src/themes/context-menu.ts

@@ -0,0 +1,38 @@
+/**
+ * Forest theme fragment — UContextMenu (right-click contextual menu).
+ *
+ * Forest opinions applied:
+ *   - `item`     — before:rounded-sm (8 px) — concentric one step inside the 12 px panel, giving
+ *                  the hover/active slab a natural inset. Stock is before:rounded-md.
+ *   - `label`    — font-bold + tracking-wide gives section headings confident hierarchy over item
+ *                  rows; stock is font-semibold with no tracking. Mirrors the CommandPalette label
+ *                  treatment for visual consistency across Forest menu surfaces.
+ *
+ * Slots touched: content, item, label.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/context-menu.ts
+ */
+
+export const contextMenuTheme = {
+  slots: {
+    content: 'data-[state=open]:animate-[scale-in_var(--motion-base)_var(--motion-ease-out)] data-[state=closed]:animate-[scale-out_var(--motion-fast)_var(--motion-ease-out)]',
+
+    // Item slab: before:rounded-sm (8 px) — concentric inside the 12 px panel.
+    item: 'before:rounded-sm',
+
+    // Section labels: bold weight + wide tracking — confident group hierarchy, not just slightly-bolder body.
+    label: 'font-bold tracking-wide',
+  },
+
+  // Touch: each row promotes ONE size up under a coarse pointer (borrows the next size's padding /
+  // gap / type / icon), scaling the tap slab as a unit — same ladder as DropdownMenu and the
+  // input/button family. xl is the ceiling; deltas only. `coarse:` carries the :not(.cut-fixed)
+  // escape so a baked mobile cut opts out.
+  variants: {
+    size: {
+      xs: { item: 'coarse:p-1.5 coarse:gap-1.5', label: 'coarse:p-1.5 coarse:gap-1.5' },
+      sm: { item: 'coarse:text-sm', label: 'coarse:text-sm', itemLeadingIcon: 'coarse:size-5', itemTrailingIcon: 'coarse:size-5' },
+      md: { item: 'coarse:p-2 coarse:gap-2', label: 'coarse:p-2 coarse:gap-2' },
+      lg: { item: 'coarse:text-base', label: 'coarse:text-base', itemLeadingIcon: 'coarse:size-6', itemTrailingIcon: 'coarse:size-6' },
+    },
+  },
+} as const;

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

@@ -0,0 +1,11 @@
+/**
+ * Forest theme fragment for UDashboardGroup.
+ *
+ * The group is the muted page shell the inset panels float on: bg-muted in light, the deep
+ * neutral-950 in dark (bg-muted collapses into the card surface there — the explicit step keeps
+ * shell and card separable). text-default seats the base ink for everything inside.
+ */
+
+export const dashboardGroupTheme = {
+  base: 'bg-muted dark:bg-(--ui-color-neutral-950) text-default',
+} as const

package/packages/ui/src/themes/dashboard-navbar.ts

@@ -0,0 +1,10 @@
+/**
+ * Forest theme fragment for UDashboardNavbar. No delta: the stock recipe is correct as-is.
+ *
+ *   - Height rides --ui-header-height, the hairline is border-default, the title weight is
+ *     font-semibold (bold via the two-weight re-map) — all already on Forest tokens.
+ *   - The docs shell composes its crumb and actions through the navbar's slots; that is usage,
+ *     not theme.
+ */
+
+export const dashboardNavbarTheme = {} as const

package/packages/ui/src/themes/dashboard-panel.ts

@@ -0,0 +1,18 @@
+/**
+ * Forest theme fragment for UDashboardPanel.
+ *
+ * The Forest dashboard panel is an INSET CARD, not stock's flat full-bleed column: the panel
+ * floats on the group's muted shell with a margin (--forest-panel-inset, which the app shell's bands
+ * read too so their edges track the card's), soft corners and the relative hairline
+ * (--forest-card-ring, the same translucent edge cards use). `lg:ms-0` hugs the panel against
+ * the sidebar rail on desktop so the shell reads as one composition, not two islands.
+ * `min-h-0` counters stock's min-h-svh — inside the group's fixed viewport the margins would
+ * otherwise push the panel past the bottom edge. `overflow-hidden` clips content to the
+ * rounded corners.
+ */
+
+export const dashboardPanelTheme = {
+  slots: {
+    root: 'bg-default overflow-hidden m-(--forest-panel-inset) lg:ms-0 rounded-lg ring ring-[var(--forest-card-ring)] min-h-0',
+  },
+} as const

package/packages/ui/src/themes/dashboard-resize-handle.ts

@@ -0,0 +1,35 @@
+/**
+ * Forest theme fragment for UDashboardResizeHandle (flat component, single `base` slot).
+ *
+ * A grab pill in the middle of the gutter, on hover and while dragging. Hidden at rest: the gutter is a
+ * seam between two surfaces, and anything permanent sitting in it reads as a divider rather than as a
+ * control — which is what the full-height hairline this replaces did.
+ *
+ * Short, and it fades rather than moves: the pill has to say "grab here", not draw the edge.
+ *
+ * It sits CLEAR of the panel's edge rather than centred on the handle. The handle's own box is zero-wide
+ * and lands exactly on the seam, so a centred pill straddles the card's rounded corner and reads as part
+ * of it; `right-1` backs it off into the shell where it reads as a separate control.
+ *
+ * Stock draws nothing and carries `cursor-ew-resize`, `touch-none` and a ±6px `before:` hit area. The
+ * paint is added here and the hit area is widened to hold it — see below.
+ */
+
+export const dashboardResizeHandleTheme = {
+  base: [
+    // ★ THE PILL HAS TO SIT INSIDE THE ZONE THAT REVEALS IT. Drawn to the shell side of the seam against
+    // stock's ±6px area, it fell outside: it appeared where the cursor was not, and vanished on approach.
+    // Widened leftwards only — the sidebar's links and its scroller's padding both stop 16px short of the
+    // seam and its scrollbar is `width: none`, so this reaches nothing. The right stays at stock.
+    'before:-left-3.5',
+    'after:absolute after:top-1/2 after:right-1 after:-translate-y-1/2',
+    'after:h-16 after:w-1 after:rounded-full after:bg-(--ui-text-dimmed)',
+    'after:opacity-0 after:transition-opacity after:duration-(--motion-fast)',
+    // ★ ONE-WAY DWELL. The delay rides the HOVER state only, so the pill waits half a second before it
+    // appears and leaves the instant the pointer does — the base carries no delay to revert to. A cursor
+    // crossing the seam on its way into the sidebar never summons it. `active` clears the wait so a drag
+    // that starts before the pill has arrived still shows what is being dragged.
+    'hover:after:opacity-100 hover:after:delay-(--motion-dwell)',
+    'active:after:opacity-100 active:after:delay-0',
+  ].join(' '),
+} as const

package/packages/ui/src/themes/dashboard-sidebar-collapse.ts

@@ -0,0 +1,7 @@
+/**
+ * Forest theme fragment for UDashboardSidebarCollapse. No delta: the stock recipe is correct
+ * as-is — a desktop-only (hidden lg:flex) neutral ghost button whose panel-open/close icon and
+ * behaviour come from the dashboard context.
+ */
+
+export const dashboardSidebarCollapseTheme = {} as const

package/packages/ui/src/themes/dashboard-sidebar-toggle.ts

@@ -0,0 +1,7 @@
+/**
+ * Forest theme fragment for UDashboardSidebarToggle. No delta: the stock recipe is correct
+ * as-is — a mobile-only (lg:hidden) neutral ghost button whose menu/close icon and behaviour
+ * come from the dashboard context.
+ */
+
+export const dashboardSidebarToggleTheme = {} as const

package/packages/ui/src/themes/dashboard-sidebar.ts

@@ -0,0 +1,58 @@
+/**
+ * Forest theme fragment for UDashboardSidebar.
+ *
+ * The sidebar sits directly on the group's muted shell with no divider — the inset panel's own
+ * hairline does the separating, so stock's border-e (side=left variant) is zeroed at the same
+ * variant path. The rail sizing vars and the mobile slideover are stock and ride the tokens.
+ *
+ * The rest is the COLLAPSED RAIL, which stock does not size for. These are properties of the
+ * component at collapsed-size=4, not of any one app, so they belong here rather than as a `:ui` on
+ * each consumer — every app would otherwise rediscover them by eye:
+ *
+ *   · Stock spends 16px a side, leaving 32px of content in a 64px rail — too little for an icon-sized
+ *     row to be square or centred, and narrower than the 41px logo badge. Halved here.
+ *   · The scrollbar claims another 11px, offsetting every row and the logo from the rail's centre
+ *     line; expanded, the same bar draws hard against the inset panel's edge and reads as a seam
+ *     between two surfaces meant to be one. Hidden in BOTH states: a nav column shows its overflow
+ *     by fading, not by a bar. Never via ::-webkit-scrollbar, which forces the classic wide
+ *     bar back — see the scrollbar note in styles/forest.css. The `!` is load-bearing: forest.css
+ *     sets `scrollbar-width: thin` on `*`, which otherwise wins.
+ *
+ * `data-collapsed` lives on the ROOT and the padding belongs to its children, so the root carries a
+ * `group` for header, body and footer to hang off — a footer carries account chrome, which collapses
+ * to an avatar and needs the same centre line as the rows above it. Nothing here touches the resize
+ * handle: it is a sibling element and keeps its own hit area, cursor and drag.
+ *
+ * ── The collapse travel ──
+ * Stock ships this component with no transition at all: the root is `w-(--width)` and nothing else, so
+ * 16rem → 4rem lands in one frame. USidebar DOES carry a `transition` variant, and themes/sidebar.ts
+ * re-points its timing at the motion tokens — but that is a different ui key and a different component,
+ * and the app rail never reads it. The width travel is re-declared here so the shell obeys the same
+ * doctrine: the largest movement the shell makes, starting and ending in view, so --motion-slow on
+ * --motion-ease-in-out rather than the near-element pair.
+ *
+ * ★ DRAGGING MUST OPT OUT. The resize handle writes `--width` on every pointermove, so a transition
+ * left on would run the column 240ms behind the pointer for the whole drag. Stock puts `data-dragging`
+ * on the root for exactly this, and the attribute selector out-specifies the bare utility, so the
+ * override holds whatever order Tailwind emits the two in.
+ *
+ * Reduced motion needs no gate here: the floor in the motion tokens re-declares transition-property as
+ * an allow-list of colour and opacity properties, and `width` is not in it, so the rail snaps.
+ */
+
+export const dashboardSidebarTheme = {
+  slots: {
+    root: [
+      'group transition-[width] duration-(--motion-slow) ease-(--motion-ease-in-out)',
+      'data-[dragging=true]:transition-none',
+    ].join(' '),
+    header: 'group-data-[collapsed=true]:px-2 group-data-[collapsed=true]:justify-center',
+    body: '[scrollbar-width:none]! group-data-[collapsed=true]:px-2',
+    footer: 'group-data-[collapsed=true]:px-2 group-data-[collapsed=true]:justify-center',
+  },
+  variants: {
+    side: {
+      left: { root: 'border-e-0' },
+    },
+  },
+} as const

package/packages/ui/src/themes/dashboard-toolbar.ts

@@ -0,0 +1,15 @@
+/**
+ * Forest theme fragment for UDashboardToolbar.
+ *
+ * One delta: the height. Stock hard-codes min-h-[49px], which tracks no token and sits a pixel proud
+ * of the navbar's h-(--ui-header-height). A floor rather than a fixed height, because a wrapping
+ * filter bar has to grow.
+ *
+ * Slots sourced from test/fixture/node_modules/.nuxt-ui/ui/dashboard-toolbar.ts.
+ */
+
+export const dashboardToolbarTheme = {
+  slots: {
+    root: 'min-h-(--ui-header-height)',
+  },
+} as const

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

@@ -0,0 +1,45 @@
+/**
+ * Forest theme fragment — UDrawer (drag-dismissable edge sheet).
+ *
+ * Deltas only (the preset APPENDS to stock Nuxt UI); slots touched: title, content radius.
+ *
+ *   content radius — rounder edge corners than stock's rounded-*-lg. CRITICAL: stock sets the edge
+ *             radius in COMPOUND VARIANTS (per direction + inset, e.g. `{direction:bottom, inset:false}
+ *             → content: rounded-t-lg`), which OUTRANK a base `slots.content` class in tv. A flat
+ *             `slots: { content: 'rounded-t-xl' }` was silently overridden (rendered rounded-t-lg).
+ *             So the override must live in matching compoundVariants — appended after stock's, they win
+ *             the merge. rounded-*-2xl (32px) on the four non-inset directions; the inset (floating)
+ *             cut steps stock's rounded-lg up to rounded-xl.
+ *
+ *   handle  — untouched: stock's neutral `!bg-accented` affordance. Only mobile re-colours it (warm,
+ *             to sit on that context's peach surface — mobile-theme.ts). NOTE for anyone overriding
+ *             it: stock's class is IMPORTANT and tw-merge keeps an important class alongside a plain
+ *             one of the same bucket, so an override has to be important too.
+ *
+ *   title   — text-base + tracking-tight, added to stock's font-semibold. Polishes the built-in
+ *             `title`-prop path; the #header slot (used in the docs demos) is free-form.
+ *
+ * Recipe shape sourced from apps/docs/node_modules/.nuxt-ui/ui/drawer.ts (radius = compoundVariants).
+ */
+
+export const drawerTheme = {
+  slots: {
+    title: 'text-base tracking-tight',
+  },
+  variants: {
+    // Inset (floating) cut rounds all four corners; read the same trait var.
+    inset: { true: { content: 'rounded-[var(--forest-drawer-radius)]' } },
+  },
+  // Edge radius via the --forest-drawer-radius TRAIT (forest.css :root = 1.5rem / xl, standard). The
+  // radius MUST live in compoundVariants — stock sets it there per direction+inset, beating any base
+  // slot class. But a per-CONTEXT override can't add compoundVariants (context UTheme merges only
+  // slots, and those lose to compoundVariants anyway). So the compoundVariant reads a VAR, and mobile/
+  // marketing re-point that var with a `[--forest-drawer-radius:2rem]` slot class — which rides the
+  // portal and never collides in tw-merge. Same trick as --fx-title-* on the card title.
+  compoundVariants: [
+    { direction: 'bottom', inset: false, class: { content: 'rounded-t-[var(--forest-drawer-radius)]' } },
+    { direction: 'top', inset: false, class: { content: 'rounded-b-[var(--forest-drawer-radius)]' } },
+    { direction: 'left', inset: false, class: { content: 'rounded-r-[var(--forest-drawer-radius)]' } },
+    { direction: 'right', inset: false, class: { content: 'rounded-l-[var(--forest-drawer-radius)]' } },
+  ],
+} as const;

package/packages/ui/src/themes/dropdown-menu.ts

@@ -0,0 +1,38 @@
+/**
+ * Forest theme fragment — UDropdownMenu (action menu, groups + nesting).
+ *
+ * Forest opinions applied:
+ *   - `item`     — before:rounded-sm (8 px) — concentric one step inside the 12 px panel, giving the
+ *                  hover/active slab a natural inset. Stock is before:rounded-md.
+ *   - `label`    — font-bold tracking-wide (group + section headings read with brand confidence;
+ *                  stock is font-semibold with no tracking).
+ *
+ * Slots touched: content · item · label
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/dropdown-menu.ts
+ */
+
+export const dropdownMenuTheme = {
+  slots: {
+    content: 'data-[state=open]:animate-[scale-in_var(--motion-base)_var(--motion-ease-out)] data-[state=closed]:animate-[scale-out_var(--motion-fast)_var(--motion-ease-out)]',
+
+    // Item slab: before:rounded-sm (8 px) — concentric inside the 12 px panel.
+    item: 'before:rounded-sm',
+
+    // Group headings: bold weight + wide tracking — confident, readable at small size.
+    label: 'font-bold tracking-wide',
+  },
+
+  // Touch: under a coarse pointer each row promotes ONE size up — it borrows the next size's
+  // padding / gap / type / icon, so the tap slab scales as a unit (mirrors the input/button ladder).
+  // xl is the ceiling. Deltas only: each size lists just the tokens that differ from its next step
+  // up (e.g. sm→md changes only type + icon, so no padding delta). `coarse:` carries the
+  // :not(.cut-fixed) escape, so a baked mobile cut opts out instead of promoting again.
+  variants: {
+    size: {
+      xs: { item: 'coarse:p-1.5 coarse:gap-1.5', label: 'coarse:p-1.5 coarse:gap-1.5' },
+      sm: { item: 'coarse:text-sm', label: 'coarse:text-sm', itemLeadingIcon: 'coarse:size-5', itemTrailingIcon: 'coarse:size-5' },
+      md: { item: 'coarse:p-2 coarse:gap-2', label: 'coarse:p-2 coarse:gap-2' },
+      lg: { item: 'coarse:text-base', label: 'coarse:text-base', itemLeadingIcon: 'coarse:size-6', itemTrailingIcon: 'coarse:size-6' },
+    },
+  },
+} as const;

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

@@ -0,0 +1,43 @@
+/**
+ * Forest theme fragment — UEmpty (empty-state placeholder).
+ *
+ * Forest opinions applied:
+ *   - `root`: radius bumped to rounded-2xl for the spacious, card-like Forest feel; padding
+ *     stepped up to p-8 sm:p-10 lg:p-12 to give the empty state breathing room — it is the
+ *     centrepiece of a blank surface, not a tucked-away widget.
+ *   - `title`: font-display (MohrAlt — always uppercase + black weight) to carry
+ *     the brand voice; the display cut renders all-caps naturally so no text-transform needed.
+ *     Bumped two steps up per size (stock caps the title at text-sm..text-lg, undersized for a
+ *     display face) so the MohrAlt title reads with presence: xs/sm text-lg, md/lg text-xl,
+ *     xl text-2xl. Overridden on the SIZE VARIANT (stock sets title size there, so a plain base
+ *     class would lose the ordering race — see the per-size-radius-hook rule).
+ *   - `description`: max-w-xs tightens the measure to ~12 words per line for comfortable reading in
+ *     the centred layout. The colour is deliberately NOT set here — stock already assigns the right
+ *     per-variant description colour (outline text-muted, soft/subtle text-toned, solid text-dimmed
+ *     so it stays legible on the inverted surface), and the variant always wins the merge, so a
+ *     slot-base colour here would just be dead weight. Leave it to stock.
+ *   - `actions`: gap-3 (12 px) — a touch more breath between CTA buttons than the stock gap-2.
+ *
+ * Slots touched: root, title, description, actions.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/empty.ts
+ */
+
+export const emptyTheme = {
+  slots: {
+    root: 'rounded-2xl p-8 sm:p-10 lg:p-12',
+    title: 'font-display',
+    description: 'max-w-xs',
+    actions: 'gap-3',
+  },
+  variants: {
+    // One step up from stock (xs/sm text-sm, md/lg text-base, xl text-lg) so the display title
+    // carries presence. Set on the size variant because stock puts the title size here.
+    size: {
+      xs: { title: 'text-lg' },
+      sm: { title: 'text-lg' },
+      md: { title: 'text-xl' },
+      lg: { title: 'text-xl' },
+      xl: { title: 'text-2xl' },
+    },
+  },
+} as const;

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

@@ -0,0 +1,52 @@
+/**
+ * Forest theme fragment — UFieldGroup (joined input/button cluster).
+ *
+ * Forest opinions applied:
+ *   - `base`: radius set to `rounded-lg` (0.5 rem, matching --ui-radius) so the outer corners of
+ *     the joined bar read with the same soft radius used across Forest controls (input, button,
+ *     card). Stock Nuxt UI's FieldGroup has no explicit radius on the wrapper — the outer corners
+ *     are therefore whatever the first/last child uses. Pinning `rounded-lg` on the wrapper ensures
+ *     the group's clip boundary matches the brand standard even when children vary.
+ *
+ * STRUCTURE (do not wrap in `slots`): UFieldGroup is a SINGLE-SLOT component — its stock theme is
+ * FLAT (`{ base: 'relative', variants: { size, orientation } }`), where `base` is the root's class
+ * string and `variants.orientation.horizontal` carries the load-bearing `inline-flex -space-x-px`
+ * (the 1px negative gap that overlaps children so adjacent inset rings/borders collapse to one).
+ * A previous version wrapped this in `{ slots: { base } }` (multi-slot shape) — that mismatched the
+ * flat recipe, broke tv() resolution (root rendered literal class "base", display:block), and DROPPED
+ * the orientation variant → no overlap → ring variants (subtle/outline) double-bordered at every join.
+ * Keep this fragment FLAT so the top-level `base` merges and the orientation/size variants survive.
+ *
+ * With the overlap intact, inner-corner stripping + ring collapse are handled automatically by Nuxt
+ * (fieldGroup variant on each child + `-space-x-px` here), so ring variants join cleanly. The one
+ * caveat is the KEYCAP lip variants (keycap/pad/framed): their ::before lip slab reads lumpy when
+ * segments butt together — for a segmented control prefer solid (active) + soft/subtle (inactive).
+ *
+ * Slot sourced from: apps/docs/node_modules/.nuxt-ui/ui/field-group.ts
+ */
+
+export const fieldGroupTheme = {
+  // FLAT top-level `base` (single-slot component) — merges with stock's `relative` base and keeps the
+  // size/orientation variants (incl. the load-bearing `-space-x-px` overlap). rounded-md = the joined
+  // bar's outer corner; the wrapper itself paints nothing, so the VISIBLE corner is the child's —
+  // capped to the same value by the orientation variants below.
+  base: 'rounded-md',
+
+  // OUTER-CORNER CAP. A joined bar's end segments must not keep their own standalone corner: the
+  // mobile cut gives every button `rounded-full`, which lands after the field-group corner-strip and
+  // domed the bar's ends (a 36px segment clamped to an 18px half-round — overshooting the group's own
+  // radius). A segmented bar is one slab, not a row of pills, so the group pins its end corners to
+  // rounded-md in EVERY context.
+  //
+  // `[&>*:first-child]` is (0,2,0), so it beats a child's plain `rounded-full`/`rounded-lg` (0,1,0),
+  // while Nuxt's inner-corner strip (`not-only:first:rounded-e-none`, higher specificity still) keeps
+  // stripping the shared edges. Flat STRINGS here to match stock's orientation variant shape — a
+  // `{ base: … }` object would mismatch the flat recipe and drop the overlap (the 2026-07-17 bug).
+  // Trade-off: inside a group the per-size radius ramp flattens to one corner, which is the point.
+  variants: {
+    orientation: {
+      horizontal: '[&>*:first-child]:rounded-s-md [&>*:last-child]:rounded-e-md',
+      vertical: '[&>*:first-child]:rounded-t-md [&>*:last-child]:rounded-b-md',
+    },
+  },
+} as const;

package/packages/ui/src/themes/file-upload.ts

@@ -0,0 +1,38 @@
+/**
+ * Forest theme fragment — UFileUpload (drop area / button upload).
+ *
+ * Deltas only — every class here overrides stock and actually lands (verified against the merged
+ * tv() output). Forest opinions:
+ *   - `base`: radius lifted from stock `rounded-lg` to `rounded-xl` (the Forest card tier, 24 px on
+ *     the scaled --ui-radius) so the drop-zone shell reads at the card/modal level, not the tighter
+ *     input level. The transition is widened
+ *     to include `border-color` (on the Forest `--motion-fast` duration) so the drag-highlight
+ *     border animates in smoothly alongside the background.
+ *   - `label`: `font-bold` — a step above stock `font-medium`, giving the call-to-action label a
+ *     confident hierarchy over the description.
+ *
+ * Deliberately NOT set (would be inert — stock overrides them in a later-merged variant, so the
+ * class is silently dropped by tailwind-merge; documenting the trap so nobody re-adds them):
+ *   - a `focus-visible:outline-*` on base is clobbered by the per-colour compoundVariant
+ *     (`focus-visible:outline-3`); the focus ring stays stock.
+ *   - an `icon` size on the base slot is clobbered by the size variant (`size-4/5/6`); a bigger
+ *     empty-state glyph would need per-size `variants.size.{…}.icon` overrides.
+ *   - a `file` radius on the base slot is clobbered by `variants.layout.list.file` (`rounded-md`);
+ *     softer list rows would need to override that layout variant.
+ *   - `fileLeadingAvatar` `rounded-lg` in the grid layout is already stock — nothing to add.
+ *
+ * Focus rings and the drag-highlight border colour are Nuxt UI compoundVariants keyed on the
+ * semantic colour vars (`--ui-color-<family>-*`), wired to the Forest OKLCH ramps in docs.css —
+ * they resolve to the correct brand values with no Forest override.
+ */
+
+export const fileUploadTheme = {
+  slots: {
+    // rounded-xl — Forest card/modal radius (24 px scaled; stock base is rounded-lg). border-color added
+    // to the transition so the drag-highlight border animates on the Forest fast duration.
+    base: 'rounded-xl transition-[background,border-color] duration-(--motion-fast)',
+
+    // font-bold — lifts the call-to-action above stock font-medium.
+    label: 'font-bold',
+  },
+} as const;

package/packages/ui/src/themes/footer-columns.ts

@@ -0,0 +1,13 @@
+/**
+ * Forest theme fragment for UFooterColumns.
+ *
+ * One delta: the column label is `text-sm font-semibold`, a size off Tailwind's default scale. A
+ * footer column heading is an overline in Forest's vocabulary — small, spaced, quiet — so it takes
+ * `.type-overline`, which carries size, tracking and case together.
+ */
+
+export const footerColumnsTheme = {
+  slots: {
+    label: 'type-overline',
+  },
+};

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

@@ -0,0 +1,9 @@
+/**
+ * Reviewed, no delta. UFooter is pure layout — every slot is flex/grid/spacing and it sets no type,
+ * colour or radius of its own. The type that appears in a footer comes from UFooterColumns.
+ *
+ * ★ It DOES cap its own width: the container slot embeds a UContainer, so a footer must not be
+ * nested inside a well. Registered on /layout/well.
+ */
+
+export const footerTheme = {};

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

@@ -0,0 +1,25 @@
+/**
+ * Forest theme fragment — UFormField (field layout: label, help, error).
+ *
+ * Forest opinions applied:
+ *
+ *   `label`:
+ *     Lifted from stock `font-medium` to `font-bold` — clearly above the field content,
+ *     giving the label a clear hierarchy. Matches the legend treatment in checkboxGroupTheme /
+ *     radioGroupTheme.
+ *
+ * Everything else is stock. Text size belongs to `variants.size`, which drives the `root` slot and
+ * lets the secondary slots (description, error, hint, help) inherit from it — a flat `text-*` here
+ * would pin one rung of a five-rung ladder. The secondary slots keep stock's `text-muted`, so the
+ * label carries the hierarchy on weight alone.
+ *
+ * Slots touched: label.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/form-field.ts
+ */
+
+export const formFieldTheme = {
+  slots: {
+    // font-bold — clearly above the field content.
+    label: 'font-bold',
+  },
+} as const;

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

@@ -0,0 +1,22 @@
+/**
+ * Forest theme fragment — UForm + UFormField (validation wrapper + field layout).
+ *
+ * Forest opinions applied:
+ *
+ *   UForm (`base`):
+ *     No visual chrome of its own — UForm is a pure behaviour wrapper (validation, loading state,
+ *     submit gate). The only Forest opinion is a comfortable `space-y-5` vertical rhythm between
+ *     FormFields, replacing the stock empty string. This gives Forest forms a consistent,
+ *     breathing density without each page needing to repeat the spacing utility.
+ *
+ * Slots touched (form): base.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/form.ts
+ *
+ * The UFormField opinions (label, description, error, hint) live in their own sibling fragment
+ * (form-field.ts), matching the one-file-per-component convention (cf. radio-group.ts).
+ */
+
+export const formTheme = {
+  // space-y-5: comfortable Forest density between FormFields (stock: empty string — no spacing).
+  base: 'space-y-5',
+} as const;

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

@@ -0,0 +1,12 @@
+/**
+ * Forest theme fragment for UHeader.
+ *
+ * One delta: the title takes `text-xl` off Tailwind's default scale. Retyped onto `.type-title` so
+ * the site wordmark sits on Forest's ladder rather than a parallel one.
+ */
+
+export const headerTheme = {
+  slots: {
+    title: 'type-title',
+  },
+};

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

@@ -0,0 +1,61 @@
+/**
+ * Forest theme fragment — UIcon
+ *
+ * UIcon is a thin pass-through to @nuxt/icon — it has no Tailwind Variants theme slots,
+ * no compound variants, and no class-generating machinery of its own. There is nothing to
+ * override in the Tailwind Variants sense.
+ *
+ * The Forest opinion for icons therefore lives entirely at the USAGE layer:
+ *
+ *   Sizing     — always use Tailwind `size-*` utilities, never the `:size` prop.
+ *                The `:size` prop inlines a `font-size` style which misaligns SVG icons in
+ *                flex/grid contexts. `size-*` sets both `width` and `height` as layout properties.
+ *
+ *                  size-3   (12 px) — inline annotation, caption badge icon
+ *                  size-3.5 (14 px) — UBadge leading/trailing icon slot
+ *                  size-4   (16 px) — UButton icon · sidebar nav item  ← default
+ *                  size-5   (20 px) — list row · prominent inline icon
+ *                  size-6   (24 px) — card icon · empty-state accent block
+ *                  size-8   (32 px) — avatar-scale accent
+ *                  size-10  (40 px) — hero / illustration icon
+ *
+ *   Colour     — always use semantic `text-*` classes so dark mode adapts automatically.
+ *                Never use raw palette classes (text-forest-500, text-maple-600, …) on icons.
+ *
+ *                  text-primary   — brand accent (forest)
+ *                  text-success   — active / healthy states
+ *                  text-warning   — low battery / caution
+ *                  text-error     — fault / critical
+ *                  text-info      — location / informational
+ *                  text-muted     — secondary / inactive
+ *                  text-dimmed    — decorative / lowest emphasis
+ *                  text-highlighted — high-contrast foreground
+ *
+ *   Flex rows  — always add `shrink-0` when UIcon sits beside text in a flex row;
+ *                omitting it causes the icon to be squeezed on narrow viewports.
+ *
+ *   Icon family — two prefixes, one drawing contract. `i-lucide-*` is the base set
+ *                 (@iconify-json/lucide) and resolves over the Iconify API. `i-forest-*` is
+ *                 Forest's own (packages/ui/icons/forest, packed by scripts/icons.ts) and must be
+ *                 registered from the bundle with addCollection() — there is no API behind it.
+ *                 Draw a Forest icon only where Lucide's glyph would misstate the operation, and
+ *                 draw it to Lucide's conventions: 24×24, fill none, stroke currentColor,
+ *                 stroke-width 2, round caps and joins. Full doctrine: /foundations/icons.
+ *
+ *   Accessibility — decorative icons (beside a label): add `aria-hidden="true"`.
+ *                   Standalone icon controls: use <UButton icon="…" aria-label="…" />.
+ *                   Meaningful icons without visible label: add <span class="sr-only">.
+ *
+ *   Render mode — keep the default mode="svg" for crisp rendering at all pixel densities;
+ *                 do not switch to mode="css" in Forest UIs.
+ *
+ * Slots touched: none — UIcon has no Tailwind Variants theme.
+ *
+ * This file exists as a Forest convention record and a named export so the theme registry
+ * can include it without breaking the import graph. The exported object is intentionally
+ * empty; the real Forest opinion is documented above and enforced at the usage layer.
+ */
+export const iconTheme = {
+  // UIcon has no Tailwind Variants slots.
+  // Forest opinions are usage conventions documented in the comment above.
+} as const;