@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.31

package/dist/test/render.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+import { RenderOptions } from "@testing-library/react";
+/**
+ * Renders with the provider stack every component in the library expects at
+ * runtime: `ThemeProvider` (component theme overrides context) wrapping
+ * `SurfaceProvider` pinned to the page floor rung (1) — the same substrate a
+ * top-level component sits on in a real app.
+ */
+export declare function renderWithProviders(ui: React.ReactElement, options?: Omit<RenderOptions, "wrapper">): import("@testing-library/react").RenderResult<typeof import("@testing-library/dom/types/queries"), HTMLElement, HTMLElement>;
+export { screen, within, waitFor, act, fireEvent } from "@testing-library/react";
+export { default as userEvent } from "@testing-library/user-event";

package/dist/test/setup.d.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/vitest";

package/dist/theme/SurfaceContext.d.ts

@@ -0,0 +1,98 @@
+import React, { ReactNode } from "react";
+/**
+ * Relative-elevation engine (Fluid Functionalism substrate context).
+ *
+ * Surfaces live on an 8-rung ladder (`--surface-1…8`). Instead of a fixed colour, a
+ * participating surface (Card, Modal, Popover, Dropdown…) reads the rung it is sitting
+ * ON from context and paints **one or more rungs above it** — PURE-RELATIVE — then
+ * provides its own rung to its children so nesting accumulates. The colour therefore
+ * always tracks the background (a menu on the page / in a popover / in a dialog renders
+ * three different shades). In light mode rungs 3–8 are all white, so the lift shows via
+ * the doubling shadow ladder rather than colour (`surfaceClasses` drives both).
+ *
+ * React context flows through portals (it follows the render tree, not the DOM), so a
+ * `<SurfaceProvider>` written as an overlay's JSX ancestor reaches its portaled content
+ * with no special threading.
+ */
+/** An elevation rung. The page/body floor is rung 1. */
+export type SurfaceLevel = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/** What callers may pass to an `elevation` prop: a raw rung or a semantic alias. */
+export type SurfaceElevation = SurfaceLevel | "background" | "surface" | "raised" | "overlay";
+/** Resolve a `SurfaceElevation` (semantic name or number) to a concrete rung. */
+export declare const resolveElevation: (elevation: SurfaceElevation) => SurfaceLevel;
+export interface SurfaceClassOptions {
+    /** Paint at 80% opacity (for frosted overlays that also set `backdrop-blur`). */
+    translucent?: boolean;
+    /** Include the per-rung elevation shadow (default `true`). */
+    shadow?: boolean;
+}
+/**
+ * Background + shadow utility classes for a rung. Place FIRST in `cn(...)` so a caller's
+ * `className` (the shadcn override) always wins.
+ *
+ * Returns a plain space-joined literal — the bg and shadow classes never conflict, so there
+ * is nothing for `twMerge` to resolve here. The call site already runs the result through
+ * `cn(...)`; running `twMerge` a second time inside would be pure waste on a hot render path.
+ */
+export declare const surfaceClasses: (level: SurfaceLevel, options?: SurfaceClassOptions) => string;
+/** The rung the current subtree is sitting ON (the substrate). Page floor = 1. */
+export declare const useSurfaceLevel: () => SurfaceLevel;
+/** Pure-relative lift: a child sitting on `substrate` paints `substrate + offset`. */
+export declare const liftLevel: (substrate: SurfaceLevel, offset?: number) => SurfaceLevel;
+export interface SurfaceProviderProps {
+    /** The rung this surface paints at — becomes the substrate for descendants. */
+    level: SurfaceLevel;
+    children: ReactNode;
+}
+/** Tell descendants which rung they are sitting on. */
+export declare const SurfaceProvider: ({ level, children }: SurfaceProviderProps) => React.ReactElement;
+/** Public override props every participating surface component accepts. */
+export interface SurfaceElevationProps {
+    /**
+     * Pin the surface elevation rung (overrides the automatic relative lift) — a rung
+     * number (1–8) or a semantic alias (`"surface"`/`"raised"`/`"overlay"`…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the component's base rung. */
+    lift?: boolean;
+}
+export interface UseSurfaceElevationArgs extends SurfaceElevationProps {
+    /**
+     * The component's semantic identity rung — the rung it paints when grounded or when
+     * lifting is opted out (`lift={false}`). Card = 3, Modal/Drawer = 4, overlays = 5.
+     */
+    baseRung: SurfaceLevel;
+    /** Pure-relative lift above the substrate (default 1). Tune per component visually. */
+    offset?: number;
+    /**
+     * Backdrop overlay — render at a FIXED rung (`baseRung`) ignoring the inherited
+     * substrate. A Modal/Drawer/CommandPalette/Toast covers the viewport (or portals to a
+     * page-level toaster), so it is conceptually grounded on the floor no matter where its
+     * JSX lives; without this it would inherit the rung of whatever container its `<Modal>`
+     * tag happens to sit inside and render too bright. Anchored overlays (Dropdown/Popover/
+     * Tooltip/…) leave this `false` so they lift relative to their host.
+     */
+    ground?: boolean;
+}
+/**
+ * Resolve the rung a participating component should paint at. Override precedence:
+ * `elevation` (pin) › `ground`/`lift={false}` (pin to baseRung) › pure-relative `substrate + offset`.
+ *
+ * NOTE: the relative default deliberately does NOT floor at `baseRung` (`max(base, …)`) — that
+ * would pin a standalone overlay to a fixed rung and reproduce the "menu is the same colour as a
+ * low host" bug. The lift is purely relative; `baseRung` is the grounded / opt-out target.
+ */
+export declare function useSurfaceElevation({ baseRung, offset, elevation, lift, ground, }: UseSurfaceElevationArgs): SurfaceLevel;
+export interface SurfaceProps extends React.HTMLAttributes<HTMLDivElement>, SurfaceClassOptions {
+    /** Explicit rung/semantic to pin; omit to lift one rung above the substrate. */
+    elevation?: SurfaceElevation;
+    /** Relative lift above substrate when `elevation` is omitted (default 1). */
+    offset?: number;
+    children?: ReactNode;
+}
+/**
+ * Generic surface primitive / region escape hatch: paints itself at a rung and provides
+ * that rung to its children. Use to manually control elevation for a subtree
+ * (`<Surface elevation="surface">…</Surface>`).
+ */
+export declare const Surface: ({ elevation, offset, translucent, shadow, className, children, ...rest }: SurfaceProps) => React.ReactElement;

