@leta-io/design-tokens 0.1.0

package/dist/map-elevation.css

@@ -0,0 +1,148 @@
+/**
+ * Map Elevation — LETA Design System
+ * @leta-io/design-tokens/map-elevation.css
+ *
+ * ─── Why this exists ───────────────────────────────────────────────────────
+ *
+ * A shadow does not communicate elevation on its own. It communicates elevation
+ * by CONTRASTING with whatever sits behind it. Every shadow in the Figma library
+ * — Neutral Drop Shadow 1/2/3 — was tuned against the app's own near-white page
+ * surfaces, where a soft 10% black reads clearly.
+ *
+ * A map is a different substrate entirely: mid-tone, saturated, and visually
+ * busy (roads, parks, water, labels). Against it those shadows disappear, and
+ * white overlays read as flat shapes pasted onto the tiles rather than floating
+ * above them. Verified directly in the app — with Neutral Drop Shadow 2 applied
+ * exactly as Figma specifies, the depot/recipient cards, zoom control and
+ * collapse button all still read flat.
+ *
+ * Compounding it, two of Neutral Drop Shadow 2's three layers use `spread: -8`
+ * against `blur: 8`, which places them inside the element's own edge — invisible
+ * behind an opaque surface. So it effectively renders as one soft 10% layer.
+ * Neutral Drop Shadow 3 is stronger but its `spread: -4/-6` eats most of it too.
+ *
+ * So map overlays get their own elevation, built the way map products (Google,
+ * Mapbox, Apple) build theirs:
+ *
+ *   1. a **hairline ring**  — guarantees a crisp edge no matter what colour the
+ *      tile underneath happens to be; a shadow alone can never promise contrast
+ *      against arbitrary imagery
+ *   2. a **contact shadow** — tight and relatively opaque, anchoring the element
+ *   3. an **ambient shadow** — wider and softer, giving the actual sense of lift
+ *
+ * ─── This is an addition to the system, not an override of it ──────────────
+ *
+ * Neutral Drop Shadow 1/2/3 remain correct and unchanged for everything on a
+ * page surface. This is a fourth, substrate-specific level. It should be added
+ * to the Figma library as an effect style ("Map Overlay Shadow") so design and
+ * code stay in sync — until then, Figma will show map overlays a step flatter
+ * than the build.
+ *
+ * ─── Usage ─────────────────────────────────────────────────────────────────
+ *
+ *   import '@leta-io/design-tokens/map-elevation.css';
+ *
+ *   // Any element floating on a map: cards, banners, legend, zoom control,
+ *   // expand/collapse buttons, popovers, notification banners.
+ *   style={{ boxShadow: 'var(--shadow-map-overlay)' }}
+ *
+ * Pins are the exception: a pin is a teardrop, not a rectangle, and `box-shadow`
+ * traces the element's BOX — it would draw a rectangular shadow around a pointed
+ * shape. Pins use `filter: drop-shadow()`, which follows the shape's alpha.
+ * `MapIcon` carries that equivalent internally (`filter` takes no custom
+ * properties reliably across engines, and it has no `spread` parameter, so the
+ * values are folded rather than copied).
+ */
+
+:root {
+  /**
+   * Elevation for anything floating on a map surface.
+   * Ring + contact + ambient — see the note above for why all three.
+   */
+  --shadow-map-overlay:
+    0 0 0 1px rgb(16 16 16 / 0.06),
+    0 1px 3px rgb(16 16 16 / 0.22),
+    0 6px 16px -4px rgb(16 16 16 / 0.28);
+
+  /**
+   * ─── Map pins do not follow the app theme ──────────────────────────────
+   *
+   * A pin sits on **map imagery**, not on the app's page surface. That is the same
+   * argument this file already makes for shadows, and it applies just as directly
+   * to the pin's own colours: the point of the white chassis is to guarantee the
+   * marker reads against arbitrary cartography, and the point of the coloured inner
+   * is to carry a status colour. Neither job changes because the app went dark.
+   *
+   * They were bound to app-surface semantic tokens, so in dark mode every pin turned
+   * inside out — measured 2026-08-26: chassis `#fefefe` → `#0d0d0d`, inner navy
+   * `#192037` → `#f9f9fa`, content `#fafafa` → `#101010`. One root cause behind three
+   * separate reports:
+   *
+   *   • "the pin colours look desaturated" — they had inverted, not desaturated.
+   *     `--surface-primary-bg` goes `#ff3941` → `#ffd7d9`: vivid red to pale pink.
+   *   • "the pins have no drop shadow and don't stand out" — a near-black pin with a
+   *     black shadow on a dark map.
+   *   • "why do these pins have a dark blur behind them" — the same black shadow,
+   *     now visible as a smudge wherever the map underneath was lighter.
+   *
+   * These are drawn from the **primitive** `--colors-*` layer, which is stable across
+   * themes (verified), so there is deliberately no `[data-theme="dark"]` block for
+   * them. A dark shadow under a light chassis then means what it is supposed to mean.
+   */
+  --map-pin-body: var(--colors-neutral-white);
+  --map-pin-edge: var(--colors-neutral-200);
+  --map-pin-content: var(--colors-neutral-50);
+
+  /**
+   * Status colours for a pin's inner shape. Callers pass one of these rather than an
+   * app-surface token, for the reason above — a pin's red has to stay red on a dark
+   * map, and `--surface-primary-bg` does not.
+   */
+  --map-pin-primary: var(--colors-primary-default);
+  --map-pin-secondary: var(--colors-secondary-default);
+  --map-pin-error: var(--colors-error-default);
+  --map-pin-success: var(--colors-success-default);
+  --map-pin-warning: var(--colors-warning-default);
+  --map-pin-neutral: var(--colors-neutral-default);
+
+  /**
+   * Pin / glyph filter — the `filter: drop-shadow()` equivalent of the above, for
+   * shapes rather than boxes (see the note on pins). Consumed by `MapIcon`.
+   *
+   * A chain rather than a single shadow, because dark mode adds a colour step to it
+   * (below). Light mode is shadow only: on light tiles a dark shadow both grounds the
+   * pin and gives its edge contrast, and the pin's own colour is already vivid
+   * against pale cartography.
+   */
+  --map-glyph-filter:
+    drop-shadow(0 1px 2px rgb(16 16 16 / 0.30))
+    drop-shadow(0 4px 8px rgb(16 16 16 / 0.22));
+}
+
+/**
+ * ─── Dark basemap: the shadow gets deeper, the colours do not move ─────────
+ *
+ * With the chassis staying light (above), a dark shadow means what it is supposed
+ * to mean again — a light object casting onto a dark ground — so this is a tuning
+ * step, not a different device. Pure black, because the light-mode value is mixed
+ * toward the page ink and reads as nothing on a dark map.
+ *
+ * **Tighter than light mode, not heavier.** The instinct is to strengthen a shadow
+ * that is failing to show; on a dark ground that produces a soft black cloud around
+ * an already-dark pin, which reads as a smudge rather than as lift — reported as
+ * "why do these pins have a dark blur behind them". So the contact layer stays close
+ * (1px blur) and the ambient one is small and faint (4px at 32%). Elevation on a
+ * dark map comes from the pin's light chassis; the shadow only has to seat it.
+ *
+ * Note what is deliberately NOT here: no halo, and no `saturate()`. Both were tried
+ * and removed (2026-08-26). The halo ringed the glyph in light and changed what the
+ * marker was; the saturation was compensating for a colour that had *inverted*
+ * rather than faded, so it could not have worked — a near-white inner does not get
+ * more colourful when you saturate it. Fixing the inversion at the source removed
+ * the need for either.
+ */
+:root[data-theme="dark"] {
+  --map-glyph-filter:
+    drop-shadow(0 1px 1px rgb(0 0 0 / 0.55))
+    drop-shadow(0 2px 4px rgb(0 0 0 / 0.32));
+}

