@adres/mgda-ui 0.0.0-stage → 0.0.2

package/src/lib/prefix-utilities.ts

@@ -0,0 +1,50 @@
+const PRESERVE = new Set([
+  "dark",
+  "elevation-0",
+  "elevation-1",
+  "elevation-2",
+  "elevation-3",
+  "prose-docs",
+])
+
+export type PrefixUtilitiesResult = {
+  text: string
+  /** Tokens left unchanged because they are not utilities. */
+  skipped: string[]
+}
+
+/**
+ * Prefix Tailwind utility tokens in a class string or an `@apply` body.
+ * The dark-mode hook and hand-written elevation classes stay as they are.
+ * Tokens that do not look like utilities are left unchanged and listed in `skipped`.
+ */
+export function prefixUtilities(source: string): PrefixUtilitiesResult {
+  const skipped: string[] = []
+
+  const text = source.replace(/[^\s]+/g, (raw) => {
+    const semicolon = raw.endsWith(";")
+    const token = semicolon ? raw.slice(0, -1) : raw
+
+    if (token === "@apply" || token.startsWith("ax:")) return raw
+    // Fumadocs utilities compile in a separate unprefixed stylesheet.
+    if (token === "fd" || token.startsWith("fd-") || token.includes("-fd-")) {
+      skipped.push(token)
+      return raw
+    }
+
+    if (PRESERVE.has(token) || !isUtilityToken(token)) {
+      skipped.push(token)
+      return raw
+    }
+
+    return `ax:${token}${semicolon ? ";" : ""}`
+  })
+
+  return { text, skipped }
+}
+
+function isUtilityToken(token: string): boolean {
+  if (token.length === 0) return false
+  if (/['"`{}]/.test(token)) return false
+  return /^[!a-zA-Z_\[(-]/.test(token)
+}

package/src/styles/base.css

@@ -0,0 +1,489 @@
+/*
+ * @adres/mgda-ui - base.css
+ *
+ * Brand-agnostic core tokens and utility wiring for Tailwind 4.
+ *
+ * What lives here:
+ *   - Universal scale primitives (space, radius, motion, breakpoints, type scale)
+ *   - The semantic-token contract (variable names only, no values)
+ *   - The Tailwind @theme inline mapping that exposes semantic tokens as utilities
+ *
+ * What does NOT live here:
+ *   - ../theme/theme.css: the MGDA values (colors, font family, shadows)
+ *
+ * Import order in your app:
+ *   @import "tailwindcss" prefix(ax);          <- Tailwind 4 entry (REQUIRED FIRST)
+ *   @import "@adres/mgda-ui/styles";     <- this file (theme + utility wiring)
+ */
+
+@import "../theme/theme.css";
+
+/* Dark mode is toggled by a `.dark` class on the root (the theme flips
+ * its tokens under `:root.dark`). Re-point Tailwind's `dark:`
+ * variant at that same class so utilities like `ax:dark:bg-primary-stronger` follow
+ * the app toggle, NOT the OS `prefers-color-scheme`, which is Tailwind's
+ * default and would otherwise apply in light mode on a dark-set OS. */
+@source "../";
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Layer 1 - Core (brand-agnostic) primitives
+ * Defaults; brand packages MAY override individual values.
+ * ─────────────────────────────────────────────────────────────────────────── */
+@layer base {
+  :root {
+    /* Absolute colour constants as HSL triplets, so they drop into the DS's
+     * `hsl(var(--token))` slots like every other token, e.g.
+     * `--card: var(--white)` → `--color-card: hsl(var(--card))`.
+     * (For a raw CSS colour just use `#fff` / `white`.) */
+    --white: 0 0% 100%;
+    --black: 0 0% 0%;
+
+    /* Spacing scale - 4px base, 9 stops */
+    --space-2xs: 0.25rem;  /*  4px */
+    --space-xs:  0.5rem;   /*  8px */
+    --space-sm:  0.75rem;  /* 12px */
+    --space-md:  1rem;     /* 16px */
+    --space-lg:  1.25rem;  /* 20px */
+    --space-xl:  1.5rem;   /* 24px */
+    --space-2xl: 2rem;     /* 32px */
+    --space-3xl: 2.5rem;   /* 40px */
+    --space-4xl: 3rem;     /* 48px */
+    --space-5xl: 4rem;     /* 64px */
+    --space-6xl: 6rem;     /* 96px */
+
+    /* Radius scale - defaults assume the Adres / Airbnb-DLS feel; brands may override */
+    --radius-xs:   0.25rem; /*  4px - fine details */
+    --radius-sm:   0.375rem;/*  6px - small badges */
+    --radius:      0.5rem;  /*  8px - DEFAULT - buttons, inputs */
+    --radius-md:   0.75rem; /* 12px - cards */
+    --radius-lg:   1rem;    /* 16px - modals, large panels */
+    --radius-xl:   1.5rem;  /* 24px */
+    --radius-full: 9999px;  /* pill */
+    --radius-badge: 9999px; /* badge default - pill; overridden by theme panel */
+
+    /* Motion - duration, easing, stagger */
+    --motion-fast:    160ms;  /* micro-interactions: hover, feedback */
+    --motion-base:    280ms;  /* standard UI: dropdowns, tooltips, small panels */
+    --motion-slow:    420ms;  /* large surfaces: drawers, modals, marketing sections */
+    --motion-exit:    200ms;  /* exit counterpart of base - 70% duration, use with ease-in */
+    /* Ease-out: fast start → smooth deceleration - use for elements entering the screen */
+    --motion-ease-out:    cubic-bezier(0.22, 1, 0.36, 1);
+    /* Ease-in: gentle start → fast exit - use for elements leaving the screen */
+    --motion-ease-in:     cubic-bezier(0.55, 0, 1, 0.45);
+    /* Ease-in-out: balanced arc - use for state transitions between two visible positions */
+    --motion-ease-in-out: cubic-bezier(0.45, 0, 0.55, 1);
+    --motion-spring:      cubic-bezier(0.34, 1.56, 0.64, 1); /* slight overshoot */
+
+    /* Shadow scale - neutral elevation, tinted by the brand's own neutral palette.
+     * --shadow-color resolves to whatever each brand sets as --neutral-900, so
+     * shadows pick up the brand's hue (cool blue-gray on thinkprop, warm gray
+     * on adres, etc.). Brands may override --shadow-color directly if they
+     * want a different tint than their neutral.
+     * Multi-layer drop shadows give a soft, dimensional lift. */
+    /* Absolute dark primitive (NOT the emphasis alias): shadows must stay dark
+     * in both modes; an emphasis alias would invert to a light colour in dark. */
+    --shadow-color: var(--neutral-900);
+    --shadow-xs: hsl(var(--shadow-color) / 0.10) 0px 1px 0px;
+    --shadow-sm: hsl(var(--shadow-color) / 0.04) 0px 0px 0px 1px, hsl(var(--shadow-color) / 0.04) 0px 0.5625px 0.5625px -0.28125px, hsl(var(--shadow-color) / 0.04) 0px 1.6875px 1.6875px -0.84375px, hsl(var(--shadow-color) / 0.04) 0px 3.375px 3.375px -1.6875px, hsl(var(--shadow-color) / 0.04) 0px 6.75px 6.75px -3.375px, hsl(var(--shadow-color) / 0.04) 0px 13.5px 13.5px -6.75px;
+    --shadow-md: hsl(var(--shadow-color) / 0.04) 0px 0px 0px 1px, hsl(var(--shadow-color) / 0.04) 0px 1px 1px -0.5px, hsl(var(--shadow-color) / 0.04) 0px 3px 3px -1.5px, hsl(var(--shadow-color) / 0.04) 0px 6px 6px -3px, hsl(var(--shadow-color) / 0.04) 0px 12px 12px -6px, hsl(var(--shadow-color) / 0.04) 0px 24px 24px -12px;
+    --shadow:    var(--shadow-sm);                    /* DEFAULT - alias of --shadow-sm so `shadow` Tailwind class keeps working */
+    --shadow-lg: hsl(var(--shadow-color) / 0.04) 0px 0px 0px 1px, hsl(var(--shadow-color) / 0.04) 0px 1.25px 1.25px -0.625px, hsl(var(--shadow-color) / 0.04) 0px 3.75px 3.75px -1.875px, hsl(var(--shadow-color) / 0.04) 0px 7.5px 7.5px -3.75px, hsl(var(--shadow-color) / 0.04) 0px 15px 15px -7.5px, hsl(var(--shadow-color) / 0.04) 0px 30px 30px -15px;
+    --shadow-xl: hsl(var(--shadow-color) / 0.04) 0px 0px 0px 1px, hsl(var(--shadow-color) / 0.04) 0px 1.5625px 1.5625px -0.78125px, hsl(var(--shadow-color) / 0.04) 0px 4.6875px 4.6875px -2.34375px, hsl(var(--shadow-color) / 0.04) 0px 9.375px 9.375px -4.6875px, hsl(var(--shadow-color) / 0.04) 0px 18.75px 18.75px -9.375px, hsl(var(--shadow-color) / 0.04) 0px 37.5px 37.5px -18.75px;
+    --shadow-2xl: hsl(var(--shadow-color) / 0.2) 0px 7px 29px 0px;
+
+    /* Tinted button shadows - opt-in via the Button `elevated` prop. Same diffuse
+     * falloff as --shadow-sm, but tinted with the variant's own hue so the lift
+     * carries the brand / status colour. Uses fixed primitives (not emphasis
+     * aliases) so the tint stays consistent in dark. Available to every theme;
+     * a brand may override either to retune its own button shadow. */
+    --shadow-primary-btn: hsl(var(--primary-700) / 0.12) 0px 0px 0px 1px, hsl(var(--primary-700) / 0.12) 0px 0.5625px 0.5625px -0.28125px, hsl(var(--primary-700) / 0.12) 0px 1.6875px 1.6875px -0.84375px, hsl(var(--primary-600) / 0.12) 0px 3.375px 3.375px -1.6875px, hsl(var(--primary-600) / 0.12) 0px 6.75px 6.75px -3.375px, hsl(var(--primary-600) / 0.12) 0px 13.5px 13.5px -6.75px;
+    --shadow-destructive-btn: hsl(var(--destructive-700) / 0.12) 0px 0px 0px 1px, hsl(var(--destructive-700) / 0.12) 0px 0.5625px 0.5625px -0.28125px, hsl(var(--destructive-700) / 0.12) 0px 1.6875px 1.6875px -0.84375px, hsl(var(--destructive-600) / 0.12) 0px 3.375px 3.375px -1.6875px, hsl(var(--destructive-600) / 0.12) 0px 6.75px 6.75px -3.375px, hsl(var(--destructive-600) / 0.12) 0px 13.5px 13.5px -6.75px;
+
+    /* Input/textarea radius - fixed value, intentionally NOT chained to --radius-sm or --radius
+     * so it stays stable when buttonRadius changes (e.g. full-pill buttons still get legible input corners). */
+    --input-radius: 0.5rem;
+    /* Button corner radius - defaults to the brand's base --radius; brands may
+     * override (e.g. Madhmoun sets this to --radius-sm). */
+    --button-radius: var(--radius);
+
+    /* Card-level overridable defaults - brand themes may set these to customise card chrome */
+    --card-border-color: transparent;
+    --card-shadow:       var(--shadow-sm);
+
+    /* Surface elevation - a self-contained container treatment that bundles a
+     * background fill with a shadow into four ascending levels (level0 → level3).
+     * Consumed by the Card `elevation` prop and the `.elevation-{0..3}` utilities,
+     * so the same ramp is reusable on any container (panels, sections, sheets).
+     *
+     * Fills default to the themeable --card surface (pure white in the default
+     * light theme, the dark card neutral in .dark) so elevation adapts to dark
+     * mode and per-brand surfaces with no extra work; brands may override any rung.
+     *   level0 - transparent, flat
+     *   level1 - translucent surface (50%) + soft lift shadow
+     *   level2 - solid surface + flat lift shadow
+     *   level3 - solid surface + pronounced lift shadow (2xl)
+     * All three lift shadows are tinted with --shadow-color (the neutral
+     * palette) rather than a fixed colour, so they stay on-brand and invert
+     * correctly in dark mode. */
+    --elevation-0-surface: transparent;
+    --elevation-0-shadow:  none;
+    --elevation-1-surface: hsl(var(--card) / 0.5);
+    --elevation-1-shadow:  hsl(var(--shadow-color) / 0.05) 0px 3px 12px;
+    --elevation-2-surface: hsl(var(--card));
+    --elevation-2-shadow:  hsl(var(--shadow-color) / 0.1) 0px 5px 16px;
+    --elevation-3-surface: hsl(var(--card));
+    --elevation-3-shadow:  var(--shadow-2xl);
+
+    /* Tabs-level overridable defaults - kept off --radius-full intentionally:
+     * tabs should not pick up the brand button-pill. Brands can still override. */
+    --tabs-list-radius:    var(--input-radius);
+    --tabs-trigger-radius: calc(var(--input-radius) - 2px);
+
+    /* Z-index scale */
+    --z-base:    0;
+    --z-raised:  10;
+    --z-sticky:  100;
+    --z-overlay: 1000;
+    --z-modal:   1100;
+    --z-toast:   1200;
+
+    /* ─── Colour shade scale - luminosity rungs ─────────────────────────────
+     * Single source of truth for every palette's lightness steps.
+     * Every semantic shade variable in every brand file references these.
+     * To shift a step globally: change the value here.
+     *
+     * Scale:  muted → lightest → lighter → light → base → dark → darker → darkest
+     * Light:  97      94         88         80      68
+     * Dark:                                                56     44       32
+     * The base (68%) is the midpoint of light (80%) ↔ dark (56%), giving equal
+     * 12% gaps on both sides. --shade-base-dm is the dark-mode base (4% above base).
+     * ─────────────────────────────────────────────────────────────────────── */
+    --shade-muted:    97%;
+    --shade-lightest: 94%;
+    --shade-lighter:  88%;
+    --shade-light:    80%;
+    --shade-base:     68%;
+    --shade-base-dm:  72%;  /* dark-mode step - slightly lighter than base */
+    --shade-dark:     56%;
+    --shade-darker:   44%;
+    --shade-darkest:  32%;
+
+    /* Typography scale - size / line-height pairs */
+    --text-3xs:  0.625rem;   /* 10px */
+    --text-2xs:  0.6875rem;  /* 11px */
+    --text-xs:   0.75rem;    /* 12px */
+    --text-sm:   0.875rem;   /* 14px */
+    --text-base: 1rem;       /* 16px */
+    --text-lg:   1.125rem;   /* 18px */
+    --text-xl:   1.375rem;   /* 22px - Adres section title */
+    --text-2xl:  1.75rem;    /* 28px */
+    --text-3xl:  2.25rem;    /* 36px - Adres display */
+    --text-4xl:  3rem;       /* 48px */
+    --text-5xl:  4rem;       /* 64px */
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Layer 2 - Semantic-token CONTRACT (variable names only).
+ * Brand packages provide the actual VALUES for these (in :root and .dark).
+ * Components consume them via Tailwind classes (bg-primary, text-foreground, etc.)
+ * thanks to the @theme inline mapping below.
+ * ─────────────────────────────────────────────────────────────────────────── */
+
+@theme inline {
+  /* Color utilities derived from semantic tokens */
+  --color-background:           hsl(var(--background));
+  --color-foreground:           hsl(var(--foreground));
+  --color-foreground-strong:    hsl(var(--foreground-strong));
+  --color-foreground-muted:     hsl(var(--foreground-muted));
+  /* Neutral scale - base + named aliases (bg-neutral, bg-neutral-weaker, …) */
+  --color-neutral:              hsl(var(--neutral));
+  --color-neutral-muted:        hsl(var(--neutral-muted));
+  --color-neutral-weakest:     hsl(var(--neutral-weakest));
+  --color-neutral-weaker:      hsl(var(--neutral-weaker));
+  --color-neutral-weak:        hsl(var(--neutral-weak));
+  --color-neutral-strong:         hsl(var(--neutral-strong));
+  --color-neutral-stronger:       hsl(var(--neutral-stronger));
+  --color-neutral-strongest:      hsl(var(--neutral-strongest));
+  --color-card:                 hsl(var(--card));
+  --color-card-foreground:      hsl(var(--card-foreground));
+  --color-popover:              hsl(var(--popover));
+  --color-popover-foreground:   hsl(var(--popover-foreground));
+  --color-primary:              hsl(var(--primary));
+  --color-primary-foreground:   hsl(var(--primary-foreground));
+  --color-primary-muted:        hsl(var(--primary-muted));
+  --color-primary-weakest:     hsl(var(--primary-weakest));
+  --color-primary-weaker:      hsl(var(--primary-weaker));
+  --color-primary-weak:        hsl(var(--primary-weak));
+  --color-primary-strong:         hsl(var(--primary-strong));
+  --color-primary-stronger:       hsl(var(--primary-stronger));
+  --color-primary-strongest:      hsl(var(--primary-strongest));
+  /* Raw deepest-navy primitive: unlike the emphasis aliases above it does NOT
+     invert in dark mode, so it's the stable "app chrome" surface (dark header
+     + rounded-panel backdrop) in both light and dark. */
+  --color-primary-900:            hsl(var(--primary-900));
+  --color-secondary:            hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+  --color-secondary-muted:      hsl(var(--secondary-muted));
+  --color-secondary-weakest:   hsl(var(--secondary-weakest));
+  --color-secondary-weaker:    hsl(var(--secondary-weaker));
+  --color-secondary-weak:      hsl(var(--secondary-weak));
+  --color-secondary-strong:       hsl(var(--secondary-strong));
+  --color-secondary-stronger:     hsl(var(--secondary-stronger));
+  --color-secondary-strongest:    hsl(var(--secondary-strongest));
+  --color-accent:               hsl(var(--accent));
+  --color-accent-foreground:    hsl(var(--accent-foreground));
+  --color-accent-muted:         hsl(var(--accent-muted));
+  --color-accent-weakest:      hsl(var(--accent-weakest));
+  --color-accent-weaker:       hsl(var(--accent-weaker));
+  --color-accent-weak:         hsl(var(--accent-weak));
+  --color-accent-strong:          hsl(var(--accent-strong));
+  --color-accent-stronger:        hsl(var(--accent-stronger));
+  --color-accent-strongest:       hsl(var(--accent-strongest));
+  /* Tertiary - currently only the Adrec brand defines these primitives; the
+   * utilities are inert on brands that don't. */
+  --color-tertiary:               hsl(var(--tertiary));
+  --color-tertiary-foreground:    hsl(var(--tertiary-foreground));
+  --color-tertiary-muted:         hsl(var(--tertiary-muted));
+  --color-tertiary-weakest:       hsl(var(--tertiary-weakest));
+  --color-tertiary-weaker:        hsl(var(--tertiary-weaker));
+  --color-tertiary-weak:          hsl(var(--tertiary-weak));
+  --color-tertiary-strong:        hsl(var(--tertiary-strong));
+  --color-tertiary-stronger:      hsl(var(--tertiary-stronger));
+  --color-tertiary-strongest:     hsl(var(--tertiary-strongest));
+  --color-muted:                hsl(var(--muted));
+  --color-muted-foreground:     hsl(var(--muted-foreground));
+  --color-selected:             hsl(var(--selected));
+  --color-destructive:            hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-destructive-muted:      hsl(var(--destructive-muted));
+  --color-destructive-weakest:   hsl(var(--destructive-weakest));
+  --color-destructive-weaker:    hsl(var(--destructive-weaker));
+  --color-destructive-weak:      hsl(var(--destructive-weak));
+  --color-destructive-strong:       hsl(var(--destructive-strong));
+  --color-destructive-stronger:     hsl(var(--destructive-stronger));
+  --color-destructive-strongest:    hsl(var(--destructive-strongest));
+  --color-success:                hsl(var(--success));
+  --color-success-foreground:     hsl(var(--success-foreground));
+  --color-success-muted:          hsl(var(--success-muted));
+  --color-success-weakest:       hsl(var(--success-weakest));
+  --color-success-weaker:        hsl(var(--success-weaker));
+  --color-success-weak:          hsl(var(--success-weak));
+  --color-success-strong:           hsl(var(--success-strong));
+  --color-success-stronger:         hsl(var(--success-stronger));
+  --color-success-strongest:        hsl(var(--success-strongest));
+  --color-warning:                hsl(var(--warning));
+  --color-warning-foreground:     hsl(var(--warning-foreground));
+  --color-warning-muted:          hsl(var(--warning-muted));
+  --color-warning-weakest:       hsl(var(--warning-weakest));
+  --color-warning-weaker:        hsl(var(--warning-weaker));
+  --color-warning-weak:          hsl(var(--warning-weak));
+  --color-warning-strong:           hsl(var(--warning-strong));
+  --color-warning-stronger:         hsl(var(--warning-stronger));
+  --color-warning-strongest:        hsl(var(--warning-strongest));
+  /* Background elevation - bg-surface-n1 … bg-surface-3 */
+  --color-surface-n1: hsl(var(--surface-n1));
+  --color-surface-0:  hsl(var(--surface-0));
+  --color-surface-1:  hsl(var(--surface-1));
+  --color-surface-2:  hsl(var(--surface-2));
+  --color-surface-3:  hsl(var(--surface-3));
+
+  --color-border:               hsl(var(--border));
+  --color-border-strong:        hsl(var(--border-strong));
+  --color-input:                hsl(var(--input));
+  --color-ring:                 hsl(var(--ring));
+
+  /* Data-visualisation palette - categorical chart colours */
+  --color-chart-1:  hsl(var(--chart-1));
+  --color-chart-2:  hsl(var(--chart-2));
+  --color-chart-3:  hsl(var(--chart-3));
+  --color-chart-4:  hsl(var(--chart-4));
+  --color-chart-5:  hsl(var(--chart-5));
+  --color-chart-6:  hsl(var(--chart-6));
+  --color-chart-7:  hsl(var(--chart-7));
+  --color-chart-8:  hsl(var(--chart-8));
+  --color-chart-9:  hsl(var(--chart-9));
+  --color-chart-10: hsl(var(--chart-10));
+
+  /* Typography */
+  --font-sans:    var(--font-family-sans);
+
+  /* Radius utilities */
+  --radius-xs:    var(--radius-xs);
+  --radius-sm:    var(--radius-sm);
+  --radius-md:    var(--radius-md);
+  --radius-lg:    var(--radius-lg);
+  --radius-xl:    var(--radius-xl);
+  --radius-full:  var(--radius-full);
+  --radius-badge: var(--radius-badge);
+
+  /* Shadow / elevation utilities - reads brand-overridable --shadow-* tokens */
+  --shadow-xs:           var(--shadow-xs);
+  --shadow-sm:           var(--shadow-sm);
+  --shadow:              var(--shadow);
+  --shadow-md:           var(--shadow-md);
+  --shadow-lg:           var(--shadow-lg);
+  --shadow-xl:           var(--shadow-xl);
+  --shadow-2xl:          var(--shadow-2xl);
+  --shadow-primary-btn:  var(--shadow-primary-btn);
+  --shadow-destructive-btn: var(--shadow-destructive-btn);
+
+  /* ─── max-width scale for typography & content columns ──────────────
+   *
+   * Tailwind v4's `max-w-{name}` utility resolves through three namespaces
+   * in priority order: `--max-width-*` → `--spacing-*` → `--container-*`.
+   *
+   * We define `--spacing-{name}` below (so `p-md`, `m-lg`, `gap-2xl` etc.
+   * pick up the Adres spacing scale). That `--spacing-*` set ALSO claims
+   * names like md / lg / xl / 2xl, which collides with `max-w-{name}`:
+   * without an explicit `--max-width-{name}` definition, Tailwind picks the
+   * spacing value (~1rem) for `max-w-md` and the page collapses.
+   *
+   * Defining `--max-width-*` here wins over `--spacing-*` and gives
+   * `max-w-{name}` the values devs expect: typography / reading-column
+   * widths matching Tailwind v4 defaults. Use these for prose, hero blocks,
+   * section intros, paragraph constraints. For full-page wrappers use
+   * `max-w-7xl` or `max-w-screen-2xl`; for off-scale needs use a literal
+   * like `max-w-[28rem]`.
+   *
+   * Earlier attempts overrode `--container-*` here with "generous reading
+   * widths", but they were inert (spacing took priority anyway) and have been
+   * removed.
+   */
+  --max-width-2xs: 18rem;
+  --max-width-xs:  20rem;
+  --max-width-sm:  24rem;
+  --max-width-md:  28rem;
+  --max-width-lg:  32rem;
+  --max-width-xl:  36rem;
+  --max-width-2xl: 42rem;
+  --max-width-3xl: 48rem;
+  --max-width-4xl: 56rem;
+  --max-width-5xl: 64rem;
+  --max-width-6xl: 72rem;
+  --max-width-7xl: 80rem;
+
+  /* Spacing tokens - mapped into Tailwind v4's --spacing-* namespace so that
+   * p-*, px-*, m-*, gap-*, w-*, h-*, size-*, min-w-*, etc. utilities AND all
+   * their variants (md:, lg:, hover:, focus:, dark:, …) are generated
+   * automatically. */
+  --spacing-2xs: var(--space-2xs);
+  --spacing-xs:  var(--space-xs);
+  --spacing-sm:  var(--space-sm);
+  --spacing-md:  var(--space-md);
+  --spacing-lg:  var(--space-lg);
+  --spacing-xl:  var(--space-xl);
+  --spacing-2xl: var(--space-2xl);
+  --spacing-3xl: var(--space-3xl);
+  --spacing-4xl: var(--space-4xl);
+  --spacing-5xl: var(--space-5xl);
+  --spacing-6xl: var(--space-6xl);
+
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Surface-elevation utilities
+ * Apply a single level's fill + shadow to any container. The Card component maps
+ * its `elevation` prop onto the same --elevation-* tokens directly (via Tailwind
+ * arbitrary-value utilities, so the level wins over the variant's own bg/shadow);
+ * these classes expose the identical ramp for non-Card containers.
+ * ─────────────────────────────────────────────────────────────────────────── */
+@layer components {
+  .elevation-0 { background-color: var(--elevation-0-surface); box-shadow: var(--elevation-0-shadow); }
+  .elevation-1 { background-color: var(--elevation-1-surface); box-shadow: var(--elevation-1-shadow); }
+  .elevation-2 { background-color: var(--elevation-2-surface); box-shadow: var(--elevation-2-shadow); }
+  .elevation-3 { background-color: var(--elevation-3-surface); box-shadow: var(--elevation-3-shadow); }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Accordion open/close keyframes
+ * ─────────────────────────────────────────────────────────────────────────── */
+@keyframes accordion-down {
+  from { height: 0; }
+  to   { height: var(--radix-accordion-content-height); }
+}
+@keyframes accordion-up {
+  from { height: var(--radix-accordion-content-height); }
+  to   { height: 0; }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Skeleton shimmer - sliding gradient overlay used by Skeleton variant="shimmer"
+ * ─────────────────────────────────────────────────────────────────────────── */
+@keyframes skeleton-shimmer {
+  from { transform: translateX(-100%); }
+  to   { transform: translateX( 100%); }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Text shimmer - a highlight sweeping across clipped text, used by ShimmerText
+ * ─────────────────────────────────────────────────────────────────────────── */
+@keyframes text-shimmer {
+  from { background-position: 100% center; }
+  to   { background-position: -100% center; }
+}
+
+@theme inline {
+  --animate-accordion-down:   accordion-down   200ms cubic-bezier(0.16, 1, 0.3, 1);
+  --animate-accordion-up:     accordion-up     200ms cubic-bezier(0.16, 1, 0.3, 1);
+  --animate-skeleton-shimmer: skeleton-shimmer 1.5s  linear infinite;
+  --animate-text-shimmer:     text-shimmer     2.5s  linear infinite;
+}
+
+
+/* ─────────────────────────────────────────────────────────────────────────────
+ * Base element styles
+ * ─────────────────────────────────────────────────────────────────────────── */
+
+@layer base {
+  * {
+    border-color: hsl(var(--border));
+  }
+
+  html {
+    font-family: var(--font-family-sans, ui-sans-serif, system-ui, sans-serif);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+  }
+
+  body {
+    background-color: hsl(var(--background));
+    color: hsl(var(--foreground));
+    font-feature-settings: "rlig" 1, "calt" 1;
+  }
+
+  /* Numeric data should be tabular-aligned by default in tables and stats */
+  [data-tabular="true"], .tabular-nums {
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* Focus-visible - semantic ring colour, generous offset */
+  :focus-visible {
+    outline: 2px solid hsl(var(--ring));
+    outline-offset: 2px;
+    border-radius: var(--radius);
+  }
+
+  /* Reduced motion - collapse durations to near-instant */
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+}
+
+/* ─── Typography utilities ───────────────────────────────────────────────── */
+@import "./typography.css";
+
+/* ─── Theme overrides ───────────────────────────────────────────────────── */
+@import "./overrides.css";
+
+/* ─── Motion utilities ──────────────────────────────────────────────────── */
+@import "./motion.css";

package/src/styles/motion.css

@@ -0,0 +1,69 @@
+@layer utilities {
+  /* ─── Duration ──────────────────────────────────────────────────────────────
+   * Semantic names map to the --motion-* scale defined in base.css.
+   * Use these instead of duration-150 / duration-200 / etc.
+   * ────────────────────────────────────────────────────────────────────────── */
+
+  /** Micro-interactions: hover states, feedback, icon swaps. */
+  .duration-fast { transition-duration: var(--motion-fast); }
+  /** Standard UI: dropdowns, tooltips, form focus rings, small panels. */
+  .duration-base { transition-duration: var(--motion-base); }
+  /** Large surfaces: drawers, modals, marketing sections. */
+  .duration-slow { transition-duration: var(--motion-slow); }
+  /** Exit counterpart of base - 70% of base duration so it leaves quickly. */
+  .duration-exit { transition-duration: var(--motion-exit); }
+
+  /* ─── Easing ────────────────────────────────────────────────────────────────
+   * Prefixed with `motion-` to avoid collision with Tailwind's built-in
+   * ease-in / ease-out / ease-in-out utilities (which use CSS keywords).
+   * ────────────────────────────────────────────────────────────────────────── */
+
+  /** Enter: fast start → smooth deceleration. Use for elements arriving. */
+  .ease-motion-out    { transition-timing-function: var(--motion-ease-out);    }
+  /** Exit: gentle start → fast departure. Use for elements leaving. */
+  .ease-motion-in     { transition-timing-function: var(--motion-ease-in);     }
+  /** State: balanced arc between two visible positions. */
+  .ease-motion-in-out { transition-timing-function: var(--motion-ease-in-out); }
+  /** Spring: slight overshoot - physical, tactile feel. */
+  .ease-motion-spring { transition-timing-function: var(--motion-spring);      }
+
+  /* ─── Preset transitions ────────────────────────────────────────────────────
+   * Compound utilities - set both duration and easing in one class.
+   * Pair with transition-* (Tailwind) to set the animated property:
+   *   transition-colors transition-snappy
+   *   transition-[border-color,box-shadow] transition-snappy
+   *
+   * These mirror the `transitions.*` presets in lib/motion.ts so the same
+   * semantic names work in both CSS and JS (motion/react) contexts.
+   * ────────────────────────────────────────────────────────────────────────── */
+
+  /** Snappy - micro-interactions: hover, feedback, icon swaps (160ms). */
+  .transition-snappy {
+    transition-duration:        var(--motion-fast);
+    transition-timing-function: var(--motion-ease-out);
+  }
+
+  /** Smooth - standard UI: dropdowns, tooltips, small panels (280ms). */
+  .transition-smooth {
+    transition-duration:        var(--motion-base);
+    transition-timing-function: var(--motion-ease-out);
+  }
+
+  /** Slow - large surfaces: drawers, modals, marketing sections (420ms). */
+  .transition-slow {
+    transition-duration:        var(--motion-slow);
+    transition-timing-function: var(--motion-ease-out);
+  }
+
+  /** Exit - quick departure, 70% of base (200ms ease-in). */
+  .transition-exit {
+    transition-duration:        var(--motion-exit);
+    transition-timing-function: var(--motion-ease-in);
+  }
+
+  /** Exit slow - large surfaces leaving (280ms ease-in). */
+  .transition-exit-slow {
+    transition-duration:        var(--motion-base);
+    transition-timing-function: var(--motion-ease-in);
+  }
+}

package/src/styles/overrides.css

@@ -0,0 +1,44 @@
+/*
+ * MGDA type and component overrides on top of the shared utilities.
+ */
+
+:root :is(.ax\:t-h1, .ax\:t-h2, .ax\:t-h3, .ax\:t-h4, .ax\:t-h5, .ax\:t-h6) {
+  font-weight: var(--ax-font-weight-medium);
+}
+
+:root :is(
+  .ax\:t-display-3xl,
+  .ax\:t-display-2xl,
+  .ax\:t-display-xl,
+  .ax\:t-display-lg,
+  .ax\:t-display-md,
+  .ax\:t-display-sm,
+  .ax\:t-body-2xl,
+  .ax\:t-body-xl,
+  .ax\:t-body-lg
+) {
+  font-weight: var(--ax-font-weight-light);
+}
+
+/* Button's primary fill, scoped via its `data-slot="button"` hook so Badge,
+ * ButtonGroup, ChatMessage, EntityHeader, and Pagination - which share the
+ * same `bg-primary-weaker`/`text-primary-foreground` utility classes - are
+ * unaffected. Both light-mode classes and their separate `dark:` utility
+ * counterparts are re-pointed; `bg-primary-weakest`/`text-primary-stronger`
+ * are themselves mode-aware, so each `@apply` already resolves to the
+ * correct value per mode. */
+:root [data-slot="button"].ax\:bg-primary-weaker {
+  @apply ax:bg-primary-weakest;
+}
+
+:root [data-slot="button"].ax\:text-primary-foreground {
+  @apply ax:text-primary-stronger;
+}
+
+:root.dark [data-slot="button"].ax\:dark\:bg-primary-strong {
+  @apply ax:bg-primary-weakest;
+}
+
+:root.dark [data-slot="button"].ax\:dark\:text-primary-weaker {
+  @apply ax:text-primary-stronger;
+}