package/dist/theme/SurfaceContext.js

@@ -0,0 +1,114 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useContext } from 'react';
+import { cn } from '../utils/cn.js';
+
+const SEMANTIC_RUNG = {
+    background: 1,
+    surface: 3,
+    raised: 4,
+    overlay: 5,
+};
+const MIN_LEVEL = 1;
+const MAX_LEVEL = 8;
+const clampLevel = (n) => Math.max(MIN_LEVEL, Math.min(MAX_LEVEL, Math.round(n)));
+/** Resolve a `SurfaceElevation` (semantic name or number) to a concrete rung. */
+const resolveElevation = (elevation) => typeof elevation === "number" ? clampLevel(elevation) : SEMANTIC_RUNG[elevation];
+// ── purge-safe literal maps ───────────────────────────────────────────────────────
+// ⚠️ Every class MUST stay a verbatim literal (mirror Grid.theme.ts). Tailwind v4 scans
+// this source text to decide which utilities to emit — NEVER build `surface-${n}` at
+// runtime or the classes drop from the scan and break in production CSS.
+const SURFACE_BG = {
+    1: "bg-[var(--surface-1)]",
+    2: "bg-[var(--surface-2)]",
+    3: "bg-[var(--surface-3)]",
+    4: "bg-[var(--surface-4)]",
+    5: "bg-[var(--surface-5)]",
+    6: "bg-[var(--surface-6)]",
+    7: "bg-[var(--surface-7)]",
+    8: "bg-[var(--surface-8)]",
+};
+const SURFACE_BG_TRANSLUCENT = {
+    1: "bg-[var(--surface-1)]/80",
+    2: "bg-[var(--surface-2)]/80",
+    3: "bg-[var(--surface-3)]/80",
+    4: "bg-[var(--surface-4)]/80",
+    5: "bg-[var(--surface-5)]/80",
+    6: "bg-[var(--surface-6)]/80",
+    7: "bg-[var(--surface-7)]/80",
+    8: "bg-[var(--surface-8)]/80",
+};
+const SURFACE_SHADOW = {
+    1: "shadow-surface-1",
+    2: "shadow-surface-2",
+    3: "shadow-surface-3",
+    4: "shadow-surface-4",
+    5: "shadow-surface-5",
+    6: "shadow-surface-6",
+    7: "shadow-surface-7",
+    8: "shadow-surface-8",
+};
+// Each surface publishes `--field-fill` = the rung ONE ABOVE itself, so a text field placed inside
+// it lifts a step out of the surface (lighter in dark; still white in light, where rungs 3–8 are all
+// white). Inputs read `bg-[var(--field-fill)]` and inherit this via the CSS cascade — no per-input
+// wiring. Clamped at 8. Arbitrary-property utilities are purge-safe literals (like the maps above).
+const SURFACE_FIELD_FILL = {
+    1: "[--field-fill:var(--surface-2)]",
+    2: "[--field-fill:var(--surface-3)]",
+    3: "[--field-fill:var(--surface-4)]",
+    4: "[--field-fill:var(--surface-5)]",
+    5: "[--field-fill:var(--surface-6)]",
+    6: "[--field-fill:var(--surface-7)]",
+    7: "[--field-fill:var(--surface-8)]",
+    8: "[--field-fill:var(--surface-8)]",
+};
+/**
+ * Background + shadow utility classes for a rung. Place FIRST in `cn(...)` so a caller's
+ * `className` (the shadcn override) always wins.
+ *
+ * Returns a plain space-joined literal — the bg and shadow classes never conflict, so there
+ * is nothing for `twMerge` to resolve here. The call site already runs the result through
+ * `cn(...)`; running `twMerge` a second time inside would be pure waste on a hot render path.
+ */
+const surfaceClasses = (level, options = {}) => {
+    const { translucent = false, shadow = true } = options;
+    const bg = (translucent ? SURFACE_BG_TRANSLUCENT : SURFACE_BG)[level];
+    const field = SURFACE_FIELD_FILL[level];
+    return shadow ? `${bg} ${SURFACE_SHADOW[level]} ${field}` : `${bg} ${field}`;
+};
+// ── context ───────────────────────────────────────────────────────────────────────
+const SurfaceLevelContext = createContext(1);
+/** The rung the current subtree is sitting ON (the substrate). Page floor = 1. */
+const useSurfaceLevel = () => useContext(SurfaceLevelContext);
+/** Pure-relative lift: a child sitting on `substrate` paints `substrate + offset`. */
+const liftLevel = (substrate, offset = 1) => clampLevel(substrate + offset);
+/** Tell descendants which rung they are sitting on. */
+const SurfaceProvider = ({ level, children }) => (jsx(SurfaceLevelContext.Provider, { value: level, children: children }));
+/**
+ * Resolve the rung a participating component should paint at. Override precedence:
+ * `elevation` (pin) › `ground`/`lift={false}` (pin to baseRung) › pure-relative `substrate + offset`.
+ *
+ * NOTE: the relative default deliberately does NOT floor at `baseRung` (`max(base, …)`) — that
+ * would pin a standalone overlay to a fixed rung and reproduce the "menu is the same colour as a
+ * low host" bug. The lift is purely relative; `baseRung` is the grounded / opt-out target.
+ */
+function useSurfaceElevation({ baseRung, offset = 1, elevation, lift = true, ground = false, }) {
+    const substrate = useSurfaceLevel();
+    if (elevation != null)
+        return resolveElevation(elevation);
+    if (ground || !lift)
+        return baseRung;
+    return liftLevel(substrate, offset);
+}
+/**
+ * Generic surface primitive / region escape hatch: paints itself at a rung and provides
+ * that rung to its children. Use to manually control elevation for a subtree
+ * (`<Surface elevation="surface">…</Surface>`).
+ */
+const Surface = ({ elevation, offset = 1, translucent, shadow, className, children, ...rest }) => {
+    const substrate = useSurfaceLevel();
+    const level = elevation != null ? resolveElevation(elevation) : liftLevel(substrate, offset);
+    return (jsx(SurfaceProvider, { level: level, children: jsx("div", { className: cn(surfaceClasses(level, { translucent, shadow }), className), ...rest, children: children }) }));
+};
+
+export { Surface, SurfaceProvider, liftLevel, resolveElevation, surfaceClasses, useSurfaceElevation, useSurfaceLevel };

