@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/themes/button.mechanics.ts

@@ -0,0 +1,191 @@
+/**
+ * UButton mechanics — the shared emphasis recipes and per-colour palettes consumed by ./button.ts.
+ * Private to the button theme: deliberately NOT re-exported by ./index.ts, so none of this reaches
+ * forestPreset.ui as a component key.
+ *
+ * NOTE: these class strings MUST be literal — Tailwind extracts utilities by scanning source text,
+ * so no template interpolation here.
+ */
+
+export const FOCUS = 'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--btn-ring)]';
+
+// Emphasis classes — each consumes the per-colour --btn-* vars, so one string covers every intent.
+// The keycap keeps the lip ANCHORED (a box-shadow lip moves with the button — the jank). The whole
+// button (face + label) is the moving key; ::before is the lip slab behind it. ::before
+// counter-translates by the EXACT inverse of the button's lift (--btn-yi/--btn-yhi), so it cancels
+// out and sits at absolute 0 in every state — the key rises/presses, the base never moves.
+// The keycap is built from TWO pseudo-layers, both BELOW the inline label (negative z), so the
+// label always shows. ::after = the face (--btn-face + a 1px --btn-lip border); ::before = the base
+// slab (--btn-lip). The button is a transparent frame that translates — the label + ::after face ride
+// with it (lift on hover, flush on press), while ::before counter-translates by the exact inverse
+// so it stays pinned at net 0. The lip NEVER moves; only the key does.
+// NOTE: Tailwind v4 translate utilities set the `translate` property (not `transform`) — the
+// transition MUST list `translate` or the motion snaps.
+export const KEYCAP = [
+  // bg lives on ::after — keep the button frame transparent in every state (clears base-theme
+  // `hover:bg-primary` / `active:bg-primary` leaks that would otherwise sit behind the face).
+  'relative isolate overflow-visible border-0 text-[var(--btn-ink)]',
+  'bg-transparent hover:bg-transparent active:bg-transparent disabled:bg-transparent aria-disabled:bg-transparent',
+  // --btn-y-focus / --btn-yi-focus = the FOCUS lift + its ::before counter. Default to the REST values
+  // (focus moves nothing — web leans on the ::before ring below). The mobile theme overrides them to a
+  // -7px pop, the sole focus signal on touch (no hover to lean on). Living on the KEYCAP recipe (PAD
+  // inherits it) is what scopes the pop to the lip variants: the flat variants never read these vars, so
+  // the slot-level mobile base can't make them jump on focus.
+  // --btn-ring-w = the ::before focus-ring width; mobile sets it to 0 (pop replaces the ring). Routing
+  // the ring through a VAR (instead of a `before:outline-0!` override in the mobile base) is deliberate:
+  // a `before:` utility on the slot-level base auto-adds `content:''`, which on the flat variants — whose
+  // ::before is NOT absolute — becomes an in-flow flex item, and `gap-1.5` then shoves the label right
+  // (a phantom leading gap on focus). Keeping the only `before:` here, where ::before is absolute, avoids it.
+  '[--btn-y-focus:var(--btn-y)] [--btn-yi-focus:var(--btn-yi)] [--btn-ring-w:2px]',
+  // motion-reduce: the lift/press still HAPPENS (it's state, not decoration) but snaps instead of
+  // animating — no positional animation under prefers-reduced-motion (WCAG 2.3.3).
+  'translate-y-[var(--btn-y)] transition-[translate] duration-(--motion-instant) ease-(--motion-ease-out) motion-reduce:transition-none',
+  'hover:translate-y-[var(--btn-y-h)] active:translate-y-0 focus-visible:translate-y-[var(--btn-y-focus)]',
+  'disabled:translate-y-0 aria-disabled:translate-y-0',
+  // face — rides with the button (label sits above it), darkens on hover/press
+  // Edge = a CSS border on the absolute, border-box ::after (face). No layout shift (the pseudo is out
+  // of flow; border draws inside inset-0), even/concentric corners, no sliver. Width = --btn-edge (1px web,
+  // 2px mobile via the platform override).
+  "after:content-[''] after:absolute after:inset-0 after:-z-10 after:rounded-[inherit] after:bg-[var(--btn-face)] after:border-solid after:[border-width:var(--btn-edge,1px)] after:border-[var(--btn-lip)] after:transition-[background-color] after:duration-(--motion-instant) after:ease-(--motion-ease-out)",
+  'hover:after:bg-[var(--btn-hover)] active:after:bg-[var(--btn-hover)]',
+  // base slab. Bottom stays anchored (counter-translate cancels the button's lift); the TOP tracks
+  // the face lift (--btn-y per state) so the slab spans the FULL keycap silhouette — face top → lip
+  // bottom — in EVERY state (lifted at rest/hover, flush when pressed/disabled). The visible lip is
+  // still only the bottom strip: the extended top sits behind the opaque face. `top` animates with
+  // the lift so the ring tracks smoothly.
+  // Lip = a STATIC slab (full footprint, constant shape). It never transforms: the key (button +
+  // face) translates, and ::before counter-translates by the exact inverse so it stays anchored at
+  // net-0 in every state. Only the face moving over it reveals/hides the lip — the lip never morphs.
+  "before:content-[''] before:absolute before:inset-x-0 before:bottom-0 before:top-[var(--btn-y)] before:-z-20 before:rounded-[inherit] before:bg-[var(--btn-lip)]",
+  'before:translate-y-[var(--btn-yi)] before:transition-[translate,top] before:duration-(--motion-instant) before:ease-(--motion-ease-out) before:motion-reduce:transition-none',
+  'hover:before:translate-y-[var(--btn-yhi)] hover:before:top-[var(--btn-y-h)] active:before:translate-y-0 active:before:top-0',
+  // ::before tracks the FOCUS lift so the slab stays anchored when the key pops (mobile); on web the
+  // focus vars equal the rest values, so it doesn't budge.
+  'focus-visible:before:top-[var(--btn-y-focus)] focus-visible:before:translate-y-[var(--btn-yi-focus)]',
+  'disabled:before:translate-y-0 disabled:before:top-0 aria-disabled:before:translate-y-0 aria-disabled:before:top-0',
+  // Focus ring rides on ::before — which now spans the full silhouette — NOT the button, so it wraps
+  // the whole key with an EVEN 2px gap on all sides in every state. outline-none kills the button's
+  // UA default ring; rounded-[inherit] keeps the corners matched.
+  'focus-visible:outline-none focus-visible:before:outline-[length:var(--btn-ring-w)] focus-visible:before:outline-offset-2 focus-visible:before:outline-[var(--btn-ring)]',
+].join(' ');
+
+export const PAD = [
+  // Quiet tactile key — the KEYCAP engine fed the TINT ramp instead of the solid face: tint fill
+  // (t1→t2→t3), a line-colour border + lip, dark text. Same lift/press/anchored focus ring as the
+  // keycap, lower emphasis (subtle's calm + the keycap's feel). Each remap is declared TWICE — plain
+  // AND `dark:` — because the colour PALs set `dark:--btn-*`, and a `.dark`-scoped rule outranks a
+  // plain one; without the dark: copy the PAL's dark face beats the remap (pad == keycap in dark).
+  // var(--btn-t1) etc. are already mode-aware, so both copies point at the live tint value.
+  '[--btn-face:var(--btn-t1)] dark:[--btn-face:var(--btn-t1)] [--btn-hover:var(--btn-t2)] dark:[--btn-hover:var(--btn-t2)] [--btn-press:var(--btn-t3)] dark:[--btn-press:var(--btn-t3)] [--btn-lip:var(--btn-line)] dark:[--btn-lip:var(--btn-line)] [--btn-ink:var(--btn-text)] dark:[--btn-ink:var(--btn-text)]',
+  KEYCAP,
+].join(' ');
+
+export const FRAMED = [
+  // Filled face + an INSET RING border (Nuxt-style: a box-shadow, NOT a CSS border — so it adds no
+  // height, unlike `border-2`, keeping every variant the same size). The lip demotes to the ring. No
+  // lip, no motion; leans on face→hover→press. Keeps light-face fills (amber, secondary) visible.
+  'ring-[length:var(--btn-edge,1px)] ring-inset ring-[var(--btn-lip)] text-[var(--btn-ink)] bg-[var(--btn-face)]',
+  'hover:bg-[var(--btn-hover)] active:bg-[var(--btn-press)]',
+  FOCUS,
+].join(' ');
+
+export const SOLID = [
+  // Plain filled face — no lip, no border, no motion (the standard Nuxt-style solid). Feedback
+  // comes from the face→hover→press colour steps. A light face (amber, secondary) has no edge on a
+  // light surface by design — reach for `framed` when a light solid needs a border.
+  'border-0 text-[var(--btn-ink)] bg-[var(--btn-face)]',
+  'hover:bg-[var(--btn-hover)] active:bg-[var(--btn-press)]',
+  FOCUS,
+].join(' ');
+
+export const GLOSS = [
+  // Web-only "gloss" emphasis — framed's lip outline with a line of light ONE pixel inside it along the
+  // top (the shine sits below the border, over the face — never on the border itself). The line is the
+  // face's OWN colour lightened (oklch l + --btn-shine-l, default 0.25), not white, so the sheen is
+  // on-brand per intent and works in both modes. Neutral's near-black face needs a bigger lift to read
+  // (PAL_NEUTRAL bumps --btn-shine-l to 0.5 in light; dark stays 0.25 — its near-white face would clip).
+  // One box-shadow, two inset layers: layer 1 (FRONT) the lip outline, --btn-edge
+  // wide; layer 2 (BEHIND) a light band offset calc(edge + 1px), so the outline covers its top `edge` px
+  // and only the next 1px shows. Both inset → footprint identical to framed.
+  'border-0 text-[var(--btn-ink)] bg-[var(--btn-face)]',
+  'shadow-[inset_0_0_0_var(--btn-edge,1px)_var(--btn-lip),inset_0_calc(var(--btn-edge,1px)_+_1px)_0_0_oklch(from_var(--btn-face)_calc(l_+_var(--btn-shine-l,0.25))_c_h)]',
+  // hover/press shift --btn-face itself (not just bg), so BOTH the fill and the shine (derived from
+  // --btn-face) track the current state — the line stays +0.25 lighter than whatever face is showing.
+  'hover:[--btn-face:var(--btn-hover)] active:[--btn-face:var(--btn-press)]',
+  FOCUS,
+].join(' ');
+
+export const SUBTLE = [
+  // A ramp-pinned INSET RING (a box-shadow, not a border → no added height) over a plain surface fill.
+  // Our width + colour override Nuxt's native subtle ring (`ring ring-inset ring-{color}/25`), so
+  // there's a single edge; `ring-inset` itself comes from that stock compound (deltas only). Same
+  // ring approach as OUTLINE. Rest sits on `bg-default` (not the --btn-t1 tint) so it reads like a
+  // select's outline field — white at rest, tinting to --btn-t2 on hover — rather than a filled slab.
+  'ring-[length:var(--btn-edge,1px)] ring-[var(--btn-line)] text-[var(--btn-text)] bg-default',
+  'hover:bg-[var(--btn-t2)] active:bg-[var(--btn-t3)]',
+  FOCUS,
+].join(' ');
+
+export const OUTLINE = [
+  // Inset ring (box-shadow), NOT a CSS border — overrides Nuxt's native outline ring's width and
+  // colour and adds no height, so every variant stays the same size. `ring-inset` itself comes
+  // from the stock outline compound (deltas only); FRAMED keeps its own — no stock counterpart.
+  'ring-[length:var(--btn-edge,1px)] ring-[var(--btn-line)] text-[var(--btn-text)] bg-transparent',
+  // Border holds at --btn-line through hover — only the fill tints — so it reads like an input, not a
+  // ring that darkens on approach.
+  'hover:bg-[var(--btn-t1)] active:bg-[var(--btn-t2)]',
+  FOCUS,
+].join(' ');
+
+export const SOFT = [
+  // Tinted fill: rest t1 → hover t2 → press t3.
+  'text-[var(--btn-text)] bg-[var(--btn-t1)]',
+  'hover:bg-[var(--btn-t2)] active:bg-[var(--btn-t3)]',
+  FOCUS,
+].join(' ');
+
+export const GHOST = [
+  // Transparent rest → hover t1 → press t2.
+  'text-[var(--btn-text)] bg-transparent',
+  'hover:bg-[var(--btn-t1)] active:bg-[var(--btn-t2)]',
+  FOCUS,
+].join(' ');
+
+export const LINK = [
+  // Text-only, link-styled — no fill, no border. Underlines on hover and deepens to the press
+  // colour. Tertiary actions ("Learn more"). Inherits the size padding so it lines up in a button row.
+  'border-0 bg-transparent text-[var(--btn-text)] underline-offset-4',
+  'hover:underline hover:text-[var(--btn-press)] active:text-[var(--btn-press)]',
+  FOCUS,
+].join(' ');
+
+// Docs mirror: apps/docs/src/pages/components/ButtonPage.vue (Specs + Engineering notes) restates
+// these recipes in prose — keep both in sync.
+// Per-colour --btn-* palettes. LITERAL strings (Tailwind-scannable), sourced from the OKLCH ramp
+// (--<family>-50..950). Solids step one level lighter in dark so they pop on a dark surface; the
+// tint / text / line layers flip too, since the ramp is monotonic. Ramp levels — light / dark:
+//   face 500/400 · hover 600/500 · press 700/600 · lip 700/600 · ring 500 · t1 100/900 · t2 200/800 · t3 300/700 · line 400/600 · text 700/300 · ink 0/950
+// On-solid ink follows FACE lightness, not mode: a dark face takes the light 0, a light face the dark 950.
+// Solids use 50 in light / 950 in dark; amber's face is light in BOTH modes, so it's 950 in both — same
+// rule, not a special case. Secondary→warm is a standard colour key (face 500/400). Neutral is the
+// exception: Nuxt-style monochrome — face-based variants invert (900/50), the rest are surface greys.
+export const PAL_FOREST = '[--btn-face:var(--forest-500)] dark:[--btn-face:var(--forest-400)] [--btn-hover:var(--forest-600)] dark:[--btn-hover:var(--forest-500)] [--btn-press:var(--forest-700)] dark:[--btn-press:var(--forest-600)] [--btn-lip:var(--forest-700)] dark:[--btn-lip:var(--forest-600)] [--btn-ring:var(--forest-500)] [--btn-t1:var(--forest-100)] dark:[--btn-t1:var(--forest-900)] [--btn-t2:var(--forest-200)] dark:[--btn-t2:var(--forest-800)] [--btn-t3:var(--forest-300)] dark:[--btn-t3:var(--forest-700)] [--btn-line:var(--forest-400)] dark:[--btn-line:var(--forest-600)] [--btn-text:var(--forest-700)] dark:[--btn-text:var(--forest-300)] [--btn-ink:var(--forest-0)] dark:[--btn-ink:var(--forest-950)]';
+export const PAL_RIVER = '[--btn-face:var(--river-500)] dark:[--btn-face:var(--river-400)] [--btn-hover:var(--river-600)] dark:[--btn-hover:var(--river-500)] [--btn-press:var(--river-700)] dark:[--btn-press:var(--river-600)] [--btn-lip:var(--river-700)] dark:[--btn-lip:var(--river-600)] [--btn-ring:var(--river-500)] [--btn-t1:var(--river-100)] dark:[--btn-t1:var(--river-900)] [--btn-t2:var(--river-200)] dark:[--btn-t2:var(--river-800)] [--btn-t3:var(--river-300)] dark:[--btn-t3:var(--river-700)] [--btn-line:var(--river-400)] dark:[--btn-line:var(--river-600)] [--btn-text:var(--river-700)] dark:[--btn-text:var(--river-300)] [--btn-ink:var(--river-0)] dark:[--btn-ink:var(--river-950)]';
+export const PAL_MAPLE = '[--btn-face:var(--maple-500)] dark:[--btn-face:var(--maple-400)] [--btn-hover:var(--maple-600)] dark:[--btn-hover:var(--maple-500)] [--btn-press:var(--maple-700)] dark:[--btn-press:var(--maple-600)] [--btn-lip:var(--maple-700)] dark:[--btn-lip:var(--maple-600)] [--btn-ring:var(--maple-500)] [--btn-t1:var(--maple-100)] dark:[--btn-t1:var(--maple-900)] [--btn-t2:var(--maple-200)] dark:[--btn-t2:var(--maple-800)] [--btn-t3:var(--maple-300)] dark:[--btn-t3:var(--maple-700)] [--btn-line:var(--maple-400)] dark:[--btn-line:var(--maple-600)] [--btn-text:var(--maple-700)] dark:[--btn-text:var(--maple-300)] [--btn-ink:var(--maple-0)] dark:[--btn-ink:var(--maple-950)]';
+// Warning = light solid: a 300 face with frozen dark ink (a dark amber would fail dark-ink contrast).
+export const PAL_AMBER = '[--btn-face:var(--amber-300)] [--btn-hover:var(--amber-400)] [--btn-press:var(--amber-500)] [--btn-lip:var(--amber-600)] [--btn-ring:var(--amber-500)] [--btn-t1:var(--amber-100)] dark:[--btn-t1:var(--amber-900)] [--btn-t2:var(--amber-200)] dark:[--btn-t2:var(--amber-800)] [--btn-t3:var(--amber-300)] dark:[--btn-t3:var(--amber-700)] [--btn-line:var(--amber-400)] dark:[--btn-line:var(--amber-600)] [--btn-text:var(--amber-700)] dark:[--btn-text:var(--amber-300)] [--btn-ink:var(--amber-950)]';
+// Secondary = warm intent — standard colour key (face 500/400 like the brand families); white ink on
+// the dark 500 face, dark ink on the lighter 400 in dark mode. Own warm focus ring.
+export const PAL_SECONDARY = '[--btn-face:var(--warm-500)] dark:[--btn-face:var(--warm-400)] [--btn-hover:var(--warm-600)] dark:[--btn-hover:var(--warm-500)] [--btn-press:var(--warm-700)] dark:[--btn-press:var(--warm-600)] [--btn-lip:var(--warm-700)] dark:[--btn-lip:var(--warm-600)] [--btn-ring:var(--warm-500)] [--btn-t1:var(--warm-100)] dark:[--btn-t1:var(--warm-900)] [--btn-t2:var(--warm-200)] dark:[--btn-t2:var(--warm-800)] [--btn-t3:var(--warm-300)] dark:[--btn-t3:var(--warm-700)] [--btn-line:var(--warm-400)] dark:[--btn-line:var(--warm-600)] [--btn-text:var(--warm-700)] dark:[--btn-text:var(--warm-300)] [--btn-ink:var(--warm-0)] dark:[--btn-ink:var(--warm-950)]';
+// Neutral = Nuxt-style monochrome (color="neutral"). Face-based variants (keycap/framed/solid) are the
+// INVERTED key — near-black face + white ink in light, near-white face + dark ink in dark (high
+// contrast, like Nuxt's bg-inverted/text-inverted). Tint/text variants (subtle/soft/outline/ghost/
+// link) fall to surface greys (t 100–300 / text 900). Grey focus/hover ring (neutral-500), so the
+// outline hover edge stays monochrome instead of leaking brand green via the shared --btn-ring.
+// Rest --btn-line is 300/700 (not the ramp's 400/600) to match UInput's resting border
+// (ring-accented → --ui-border-accented = neutral-300/700), so a neutral button sits flush with a field.
+export const PAL_NEUTRAL = '[--btn-face:var(--neutral-900)] dark:[--btn-face:var(--neutral-50)] [--btn-hover:var(--neutral-800)] dark:[--btn-hover:var(--neutral-100)] [--btn-press:var(--neutral-700)] dark:[--btn-press:var(--neutral-200)] [--btn-lip:var(--neutral-400)] dark:[--btn-lip:var(--neutral-300)] [--btn-ring:var(--neutral-500)] [--btn-t1:var(--neutral-50)] dark:[--btn-t1:var(--neutral-950)] [--btn-t2:var(--neutral-100)] dark:[--btn-t2:var(--neutral-900)] [--btn-t3:var(--neutral-200)] dark:[--btn-t3:var(--neutral-800)] [--btn-line:var(--neutral-300)] dark:[--btn-line:var(--neutral-700)] [--btn-text:var(--neutral-900)] dark:[--btn-text:var(--neutral-100)] [--btn-ink:var(--neutral-0)] dark:[--btn-ink:var(--neutral-900)] [--btn-shine-l:0.5] dark:[--btn-shine-l:0.25]';
+
+// All seven intents share the colour-keyed solid/flat/outline/soft/ghost classes.
+export const ALL = ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'neutral'];
+export const emphasis = (variant: string, cls: string) => ALL.map((color) => ({ color, variant, class: cls }));

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

