@bearmenu/ui 0.8.7 → 0.8.9

package/dist/components/weekend-panel.js

@@ -1,17 +1,18 @@
+import { useMediaQuery, DESKTOP_MEDIA_QUERY } from '../chunk-OPVKL4VS.js';
 import { MotionPlayPause } from '../chunk-TT3WFS6S.js';
 import '../chunk-2WDJR6K7.js';
+import { useDragSwipe } from '../chunk-IYDH5IU6.js';
 import { Skeleton } from '../chunk-QXHMPJ35.js';
 import { cn } from '../chunk-FEK5XGZW.js';
-import { __objRest, __spreadValues } from '../chunk-3GWWZKX7.js';
+import { __spreadProps, __spreadValues, __objRest } from '../chunk-3GWWZKX7.js';
 import * as React from 'react';
 import { ChevronRight } from 'lucide-react';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
 var WEEKEND_PANEL_TRACK_GAP_PX = 14;
 var WEEKEND_PANEL_DEFAULT_DURATION_SECONDS = 7;
-var WEEKEND_PANEL_SLIDE_KEYFRAMES_ID = "ds-weekend-panel-slide";
-var WEEKEND_PANEL_DOT_A_KEYFRAMES_ID = "ds-weekend-panel-dot-a";
-var WEEKEND_PANEL_DOT_B_KEYFRAMES_ID = "ds-weekend-panel-dot-b";
+var WEEKEND_PANEL_PAGE_COUNT = 2;
+var WEEKEND_PANEL_CARDS_PER_PAGE = 2;
 function usePrefersReducedMotion() {
   const [reduced, setReduced] = React.useState(false);
   React.useEffect(() => {
@@ -30,9 +31,12 @@ function useInViewport() {
   React.useEffect(() => {
     const node = ref.current;
     if (!node || typeof IntersectionObserver === "undefined") return;
-    const observer = new IntersectionObserver(([entry]) => setInView(entry.isIntersecting), {
-      threshold: 0
-    });
+    const observer = new IntersectionObserver(
+      ([entry]) => setInView(entry.isIntersecting),
+      {
+        threshold: 0
+      }
+    );
     observer.observe(node);
     return () => observer.disconnect();
   }, []);
@@ -56,16 +60,36 @@ function WeekendPanel({
   className
 }) {
   const prefersReducedMotion = usePrefersReducedMotion();
+  const isDesktop = useMediaQuery(DESKTOP_MEDIA_QUERY);
   const [panelRef, inView] = useInViewport();
   const [isHovered, setIsHovered] = React.useState(false);
   const [isFocused, setIsFocused] = React.useState(false);
   const [isManuallyPaused, setIsManuallyPaused] = React.useState(false);
   const [playPauseReplayToken, setPlayPauseReplayToken] = React.useState(0);
-  const isPaused = isManuallyPaused || isHovered || isFocused || !inView;
+  const [page, setPage] = React.useState(0);
+  const autoplays = isDesktop && !prefersReducedMotion;
+  const isPaused = !autoplays || isManuallyPaused || isHovered || isFocused || !inView;
+  React.useEffect(() => {
+    if (isPaused) return void 0;
+    const interval = window.setInterval(
+      () => setPage((current) => (current + 1) % WEEKEND_PANEL_PAGE_COUNT),
+      durationSeconds * 1e3 / WEEKEND_PANEL_PAGE_COUNT
+    );
+    return () => window.clearInterval(interval);
+  }, [durationSeconds, isPaused]);
+  const turnTo = (next) => {
+    setPage(Math.max(0, Math.min(WEEKEND_PANEL_PAGE_COUNT - 1, next)));
+    setIsManuallyPaused(true);
+  };
+  const { dragX, isDragging, handlers } = useDragSwipe({
+    onSwipe: (direction) => turnTo(page + direction),
+    disabled: prefersReducedMotion
+  });
   const action = /* @__PURE__ */ jsxs("span", { className: "ml-auto flex items-center gap-0.5 text-[12.5px] text-muted-foreground", children: [
     actionLabel,
     /* @__PURE__ */ jsx(ChevronRight, { className: "h-3.5 w-3.5", "aria-hidden": true })
   ] });
+  const cards = React.Children.toArray(children);
   return /* @__PURE__ */ jsxs(
     "div",
     {
@@ -80,25 +104,6 @@ function WeekendPanel({
         className
       ),
       children: [
-        /* @__PURE__ */ jsx("style", { children: `
-        @keyframes ${WEEKEND_PANEL_SLIDE_KEYFRAMES_ID} {
-          0%, 45% { transform: translateX(0); }
-          50%, 95% { transform: translateX(calc(-100% - ${WEEKEND_PANEL_TRACK_GAP_PX}px)); }
-          100% { transform: translateX(0); }
-        }
-        @keyframes ${WEEKEND_PANEL_DOT_A_KEYFRAMES_ID} {
-          0% { background: var(--primary); width: 18px; }
-          45% { background: var(--primary); width: 18px; }
-          50% { background: color-mix(in oklch, var(--muted-foreground) 35%, transparent); width: 6px; }
-          100% { background: color-mix(in oklch, var(--muted-foreground) 35%, transparent); width: 6px; }
-        }
-        @keyframes ${WEEKEND_PANEL_DOT_B_KEYFRAMES_ID} {
-          0% { background: color-mix(in oklch, var(--muted-foreground) 35%, transparent); width: 6px; }
-          50% { background: color-mix(in oklch, var(--muted-foreground) 35%, transparent); width: 6px; }
-          95% { background: var(--primary); width: 18px; }
-          100% { background: var(--primary); width: 18px; }
-        }
-      ` }),
         /* @__PURE__ */ jsxs("div", { className: "flex items-baseline gap-[9px] px-4 pb-3", children: [
           /* @__PURE__ */ jsx(
             "span",
@@ -130,51 +135,57 @@ function WeekendPanel({
             }
           ) : action
         ] }),
-        prefersReducedMotion ? /* @__PURE__ */ jsx("div", { className: "grid grid-cols-2 gap-3.5 px-4", children }) : /* @__PURE__ */ jsx("div", { className: "overflow-hidden px-4", children: /* @__PURE__ */ jsx(
-          "div",
-          {
-            className: "flex gap-3.5",
-            style: {
-              animationName: WEEKEND_PANEL_SLIDE_KEYFRAMES_ID,
-              animationDuration: `${durationSeconds}s`,
-              animationTimingFunction: "ease-in-out",
-              animationIterationCount: "infinite",
-              animationPlayState: isPaused ? "paused" : "running"
-            },
-            children: React.Children.map(children, (child) => /* @__PURE__ */ jsx("div", { className: "w-[calc((100%-14px)/2)] flex-none", children: child }))
-          }
-        ) }),
+        prefersReducedMotion ? /* @__PURE__ */ jsx("div", { className: "grid grid-cols-2 gap-3.5 px-4", children }) : (
+          // Padding OUTSIDE the clip. `overflow-hidden` clips at the padding
+          // edge, so with the padding on the clipping element the next page's
+          // first card showed through the 16px inset — a sliver of the slide
+          // cutting in. The reader should see exactly the two cards of a page.
+          /* @__PURE__ */ jsx("div", { className: "px-4", children: /* @__PURE__ */ jsx(
+            "div",
+            __spreadProps(__spreadValues({}, handlers), {
+              className: "overflow-hidden select-none [touch-action:pan-y]",
+              children: /* @__PURE__ */ jsx(
+                "div",
+                {
+                  className: cn(
+                    "flex gap-3.5",
+                    !isDragging && "transition-transform duration-[420ms] ease-[cubic-bezier(0.22,1,0.36,1)]"
+                  ),
+                  style: {
+                    transform: `translateX(calc(${-page} * (100% + ${WEEKEND_PANEL_TRACK_GAP_PX}px) + ${dragX}px))`
+                  },
+                  children: cards.map((child, index) => /* @__PURE__ */ jsx(
+                    "div",
+                    {
+                      className: "w-[calc((100%-14px)/2)] flex-none",
+                      onFocus: () => {
+                        const cardPage = Math.floor(
+                          index / WEEKEND_PANEL_CARDS_PER_PAGE
+                        );
+                        if (cardPage !== page) turnTo(cardPage);
+                      },
+                      children: child
+                    },
+                    index
+                  ))
+                }
+              )
+            })
+          ) })
+        ),
         !prefersReducedMotion && /* @__PURE__ */ jsxs("div", { className: "mt-3.5 grid grid-cols-[1fr_auto_1fr] items-center px-4", children: [
           /* @__PURE__ */ jsx("span", { "aria-hidden": true }),
-          /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-center gap-1.5", "aria-hidden": true, children: [
-            /* @__PURE__ */ jsx(
-              "span",
-              {
-                className: "block h-1.5 w-[18px] rounded-full bg-primary",
-                style: {
-                  animationName: WEEKEND_PANEL_DOT_A_KEYFRAMES_ID,
-                  animationDuration: `${durationSeconds}s`,
-                  animationTimingFunction: "ease-in-out",
-                  animationIterationCount: "infinite",
-                  animationPlayState: isPaused ? "paused" : "running"
-                }
-              }
-            ),
-            /* @__PURE__ */ jsx(
-              "span",
-              {
-                className: "block h-1.5 w-1.5 rounded-full bg-muted-foreground/35",
-                style: {
-                  animationName: WEEKEND_PANEL_DOT_B_KEYFRAMES_ID,
-                  animationDuration: `${durationSeconds}s`,
-                  animationTimingFunction: "ease-in-out",
-                  animationIterationCount: "infinite",
-                  animationPlayState: isPaused ? "paused" : "running"
-                }
-              }
-            )
-          ] }),
-          /* @__PURE__ */ jsx("div", { className: "flex justify-end", children: /* @__PURE__ */ jsx(
+          /* @__PURE__ */ jsx("div", { className: "flex items-center justify-center gap-1.5", "aria-hidden": true, children: Array.from({ length: WEEKEND_PANEL_PAGE_COUNT }, (_, index) => /* @__PURE__ */ jsx(
+            "span",
+            {
+              className: cn(
+                "block h-1.5 rounded-full transition-[width,background-color] duration-300 motion-reduce:transition-none",
+                index === page ? "w-[18px] bg-primary" : "w-1.5 bg-muted-foreground/35"
+              )
+            },
+            index
+          )) }),
+          /* @__PURE__ */ jsx("div", { className: "flex justify-end", children: autoplays && /* @__PURE__ */ jsx(
             "button",
             {
               type: "button",
@@ -198,7 +209,10 @@ function WeekendPanel({
     }
   );
 }
-function WeekendPanelSkeleton({ isHighlighted, className }) {
+function WeekendPanelSkeleton({
+  isHighlighted,
+  className
+}) {
   return /* @__PURE__ */ jsxs(
     "div",
     {

package/dist/hooks/use-drag-swipe.d.ts

@@ -0,0 +1,44 @@
+import { PointerEvent } from 'react';
+
+/**
+ * useDragSwipe — horizontal drag-to-step for a stage that is not a native
+ * scroller (a coverflow ring, a paged track). Pointer events, so one code path
+ * covers touch, pen and mouse.
+ *
+ * Returns the live drag distance (`dragX`, for the stage to follow the finger
+ * a little while dragging) and the handlers to spread onto the stage. On
+ * release past `threshold` it calls `onSwipe(-1 | 1)` — `1` for a leftward
+ * drag, i.e. "next". `didDrag` is set for the tick after a real drag so the
+ * stage's `onClickCapture` can swallow the click a drag would otherwise
+ * become on a card underneath.
+ *
+ * The stage keeps vertical scrolling: pair these with `touch-action: pan-y`
+ * so the browser owns vertical gestures and hands only horizontal ones here.
+ * Pointer capture is taken on move, not on down, so a tap still reaches the
+ * card underneath as a plain click.
+ *
+ * `onDragStart` is part of the handlers for a reason: the cards under a stage
+ * are usually links wrapping images, and a mouse drag on either starts a
+ * NATIVE HTML5 drag, which cancels the pointer stream mid-gesture — the swipe
+ * silently never completes. Preventing it keeps the pointer events flowing.
+ */
+type DragSwipeOptions = {
+    /** Distance in px that counts as a swipe. Default 40. */
+    threshold?: number;
+    onSwipe: (direction: -1 | 1) => void;
+    disabled?: boolean;
+};
+declare function useDragSwipe({ threshold, onSwipe, disabled }: DragSwipeOptions): {
+    dragX: number;
+    isDragging: boolean;
+    handlers: {
+        onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+        onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+        onPointerUp: (event: PointerEvent<HTMLElement>) => void;
+        onPointerCancel: (event: PointerEvent<HTMLElement>) => void;
+        onClickCapture: (event: PointerEvent<HTMLElement> | React.MouseEvent) => void;
+        onDragStart: (event: React.DragEvent<HTMLElement>) => void;
+    };
+};
+
+export { type DragSwipeOptions, useDragSwipe };

package/dist/hooks/use-drag-swipe.js

@@ -0,0 +1,2 @@
+export { useDragSwipe } from '../chunk-IYDH5IU6.js';
+import '../chunk-3GWWZKX7.js';

package/dist/hooks/use-media-query.d.ts

@@ -0,0 +1,17 @@
+/**
+ * useMediaQuery — a boolean for a CSS media query that is hydration-safe.
+ *
+ * `useSyncExternalStore` with a fixed server snapshot (`false`) means the
+ * server and the hydrating client render the same tree; the real value
+ * arrives on the next render. Components that switch behaviour per breakpoint
+ * (not just classes) need this rather than `window.matchMedia` in an effect,
+ * which flashes the wrong variant for a frame.
+ *
+ * Mobile-first: `false` on the server and until measured, so the phone
+ * variant is the one that prerenders.
+ */
+declare function useMediaQuery(query: string): boolean;
+/** The design system's desktop breakpoint, Tailwind's `lg`. */
+declare const DESKTOP_MEDIA_QUERY = "(min-width: 1024px)";
+
+export { DESKTOP_MEDIA_QUERY, useMediaQuery };

package/dist/hooks/use-media-query.js

@@ -0,0 +1,2 @@
+export { DESKTOP_MEDIA_QUERY, useMediaQuery } from '../chunk-OPVKL4VS.js';
+import '../chunk-3GWWZKX7.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bearmenu/ui",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "BearMenu design system — shared UI tokens, primitives, and components",
   "license": "UNLICENSED",
   "repository": {

package/src/components/category-deck.tsx

@@ -31,7 +31,11 @@ const DECK_POSTER_COUNT = 4;
 const DECK_TRANSITION =
   "transition-transform duration-[400ms] ease-[cubic-bezier(0.2,0.8,0.2,1)] motion-reduce:transition-none";
 
-const DECK_CARD_TRANSFORMS: ReadonlyArray<{ rest: string; spread: string; z: string }> = [
+const DECK_CARD_TRANSFORMS: ReadonlyArray<{
+  rest: string;
+  spread: string;
+  z: string;
+}> = [
   {
     rest: "[transform:translateX(-50%)_rotate(-9deg)_translateX(-26px)]",
     spread:
@@ -115,13 +119,12 @@ export function CategoryDeck({
 }: CategoryDeckProps) {
   const slots = Array.from(
     { length: DECK_POSTER_COUNT },
-    (_, index): CategoryDeckPoster => posters[index] ?? {}
+    (_, index): CategoryDeckPoster => posters[index] ?? {},
   );
 
   const body = (
     <>
       <div className="relative h-[150px] sm:h-[186px]" aria-hidden>
-
         {slots.map((poster, index) => {
           const transform = DECK_CARD_TRANSFORMS[index];
           return (
@@ -129,12 +132,15 @@ export function CategoryDeck({
               key={index}
               className={cn(
                 "absolute left-1/2 top-0 aspect-[4/5] w-24 overflow-hidden rounded-[10px] bg-muted",
+                // Keyed to --foreground so the shadow is ink in light mode; in
+                // dark mode that same 18% is a light halo, so it drops to 7%.
                 "shadow-[0_10px_26px_color-mix(in_oklch,var(--foreground)_18%,transparent)]",
+                "dark:shadow-[0_10px_26px_color-mix(in_oklch,var(--foreground)_7%,transparent)]",
                 "sm:w-[120px]",
                 transform.rest,
                 transform.spread,
                 transform.z,
-                DECK_TRANSITION
+                DECK_TRANSITION,
               )}
             >
               {poster.content ? (
@@ -161,9 +167,14 @@ export function CategoryDeck({
           <div className="truncate text-[14.5px] font-extrabold tracking-[-0.015em] sm:text-base">
             {name}
           </div>
-          <div className="truncate font-mono text-[11.5px] text-muted-foreground">{meta}</div>
+          <div className="truncate font-mono text-[11.5px] text-muted-foreground">
+            {meta}
+          </div>
         </div>
-        <ChevronRight className="ml-auto h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+        <ChevronRight
+          className="ml-auto h-4 w-4 shrink-0 text-muted-foreground"
+          aria-hidden
+        />
       </div>
     </>
   );
@@ -172,7 +183,7 @@ export function CategoryDeck({
     "group flex min-w-0 flex-col text-left",
     (href || onClick) &&
       "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 rounded-xl",
-    className
+    className,
   );
 
   if (href) {
@@ -209,7 +220,7 @@ export function CategoryDeckSkeleton({ className }: CategoryDeckSkeletonProps) {
             className={cn(
               "absolute left-1/2 top-0 aspect-[4/5] w-24 rounded-[10px] sm:w-[120px]",
               transform.rest,
-              transform.z
+              transform.z,
             )}
           />
         ))}

package/src/components/colour-dictionary.stories.tsx

@@ -0,0 +1,227 @@
+import type { Meta, StoryObj } from "@storybook/react";
+
+/**
+ * Foundations / Colour dictionary — every colour a menu surface paints, in one
+ * table grouped by the forest element it is, with the reason beside it. A page,
+ * not a component: the values live in the consuming app (see the notes under
+ * the table), this is where a person goes to understand them.
+ */
+
+type Chip = { label: string; value: string };
+
+type Row = {
+  element: string;
+  why: string;
+  /** The three `--menu-field-<family>-<n>` tints, when this element is a card-field family. */
+  field?: { family: string; tints: [string, string, string]; draws: string };
+  /** `FAMILY_HUES` entries painted by the hub's family cards (chips, price band, photo tint). */
+  familyCards: Chip[];
+  /** `INTENT_GRADIENTS` entries painted by the hub's intent tiles. */
+  intents: Chip[];
+};
+
+const ROWS: Row[] = [
+  {
+    element: "Wheat and honey",
+    why: "Grain and what goes on it — crust, pasta, pizza base, pastry, yolk — is this gold before it is cooked. Honey in the comb is the same colour, and so is morning light on toast, which is why brunch and beer (roasted malt) sit here too.",
+    field: { family: "larder", tints: ["oklch(0.505 0.11 74)", "oklch(0.555 0.105 80)", "oklch(0.465 0.115 68)"], draws: "bread, pasta, pizza, eggs, sides, sauces, spirits" },
+    familyCards: [{ label: "Breakfast & brunch", value: "oklch(0.62 0.14 82)" }, { label: "Bakeries", value: "oklch(0.58 0.11 72)" }, { label: "Beer", value: "oklch(0.62 0.13 86)" }],
+    intents: [{ label: "Brunch", value: "oklch(0.62 0.14 82)" }],
+  },
+  {
+    element: "Lake water",
+    why: "Fish, shellfish and soup come out of water, and a cocktail is a glass of it. A forest has a lake, not a sea: dark, blue-green, in shade — so the hue stays on the green side (198–220) and never reads as sky or as a pool.",
+    field: { family: "sea", tints: ["oklch(0.485 0.095 205)", "oklch(0.535 0.09 198)", "oklch(0.445 0.095 212)"], draws: "fish, shellfish, soups, cocktails" },
+    familyCards: [{ label: "Cocktails", value: "oklch(0.47 0.10 205)" }],
+    intents: [{ label: "Cocktail bars", value: "oklch(0.47 0.10 205)" }],
+  },
+  {
+    element: "Ember and terracotta",
+    why: "Meat is the family cooked over fire: the red of the coals, the crust on beef, cured and smoked meat. Red wine shares the glass and the colour. Terracotta is the same fire one step warmer — the oven's brick and the tomato — which is why Italian sits beside Romanian here.",
+    field: { family: "meat", tints: ["oklch(0.49 0.13 28)", "oklch(0.54 0.13 34)", "oklch(0.45 0.13 22)"], draws: "beef, game, cured meat, burgers, red wine" },
+    familyCards: [{ label: "Romanian", value: "oklch(0.48 0.16 25)" }, { label: "Italian", value: "oklch(0.56 0.15 38)" }],
+    intents: [{ label: "Burgers", value: "oklch(0.48 0.16 25)" }, { label: "Italian tonight", value: "oklch(0.56 0.15 38)" }],
+  },
+  {
+    element: "Maple and amber",
+    why: "Sugar turns this colour when it meets heat: caramel, syrup, the top of a crème brûlée, the maple leaf in autumn — and a pizza crust out of the oven, which is why the Pizza card wears it. Beer's amber is the same chemistry, malt roasted, so beer items draw this field even though the beer card wears honey.",
+    field: { family: "sweet", tints: ["oklch(0.505 0.14 50)", "oklch(0.555 0.135 58)", "oklch(0.465 0.14 44)"], draws: "desserts, pastry, beer" },
+    familyCards: [{ label: "Pizza", value: "oklch(0.52 0.14 58)" }],
+    intents: [],
+  },
+  {
+    element: "Fern and pine",
+    why: "The leaf itself. Salads, vegetables and the non-alcoholic glass — juice, lemonade, the herb in it — are the green things on the menu and take the forest's own green: pine-deep rather than lime, so it stays a forest and not a lawn.",
+    field: { family: "verdant", tints: ["oklch(0.505 0.115 148)", "oklch(0.555 0.11 138)", "oklch(0.465 0.115 156)"], draws: "salads, vegetables, non-alcoholic" },
+    familyCards: [{ label: "Vegetarian", value: "oklch(0.52 0.14 148)" }, { label: "Vegan", value: "oklch(0.55 0.12 135)" }],
+    intents: [{ label: "Vegan", value: "oklch(0.52 0.14 148)" }],
+  },
+  {
+    element: "Bark and walnut",
+    why: "The roasted bean is the colour of tree bark, and a coffee house is made of both — wood and roast. Walnut is the same brown darker: a lit doorway at night, which is what \"open right now\" looks like from the street. Coffee items themselves draw the non-alcoholic field (pine), not this.",
+    familyCards: [{ label: "Coffee", value: "oklch(0.44 0.10 52)" }],
+    intents: [{ label: "Coffee", value: "oklch(0.44 0.10 52)" }, { label: "Open right now", value: "oklch(0.44 0.08 62)" }],
+  },
+  {
+    element: "Rosehip",
+    why: "The forest's berry: the jam in the tart, the fruit on the cake, the glass of red. A red with no purple in it — the magenta and violet it replaced belong to no place a bear has been.",
+    familyCards: [{ label: "Wine by the glass", value: "oklch(0.48 0.14 12)" }],
+    intents: [{ label: "Patisseries", value: "oklch(0.52 0.15 12)" }],
+  },
+  {
+    element: "Moss in sun",
+    why: "The sunlit forest floor. Yellow-green because a terrace is the one intent about being outdoors in daylight; deeper than lime so it is ground, not a highlighter.",
+    familyCards: [],
+    intents: [{ label: "On a terrace", value: "oklch(0.60 0.13 122)" }],
+  },
+  {
+    element: "Stone",
+    why: "No colour of its own. An untagged dish gets it because there is no ingredient to be coloured by; Centru gets it because the town is the one intent that is a place and not a taste. Never a section mark — as a mark, grey reads as absent.",
+    field: { family: "neutral", tints: ["oklch(0.505 0.02 60)", "oklch(0.555 0.022 66)", "oklch(0.465 0.018 54)"], draws: "an untagged dish only" },
+    familyCards: [],
+    intents: [{ label: "In Centru", value: "oklch(0.50 0.03 70)" }],
+  },
+];
+
+const NOT_THESE: Chip[] = [
+  { label: "sky blue", value: "oklch(0.5 0.13 240)" },
+  { label: "teal", value: "oklch(0.55 0.12 190)" },
+  { label: "violet", value: "oklch(0.5 0.11 300)" },
+  { label: "magenta", value: "oklch(0.52 0.13 340)" },
+  { label: "olive-yellow", value: "oklch(0.58 0.12 95)" },
+];
+
+const darker = (value: string) =>
+  value.replace(/oklch\(([\d.]+) /, (_m, l: string) => `oklch(${(Number(l) - 0.09).toFixed(3)} `);
+
+function Swatch({ label, value, angle = 135, tall }: Chip & { angle?: number; tall?: boolean }) {
+  return (
+    <div className="flex w-[104px] shrink-0 flex-col gap-1">
+      <span
+        aria-hidden
+        className={tall ? "block h-14 rounded-lg" : "block h-9 rounded-lg"}
+        style={{ backgroundImage: `linear-gradient(${angle}deg, ${value}, ${darker(value)})` }}
+      />
+      <span className="text-[11px] font-semibold leading-tight">{label}</span>
+      <code className="text-[9.5px] leading-tight text-muted-foreground">{value.replace("oklch(", "").replace(")", "")}</code>
+    </div>
+  );
+}
+
+const TH = "px-3 py-2 text-left text-[11px] font-bold uppercase tracking-[0.08em] text-muted-foreground";
+const TD = "px-3 py-3 align-top";
+
+function ColourDictionaryPage() {
+  return (
+    <article className="mx-auto max-w-[1440px] px-6 py-7 text-foreground">
+      <p className="text-[11px] font-bold uppercase tracking-[0.09em] text-muted-foreground">Foundations</p>
+      <h1 className="mt-0.5 text-[26px] font-extrabold tracking-[-0.02em]">The menu colour dictionary</h1>
+      <p className="mt-1 max-w-[90ch] text-[14px] leading-[1.55] text-foreground/85">
+        Every hue is a forest object, at full strength — the floor and canopy of a forest and what a bear eats off it.
+        Every colour a menu surface paints is in this table, grouped by the element it is, with why it belongs.
+        <span className="ml-2 inline-flex items-center gap-2 align-middle text-[12px] text-muted-foreground">
+          Not in the forest, so not in the palette:
+          {NOT_THESE.map((c) => (
+            <span key={c.label} className="inline-flex items-center gap-1 line-through">
+              <span aria-hidden className="inline-block h-3.5 w-5 rounded-sm" style={{ background: c.value }} />
+              {c.label}
+            </span>
+          ))}
+        </span>
+      </p>
+
+      <div className="mt-5 overflow-x-auto rounded-xl border border-border">
+        <table className="w-full min-w-[1180px] border-collapse text-[13px]">
+          <thead className="bg-muted/60">
+            <tr>
+              <th className={`${TH} w-[290px]`}>Element · why it belongs</th>
+              <th className={TH}>Card fields · the three tints</th>
+              <th className={TH}>Family cards · chips, price band, photo tint</th>
+              <th className={TH}>Intent tiles</th>
+            </tr>
+          </thead>
+          <tbody>
+            {ROWS.map((row) => (
+              <tr key={row.element} className="border-t border-border">
+                <td className={TD}>
+                  <div className="text-[15px] font-extrabold tracking-[-0.01em]">{row.element}</div>
+                  <p className="mt-1 text-[12.5px] leading-[1.5] text-foreground/85">{row.why}</p>
+                </td>
+                <td className={TD}>
+                  {row.field ? (
+                    <div className="flex flex-col gap-2">
+                      <div className="flex gap-2">
+                        {row.field.tints.map((tint, index) => (
+                          <Swatch key={tint} label={`${row.field!.family}-${index}`} value={tint} tall />
+                        ))}
+                      </div>
+                      <div className="text-[11.5px] text-muted-foreground">
+                        <span className="font-semibold text-foreground/80">draws</span> {row.field.draws}
+                      </div>
+                    </div>
+                  ) : (
+                    <span className="text-[12px] text-muted-foreground">—</span>
+                  )}
+                </td>
+                <td className={TD}>
+                  {row.familyCards.length ? (
+                    <div className="flex gap-2">
+                      {row.familyCards.map((c) => (
+                        <Swatch key={c.label} {...c} angle={150} />
+                      ))}
+                    </div>
+                  ) : (
+                    <span className="text-[12px] text-muted-foreground">—</span>
+                  )}
+                </td>
+                <td className={TD}>
+                  {row.intents.length ? (
+                    <div className="flex gap-2">
+                      {row.intents.map((c) => (
+                        <Swatch key={c.label} {...c} angle={150} />
+                      ))}
+                    </div>
+                  ) : (
+                    <span className="text-[12px] text-muted-foreground">—</span>
+                  )}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      <div className="mt-8 grid gap-8 md:grid-cols-3">
+        <section>
+          <h2 className="text-[15px] font-extrabold">How a colour is chosen</h2>
+          <ol className="mt-2 list-decimal space-y-1.5 pl-4 text-[13px] leading-[1.55] text-foreground/85">
+            <li><b>What is the family made of, or where is it consumed?</b> Grain, fire, water, sugar, leaf; a night out, a morning, the town.</li>
+            <li><b>Which forest element already has that colour — literally?</b> Wheat is gold, embers are red, lake water is blue-green. If nothing in a forest has it, it does not go in; that is how violet and magenta left.</li>
+            <li><b>Take it at full strength.</b> An early pass pulled every chroma down to feel earthy and read as faded. Keep lightness 0.44–0.62 so white type at 0.26–0.30 alpha stays readable.</li>
+          </ol>
+        </section>
+        <section>
+          <h2 className="text-[15px] font-extrabold">The colour names a family, never an item</h2>
+          <p className="mt-2 text-[13px] leading-[1.55] text-foreground/85">
+            Sixteen appetizers draw one colour. Two dishes in one family differ only by one of the three tints, keyed on the parent concept so the same dish is the same tint on every menu and after every re-sort. A category's section mark always uses tint <code>-0</code>. Where a family has both a card and an intent tile, they share the value so the two doors to one page agree.
+          </p>
+        </section>
+        <section>
+          <h2 className="text-[15px] font-extrabold">Where the values live</h2>
+          <p className="mt-2 text-[13px] leading-[1.55] text-foreground/85">
+            The design system owns the typography, the falloff and the layering (<code>MenuField</code>, <code>MenuFamilyCard</code>, <code>MenuIntentTiles</code>) and takes a finished colour as a prop. The palette lives in the fe app: the eighteen <code>--menu-field-*</code> tokens in <code>app/globals.css</code>, <code>FAMILY_HUES</code> and <code>INTENT_GRADIENTS</code> in <code>hub-gradients.ts</code>, category → family in <code>category-colors.ts</code>. The Storybook mocks carry the same values so post-generator films what the app paints.
+          </p>
+        </section>
+      </div>
+    </article>
+  );
+}
+
+const meta: Meta<typeof ColourDictionaryPage> = {
+  title: "Foundations/Colour dictionary",
+  component: ColourDictionaryPage,
+  parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+export const Page: StoryObj<typeof ColourDictionaryPage> = {};