@helloimjolopez-pathway/pathway-tokens 5.4.0 → 7.0.0

package/README.md

@@ -2,43 +2,105 @@
 
 Design system for Ministry Brands Amplify. Tokens + components + specifications, all versioned in one place, with Storybook deployed from `main`.
 
+> **Looking for the tokens?** → **[TOKENS.md](TOKENS.md)** — where the CSS lives, which
+> of the 267 names you may use, and what to link in what order.
+
 ## Using the tokens
 
-The Pathway token library is published to npm and updated automatically on every token sync.
+**The colour contract is 169 names. Your full working vocabulary is 267.**
+
+That is the number worth knowing, because adding up every declaration in the token
+folder gives 966 and the retired `tokens.css` used to emit 2,338. Neither is the
+contract. The difference is that primitives ship but are not named, and the modes share
+one name set rather than each having their own.
+
+| | Count | Name these? |
+|---|---|---|
+| Colour (`themes/light.css`, `themes/midnight.css` — same names) | **169** | Yes |
+| Type scale (`type.css`) | 41 | Yes |
+| Spacing, radii, borders (`layout.css`) | 40 | Yes |
+| Motion (`motion.css`) | 17 | Yes |
+| Sheet and TopNav padding (`layout-responsive.css`) | 6 | Yes |
+| Breakpoints (`breakpoints.css`) | 5 | Yes |
+| **Working vocabulary** | **267** | |
+| Raw ramps (`primitives.css`) | 350 | **No** — but you must load it |
+| Component metrics (`layout-contextual.css`) | 26 | This repo's components |
+
+**The CSS lives in [`src/tokens/`](src/tokens/), and that folder has its own README**
+covering load order, theming, the primitives question and the traps. Read it before
+wiring anything up. The published package carries the same guidance in `dist/README.md`,
+plus `dist/contract.json` listing every consumable name if you want to lint against it.
+
+### Install
 
 ```bash
 npm install @helloimjolopez-pathway/pathway-tokens
 ```
 
-```js
-// CSS custom properties — import once in your app entry point
-import "@helloimjolopez-pathway/pathway-tokens/css";
+NuGet: `Pathway.DesignTokens`.
 
-// JS token object
+```js
+// Every stylesheet is a named subpath export. primitives.css MUST come first —
+// the themes resolve through it, so without it all colour resolves to nothing
+// and the page renders unstyled with no console error.
+import "@helloimjolopez-pathway/pathway-tokens/primitives.css";
+import "@helloimjolopez-pathway/pathway-tokens/themes/light.css";
+import "@helloimjolopez-pathway/pathway-tokens/themes/midnight.css";
+import "@helloimjolopez-pathway/pathway-tokens/type.css";
+import "@helloimjolopez-pathway/pathway-tokens/layout.css";
+import "@helloimjolopez-pathway/pathway-tokens/layout-responsive.css";
+import "@helloimjolopez-pathway/pathway-tokens/motion.css";
+import "@helloimjolopez-pathway/pathway-tokens/breakpoints.css";
+
+// JS token object, and the raw DTCG JSON for tooling
 import tokens from "@helloimjolopez-pathway/pathway-tokens";
-
-// Raw DTCG JSON (for tooling)
 import tokenJson from "@helloimjolopez-pathway/pathway-tokens/json";
+import contract from "@helloimjolopez-pathway/pathway-tokens/contract.json";
 ```
 
-Without a bundler — link the CSS directly:
+There is deliberately no single `/css` entry point. One combined file was what
+`tokens.css` used to be: it emitted every token times every mode with the mode baked
+into the property name, 2,338 custom properties, and it is the reason this system read
+as too granular to adopt. Retired 2026-09-03 and not coming back.
+
+### Without a bundler
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/tokens.css" />
+<!-- primitives first: the themes reference these via var(), so this must load -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/primitives.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/themes/light.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/themes/midnight.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/type.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/layout.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/layout-responsive.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/motion.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/helloimjolopez-collab/pathway-ds@main/src/tokens/breakpoints.css" />
 ```
 
-Once loaded, use the custom properties anywhere:
+`@main` tracks the latest. Pin a tag instead if you need a fixed version.
+
+### Using a token
 
 ```css
-.my-component {
-  background: var(--semantic-color-light-mode-fill-static-brand-base);
-  color:      var(--semantic-color-light-mode-text-static-primary-inverse);
+.card {
+  background: var(--semantic-color-fill-surface-sheet);
+  color:      var(--semantic-color-foreground-static-neutral-strong);
+  border:     var(--semantic-layout-units-borderwidth-base) solid
+              var(--semantic-color-stroke-static-neutral-base);
+  border-radius: var(--semantic-layout-units-cornerradius-medium);
 }
 ```
 