@@ -0,0 +1,136 @@
+/**
+ * Forest theme fragment for UButton — the 9-rung emphasis ladder. The default is the signature
+ * tactile "keycap" (à la Sentry): a coloured face on a darker bottom lip (pseudo-layers behind the
+ * label) that lifts on hover and collapses flush on press.
+ *
+ * Intent × emphasis taxonomy, mapped onto Nuxt UI's color × variant axes:
+ *
+ *   color (intent)                      | variant (emphasis, high → low)
+ *   ----------------------------------- | -------------------------------------------------
+ *   primary   primary    forest         | keycap   tactile lip (lifts on hover, flush on press)
+ *   success   success    forest         | pad      tint + border + lip — quiet but tactile
+ *   error     danger     maple          | framed   filled face + border (light faces stay visible)
+ *   info      info       river          | solid    filled face, no border, no lip
+ *   warning   warning    amber (ink)    | subtle   tint + border
+ *   secondary secondary  warm           | soft     tint, no border
+ *   neutral   neutral    neutral        | outline  border only
+ *                                       | ghost    text, bg tint on hover
+ *                                       | link     text-only, underline on hover
+ *
+ * Each `color` sets per-family CSS custom properties (--btn-*) consumed by the shared emphasis
+ * classes in ./button.mechanics, so each variant is written once. Buttons override their own
+ * colours via these vars, independent of the preset's semantic role map.
+ *
+ * On-face ink follows FACE lightness, not mode: a dark face takes the family's 0, a light face its
+ * 950 (so amber — a light face in both modes — is 950 in both). Neutral is Nuxt-style monochrome:
+ * its face-based variants are the inverted key (face 900/50, ink 0/900); the rest fall to greys.
+ * Token source of truth: forest-web.DESIGN.md › Components.
+ */
+
+import {
+  KEYCAP,
+  PAD,
+  FRAMED,
+  SOLID,
+  SUBTLE,
+  SOFT,
+  OUTLINE,
+  GHOST,
+  LINK,
+  PAL_FOREST,
+  PAL_RIVER,
+  PAL_MAPLE,
+  PAL_AMBER,
+  PAL_SECONDARY,
+  PAL_NEUTRAL,
+  emphasis,
+} from './button.mechanics';
+
+export const buttonTheme = {
+  slots: {
+    // motion-reduce: colour fades may stay; transform/box-shadow movement must not animate.
+    base: 'font-bold transition-[transform,box-shadow,background-color,border-color,color] duration-(--motion-fast) motion-reduce:transition-[background-color,border-color,color]',
+  },
+
+  variants: {
+    // `color` sets the per-family --btn-* vars (string → applies to the base slot).
+    color: {
+      primary: PAL_FOREST,
+      success: PAL_FOREST,
+      info: PAL_RIVER,
+      error: PAL_MAPLE,
+      warning: PAL_AMBER,
+      secondary: PAL_SECONDARY,
+      neutral: PAL_NEUTRAL,
+    },
+    // Custom emphasis keys not in Nuxt UI's native variant set — registered so the
+    // compoundVariants below bind. subtle/link are registered too, so binding never depends on
+    // the base preset's variant list. All are styled via the compounds.
+    variant: {
+      keycap: '',
+      pad: '',
+      framed: '',
+      gloss: '',
+      subtle: '',
+      link: '',
+    },
+    // Size-scaled padding, radius, and lip elevation.
+    size: {
+      // --btn-y = key lift (lip thickness), --btn-y-h = hover lift; --btn-yi/--btn-yhi = the exact
+      // inverses, applied to the base slab so it cancels the lift and stays anchored.
+      // Radius on the system's named scale (rounded-sm 8 · rounded-md 12 · rounded-lg 16 — the
+      // --radius-* tokens) instead of arbitrary [Npx]. The scale is coarser than the old 2px ladder,
+      // so sm snaps 10→8 and lg snaps 14→16, each sharing a step with a neighbour; xs/md/xl are
+      // unchanged (8/12/16). --btn-y* are lip mechanics, not a scale — left as-is.
+      // TWO LADDERS, selected by pointer, not by context:
+      //   fine  24/28/32/36/40 (xs→xl) — the pointer ladder, matching UInput at every size.
+      //   touch 28/36/40/44/52         — bigger box + a type step, so lg is Apple's 44 and xl 52.
+      // A control's height changes ONLY with its `size` and with the ladder in force. Per-ladder
+      // height does NOT break a mixed <UFieldGroup>: every field member carries the same `touch:`
+      // ladder, so button==input at every rung on either side.
+      // `min-h` is RETAINED (not removed): it is the height driver `aspect-square` mirrors into width
+      // for icon-only buttons (stock supplies the equal `p-1.5` square padding). A prior attempt that
+      // removed min-h collapsed every icon button — only its VALUE moved down to the input's.
+      // touch: = the touch ladder (custom variant, styles/forest.css). ONE set of numbers, fired
+      // either by a coarse primary pointer (any context — a touched web page counts) or by the mobile
+      // cut's baked `.cut-fixed` marker. Same values under both, so a real phone can't step twice and
+      // the desktop mock of the mobile app shows true size with no pointer to query.
+      //   height  min-h 28/36/40/44/52 — min-h is the authority, and the ONLY height driver for
+      //           icon-only buttons (the square compound zeroes the padding, which would skew them).
+      //   type    sm/lg/xl gain a step; xs/md keep their pair's text (12·14·14·16·18 across the ladder).
+      //   icons   size-5/6/7 follow the box, so the glyph doesn't strand inside a bigger target.
+      // Radius is deliberately absent — the mobile cut is already rounded-full, and the web radius
+      // ramp reads correctly at both ladders. Lip vars (--btn-y*, keycap-only, ~1px) stay on `coarse:`:
+      // they're depth, not size, and the mobile cut sets its own flat lip in mobile-theme.ts.
+      xs: { base: 'min-h-6 px-2.5 rounded-sm touch:min-h-7 [--btn-y:-1px] [--btn-yi:1px] [--btn-y-h:-2px] [--btn-yhi:2px] coarse:[--btn-y:-2px] coarse:[--btn-yi:2px] coarse:[--btn-y-h:-3px] coarse:[--btn-yhi:3px]' },
+      sm: { base: 'min-h-7 px-3 rounded-md touch:min-h-9 touch:text-sm [--btn-y:-2px] [--btn-yi:2px] [--btn-y-h:-3px] [--btn-yhi:3px]', leadingIcon: 'touch:size-5', trailingIcon: 'touch:size-5' },
+      md: { base: 'min-h-8 px-3.5 rounded-md touch:min-h-10 [--btn-y:-2px] [--btn-yi:2px] [--btn-y-h:-3px] [--btn-yhi:3px] coarse:[--btn-y:-3px] coarse:[--btn-yi:3px] coarse:[--btn-y-h:-4px] coarse:[--btn-yhi:4px]' },
+      lg: { base: 'min-h-9 px-4 rounded-lg touch:min-h-11 touch:text-base [--btn-y:-3px] [--btn-yi:3px] [--btn-y-h:-4px] [--btn-yhi:4px]', leadingIcon: 'touch:size-6', trailingIcon: 'touch:size-6' },
+      xl: { base: 'min-h-10 px-4 rounded-lg touch:min-h-13 touch:text-lg [--btn-y:-3px] [--btn-yi:3px] [--btn-y-h:-4px] [--btn-yhi:4px]', leadingIcon: 'touch:size-7', trailingIcon: 'touch:size-7' },
+    },
+  },
+
+  compoundVariants: [
+    ...emphasis('keycap', KEYCAP),
+    ...emphasis('pad', PAD),
+    ...emphasis('framed', FRAMED),
+    // ...emphasis('gloss', GLOSS),
+    ...emphasis('solid', SOLID),
+    ...emphasis('subtle', SUBTLE),
+    ...emphasis('soft', SOFT),
+    ...emphasis('outline', OUTLINE),
+    ...emphasis('ghost', GHOST),
+    ...emphasis('link', LINK),
+    // Icon-only: `min-h` floors the height, `aspect-square` mirrors it into width; stock supplies the
+    // equal `p-*` square padding, which asymmetric touch padding would skew — so zero it and let the
+    // size's `touch:min-h-*` rung carry the growth on its own. That rung must therefore exist for
+    // every size: without it a touched icon button grows its glyph while the box holds still.
+    { square: true, class: 'justify-center aspect-square touch:px-0 touch:py-0' },
+  ],
+
+  defaultVariants: {
+    color: 'primary',
+    variant: 'solid',
+    size: 'md',
+  },
+} as const

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