package/dist/theme/ThemeContext.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useMemo, useContext } from 'react';
+
+// Create context with default theme
+const ThemeContext = createContext({
+    theme: {
+        components: {
+        // Default component themes
+        }
+    }
+});
+const ThemeProvider = ({ theme = {}, children }) => {
+    const value = useMemo(() => ({ theme }), [theme]);
+    return (jsx(ThemeContext.Provider, { value: value, children: children }));
+};
+const useTheme = () => useContext(ThemeContext);
+
+export { ThemeProvider, useTheme };

package/dist/theme/animations.d.ts

@@ -0,0 +1,75 @@
+import { Variants } from "motion/react";
+export type AnimationSide = "top" | "bottom" | "left" | "right";
+/**
+ * Centered spring presets for unified motion across the library.
+ * Designed to feel natural, responsive, and premium.
+ */
+export declare const springs: {
+    /** High-end tuning for small overlays (dropdowns, popovers, select menus, tooltips). Damping ratio ≈ 0.9. */
+    premium: {
+        type: "spring";
+        stiffness: number;
+        damping: number;
+    };
+    /** Soft, elegant tuning for larger panels (drawers, dialogs, slide-overs). Damping ratio ≈ 0.93. */
+    smooth: {
+        type: "spring";
+        stiffness: number;
+        damping: number;
+        mass: number;
+    };
+    /** Quick, responsive tuning for minor state transitions (switches, toggles, badge bounces). */
+    snappy: {
+        type: "spring";
+        stiffness: number;
+        damping: number;
+    };
+    /** Organic, relaxed tuning for decorative or slow-moving elements. */
+    gentle: {
+        type: "spring";
+        stiffness: number;
+        damping: number;
+    };
+};
+/**
+ * Standard cubic-bezier easing presets for CSS/framer-motion tween animations.
+ */
+export declare const easings: {
+    easeOut: [number, number, number, number];
+    easeIn: [number, number, number, number];
+    easeInOut: [number, number, number, number];
+};
+interface OverlayVariantsOptions {
+    /** The starting scale factor of the menu. Defaults to 0.97. */
+    scale?: number;
+    /** The shift distance in pixels from the target side. Defaults to 6. */
+    shift?: number;
+    /** The transition configuration for the enter state. Defaults to springs.premium. */
+    enterTransition?: any;
+    /** The transition configuration for the exit state. Defaults to 0.12s easeIn. */
+    exitTransition?: any;
+}
+/**
+ * Generates context-aware animation variants for popups, dropdowns, and selects.
+ * Automatically handles slide direction and opacity based on which side the overlay opens from.
+ *
+ * @param side The viewport side where the menu opened relative to the trigger.
+ * @param options Styling and transition customisations.
+ */
+export declare const getOverlayMenuVariants: (side: AnimationSide, options?: OverlayVariantsOptions) => Variants;
+/**
+ * Unified backdrop animations (fade-in / fade-out) for drawers, modals, and popovers.
+ */
+export declare const overlayBackdropAnimations: Variants;
+interface ExpandCollapseVariantsOptions {
+    /** The stagger duration between child node animations. Defaults to 0.03. */
+    staggerChildren?: number;
+    /** The delay before starting child node animations. Defaults to 0.03. */
+    delayChildren?: number;
+}
+/**
+ * Generates smooth vertical expand/collapse animation variants for collapsible panels
+ * (like Accordions, Tree nodes, and Collapsible menus).
+ */
+export declare const getExpandCollapseVariants: (options?: ExpandCollapseVariantsOptions) => Variants;
+export {};

