@gradeui/ui 3.1.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradeui/ui",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Grade Design System — React components, theme engine, and design tokens",
   "license": "MIT",
   "author": {
@@ -146,6 +146,7 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@tanstack/react-table": "^8.20.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",

package/styles/globals.css

@@ -48,102 +48,108 @@
 @theme {
   --text-2xs: 0.6875rem;
   --text-2xs--line-height: 1rem;
+  /* Accent font role — gives a `font-accent` utility that references the
+     runtime --font-accent var (set by the theme generator / apply.ts).
+     Plain @theme (not inline) so the utility stays var-referencing and
+     re-skins live; falls back to the display/sans stack until a theme
+     sets one. */
+  --font-accent: var(--font-display, var(--font-sans));
 }
 
 @theme inline reference {
   /* -- Brand color ramps — values live in @gradeui/core as --gds-* vars. -- */
-  --color-rds-green: var(--gds-green);
-  --color-rds-green-50: var(--gds-green-50);
-  --color-rds-green-100: var(--gds-green-100);
-  --color-rds-green-200: var(--gds-green-200);
-  --color-rds-green-300: var(--gds-green-300);
-  --color-rds-green-400: var(--gds-green-400);
-  --color-rds-green-500: var(--gds-green-500);
-  --color-rds-green-600: var(--gds-green-600);
-  --color-rds-green-700: var(--gds-green-700);
-  --color-rds-green-800: var(--gds-green-800);
-  --color-rds-green-900: var(--gds-green-900);
-  --color-rds-green-950: var(--gds-green-950);
-  --color-rds-yellow: var(--gds-yellow);
-  --color-rds-yellow-50: var(--gds-yellow-50);
-  --color-rds-yellow-100: var(--gds-yellow-100);
-  --color-rds-yellow-200: var(--gds-yellow-200);
-  --color-rds-yellow-300: var(--gds-yellow-300);
-  --color-rds-yellow-400: var(--gds-yellow-400);
-  --color-rds-yellow-500: var(--gds-yellow-500);
-  --color-rds-yellow-600: var(--gds-yellow-600);
-  --color-rds-yellow-700: var(--gds-yellow-700);
-  --color-rds-yellow-800: var(--gds-yellow-800);
-  --color-rds-yellow-900: var(--gds-yellow-900);
-  --color-rds-orange: var(--gds-orange);
-  --color-rds-orange-50: var(--gds-orange-50);
-  --color-rds-orange-100: var(--gds-orange-100);
-  --color-rds-orange-200: var(--gds-orange-200);
-  --color-rds-orange-300: var(--gds-orange-300);
-  --color-rds-orange-400: var(--gds-orange-400);
-  --color-rds-orange-500: var(--gds-orange-500);
-  --color-rds-orange-600: var(--gds-orange-600);
-  --color-rds-orange-700: var(--gds-orange-700);
-  --color-rds-orange-800: var(--gds-orange-800);
-  --color-rds-orange-900: var(--gds-orange-900);
-  --color-rds-red: var(--gds-red);
-  --color-rds-red-50: var(--gds-red-50);
-  --color-rds-red-100: var(--gds-red-100);
-  --color-rds-red-200: var(--gds-red-200);
-  --color-rds-red-300: var(--gds-red-300);
-  --color-rds-red-400: var(--gds-red-400);
-  --color-rds-red-500: var(--gds-red-500);
-  --color-rds-red-600: var(--gds-red-600);
-  --color-rds-red-700: var(--gds-red-700);
-  --color-rds-red-800: var(--gds-red-800);
-  --color-rds-red-900: var(--gds-red-900);
-  --color-rds-teal: var(--gds-teal);
-  --color-rds-teal-50: var(--gds-teal-50);
-  --color-rds-teal-100: var(--gds-teal-100);
-  --color-rds-teal-200: var(--gds-teal-200);
-  --color-rds-teal-300: var(--gds-teal-300);
-  --color-rds-teal-400: var(--gds-teal-400);
-  --color-rds-teal-500: var(--gds-teal-500);
-  --color-rds-teal-600: var(--gds-teal-600);
-  --color-rds-teal-700: var(--gds-teal-700);
-  --color-rds-teal-800: var(--gds-teal-800);
-  --color-rds-teal-900: var(--gds-teal-900);
-  --color-rds-teal-950: var(--gds-teal-950);
-  --color-rds-navy: var(--gds-navy);
-  --color-rds-navy-50: var(--gds-navy-50);
-  --color-rds-navy-100: var(--gds-navy-100);
-  --color-rds-navy-200: var(--gds-navy-200);
-  --color-rds-navy-300: var(--gds-navy-300);
-  --color-rds-navy-400: var(--gds-navy-400);
-  --color-rds-navy-500: var(--gds-navy-500);
-  --color-rds-navy-600: var(--gds-navy-600);
-  --color-rds-navy-700: var(--gds-navy-700);
-  --color-rds-navy-800: var(--gds-navy-800);
-  --color-rds-navy-900: var(--gds-navy-900);
-  --color-rds-blue: var(--gds-blue);
-  --color-rds-blue-50: var(--gds-blue-50);
-  --color-rds-blue-100: var(--gds-blue-100);
-  --color-rds-blue-200: var(--gds-blue-200);
-  --color-rds-blue-300: var(--gds-blue-300);
-  --color-rds-blue-400: var(--gds-blue-400);
-  --color-rds-blue-500: var(--gds-blue-500);
-  --color-rds-blue-600: var(--gds-blue-600);
-  --color-rds-blue-700: var(--gds-blue-700);
-  --color-rds-blue-800: var(--gds-blue-800);
-  --color-rds-blue-900: var(--gds-blue-900);
-  --color-rds-gray-50: var(--gds-gray-50);
-  --color-rds-gray-100: var(--gds-gray-100);
-  --color-rds-gray-200: var(--gds-gray-200);
-  --color-rds-gray-300: var(--gds-gray-300);
-  --color-rds-gray-400: var(--gds-gray-400);
-  --color-rds-gray-500: var(--gds-gray-500);
-  --color-rds-gray-600: var(--gds-gray-600);
-  --color-rds-gray-700: var(--gds-gray-700);
-  --color-rds-gray-800: var(--gds-gray-800);
-  --color-rds-gray-900: var(--gds-gray-900);
-  --color-rds-gray-950: var(--gds-gray-950);
-  --color-rds-black: var(--gds-black);
-  --color-rds-white: var(--gds-white);
+  --color-gds-green: var(--gds-green);
+  --color-gds-green-50: var(--gds-green-50);
+  --color-gds-green-100: var(--gds-green-100);
+  --color-gds-green-200: var(--gds-green-200);
+  --color-gds-green-300: var(--gds-green-300);
+  --color-gds-green-400: var(--gds-green-400);
+  --color-gds-green-500: var(--gds-green-500);
+  --color-gds-green-600: var(--gds-green-600);
+  --color-gds-green-700: var(--gds-green-700);
+  --color-gds-green-800: var(--gds-green-800);
+  --color-gds-green-900: var(--gds-green-900);
+  --color-gds-green-950: var(--gds-green-950);
+  --color-gds-yellow: var(--gds-yellow);
+  --color-gds-yellow-50: var(--gds-yellow-50);
+  --color-gds-yellow-100: var(--gds-yellow-100);
+  --color-gds-yellow-200: var(--gds-yellow-200);
+  --color-gds-yellow-300: var(--gds-yellow-300);
+  --color-gds-yellow-400: var(--gds-yellow-400);
+  --color-gds-yellow-500: var(--gds-yellow-500);
+  --color-gds-yellow-600: var(--gds-yellow-600);
+  --color-gds-yellow-700: var(--gds-yellow-700);
+  --color-gds-yellow-800: var(--gds-yellow-800);
+  --color-gds-yellow-900: var(--gds-yellow-900);
+  --color-gds-orange: var(--gds-orange);
+  --color-gds-orange-50: var(--gds-orange-50);
+  --color-gds-orange-100: var(--gds-orange-100);
+  --color-gds-orange-200: var(--gds-orange-200);
+  --color-gds-orange-300: var(--gds-orange-300);
+  --color-gds-orange-400: var(--gds-orange-400);
+  --color-gds-orange-500: var(--gds-orange-500);
+  --color-gds-orange-600: var(--gds-orange-600);
+  --color-gds-orange-700: var(--gds-orange-700);
+  --color-gds-orange-800: var(--gds-orange-800);
+  --color-gds-orange-900: var(--gds-orange-900);
+  --color-gds-red: var(--gds-red);
+  --color-gds-red-50: var(--gds-red-50);
+  --color-gds-red-100: var(--gds-red-100);
+  --color-gds-red-200: var(--gds-red-200);
+  --color-gds-red-300: var(--gds-red-300);
+  --color-gds-red-400: var(--gds-red-400);
+  --color-gds-red-500: var(--gds-red-500);
+  --color-gds-red-600: var(--gds-red-600);
+  --color-gds-red-700: var(--gds-red-700);
+  --color-gds-red-800: var(--gds-red-800);
+  --color-gds-red-900: var(--gds-red-900);
+  --color-gds-teal: var(--gds-teal);
+  --color-gds-teal-50: var(--gds-teal-50);
+  --color-gds-teal-100: var(--gds-teal-100);
+  --color-gds-teal-200: var(--gds-teal-200);
+  --color-gds-teal-300: var(--gds-teal-300);
+  --color-gds-teal-400: var(--gds-teal-400);
+  --color-gds-teal-500: var(--gds-teal-500);
+  --color-gds-teal-600: var(--gds-teal-600);
+  --color-gds-teal-700: var(--gds-teal-700);
+  --color-gds-teal-800: var(--gds-teal-800);
+  --color-gds-teal-900: var(--gds-teal-900);
+  --color-gds-teal-950: var(--gds-teal-950);
+  --color-gds-navy: var(--gds-navy);
+  --color-gds-navy-50: var(--gds-navy-50);
+  --color-gds-navy-100: var(--gds-navy-100);
+  --color-gds-navy-200: var(--gds-navy-200);
+  --color-gds-navy-300: var(--gds-navy-300);
+  --color-gds-navy-400: var(--gds-navy-400);
+  --color-gds-navy-500: var(--gds-navy-500);
+  --color-gds-navy-600: var(--gds-navy-600);
+  --color-gds-navy-700: var(--gds-navy-700);
+  --color-gds-navy-800: var(--gds-navy-800);
+  --color-gds-navy-900: var(--gds-navy-900);
+  --color-gds-blue: var(--gds-blue);
+  --color-gds-blue-50: var(--gds-blue-50);
+  --color-gds-blue-100: var(--gds-blue-100);
+  --color-gds-blue-200: var(--gds-blue-200);
+  --color-gds-blue-300: var(--gds-blue-300);
+  --color-gds-blue-400: var(--gds-blue-400);
+  --color-gds-blue-500: var(--gds-blue-500);
+  --color-gds-blue-600: var(--gds-blue-600);
+  --color-gds-blue-700: var(--gds-blue-700);
+  --color-gds-blue-800: var(--gds-blue-800);
+  --color-gds-blue-900: var(--gds-blue-900);
+  --color-gds-gray-50: var(--gds-gray-50);
+  --color-gds-gray-100: var(--gds-gray-100);
+  --color-gds-gray-200: var(--gds-gray-200);
+  --color-gds-gray-300: var(--gds-gray-300);
+  --color-gds-gray-400: var(--gds-gray-400);
+  --color-gds-gray-500: var(--gds-gray-500);
+  --color-gds-gray-600: var(--gds-gray-600);
+  --color-gds-gray-700: var(--gds-gray-700);
+  --color-gds-gray-800: var(--gds-gray-800);
+  --color-gds-gray-900: var(--gds-gray-900);
+  --color-gds-gray-950: var(--gds-gray-950);
+  --color-gds-black: var(--gds-black);
+  --color-gds-white: var(--gds-white);
 
   /* -- Semantic roles — runtime vars hold bare "L C H" OKLCH triplets,
      wrapped with oklch() at use. Opacity shortcuts (bg-primary/50) come
@@ -767,6 +773,8 @@
      ---------------------------------------- */
   --background: 0.985 0.0018 85;          /* neutral 50 */
   --foreground: 0.170 0.0048 85;          /* neutral 950 */
+  --bg-base: 0.985 0.0018 85;             /* stable mirror for scope-inverse */
+  --fg-base: 0.170 0.0048 85;
   --card: 1 0 0;                            /* pure white */
   --card-foreground: 0.170 0.0048 85;
   --popover: 1 0 0;
@@ -869,6 +877,19 @@
   --gds-map-marker-border: oklch(var(--border));
   --gds-map-marker-shadow: 0 1px 3px oklch(0 0 0 / 0.22),
     0 0 0 1px oklch(0 0 0 / 0.05);
+  /* Halo behind floating map labels (the text-stroke that separates a
+     label from busy tiles). Mode-aware: a white halo reads on pale
+     light tiles; the dark-mode override flips it to near-black so a
+     light label on dark tiles isn't a white-on-white wash-out. Applied
+     via the `.gds-map-label` helper. */
+  --gds-map-label-halo: oklch(1 0 0);
+  /* Map canvas — the backing colour BEHIND the raster tiles. Leaflet's
+     default is `#dddddd`, so subpixel gaps between tiles flash light
+     "seams" over a dark basemap. Defaulting this to the tile base
+     colour (here, the CARTO voyager land tone) makes those gaps blend
+     away. Neutral on purpose: tint it and the seams come back as
+     coloured lines unless your tiles match. */
+  --gds-map-canvas: oklch(0.97 0.004 95);
 
   /* Sidebar knobs — the width pair drives the collapsed/expanded animation
      on `<Sidebar>` (compound nav primitive). Header height + section
@@ -881,6 +902,33 @@
   --gds-sidebar-section-px: 0.5rem;
   --gds-sidebar-section-gap: 0.125rem;
 
+  /* Property list knobs — <PropertyList> renders a single record as
+     label / value rows (a Table row transposed). The label column width
+     and the row/column rhythm are exposed so a dense inspector and an
+     airy settings page share one primitive. Read as
+     `var(--gds-property-list-* , <fallback>)` in the component, so a
+     missing stanza degrades gracefully. */
+  --gds-property-list-label-width: 8.5rem;
+  --gds-property-list-col-gap: 1rem;
+  --gds-property-list-row-gap: 0.625rem;
+  --gds-property-list-row-gap-compact: 0.375rem;
+  --gds-property-list-row-gap-relaxed: 1rem;
+  --gds-property-list-icon-size: 0.875rem;
+  --gds-property-list-label-color: oklch(var(--muted-foreground));
+  --gds-property-list-divider-color: oklch(var(--border));
+
+  /* Data view knobs — <DataView> draws one dataset as a table, cards, or a
+     grid. The card / grid tiles auto-fill, so these min column widths set
+     how many tiles sit per row at a given container width; the pinned and
+     header backgrounds back the sticky column / header so scrolled content
+     doesn't bleed through. */
+  --gds-data-view-card-min: 18rem;
+  --gds-data-view-grid-min: 11rem;
+  --gds-data-view-gap: 0.75rem;
+  --gds-data-view-pinned-bg: oklch(var(--background));
+  --gds-data-view-header-bg: oklch(var(--background));
+  --gds-data-view-table-max-h: 28rem; /* scroll height when stickyHeader is on */
+
   /* Carousel knobs — every visual dimension of <Carousel> is driven from
      this stanza so consumers can re-skin the slideshow (dot shape, arrow
      chrome, transition feel) without prop-drilling. The component reads
@@ -962,6 +1010,8 @@
      ---------------------------------------- */
   --background: 0.170 0.0048 85;
   --foreground: 0.985 0.0018 85;
+  --bg-base: 0.170 0.0048 85;
+  --fg-base: 0.985 0.0018 85;
   --card: 0.245 0.0096 85;                  /* neutral 900 */
   --card-foreground: 0.985 0.0018 85;
   --popover: 0.245 0.0096 85;
@@ -1008,6 +1058,12 @@
   --gds-map-marker-border: oklch(1 0 0 / 0.3);
   --gds-map-marker-shadow: 0 1px 3px oklch(0 0 0 / 0.5),
     0 0 0 1px oklch(0 0 0 / 0.4);
+  /* Dark-mode label halo — near-black so light labels stay legible on
+     dark tiles (mirror of the light-mode white halo above). */
+  --gds-map-label-halo: oklch(0.18 0 0);
+  /* Dark-mode map canvas — near-black to match the CARTO dark_all base,
+     so tile seams vanish on the dark basemap. */
+  --gds-map-canvas: oklch(0.17 0 0);
 
   /* Alert surface pairs — dark-mode variant: tint sits just above the dark
      background without going gray; deep text stays bright and readable. */
@@ -1071,6 +1127,8 @@
 :root[data-grade-theme="energy"] {
   --background: 0.985 0.0012 175;           /* neutral 50 */
   --foreground: 0.170 0.0032 175;           /* neutral 950 */
+  --bg-base: 0.985 0.0012 175;
+  --fg-base: 0.170 0.0032 175;
   --card: 1 0 0;
   --card-foreground: 0.170 0.0032 175;
   --popover: 1 0 0;
@@ -1095,6 +1153,8 @@
 .dark[data-grade-theme="energy"] {
   --background: 0.170 0.0032 175;
   --foreground: 0.985 0.0012 175;
+  --bg-base: 0.170 0.0032 175;
+  --fg-base: 0.985 0.0012 175;
   --card: 0.245 0.0064 175;
   --card-foreground: 0.985 0.0012 175;
   --popover: 0.245 0.0064 175;
@@ -1673,21 +1733,23 @@
 }
 
 /* ============================================
-   MAP MARKER LIFT — every pin gets a border
+   MAP MARKER — intentionally unstyled
    ============================================
-   Map tiles are external imagery and don't follow the theme, so marker
-   content (Badge price pins, numbered markers, avatars) can melt into
-   them — illegible dark-on-dark pins were the symptom. Guarantee the
-   lift at the DS level: every DIRECT child of a MapMarker's content
-   wrapper gets a 1px border + ambient shadow from the mode-aware
-   `--gds-map-marker-*` pair (light hairline on dark tiles, dark line
-   on light). Being unlayered, this wins over a Badge's own
-   border-transparent utility — deliberate: the border is the floor,
-   not a suggestion. Backgrounds/text are NOT touched; content keeps
-   its own surface tokens. */
-[data-gds-part="map-marker-content"] > * {
-  border: 1px solid var(--gds-map-marker-border);
-  box-shadow: var(--gds-map-marker-shadow);
+   Marker content (Badge price pins, numbered markers, avatars, custom pin
+   types) is the CONSUMER's design. The DS used to force a 1px border + ambient
+   shadow on every direct child of a marker as a legibility "floor", but that's
+   too opinionated for a primitive — it imposed a look on content you supply.
+   Removed. The mode-aware `--gds-map-marker-border` / `--gds-map-marker-shadow`
+   tokens remain defined, and `.gds-map-label` (below) still gives text a halo,
+   so legibility on busy tiles is OPT-IN, not mandatory. */
+
+/* Floating map label halo — put this class on a text element inside a
+   MapMarker to give it a mode-aware outline (white on light tiles,
+   near-black on dark) instead of hard-coding a white text-stroke that
+   washes out in dark mode. Pairs with the `--gds-map-label-halo` token. */
+.gds-map-label {
+  -webkit-text-stroke: 1.5px var(--gds-map-label-halo);
+  paint-order: stroke;
 }
 
 /* Vendor font reset — Leaflet (`.leaflet-container`) and MapLibre
@@ -1702,6 +1764,32 @@
   font-family: var(--font-sans);
 }
 
+/* Vendor z-index neutralizer — Leaflet's stylesheet sets `z-index: 200`
+   on every `<svg>` inside the map. That hijacks an inline SVG used as
+   marker content (e.g. a pin shield) and paints it ABOVE later sibling
+   DOM — so a count/label sitting on top of the shield vanishes behind
+   it. The Mapbox/MapLibre/Google adapters have no such rule, so the
+   same marker markup renders fine there; this made pins look provider-
+   dependent ("numbers show on Mapbox, not Leaflet"). Reset marker SVGs
+   to `z-index: auto` so author paint order (DOM order) holds on every
+   provider. `!important` to beat Leaflet's vendor selector. */
+[data-gds-part="map-marker-content"] svg {
+  z-index: auto !important;
+}
+
+/* Map canvas backing — sits behind the tiles so Leaflet's default
+   `#dddddd` no longer flashes through the subpixel gaps between raster
+   tiles ("seams"), most visible on a dark basemap. Harmless on the GL
+   providers (their opaque canvas covers it). Mode-aware via the token.
+   NB the selector is compounded with `[data-gds-part="map"]` on purpose:
+   Leaflet stamps `.leaflet-container` (which sets `background:#ddd`) onto
+   the SAME element, and its stylesheet loads after ours — a bare
+   `.gds-map` ties on specificity and loses. The data-part attribute
+   (present on every provider's root) lifts us above Leaflet's default. */
+.gds-map[data-gds-part="map"] {
+  background-color: var(--gds-map-canvas);
+}
+
 /* ============================================
    STREAM-IN — data-gds-streaming on <html>
    ============================================
@@ -1985,6 +2073,153 @@ html[data-gds-streaming] body * {
   }
 }
 
+@layer utilities {
+  /* Colour SCOPES (STUDIO-COLOR.md) — a local colour mode, the same idea as
+     light/dark but scoped to a wrapper and focused on surfaces.
+     Apply `scope-inverse` (etc.) to any element and it becomes a mini themed
+     region: it re-points the SURFACE family of tokens — page background, card,
+     popover, muted, border, and every foreground — at the named pair, so the
+     whole subtree re-tones (a dark band with light text, cards that sit on the
+     band instead of glaring white). Descendants keep using the ordinary tokens
+     (bg-background / text-foreground / bg-card); only what they resolve to
+     changes. It deliberately leaves the ACTION colours (--primary / --accent /
+     --secondary / --destructive) untouched, so a CTA stays branded and vivid
+     on top of the band.
+     `inverse` reads --fg-base / --bg-base (stable literal mirrors of the page
+     ink/paper that the generator emits) so the fg/bg swap can't form a custom-
+     property cycle; the other scopes read the theme's own tokens directly. */
+  .scope-default,
+  .scope-inverse,
+  .scope-brand,
+  .scope-accent,
+  .scope-muted,
+  .scope-card {
+    background-color: oklch(var(--background));
+    color: oklch(var(--foreground));
+  }
+  /* default = identity: paints the page tokens as-is, no overrides. */
+  .scope-inverse {
+    --background: var(--fg-base);
+    --foreground: var(--bg-base);
+    --card: var(--fg-base);
+    --card-foreground: var(--bg-base);
+    --popover: var(--fg-base);
+    --popover-foreground: var(--bg-base);
+    --muted: var(--fg-base);
+    --muted-foreground: var(--bg-base);
+    --border: var(--bg-base);
+    --input: var(--bg-base);
+  }
+  .scope-brand {
+    --background: var(--primary);
+    --foreground: var(--primary-foreground);
+    --card: var(--primary);
+    --card-foreground: var(--primary-foreground);
+    --popover: var(--primary);
+    --popover-foreground: var(--primary-foreground);
+    --muted: var(--primary);
+    --muted-foreground: var(--primary-foreground);
+    --border: var(--primary-foreground);
+    --input: var(--primary-foreground);
+  }
+  .scope-accent {
+    --background: var(--accent);
+    --foreground: var(--accent-foreground);
+    --card: var(--accent);
+    --card-foreground: var(--accent-foreground);
+    --popover: var(--accent);
+    --popover-foreground: var(--accent-foreground);
+    --muted: var(--accent);
+    --muted-foreground: var(--accent-foreground);
+    --border: var(--accent-foreground);
+    --input: var(--accent-foreground);
+  }
+  .scope-muted {
+    --background: var(--muted);
+    --card: var(--muted);
+    --popover: var(--muted);
+    /* foreground + muted-foreground stay the page's: already tuned to read on
+       a muted surface. */
+  }
+  .scope-card {
+    --background: var(--card);
+    --foreground: var(--card-foreground);
+    --popover: var(--card);
+    --popover-foreground: var(--card-foreground);
+    --muted-foreground: var(--card-foreground);
+  }
+}
+
+/* ============================================
+   EXPRESSIVE colour layer — see STUDIO-EXPRESSIVE.md
+   A highlight layer for painting whole SECTIONS, deliberately louder than the
+   neutral product chrome (marketing bands, feature cards, promo strips).
+   Orthogonal to the surface scopes above: it does NOT touch --primary/--accent,
+   so it stacks on top of any theme. Two attributes resolve a section's colour:
+     data-expressive="accent1..5"   picks one of 5 accent slots
+     data-expressive-tier="…"       picks one of 4 tiers (default: light)
+   …landing an accessible pair on --gds-expressive-bg / --gds-expressive-fg,
+   which the `.expressive` helper paints. Values mirror the Figma "Expressive"
+   collection (accent1..5 = rose, orange, amber, yellow, olive). The accents are
+   fixed ramps today; the generator will later write them from one hue per slot
+   — the token shape stays identical. Tiers use ramp steps 100/300/700/900. */
+:root {
+  --gds-expressive-accent1-100: #ffe9e6; --gds-expressive-accent1-300: #ffaaa2; --gds-expressive-accent1-700: #8b181d; --gds-expressive-accent1-900: #3f0b0b;
+  --gds-expressive-accent2-100: #ffeae0; --gds-expressive-accent2-300: #ffae89; --gds-expressive-accent2-700: #822c00; --gds-expressive-accent2-900: #3c1100;
+  --gds-expressive-accent3-100: #ffecd8; --gds-expressive-accent3-300: #f6b575; --gds-expressive-accent3-700: #743b00; --gds-expressive-accent3-900: #331900;
+  --gds-expressive-accent4-100: #fdefd2; --gds-expressive-accent4-300: #e5bf6d; --gds-expressive-accent4-700: #634600; --gds-expressive-accent4-900: #2d1d00;
+  --gds-expressive-accent5-100: #f4f2d4; --gds-expressive-accent5-300: #cfc871; --gds-expressive-accent5-700: #544e00; --gds-expressive-accent5-900: #252100;
+}
+
+/* accent slot → generic step vars */
+[data-expressive="accent1"] { --exp-100: var(--gds-expressive-accent1-100); --exp-300: var(--gds-expressive-accent1-300); --exp-700: var(--gds-expressive-accent1-700); --exp-900: var(--gds-expressive-accent1-900); }
+[data-expressive="accent2"] { --exp-100: var(--gds-expressive-accent2-100); --exp-300: var(--gds-expressive-accent2-300); --exp-700: var(--gds-expressive-accent2-700); --exp-900: var(--gds-expressive-accent2-900); }
+[data-expressive="accent3"] { --exp-100: var(--gds-expressive-accent3-100); --exp-300: var(--gds-expressive-accent3-300); --exp-700: var(--gds-expressive-accent3-700); --exp-900: var(--gds-expressive-accent3-900); }
+[data-expressive="accent4"] { --exp-100: var(--gds-expressive-accent4-100); --exp-300: var(--gds-expressive-accent4-300); --exp-700: var(--gds-expressive-accent4-700); --exp-900: var(--gds-expressive-accent4-900); }
+[data-expressive="accent5"] { --exp-100: var(--gds-expressive-accent5-100); --exp-300: var(--gds-expressive-accent5-300); --exp-700: var(--gds-expressive-accent5-700); --exp-900: var(--gds-expressive-accent5-900); }
+
+/* tier → which steps become bg / fg (default = light) */
+[data-expressive] { --gds-expressive-bg: var(--exp-300); --gds-expressive-fg: var(--exp-900); }
+[data-expressive][data-expressive-tier="superlight"] { --gds-expressive-bg: var(--exp-100); --gds-expressive-fg: var(--exp-900); }
+[data-expressive][data-expressive-tier="light"]      { --gds-expressive-bg: var(--exp-300); --gds-expressive-fg: var(--exp-900); }
+[data-expressive][data-expressive-tier="dark"]       { --gds-expressive-bg: var(--exp-700); --gds-expressive-fg: var(--exp-100); }
+[data-expressive][data-expressive-tier="superdark"]  { --gds-expressive-bg: var(--exp-900); --gds-expressive-fg: var(--exp-100); }
+
+/* the surface helper a section wears: paints the resolved expressive pair */
+.expressive { background-color: var(--gds-expressive-bg); color: var(--gds-expressive-fg); }
+
+/* ============================================
+   REVEAL — scroll-in motion for sections (and any element). Token-driven:
+   reuses the DS transition durations + eases (above), adds a reveal distance.
+   An element with `data-reveal` starts hidden/offset; an IntersectionObserver
+   in the consumer adds `.in-view` to animate it in. Entirely disabled under
+   prefers-reduced-motion (the hidden state lives inside the media query, so
+   content is always visible if motion is off or JS never runs). */
+:root {
+  --gds-reveal-distance: 1.25rem;
+  --gds-reveal-duration: var(--gds-transition-slower); /* 500ms */
+  --gds-reveal-ease: var(--gds-ease-out);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  [data-reveal] {
+    opacity: 0;
+    transform: translateY(var(--gds-reveal-distance));
+    transition:
+      opacity var(--gds-reveal-duration) var(--gds-reveal-ease),
+      transform var(--gds-reveal-duration) var(--gds-reveal-ease);
+    will-change: opacity, transform;
+  }
+  [data-reveal="fade"] { transform: none; }
+  [data-reveal="fade-down"] { transform: translateY(calc(-1 * var(--gds-reveal-distance))); }
+  [data-reveal="fade-left"] { transform: translateX(var(--gds-reveal-distance)); }
+  [data-reveal="fade-right"] { transform: translateX(calc(-1 * var(--gds-reveal-distance))); }
+  [data-reveal].in-view {
+    opacity: 1;
+    transform: none;
+  }
+}
+
 /* Keyframes */
 @keyframes fadeIn {
   from { opacity: 0; }