@@ -0,0 +1,29 @@
+/**
+ * Forest theme fragment — UCalendar
+ *
+ * Deltas only — every token here changes stock. The card shell, the confident heading weight, and
+ * the offset brand focus ring are the whole opinion; shape, colour intents, sizes and the range /
+ * today fills are stock Nuxt UI on the Forest ramps.
+ *
+ * Slots touched: root, headingLabel, cellTrigger.
+ * Stock recipe (for the diff): apps/docs/node_modules/.nuxt-ui/ui/calendar.ts
+ */
+
+export const calendarTheme = {
+  slots: {
+    // Card-style container — stock `root` is empty; Forest frames the inline grid as a contained
+    // card (soft radius + border + gentle padding) rather than a raw grid floating in white space.
+    root: 'rounded-xl border border-default bg-elevated/30 p-4 inline-block',
+
+    // Month / year label — the actual text span (nested inside `heading`, which is why the weight
+    // must land here, not on the wrapper). Confident weight replaces stock's `font-medium` (banned
+    // by the two-weight system) and picks up display tracking without the full Mohr uppercase.
+    headingLabel: 'font-bold tracking-tight text-highlighted',
+
+    // Date cell — the only cell delta: a brand focus ring pushed out 2px (replaces stock's flat
+    // `focus-visible:outline-3`) so it clears the circle edge, plus a bolder today marker
+    // (`font-bold` over stock `font-semibold`). Shape (rounded-full), sizes and the colour-variant
+    // fills stay stock.
+    cellTrigger: 'focus-visible:ring-2 focus-visible:ring-offset-2 focus:outline-none data-today:font-bold',
+  },
+} as const

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