package/dist/theme/animations.js

@@ -0,0 +1,132 @@
+"use client";
+/**
+ * Centered spring presets for unified motion across the library.
+ * Designed to feel natural, responsive, and premium.
+ */
+const springs = {
+    /** High-end tuning for small overlays (dropdowns, popovers, select menus, tooltips). Damping ratio ≈ 0.9. */
+    premium: {
+        type: "spring",
+        stiffness: 380,
+        damping: 35,
+    },
+    /** Soft, elegant tuning for larger panels (drawers, dialogs, slide-overs). Damping ratio ≈ 0.93. */
+    smooth: {
+        type: "spring",
+        stiffness: 280,
+        damping: 28,
+        mass: 0.8,
+    },
+    /** Quick, responsive tuning for minor state transitions (switches, toggles, badge bounces). */
+    snappy: {
+        type: "spring",
+        stiffness: 500,
+        damping: 30,
+    },
+    /** Organic, relaxed tuning for decorative or slow-moving elements. */
+    gentle: {
+        type: "spring",
+        stiffness: 200,
+        damping: 25,
+    },
+};
+/**
+ * Standard cubic-bezier easing presets for CSS/framer-motion tween animations.
+ */
+const easings = {
+    easeOut: [0, 0, 0.2, 1],
+    easeIn: [0.4, 0, 1, 1],
+    easeInOut: [0.4, 0, 0.2, 1],
+};
+/**
+ * Generates context-aware animation variants for popups, dropdowns, and selects.
+ * Automatically handles slide direction and opacity based on which side the overlay opens from.
+ *
+ * @param side The viewport side where the menu opened relative to the trigger.
+ * @param options Styling and transition customisations.
+ */
+const getOverlayMenuVariants = (side, options = {}) => {
+    const { scale = 0.97, shift = 6, enterTransition = springs.premium, exitTransition = { duration: 0.12, ease: "easeIn" }, } = options;
+    const closedShift = side === "top"
+        ? { y: shift }
+        : side === "left"
+            ? { x: shift }
+            : side === "right"
+                ? { x: -shift }
+                : { y: -shift };
+    return {
+        initial: { opacity: 0, scale, x: 0, y: 0, ...closedShift },
+        hidden: { opacity: 0, scale, x: 0, y: 0, ...closedShift },
+        visible: {
+            opacity: 1,
+            scale: 1,
+            x: 0,
+            y: 0,
+            transition: enterTransition,
+        },
+        animate: {
+            opacity: 1,
+            scale: 1,
+            x: 0,
+            y: 0,
+            transition: enterTransition,
+        },
+        exit: {
+            opacity: 0,
+            scale,
+            x: 0,
+            y: 0,
+            ...closedShift,
+            transition: exitTransition,
+        },
+    };
+};
+/**
+ * Unified backdrop animations (fade-in / fade-out) for drawers, modals, and popovers.
+ */
+const overlayBackdropAnimations = {
+    initial: { opacity: 0 },
+    animate: { opacity: 1, transition: { duration: 0.15 } },
+    exit: { opacity: 0, transition: { duration: 0.1 } },
+};
+/**
+ * Generates smooth vertical expand/collapse animation variants for collapsible panels
+ * (like Accordions, Tree nodes, and Collapsible menus).
+ */
+const getExpandCollapseVariants = (options = {}) => {
+    const { staggerChildren = 0.03, delayChildren = 0.03 } = options;
+    return {
+        expanded: {
+            height: "auto",
+            opacity: 1,
+            transition: {
+                height: {
+                    type: "spring",
+                    stiffness: 280,
+                    damping: 28,
+                    mass: 0.8,
+                },
+                opacity: { duration: 0.2 },
+                staggerChildren,
+                delayChildren,
+            },
+        },
+        collapsed: {
+            height: 0,
+            opacity: 0,
+            transition: {
+                height: {
+                    type: "spring",
+                    stiffness: 280,
+                    damping: 28,
+                    mass: 0.8,
+                },
+                opacity: { duration: 0.15 },
+                staggerChildren: staggerChildren * 0.5,
+                staggerDirection: -1,
+            },
+        },
+    };
+};
+
+export { easings, getExpandCollapseVariants, getOverlayMenuVariants, overlayBackdropAnimations, springs };