-Full token reference: [Storybook → Tokens](https://helloimjolopez-collab.github.io/pathway-ds/storybook/?path=/docs/tokens-primitives-color--docs) · [Token architecture](tokens/README.md) · [Agent brief](tokens/agent-brief.md)
+One name carries both modes. Set `data-theme="midnight"` on `<html>` to flip the page,
+or on any element to flip just that subtree. Never write a mode into a property name —
+`--semantic-color-light-mode-*` resolves to nothing.
+
+### Can I use a primitive?
 
----
+Yes, and nothing stops you. But `Primitive: Color` has exactly one mode, so a primitive
+holds one value forever and will **not** respond to `data-theme`. Reach for one only
+when you specifically want a fixed value. Full reasoning in
+[`src/tokens/README.md`](src/tokens/README.md).
 
 ## Layout
 
@@ -57,7 +119,7 @@ pathway-ds/
 │   ├── figma-export/            Raw Figma export (sync target)
 │   └── pathway-design-tokens.json   W3C DTCG format
 ├── src/
-│   ├── tokens/                  Built output (tokens.css + tokens.js)
+│   ├── tokens/                  Built output (the 8-file contract + tokens.js)
 │   └── stories/                 Storybook sources
 │       ├── Primitives/          Token primitives (Color, Typography, Units)
 │       ├── Semantics/           Semantic tokens (light/dark, layout, typography)
@@ -65,7 +127,6 @@ pathway-ds/
 ├── .storybook/
 ├── .github/workflows/           Token sync · component sync · Storybook deploy
 ├── scripts/                     Token sync/audit/fix + component build scripts
-└── storybook/                   Built Storybook output (deployed by CI)
 ```
 
 ## Governance — where things live
@@ -74,7 +135,7 @@ pathway-ds/
 |---|---|
 | Published token package | [`@helloimjolopez-pathway/pathway-tokens`](https://www.npmjs.com/package/@helloimjolopez-pathway/pathway-tokens) |
 | Token values | [`tokens/pathway-design-tokens.json`](tokens/pathway-design-tokens.json) (source-of-truth, synced from Figma) |
-| Built CSS consumed by Storybook | [`src/tokens/tokens.css`](src/tokens/tokens.css) (auto-regenerated by Style Dictionary) |
+| Built CSS consumed by Storybook | the eight files in [`src/tokens/`](src/tokens/) (auto-regenerated by Style Dictionary) |
 | Component geometry, tokens, accessibility rules | [`components/<name>/<name>-spec.md`](components/) |
 | Component reference implementation | [`components/<name>/<name>.html`](components/) |
 | How a component appears in Storybook | [`src/stories/Library/<Name>/`](src/stories/Library/) |
@@ -87,7 +148,7 @@ Three workflows in `.github/workflows/`:
 
 1. **`sync-tokens.yml`** — fires when `tokens/figma-export/**` changes. Normalises the Figma export into the W3C DTCG JSON and commits `tokens/pathway-design-tokens.json`.
 2. **`sync-component.yml`** — fires when `components/sidenav/sidenav.html` changes. Regenerates the `sidenav-figmamake.html` variant and commits it.
-3. **`deploy-storybook.yml`** — fires when `tokens/`, `src/`, `.storybook/`, `components/`, `docs/`, or `style-dictionary.config.js` changes. Rebuilds Style Dictionary + Storybook and commits the built site to `/storybook/` on `main`. GitHub Pages serves that folder.
+3. **`deploy-pages.yml`** — fires on every push to `main`. Builds Style Dictionary and Storybook fresh and deploys a clean `_site` artifact through the official Pages actions. Nothing is committed back to `main`. (`deploy-storybook.yml` is the retired predecessor, kept manual-only; it committed 14MB of build output per push.)
 
 Source of truth is always the repo on `main`; Storybook is a downstream artifact.
 

package/components/scrollbar/scrollbar.jsx

@@ -0,0 +1,184 @@
+/**
+ * Scrollable — Pathway Design System
+ *
+ * A reusable overlay-scrollbar wrapper. Hides the native OS scrollbar entirely and renders
+ * one custom liquid-glass thumb so scrolling looks and behaves IDENTICALLY on macOS, Windows,
+ * iOS, and Android (native scrollbars can't be made consistent — this sidesteps them).
+ *
+ * Behaviour (see components/scrollbar/scrollbar-spec.md):
+ *   - Thumb height is PROPORTIONAL to content: (viewport / total) × track, floored at 28px.
+ *   - Reveal: appears while scrolling, fades ~900ms after; also appears when the MOUSE is near
+ *     the right-edge bar (so it can be grabbed). It does NOT appear from hovering the panel.
+ *   - Drag: MOUSE only, via a wider invisible grab strip (the 6px thumb alone is hard to hit).
+ *   - Touch: passive — the bar just shows position; you scroll by swiping content. The grab
+ *     strip is disabled on touch devices via a `(hover: none)` rule.
+ *   - Keyboard / a11y: the content scrolls natively (arrows, PageUp/Down, Home/End, Space); the
+ *     thumb is decorative (`aria-hidden`) and never the only scroll mechanism.
+ *
+ * Usage:
+ *   <Scrollable style={{ flex: 1, minHeight: 0 }}>…tall content…</Scrollable>
+ */
+
+import React, { useRef, useState, useEffect, useCallback } from "react";
+
+// ─── TOKENS ──────────────────────────────────────────────────────────────────
+// Every colour + unit resolves through a SEMANTIC Pathway token — no primitives,
+// no hardcoded hex/px. Motion uses the --motion-* tokens (durations/easings from design-system-spec §2).
+export const SCROLL = {
+  thumbWidth:  "var(--semantic-layout-units-padding-xtight)",     // 6px — visible thumb thickness
+  thumbRadius: "var(--semantic-layout-units-cornerradius-full)",  // fully-rounded pill
+  thumbMin:    28,                                                // px — min thumb length (grab-target floor); JS layout math
+  gutter:      "var(--semantic-layout-units-padding-xxxtight)",   // 2px — inset from the right edge
+  grabZone:    16,                                                // px — invisible mouse grab strip (wider than the 6px thumb so it's catchable)
+  thumbRest:   "var(--semantic-color-scrim-faint)",    // black 16% — faint overlay (rest)
+  thumbHover:  "var(--semantic-color-scrim-light)",    // black 30% — hover/drag
+  thumbBlur:   "blur(8px) saturate(180%)",
+  // Hairline glass edge: semantic white at 35% via color-mix.
+  thumbEdge:   "inset 0 0 0 0.5px color-mix(in srgb, var(--semantic-color-fill-static-neutral-faint) 35%, transparent)",
+  // Asymmetric fade, motion-token driven: snappy appear (200ms decelerate glide-in), graceful fade-out (380ms).
+  fadeIn:      "opacity var(--motion-duration-3) var(--motion-easing-decelerate), background var(--motion-duration-3) var(--motion-easing-standard)",
+  fadeOut:     "opacity var(--motion-duration-5) var(--motion-easing-standard)",
+  idleHideMs:  500,                                               // hide the thumb this long after scrolling stops / mouse leaves the bar
+};
+
+// Injected once: hide the native bar on the opt-in class, and disable the mouse grab strip on
+// touch devices so finger-swipes scroll the content underneath (the thumb stays a passive indicator).
+if (typeof document !== "undefined" && !document.getElementById("pds-scrollable-base")) {
+  const s = document.createElement("style");
+  s.id = "pds-scrollable-base";
+  s.textContent =
+    ".pds-scrollable__view{scrollbar-width:none;-ms-overflow-style:none}" +
+    ".pds-scrollable__view::-webkit-scrollbar{width:0;height:0;display:none}" +
+    "@media (hover: none){.pds-scrollable__grab{pointer-events:none!important}}";
+  document.head.appendChild(s);
+}
+
+export function Scrollable({ children, className = "", style = {}, viewClassName = "", viewStyle = {} }) {
+  const viewRef = useRef(null);
+  const dragRef = useRef(null);
+  const idleRef = useRef(null);
+  const nearRef = useRef(false);                    // mouse currently near the right-edge bar
+  const [thumb, setThumb] = useState({ h: 0, top: 0, show: false });
+  const [active, setActive] = useState(false);       // thumb visible (scrolling, near-bar, or dragging)
+  const [hot, setHot]       = useState(false);       // mouse over / dragging the grab strip
+
+  // Thumb height is PROPORTIONAL to content; floored at thumbMin. Position maps the floored
+  // thumb across the full track so it still reaches top and bottom exactly.
+  const recompute = useCallback(() => {
+    const el = viewRef.current;
+    if (!el) return;
+    const { scrollHeight, clientHeight, scrollTop } = el;
+    if (scrollHeight <= clientHeight + 1) { setThumb(t => (t.show ? { ...t, show: false } : t)); return; }
+    const h   = Math.max(SCROLL.thumbMin, (clientHeight / scrollHeight) * clientHeight);
+    const top = (scrollTop / (scrollHeight - clientHeight)) * (clientHeight - h);
+    setThumb({ h, top, show: true });
+  }, []);
+
+  useEffect(() => {
+    recompute();
+    const el = viewRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(recompute);
+    ro.observe(el);
+    Array.from(el.children).forEach(c => ro.observe(c));
+    return () => ro.disconnect();
+  }, [children, recompute]);
+
+  const scheduleHide = () => {
+    clearTimeout(idleRef.current);
+    idleRef.current = setTimeout(() => {
+      if (!dragRef.current && !nearRef.current) setActive(false);
+    }, SCROLL.idleHideMs);
+  };
+  const wake = () => { setActive(true); scheduleHide(); };          // reveal while scrolling
+  const onScroll = () => { recompute(); wake(); };
+
+  // Edge-proximity reveal (mouse): show the bar when the cursor is within grabZone of the right
+  // edge, so it can be grabbed — but NOT from hovering the rest of the panel.
+  const onMouseMove = (e) => {
+    const rect = e.currentTarget.getBoundingClientRect();
+    if (rect.right - e.clientX <= SCROLL.grabZone) {
+      nearRef.current = true; setActive(true); clearTimeout(idleRef.current);
+    } else if (nearRef.current) {
+      nearRef.current = false; scheduleHide();
+    }
+  };
+  const onMouseLeave = () => { nearRef.current = false; if (!dragRef.current) scheduleHide(); };
+
+  // Drag (mouse only). The grab strip carries this; the visual thumb is decorative.
+  const onGrabDown = (e) => {
+    e.preventDefault();
+    const el = viewRef.current;
+    if (!el) return;
+    dragRef.current = { startY: e.clientY, startTop: el.scrollTop };
+    setHot(true); setActive(true); clearTimeout(idleRef.current);
+    const onMove = (ev) => {
+      const { scrollHeight, clientHeight } = el;
+      const h = Math.max(SCROLL.thumbMin, (clientHeight / scrollHeight) * clientHeight);
+      const ratio = (scrollHeight - clientHeight) / (clientHeight - h);
+      el.scrollTop = dragRef.current.startTop + (ev.clientY - dragRef.current.startY) * ratio;
+    };
+    const onUp = () => {
+      dragRef.current = null; setHot(false);
+      document.removeEventListener("mousemove", onMove);
+      document.removeEventListener("mouseup", onUp);
+      wake();
+    };
+    document.addEventListener("mousemove", onMove);
+    document.addEventListener("mouseup", onUp);
+  };
+
+  const barTop = thumb.top, barH = thumb.h;
+
+  return (
+    <div
+      className={`pds-scrollable ${className}`}
+      style={{ position: "relative", minHeight: 0, ...style }}
+      onMouseMove={onMouseMove}
+      onMouseLeave={onMouseLeave}
+    >
+      <div
+        ref={viewRef}
+        className={`pds-scrollable__view ${viewClassName}`}
+        onScroll={onScroll}
+        style={{ height: "100%", overflowY: "auto", overflowX: "hidden", ...viewStyle }}
+      >
+        {children}
+      </div>
+
+      {thumb.show && (
+        <>
+          {/* Visual thumb — decorative, never intercepts pointer events. */}
+          <div
+            aria-hidden="true"
+            style={{
+              position: "absolute", top: barTop, right: SCROLL.gutter,
+              width: SCROLL.thumbWidth, height: barH, borderRadius: SCROLL.thumbRadius,
+              background: hot ? SCROLL.thumbHover : SCROLL.thumbRest,
+              backdropFilter: SCROLL.thumbBlur, WebkitBackdropFilter: SCROLL.thumbBlur,
+              boxShadow: SCROLL.thumbEdge,
+              opacity: active ? 1 : 0, transition: active ? SCROLL.fadeIn : SCROLL.fadeOut,
+              pointerEvents: "none", zIndex: 5,
+            }}
+          />
+          {/* Invisible mouse grab strip — wider than the thumb so it's catchable; disabled on
+              touch via the (hover:none) rule so finger-swipes scroll the content beneath. */}
+          <div
+            aria-hidden="true"
+            className="pds-scrollable__grab"
+            onMouseDown={onGrabDown}
+            onMouseEnter={() => setHot(true)}
+            onMouseLeave={() => setHot(false)}
+            style={{
+              position: "absolute", top: barTop, right: 0,
+              width: SCROLL.grabZone, height: barH,
+              pointerEvents: active ? "auto" : "none", zIndex: 6, background: "transparent",
+            }}
+          />
+        </>
+      )}
+    </div>
+  );
+}
+
+export default Scrollable;