@@ -0,0 +1,67 @@
+/**
+ * Forest theme fragment for UCard.
+ *
+ * Radius xl (24px). `forest-card` marker (PRESET_STRUCTURAL_MARKERS) drives the NESTED-surface +
+ * concentric-radius CSS in styles/forest.css (§ card nesting): each nested card steps one
+ * neutral-ramp level (light darker / dark lighter) and its corners stay concentric
+ * (radius = parent − padding). Uniform p-4 padding — kill the stock desktop bump (body sm:p-6,
+ * header/footer sm:px-6).
+ */
+
+// Stock puts `divide-y` on the VARIANT root (outline/soft/subtle), not the base slots — so a variant
+// with no divider (solid, and the tinted set below, which stock never supplied one for) shows the
+// header→body→footer gap DOUBLED (header pb-4 + body pt-4 = 32px) with nothing sitting in it. These
+// two rules collapse it back to the single 16px the body's own p-4 already provides.
+// The :not(:last-child)/:not(:first-child) guards are load-bearing: a header-only card (title +
+// description, no body/footer) must keep its bottom padding — with a bare pb-0 the text sat flush
+// against the edge. The collapse only fires when a sibling actually follows/precedes.
+const flatGap = {
+  header: '[&:not(:last-child)]:pb-0',
+  footer: '[&:not(:first-child)]:pt-0',
+} as const
+
+export const cardTheme = {
+  slots: {
+    root: 'rounded-xl forest-card',
+    body: 'sm:p-4',
+    header: 'sm:px-4',
+    footer: 'sm:px-4',
+    // Title voice rides the --fx-* traits (forest.css): sans/none at rest, so web is unchanged —
+    // a louder context (marketing delta) re-points the vars to Mohr + uppercase without touching
+    // this recipe. Weight is NOT a trait: the delta adds font-black as a plain class instead
+    // (Mohr only ships 900; a weight var would alter the stock title at rest).
+    title: '[font-family:var(--fx-title-family)] [text-transform:var(--fx-title-transform)]',
+  },
+  // Quiet fill: `soft`/`subtle` both draw from --forest-card-bg (the depth-stepped neutral surface,
+  // set by the nesting CSS) — soft no ring, subtle + ring (the stock "soft +ring = subtle"
+  // relationship, now on an opaque ramp surface that reads distinctly when nested and in dark,
+  // where bg-muted == bg-elevated). soft also kills the divide-y for a flat single surface.
+  // `outline` (bg-default + ring) and `solid` (bg-inverted) stay stock — the ring/contrast do the
+  // separating there.
+  variants: {
+    variant: {
+      // Borderless variants take flatGap; divided ones keep the full gap — the hairline sits in it.
+      soft: { root: 'bg-[var(--forest-card-bg)] divide-y-0', ...flatGap },
+      solid: { ...flatGap },
+      // subtle AND outline use the translucent RELATIVE hairline (--forest-card-ring) for ring +
+      // divide, not the fixed border-default ramp token — one consistent border language across
+      // cards (and it keeps subtle collision-proof on the stepped surface). Only the FILL differs:
+      // subtle = stepped surface, outline = bg-default.
+      subtle: { root: 'bg-[var(--forest-card-bg)] ring-[var(--forest-card-ring)] divide-[color:var(--forest-card-ring)]' },
+      outline: { root: 'ring-[var(--forest-card-ring)] divide-[color:var(--forest-card-ring)]' },
+      // Tinted accent variants — surfaces off the brand ramps (see --forest-card-<hue>-* in
+      // styles/forest.css: soft tint in light, deep ramp tone in dark). Ink is tone-on-tone: title +
+      // description take the hue's own -text / -muted step (deep on the light tint, light on the deep
+      // tone) so the copy reads as part of the accent, not neutral ink dropped on top. For featured/
+      // promo cards. Flat like soft: the hue carries the surface, so there is no divider and the
+      // sections take flatGap. Stock has no tinted variant to inherit a `divide-y` from.
+      peach: { root: 'bg-[var(--forest-card-peach-bg)] ring-[var(--forest-card-peach-ring)]', title: 'text-[var(--forest-card-peach-text)]', description: 'text-[var(--forest-card-peach-muted)]', ...flatGap },
+      mint:  { root: 'bg-[var(--forest-card-mint-bg)] ring-[var(--forest-card-mint-ring)]', title: 'text-[var(--forest-card-mint-text)]', description: 'text-[var(--forest-card-mint-muted)]', ...flatGap },
+      sky:   { root: 'bg-[var(--forest-card-sky-bg)] ring-[var(--forest-card-sky-ring)]', title: 'text-[var(--forest-card-sky-text)]', description: 'text-[var(--forest-card-sky-muted)]', ...flatGap },
+      amber: { root: 'bg-[var(--forest-card-amber-bg)] ring-[var(--forest-card-amber-ring)]', title: 'text-[var(--forest-card-amber-text)]', description: 'text-[var(--forest-card-amber-muted)]', ...flatGap },
+    },
+  },
+  defaultVariants: {
+    variant: 'soft',
+  },
+} as const

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