package/dist/theme/index.d.ts

@@ -0,0 +1,5 @@
+export { ThemeProvider, useTheme } from "./ThemeContext";
+export type { ThemeConfig, ThemeProviderProps } from "./ThemeContext";
+export { Surface, SurfaceProvider, surfaceClasses, useSurfaceLevel, useSurfaceElevation, liftLevel, resolveElevation, } from "./SurfaceContext";
+export type { SurfaceLevel, SurfaceElevation, SurfaceElevationProps, SurfaceClassOptions, SurfaceProviderProps, SurfaceProps, UseSurfaceElevationArgs, } from "./SurfaceContext";
+export * from "./animations";

package/dist/theme.css

@@ -0,0 +1,28 @@
+/* NOTE: this file ships as dist/theme.css (copied verbatim by build:copy-css) and is
+   only ever consumed from there. Paths below are therefore resolved relative to dist/:
+   `../src/global.scss` = the shipped src/global.scss (package.json `files` ships src/global.scss
+   + src/styles), and `../dist` = the built components scanned for used classes. */
+@source "../dist";
+@import "../src/global.scss";
+
+@theme {
+  --font-weight-light: 300;
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+  --font-weight-extrabold: 800;
+}
+
+/* bg-image arbitrary value support for consumers */
+@utility bg-image-scale-* {
+  --bg-image-scale: --value([number]);
+}
+
+@utility bg-image-blur-* {
+  --bg-image-blur: --value([length]);
+}
+
+@utility bg-image-opacity-* {
+  --bg-image-opacity: --value([number], [percentage]);
+}