package/dist/scroll-utilities.css

@@ -0,0 +1,258 @@
+/**
+ * Scroll Utilities — LETA Design System
+ * @leta-io/design-tokens/scroll-utilities.css
+ *
+ * Scroll behaviour + scrollbar appearance utilities.
+ * Import alongside tokens.css and text-styles.css wherever the design system
+ * is consumed (Storybook, Playground, host applications).
+ *
+ * Three independent concerns live here:
+ *   1. Scroll CHAINING  — .scroll-isolated / .scroll-rigid  (overscroll-behavior)
+ *   2. Scrollbar LOOK   — .scroll-slim / .scroll-hidden     (see the note below)
+ *   3. SCROLL EDGES     — --scroll-edge-* tokens            (see the note below)
+ *
+ * ─── Rule reference ────────────────────────────────────────────────────────
+ *
+ *  .scroll-isolated  (overscroll-behavior: contain)
+ *    Use on all NESTED / INTERNAL scroll containers: dropdown option lists,
+ *    modal body panels, sidebar navigation, search-results panels, date-picker
+ *    lists, mobile dropdown panels, and configuration form columns.
+ *    Effect: the browser stops at the element boundary — no scroll chain to
+ *    the parent and no pull-to-refresh trigger when the user reaches the top
+ *    or bottom of the inner list.
+ *
+ *  .scroll-rigid  (overscroll-behavior: none)
+ *    Use on DATA TABLE bodies and precision SNAP-SCROLL surfaces (time wheels).
+ *    Effect: zero overscroll bounce / rubber-band on any axis. Prevents
+ *    distracting UI shifts when aligning tabular data or advancing a snap list.
+ *
+ *  Root page / document scroll: leave untouched (native elastic bounce on iOS,
+ *  standard desktop behaviour). Do NOT apply either class to <html> or <body>.
+ *
+ * ─── Usage in component code (inline-style equivalent) ────────────────────
+ *
+ *   Nested list / panel   → style={{ overscrollBehavior: 'contain' }}
+ *   Data table / wheel    → style={{ overscrollBehavior: 'none' }}
+ *
+ * ─── Usage in playground / host app (class-based) ─────────────────────────
+ *
+ *   import '@leta-io/design-tokens/scroll-utilities.css';
+ *
+ *   // Internal panel
+ *   <div className="scroll-isolated" style={{ overflowY: 'auto', maxHeight: 300 }}>
+ *     {items}
+ *   </div>
+ *
+ *   // Data table viewport
+ *   <div className="scroll-rigid" style={{ overflow: 'auto', maxHeight: 600 }}>
+ *     <table>…</table>
+ *   </div>
+ *
+ * ─── Already applied in design-system components ──────────────────────────
+ *
+ *  contain:  ModalShell (body) · SideBar (nav content) · DesktopDropdowns (all
+ *            scroll lists + filter-group panes) · MapSearchInput (results panel) ·
+ *            MobileDropdown (panel) · DateTimePicker (desktop time-list, mobile
+ *            content) · Page (config column)
+ *
+ *  none:     Table (body — both fillHeight and maxBodyHeight modes, both-axes
+ *            scrollX mode) · DateTimePicker WheelColumn (snap-scroll time wheel)
+ */
+
+/* ─── Scroll Edges ───────────────────────────────────────────────────────────
+ *
+ * **"Scroll Edge"** is the LETA name for the affordance that tells a user
+ * *there is more content past this edge*. One concept, two treatments — chosen by
+ * what sits at the edge, not by axis:
+ *
+ *  · **Edge fade** — a soft gradient painted OVER the scrolling content itself,
+ *    for when content slides under an opaque neighbour with no chrome between
+ *    them. Used by the Table's pinned anchor columns (Order ID left / Actions
+ *    right) on horizontal scroll.
+ *
+ *  · **Edge shadow** — a drop shadow cast BY a piece of chrome onto the content
+ *    scrolling beneath it, for when a fixed header or footer needs to read as
+ *    separate from (and above) the scroll region. Used by ModalShell's header and
+ *    footer, and by FooterFrame's `scrollShadow`.
+ *
+ * Both are driven by the same detection primitive — `useScrollEdges(ref)` in
+ * `@leta-io/components` — so "is there more past this edge?" is answered one way
+ * everywhere. Never hand-roll that check; the hook also catches the cases a naive
+ * implementation misses (content growing without the container resizing, and the
+ * scroll target being swapped out under a stable ref).
+ *
+ * ─── Why these are tokens and not literals ─────────────────────────────────
+ *
+ * A scroll edge is drawn in INK over a surface, so it must invert with the theme.
+ * The light palette's table/modal surface is `#fefefe` and the dark palette's is
+ * `#0d0d0d` — very nearly black. A dark-ink fade (the light-mode treatment) over
+ * `#0d0d0d` is mathematically invisible: there is almost no headroom left to
+ * darken. So dark mode flips to LIGHT ink, the same logic as the hairline in
+ * `dark-elevation.css` — on a dark surface, "lifted" reads as light, not darker.
+ *
+ * Deliberately NOT reusing `--shadow-neutral-*`: those are ELEVATION (an object
+ * floating above a page) and in dark mode they carry a full 1px hairline ring on
+ * all four sides. A scroll edge is a single-edge affordance — a ring around a
+ * modal header is wrong, and that is exactly what reusing the elevation token
+ * produced before this was split out.
+ *
+ * Consume as:
+ *   background: linear-gradient(to right,
+ *     rgb(var(--scroll-edge-ink) / var(--scroll-edge-fade-1)), …);
+ *   box-shadow: var(--scroll-edge-shadow-down);
+ */
+
+:root {
+  /** Ink the edge is drawn in — dark over light surfaces. Space-separated RGB
+   *  channels so callers can apply their own alpha via `rgb(… / …)`. */
+  --scroll-edge-ink: 16 16 16;
+  /** Eased fade falloff (4 stops — a plain 2-stop gradient reads as a hard band). */
+  --scroll-edge-fade-1: 0.045;
+  --scroll-edge-fade-2: 0.028;
+  --scroll-edge-fade-3: 0.012;
+  /** Chrome edge shadows — `down` for a header above content, `up` for a footer below. */
+  --scroll-edge-shadow-down: 0 4px 10px -4px rgb(var(--scroll-edge-ink) / 0.1);
+  --scroll-edge-shadow-up: 0 -4px 10px -4px rgb(var(--scroll-edge-ink) / 0.1);
+}
+
+/* Dark mode: light ink, and LOWER alphas than light mode.
+ *
+ * The ink flips because a near-black surface (`#0d0d0d`) gives a dark fade nowhere
+ * to go — the edge has to be drawn as a subtle lift rather than a shadow.
+ *
+ * The alphas come DOWN rather than up, which is the counter-intuitive part: light
+ * ink on near-black is far more perceptible than dark ink on near-white, because
+ * perception near black is logarithmic (a small absolute lift is a large relative
+ * change). Matching light mode's alphas here reads as a hard white band — an
+ * "intense glow", reported 2026-08-24 — so these sit at roughly half. Tune by eye
+ * against the Table's pinned columns and a scrolling modal footer, not by matching
+ * the light-mode numbers. */
+[data-theme='dark'] {
+  --scroll-edge-ink: 255 255 255;
+  --scroll-edge-fade-1: 0.05;
+  --scroll-edge-fade-2: 0.028;
+  --scroll-edge-fade-3: 0.01;
+  --scroll-edge-shadow-down: 0 4px 10px -4px rgb(var(--scroll-edge-ink) / 0.06);
+  --scroll-edge-shadow-up: 0 -4px 10px -4px rgb(var(--scroll-edge-ink) / 0.06);
+}
+
+/** Isolate scroll chain — for nested lists, panels, and navigation drawers. */
+.scroll-isolated {
+  overscroll-behavior: contain;
+}
+
+/** Rigid scroll — for data tables and snap-scroll precision surfaces. */
+.scroll-rigid {
+  overscroll-behavior: none;
+}
+
+/* ─── Scrollbar appearance ───────────────────────────────────────────────────
+ *
+ * WHAT IS AND ISN'T POSSIBLE, per platform:
+ *
+ *  · macOS  — the OS default is already an *overlay* scrollbar: invisible at
+ *             rest, fading in while scrolling, taking zero layout width. Nothing
+ *             needs fixing there, which is why this problem is usually invisible
+ *             to a designer on a Mac and glaring to a user on Windows.
+ *             (A Mac set to "Always show scroll bars" behaves like Windows, and
+ *             these rules cover that too.)
+ *  · Windows / Linux — classic scrollbars: always visible and, critically, they
+ *             OCCUPY LAYOUT WIDTH (~15px), so a panel silently gets narrower and
+ *             a chunky grey gutter sits against the design.
+ *
+ * Both engine families can be styled, so a consistent result IS achievable:
+ *  · `scrollbar-width` / `scrollbar-color` — the standard properties. Firefox
+ *    has had them for years; Chrome/Edge support them from 121. `thin` still
+ *    reserves a (narrow) gutter, so layout stays stable and nothing overlaps.
+ *  · `::-webkit-scrollbar*` — the older Blink/WebKit pseudo-elements, giving
+ *    exact width, colour and radius. Kept alongside the standard properties
+ *    because they win where both are supported and give a nicer thumb.
+ *
+ * Deliberately NOT doing `scrollbar-width: none` / `display: none` as a general
+ * rule: that removes the only cue that a region scrolls at all. Hiding is right
+ * only where another element already carries that signal — the Table hides its
+ * vertical bar because the pagination footer is the boundary, and the horizontal
+ * bar stays visible precisely because nothing else says "there is more to the
+ * right". Use `.scroll-hidden` for that narrow case, `.scroll-slim` by default.
+ */
+
+/**
+ * Slim, low-contrast scrollbar — the default for internal scroll containers
+ * (modal panels, dropdown lists, drawers, side panels).
+ *
+ * The thumb is a neutral token at low opacity that darkens on hover, so it reads
+ * as part of the surface rather than as OS chrome, and the track is transparent
+ * so it disappears against whatever it is sitting on.
+ */
+.scroll-slim {
+  scrollbar-width: thin;
+  scrollbar-color: var(--border-neutral-default) transparent;
+}
+.scroll-slim::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+.scroll-slim::-webkit-scrollbar-track {
+  background: transparent;
+}
+.scroll-slim::-webkit-scrollbar-thumb {
+  background-color: var(--border-neutral-default);
+  border-radius: var(--rounding-round);
+  /* Inset the thumb inside its 8px lane so it reads as a 4px pill with padding,
+     rather than a bar wedged against the content edge. */
+  border: 2px solid transparent;
+  background-clip: content-box;
+}
+.scroll-slim::-webkit-scrollbar-thumb:hover {
+  background-color: var(--icons-neutral-idle);
+}
+/* Stops the little square where the two bars meet from rendering as grey chrome. */
+.scroll-slim::-webkit-scrollbar-corner {
+  background: transparent;
+}
+
+/**
+ * Fully hidden scrollbar — only where a *different* element already tells the
+ * user the region scrolls (see the note above). Scrolling itself is unaffected.
+ */
+.scroll-hidden {
+  scrollbar-width: none;
+}
+.scroll-hidden::-webkit-scrollbar {
+  width: 0;
+  height: 0;
+}
+
+/* ─── Global slim scrollbars, gated on platform ──────────────────────────────
+ *
+ * Applied only when `applyScrollbarMode()` has detected CLASSIC scrollbars —
+ * i.e. Windows/Linux, where bars are always visible and eat layout width.
+ * macOS's overlay scrollbars are already invisible-at-rest and zero-width, and
+ * styling them would REGRESS that into a permanent gutter, so they are left
+ * alone. See `scrollbars.ts` for the full reasoning.
+ *
+ * Call once from the app entry:  applyScrollbarMode()
+ */
+[data-scrollbars='classic'] * {
+  scrollbar-width: thin;
+  scrollbar-color: var(--border-neutral-default) transparent;
+}
+[data-scrollbars='classic'] *::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+[data-scrollbars='classic'] *::-webkit-scrollbar-track {
+  background: transparent;
+}
+[data-scrollbars='classic'] *::-webkit-scrollbar-thumb {
+  background-color: var(--border-neutral-default);
+  border-radius: var(--rounding-round);
+  border: 2px solid transparent;
+  background-clip: content-box;
+}
+[data-scrollbars='classic'] *::-webkit-scrollbar-thumb:hover {
+  background-color: var(--icons-neutral-idle);
+}
+[data-scrollbars='classic'] *::-webkit-scrollbar-corner {
+  background: transparent;
+}