@@ -0,0 +1,41 @@
+/**
+ * Forest theme fragment — UCarousel (Embla-powered sliding gallery). Deltas only.
+ *
+ * Two opinions, both on the controls:
+ *
+ *   prev / next — the arrow buttons gain the Forest outline focus ring
+ *     (`focus-visible:outline-2 outline-offset-2 outline-[var(--forest-500)]`) so keyboard
+ *     navigation matches every other Forest interactive primitive. Stock leaves the slot at
+ *     `absolute rounded-full` and relies on the UButton's own focus-visible ring.
+ *
+ *   dot — the active pagination pip adopts the primary brand green
+ *     (`var(--forest-500)` light / `var(--forest-400)` dark) instead of stock's `bg-inverted`,
+ *     plus the same outline focus ring. ★ The colour MUST live in the `active` variant, not the
+ *     base slot: stock sets `data-[state=active]:bg-inverted` in `variants.active.true.dot`, and
+ *     tv applies the size/state variant AFTER the base slot — so a base-slot colour loses the
+ *     tailwind-merge race and the pip stays inverted. Overriding the variant (deep-merged, appended
+ *     last) is the seam that actually wins. Inactive pip stays stock `bg-accented`.
+ *
+ * Untouched (inherited from stock): root/viewport/container/item layout, controls/arrows wrappers,
+ * dots positioning, orientation variants, drag/keyboard/plugin behaviour (all Embla's).
+ */
+
+const FOCUS_RING =
+  'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--forest-500)]';
+
+export const carouselTheme = {
+  slots: {
+    prev: FOCUS_RING,
+    next: FOCUS_RING,
+    dot: `focus:outline-none ${FOCUS_RING}`,
+  },
+  variants: {
+    active: {
+      true: {
+        // Overrides stock's `data-[state=active]:bg-inverted` — wins because the active variant is
+        // deep-merged (Forest appended last) and applied after the base slot.
+        dot: 'data-[state=active]:bg-[var(--forest-500)] dark:data-[state=active]:bg-[var(--forest-400)]',
+      },
+    },
+  },
+} as const;

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