package/dist/themes/ember.css

@@ -0,0 +1,131 @@
+/* ============================================================
+   @flikk/ui — Ember theme
+   Coral/burnt-orange primary × Plus Jakarta Sans × pill geometry × zinc neutrals.
+
+   Usage (import AFTER styles.css):
+     import "@flikk/ui/styles.css";
+     import "@flikk/ui/themes/ember.css";
+
+   Theme-file authoring rules (applies to every preset theme):
+   - All rules live in `@layer theme` — an unlayered :root would beat the
+     layered `.dark` overrides in styles.css and break dark mode.
+   - Any token overridden here in :root that styles.css ALSO overrides in
+     `.dark` MUST get an explicit `.dark` value below (this file is later in
+     source order, so its :root wins over styles.css's `.dark` otherwise).
+   - Never redeclare `--color-*-contrast` — it auto-derives from the live
+     base var (see CLAUDE.md §3).
+   ============================================================ */
+@import url("https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,400&display=swap");
+
+@layer theme {
+  :root {
+    /* Primary — Tailwind v4 orange ramp (coral/terracotta accent) */
+    --color-primary-50: oklch(98% 0.016 73.684);
+    --color-primary-100: oklch(95.4% 0.038 75.164);
+    --color-primary-200: oklch(90.1% 0.076 70.697);
+    --color-primary-300: oklch(83.7% 0.128 66.29);
+    --color-primary-400: oklch(75% 0.183 55.934);
+    --color-primary-500: oklch(70.5% 0.213 47.604);
+    --color-primary-600: oklch(64.6% 0.222 41.116);
+    --color-primary-700: oklch(55.3% 0.195 38.402);
+    --color-primary-800: oklch(47% 0.157 37.304);
+    --color-primary-900: oklch(40.8% 0.123 38.172);
+    --color-primary-950: oklch(26.6% 0.079 36.259);
+    --color-primary: var(--color-primary-600);
+
+    /* Neutrals — Tailwind v4 zinc ramp (cool near-neutral cast; reads as the
+       dark navy-black used for filled badges/buttons/headings in the
+       reference dashboard). Dark text tokens reference these rungs by var(),
+       so dark picks the cast up too. */
+    --color-mono-50: oklch(98.5% 0 0);
+    --color-mono-100: oklch(96.7% 0.001 286.375);
+    --color-mono-200: oklch(92% 0.004 286.32);
+    --color-mono-300: oklch(87.1% 0.006 286.286);
+    --color-mono-400: oklch(70.5% 0.015 286.067);
+    --color-mono-500: oklch(55.2% 0.016 285.938);
+    --color-mono-600: oklch(44.2% 0.017 285.786);
+    --color-mono-700: oklch(37% 0.013 285.805);
+    --color-mono-800: oklch(27.4% 0.006 286.033);
+    --color-mono-900: oklch(21% 0.006 285.885);
+    --color-mono-950: oklch(14.1% 0.005 285.823);
+
+    /* Borders — zinc-tinted hairlines at the same lightness rungs as the
+       base theme's neutral borders (93% / 87% / 80%) */
+    --color-border: oklch(92% 0.004 286.32);
+    --color-border-secondary: oklch(87.1% 0.006 286.286);
+    --color-border-hover: oklch(80% 0.01 286);
+
+    /* Typography */
+    --font-family-base: "Plus Jakarta Sans", var(--font-sans);
+
+    /* Geometry — rounder, softer cards; every --*-radius derives from this */
+    --radius-base: 24px;
+
+    /* Taller, pill-leaning controls (base: 32/40/48). Buttons inherit via
+       --button-min-h-* = var(--form-min-h-*). */
+    --form-min-h-sm: 40px;
+    --form-min-h-md: 48px;
+    --form-min-h-lg: 56px;
+
+    /* Wider padding to suit the pill shape */
+    --form-px-sm: 16px;
+    --form-px-md: 20px;
+    --form-px-lg: 24px;
+    --button-px-sm: 18px;
+    --button-px-md: 22px;
+    --button-px-lg: 28px;
+    --button-icon-p-sm: 8px;
+    --button-icon-p-md: 10px;
+    --button-icon-p-lg: 12px;
+
+    /* Chip tier — grow badges/pills/tags/keycaps to match the spacious controls.
+       Radius rides --radius-base (24px → pill), so only padding is set here. */
+    --badge-px-sm: 8px;
+    --badge-px-md: 10px;
+    --badge-py-sm: 2px;
+    --badge-py-md: 4px;
+    --badge-pill-px-sm: 12px;
+    --badge-pill-px-md: 14px;
+    --pill-px-sm: 14px;
+    --pill-px-md: 14px;
+    --pill-px-lg: 18px;
+    --pill-py-sm: 4px;
+    --pill-py-md: 4px;
+    --pill-py-lg: 6px;
+    --tag-px-sm: 12px;
+    --tag-px-md: 12px;
+    --tag-pl-md: 14px;
+    --tag-py-sm: 4px;
+    --tag-py-md: 4px;
+    --kbd-px-sm: 8px;
+    --kbd-px-md: 10px;
+  }
+
+  .dark {
+    /* One step lighter on dark surfaces, matching Iris/Jade: orange-500 keeps
+       saturated white-on-coral legible without reading washy like -400 would
+       on a big filled button. */
+    --color-primary: var(--color-primary-500);
+
+    /* Zinc in light, NEUTRAL in dark. Mid/deep zinc rungs read violet-tinted
+       against the hueless dark surfaces (#171717…) — same judgment as
+       Iris's "slate reads navy" — so the whole dark ramp reverts to the base
+       hueless values; light keeps the cool zinc cast. */
+    --color-mono-50: oklch(98.5% 0 0);
+    --color-mono-100: oklch(97% 0 0);
+    --color-mono-200: oklch(92.2% 0 0);
+    --color-mono-300: oklch(87% 0 0);
+    --color-mono-400: oklch(70.8% 0 0);
+    --color-mono-500: oklch(55.6% 0 0);
+    --color-mono-600: oklch(43.9% 0 0);
+    --color-mono-700: oklch(37.1% 0 0);
+    --color-mono-800: oklch(26.9% 0 0);
+    --color-mono-900: oklch(20.5% 0 0);
+    --color-mono-950: oklch(14.5% 0 0);
+
+    /* Restated verbatim from styles.css .dark (see authoring rules above) */
+    --color-border: oklch(100% 0.01 255 / 0.05);
+    --color-border-secondary: oklch(100% 0.01 255 / 0.1);
+    --color-border-hover: oklch(100% 0.01 255 / 0.18);
+  }
+}