@@ -0,0 +1,20 @@
+/**
+ * Forest theme fragment — UCheckboxGroup.
+ *
+ * Forest opinions applied:
+ *   `legend` slot: font-bold lifts the group legend above the individual checkbox labels
+ *   (stock: font-medium), matching the legend treatment in radioGroupTheme and the label
+ *   treatment in formFieldTheme.
+ *
+ * The card and table variants are left entirely stock — no radius override.
+ *
+ * Slots touched: legend.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/checkbox-group.ts
+ */
+
+export const checkboxGroupTheme = {
+  slots: {
+    // font-bold lifts the group legend above the individual checkbox labels (stock: font-medium).
+    legend: 'font-bold',
+  },
+} as const;

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

@@ -0,0 +1,47 @@
+/**
+ * Forest theme fragment — UCheckbox + UCheckboxGroup.
+ *
+ * Forest opinions applied:
+ *   - `base` (checkbox): radius lifted from `rounded-sm` (2 px stock) to `rounded` (4 px, i.e.
+ *     0.25 rem), which is softer without being pill-like. Keeps it reading as a square control
+ *     while aligning with Forest's overall soft-radius vocabulary (--ui-radius = 0.5 rem).
+ *   - `label`: font-medium is already stock; we keep it and add nothing — the Nuxt UI default is
+ *     correct here.
+ *   - `base` focus ring: Forest's house convention `focus-visible:outline-2 focus-visible:outline-offset-2`
+ *     (an offset ring), over stock's flush `focus-visible:outline-3`. The outline COLOUR is stock's
+ *     semantic value, resolved to the Forest OKLCH ramp via docs.css / forest-preset — no colour
+ *     override needed, only the width + offset.
+ *   - `legend` (CheckboxGroup): font-bold — bold against the regular item labels, giving the
+ *     group label a clear hierarchy above the individual checkbox labels.
+ *
+ * The card variant is left entirely stock — no radius override.
+ *
+ * Slots touched: base.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/checkbox.ts
+ *
+ * The CheckboxGroup legend opinion lives in its own sibling fragment (checkbox-group.ts),
+ * matching the one-file-per-component convention (cf. radio-group.ts, field-group.ts).
+ */
+
+export const checkboxTheme = {
+  slots: {
+    // Deltas over stock: `rounded` (4px) for the Forest soft radius (stock rounded-sm/2px), and the
+    // house focus ring `outline-2 outline-offset-2` (stock is a flush outline-3). Ring colour and the
+    // indicator bg resolve to the Forest OKLCH ramps via the colour-alias bridge — no override there.
+    base: 'rounded focus-visible:outline-2 focus-visible:outline-offset-2',
+  },
+  // Touch: a checkbox's tap target is the whole label ROW, and at md that row is short (~20px). Under
+  // a coarse (finger) pointer each size grows one size up — box (base), row height (container) and
+  // label text (wrapper) — so the row becomes a taller, easier target. No sliding part, so the bump
+  // is clean (unlike the switch thumb). xl is the ceiling; each size lists only its deltas up.
+  // `coarse:` carries the `:not(.cut-fixed)` escape so the mobile cut (baked size lg) opts out.
+  variants: {
+    size: {
+      xs: { base: 'coarse:size-3.5' },
+      sm: { base: 'coarse:size-4', container: 'coarse:h-5', wrapper: 'coarse:text-sm' },
+      md: { base: 'coarse:size-4.5' },
+      lg: { base: 'coarse:size-5', container: 'coarse:h-6', wrapper: 'coarse:text-base' },
+      // xl: ceiling
+    },
+  },
+} as const;

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

@@ -0,0 +1,50 @@
+/**
+ * Forest theme fragment — UChip
+ *
+ * Two deltas over stock (the preset APPENDS, so this carries only what changes):
+ *
+ *   1. base: `font-bold` — stock is `font-medium`, thin on the tiny count labels.
+ *
+ *   2. Text-mode bump. Stock sizes a chip as a DOT: height = min-width = text all equal (md is an
+ *      8px dot with 8px text), so a count digit is unreadable. A chip WITH content is distinguishable
+ *      from an empty dot via `:not(:empty)` (an empty dot holds only Vue comment placeholders, which
+ *      `:empty` ignores). So we bump ONLY text chips and leave status dots byte-for-byte stock:
+ *        - base:  `px-1` breathing room + `leading-none` centring, size-independent.
+ *        - size:  per step, a `:not(:empty)` text floor + a min-height/width so a single digit sits
+ *                 in a roughly square pill. `min-height` beats the stock fixed `h-[Npx]` on its own
+ *                 (no `h-auto` needed); the arbitrary `[&:not(:empty)]` variant is (0,2,0), so it
+ *                 wins over the stock `text-[Npx]`/`min-w-[Npx]` (0,1,0) without a tailwind-merge
+ *                 collision. Text scales md 11 → 3xl 15px.
+ *
+ * Everything else is stock: rounded-full pill, the `ring ring-bg` separator, bg-{color} faces
+ * (bridged to the Forest ramps in docs.css), text-inverted ink, position / inset / standalone.
+ * `root` needs no override.
+ */
+export const chipTheme = {
+  slots: {
+    base: 'font-bold [&:not(:empty)]:px-1 [&:not(:empty)]:leading-none',
+  },
+  variants: {
+    // Standalone chips have no host corner to hug, but stock's position compound-variant still
+    // applies `-translate-y-1/2 translate-x-1/2`, shoving the inline dot up-and-right off the text
+    // centre. Zero the translate so a standalone dot sits centred in its flow. Hooked on `.ring`
+    // (always on the base slot) for (0,2,0) specificity — beats the compound regardless of tv
+    // ordering, no !important.
+    standalone: {
+      true: '[&.ring]:translate-x-0 [&.ring]:translate-y-0',
+    },
+    // Per-size text-mode floor — applies ONLY when the chip has content (a count/label), so empty
+    // status dots keep the stock 4–12px ladder untouched.
+    size: {
+      '3xs': '[&:not(:empty)]:min-h-[14px] [&:not(:empty)]:min-w-[14px] [&:not(:empty)]:text-[10px]',
+      '2xs': '[&:not(:empty)]:min-h-[14px] [&:not(:empty)]:min-w-[14px] [&:not(:empty)]:text-[10px]',
+      'xs':  '[&:not(:empty)]:min-h-[15px] [&:not(:empty)]:min-w-[15px] [&:not(:empty)]:text-[10px]',
+      'sm':  '[&:not(:empty)]:min-h-[15px] [&:not(:empty)]:min-w-[15px] [&:not(:empty)]:text-[11px]',
+      'md':  '[&:not(:empty)]:min-h-[16px] [&:not(:empty)]:min-w-[16px] [&:not(:empty)]:text-[11px]',
+      'lg':  '[&:not(:empty)]:min-h-[17px] [&:not(:empty)]:min-w-[17px] [&:not(:empty)]:text-[12px]',
+      'xl':  '[&:not(:empty)]:min-h-[18px] [&:not(:empty)]:min-w-[18px] [&:not(:empty)]:text-[13px]',
+      '2xl': '[&:not(:empty)]:min-h-[20px] [&:not(:empty)]:min-w-[20px] [&:not(:empty)]:text-[14px]',
+      '3xl': '[&:not(:empty)]:min-h-[22px] [&:not(:empty)]:min-w-[22px] [&:not(:empty)]:text-[15px]',
+    },
+  },
+} as const;

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

@@ -0,0 +1,26 @@
+/**
+ * Forest theme fragment — UCollapsible (single animated expand/collapse).
+ *
+ * Deltas over stock (stock: root '', content = raw collapsible keyframes at 200ms ease-out):
+ *   - `root`: adds `rounded-lg` so the container reads at the Forest soft-radius register when
+ *     consumers wrap the collapsible in a bordered shell.
+ *   - `content`: retimes the open/close keyframes to the shared --motion-slow / --motion-ease-out
+ *     tokens (stock is a raw 200ms ease-out) and adds `text-sm text-muted` so body content is
+ *     subordinate in the reading hierarchy — consistent with how the accordion body slot is styled.
+ *     `overflow-hidden` clips the region during the height animation. Trigger styling is entirely the
+ *     consumer's concern; the default slot exposes a scoped `{ open }`.
+ *
+ * Slots touched: root, content.
+ * Slot names sourced from: apps/docs/node_modules/.nuxt-ui/ui/collapsible.ts
+ */
+
+export const collapsibleTheme = {
+  slots: {
+    // rounded-lg: aligns with Forest's --ui-radius = 0.5rem soft-radius register. Keeps the
+    // collapsible shell consistent with other Forest panel-level components (Card, Alert, etc.).
+    root: 'rounded-lg',
+    // text-sm text-muted: matches Forest's body-content hierarchy (content is subordinate to the
+    // trigger/heading above it). The stock open/close keyframe animations are intentionally kept.
+    content: 'data-[state=open]:animate-[collapsible-down_var(--motion-slow)_var(--motion-ease-out)] data-[state=closed]:animate-[collapsible-up_var(--motion-slow)_var(--motion-ease-out)] overflow-hidden text-sm text-muted',
+  },
+} as const;

package/packages/ui/src/themes/color-picker.ts

@@ -0,0 +1,13 @@
+/**
+ * Forest theme fragment — UColorPicker. No delta: the stock recipe is correct as-is.
+ *
+ *   - Selector, gradient canvas and track all sit on rounded-md — already the control-family
+ *     standard, so there is nothing to override.
+ *   - The thumbs are rounded-full with the ring-2 ring-white halo — circular handles are the
+ *     right affordance and the halo is already tactile.
+ *
+ * The empty export keeps the component in the register as reviewed; the deltas-only test keeps
+ * it from ever restating stock.
+ */
+
+export const colorPickerTheme = {} as const