@helloimjolopez-pathway/pathway-tokens 6.0.0 → 7.0.1

package/README.md

@@ -2,26 +2,68 @@
 
 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
 <!-- primitives first: the themes reference these via var(), so this must load -->
@@ -30,23 +72,35 @@ Without a bundler — link the CSS directly:
 <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-contextual.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
 

package/components/scrollbar/scrollbar.jsx

@@ -30,13 +30,28 @@ export const SCROLL = {
   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
+  // WHY THESE TWO RUNGS AND NOT THE FAINTER ONES (2026-09-16):
+  //
+  // Rest was Scrim/Faint (black 16%), which composites to 1.4:1 against both
+  // canvas and sheet. The AA floor for a non-text UI component is 3:1, so a 6px
+  // pill at 1.4:1 sat right at the threshold of perception: one person saw it
+  // and another, on a brighter display, reported the scrollbar as missing
+  // entirely. That was a real report, not a misconfiguration.
+  //
+  // Measured over #fafafa: Faint 16% = 1.4:1, Light 24% = 1.68:1,
+  // Subtle 50% = 3.4:1, Base 70% = 6.57:1. Subtle is the lightest rung that
+  // clears the floor, so rest takes it and hover takes Base, which keeps the
+  // hover step legible as a step.
+  thumbRest:   "var(--semantic-color-scrim-subtle)",   // black 50% — 3.4:1, the lightest rung clearing 3:1
+  thumbHover:  "var(--semantic-color-scrim-base)",     // black 70% — 6.57:1, 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)",
+  // Fade OUT gracefully, but appear INSTANTLY. Animating opacity on the way in
+  // multiplied the thumb's own alpha by the in-flight opacity, so during the
+  // 200ms glide-in it rendered as low as 1.18:1 — below the floor at the exact
+  // moment the user is looking for it. Only the fade-out is animated now.
+  fadeIn:      "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
 };

package/components/sidenav/sidenav.jsx

@@ -62,7 +62,7 @@ export const T = {
     navHover:   c("fill-action-selection-hover"),
     navActive:  c("fill-action-selection-selected"),
     navTrail:   c("fill-action-selection-trail"),
-    infoSubtle: c("stroke-static-neutral-subtle"),   // container right border
+    infoSubtle: c("stroke-static-neutral-base"),   // container right border
   },
   surface: { navLight: c("fill-surface-sheet") },
   // Label, icon and chevron all resolve to the SAME token per state. A nav item
@@ -73,8 +73,8 @@ export const T = {
     navHover:        c("foreground-action-secondary-hover"),
     navActive:       c("foreground-action-secondary-pressed"),
     navDisabled:     c("foreground-action-disabled"),
-    secondary:       c("foreground-static-neutral-subtle"),   // PopoverMenu.SectionLabel
-    secondarySubtle: c("foreground-static-neutral-subtle"),   // NavSectionLabel
+    secondary:       c("foreground-static-neutral-base"),   // PopoverMenu.SectionLabel
+    secondarySubtle: c("foreground-static-neutral-base"),   // NavSectionLabel
   },
   icon: {
     navBase:         c("foreground-action-secondary-rest"),
@@ -85,7 +85,7 @@ export const T = {
   },
   // The active-item stripe takes the loud brand blue straight from the Action
   // tier rather than owning a token of its own.
-  indicator: c("fill-action-primary-pressed"),
+  indicator: c("fill-action-primary-strong-pressed"),
   radius:    u("cornerradius-medium", 8),
 };
 
@@ -310,7 +310,7 @@ export function SideNavTooltip({ label, anchorRect, onMouseEnter, onMouseLeave }
 
 // ─── SectionLabel ─────────────────────────────────────────────────────────────
 // Figma node 40006794-5977 — building block used in CollapsedPopover headers.
-// Tokens: Foreground/Static/Neutral/Light (#7b7b7b), Label/Section/Small/Semibold
+// Tokens: Foreground/Static/Neutral/Base (#313131), Label/Section/Small/Semibold
 //         (11px / 600 / 16px / 0.6px letter-spacing, uppercase)
 // Padding: Padding/Tight (12px left), Padding/XTight (8px vertical)
 export function SectionLabel({ label }) {
@@ -381,7 +381,7 @@ export function PopoverRow({ item, onClick, activeId }) {
 export function CollapseButton({ isSidebarCollapsed, onToggle, collapseIcon, expandIcon }) {
   const [h, setH] = useState(false);
   const labelColor = h ? T.text.navHover : T.text.navBase;
-  const actionIconColor = T.icon.actionSecondary; // #6b6b6b — always static, no hover change
+  const actionIconColor = T.foreground.actionSecondary; // #6b6b6b — always static, no hover change
   return (
     <div style={{ width: "100%" }}>
       <div style={{ height: 1, backgroundColor: T.fill.infoSubtle, marginBottom: L.collapseGap }} />
@@ -431,7 +431,7 @@ export function CollapseButton({ isSidebarCollapsed, onToggle, collapseIcon, exp
 // ─── SideNav (top-level container) ────────────────────────────────────────────
 // ── NavSectionLabel ──────────────────────────────────────────────────────────
 // Optional in-nav section heading. Figma: SideNav.SectionLabel (node 40006794:5975).
-// Tokens: Label/Section/Small/Semibold (11px/600/16px/0.6px), Foreground/Static/Neutral/Subtle (#606060)
+// Tokens: Label/Section/Small/Semibold (11px/600/16px/0.6px), Foreground/Static/Neutral/Base (#606060)
 // Container: h-[40px], pl-[4px], pr-[4px], py-[8px]
 // In collapsed rail: hidden — replaced by a Divider (rendered by SideNav itself, see §2.3)
 // ── NavHeader ────────────────────────────────────────────────────────────────
@@ -441,7 +441,7 @@ export function CollapseButton({ isSidebarCollapsed, onToggle, collapseIcon, exp
 // Hidden on mobile (<768px) — TopNav hamburger is the sole toggle there.
 export function NavHeader({ isSidebarCollapsed, onToggle, collapseIcon, expandIcon }) {
   const [h, setH] = useState(false);
-  const actionIconColor = T.icon.actionSecondary; // #6b6b6b — always static
+  const actionIconColor = T.foreground.actionSecondary; // #6b6b6b — always static
   return (
     <div style={{ width: "100%", flexShrink: 0 }}>
       <div onClick={onToggle} onMouseEnter={() => setH(true)} onMouseLeave={() => setH(false)}
@@ -471,7 +471,7 @@ export function NavHeader({ isSidebarCollapsed, onToggle, collapseIcon, expandIc
           </div>
         )}
       </div>
-      {/* Divider — Stroke/Static/Neutral/Subtle, py-[2px] in Figma */}
+      {/* Divider — Stroke/Static/Neutral/Base, py-[2px] in Figma */}
       <div style={{ padding: "2px 0" }}>
         <div style={{ height: 1, backgroundColor: T.fill.infoSubtle }} />
       </div>
@@ -570,6 +570,34 @@ export function SideNav({
   hideCollapseButton = false,
   defaultExpanded = {},
   className = "",
+  // ── SLOTS ─────────────────────────────────────────────────────────────────
+  // Three insertion points, mirroring the slot structure in Figma. Added
+  // 2026-09-10 at the user's explicit request (which is what the §1.1 Figma
+  // exemption requires before SideNav changes).
+  //
+  // WHY SLOTS RATHER THAN MORE PROPS: the `items` array can express anything
+  // item-SHAPED - a label, an icon, nesting, a disabled state. It cannot
+  // express a module-specific widget: a support button, a plan-usage meter, a
+  // "New" badge component a team already owns. Without a slot those teams have
+  // exactly one option, which is to stop using the component and rebuild the
+  // nav. That is the drift this component exists to prevent, so the escape
+  // hatch has to be inside it.
+  //
+  //   headerEnd  after the collapse toggle in the pinned header. This is the
+  //              common case: a module name, a small action. In Figma the
+  //              header is a slot that can hold the toggle alone, or the
+  //              toggle plus a label or button.
+  //   children   inside the scroll region, after the items. Anything that
+  //              scrolls with the list.
+  //   footer     PINNED below the scroll region, so it stays put while the
+  //              list scrolls. Buttons live here.
+  //
+  // Each is null by default and renders NOTHING when null - no wrapper, no
+  // padding, no border. An always-rendered empty wrapper would shift the
+  // layout of every nav that does not use the slot.
+  headerEnd = null,
+  children = null,
+  footer = null,
 }) {
   const [expanded, setExpanded] = useState(defaultExpanded);
   const [popoverId, setPopoverId] = useState(null);
@@ -670,10 +698,31 @@ export function SideNav({
     }}>
       {/* NavHeader — TOP of nav, PINNED (flexShrink:0) so it stays visible while the
           item list scrolls beneath it. Hidden on mobile (<768px). */}
-      {!hideCollapseButton && (
+      {(!hideCollapseButton || headerEnd) && (
         <div style={{ flexShrink: 0 }}>
-          <NavHeader isSidebarCollapsed={collapsed}
-            onToggle={() => onCollapseChange && onCollapseChange(!collapsed)} />
+          {!hideCollapseButton && (
+            <NavHeader isSidebarCollapsed={collapsed}
+              onToggle={() => onCollapseChange && onCollapseChange(!collapsed)} />
+          )}
+          {/* headerEnd slot. Hidden on the 72px rail: the rail is only wide
+              enough for a centred icon, so arbitrary header content would
+              either overflow it or force it wider. It fades rather than
+              unmounting, on the same curve as the section labels, so the
+              header does not jump when the rail toggles. */}
+          {headerEnd && (
+            <div style={{
+              opacity: collapsed ? 0 : 1,
+              maxHeight: collapsed ? 0 : 200,
+              overflow: "hidden",
+              pointerEvents: collapsed ? "none" : "auto",
+              padding: collapsed ? 0 : `0 ${L.navPadH}`,
+              transition:
+                "opacity var(--motion-duration-4) var(--motion-easing-standard), " +
+                "max-height var(--motion-duration-5) var(--motion-easing-spring)",
+            }}>
+              {headerEnd}
+            </div>
+          )}
         </div>
       )}
 
@@ -734,9 +783,31 @@ export function SideNav({
           </div>
         )}
 
+        {/* Body slot — scrolls with the item list, so it sits INSIDE
+            Scrollable and above the spacer. Use this for content that belongs
+            with the items; use `footer` for anything that must stay visible. */}
+        {children && <div style={{ flexShrink: 0 }}>{children}</div>}
+
         {/* Bottom spacer — fills remaining height */}
         <div style={{ flex: 1, minHeight: L.menuPadB }} />
       </Scrollable>
+
+      {/* Footer slot — OUTSIDE Scrollable and flexShrink:0, so it is pinned to
+          the bottom of the nav and stays put while the list scrolls. The
+          divider only appears when the slot has content, so a nav without a
+          footer is unchanged. Padding drops to the rail's narrower inset when
+          collapsed rather than hiding: a footer button is usually an icon
+          button that still works at 72px, unlike arbitrary header content. */}
+      {footer && (
+        <div style={{
+          flexShrink: 0,
+          borderTop: `0.5px solid ${T.fill.infoSubtle}`,
+          padding: collapsed ? `8px ${L.navColPadH}` : `8px ${L.navPadH}`,
+          transition: "padding var(--motion-duration-6) var(--motion-easing-emphasized)",
+        }}>
+          {footer}
+        </div>
+      )}
     </nav>
   );
 }
@@ -775,7 +846,7 @@ function ChevUp({ size = 10, color }) {
 // right_panel_open — used on the collapse button when sidebar is EXPANDED (click to collapse)
 // Token: Foreground/Action/Secondary/Rest (#6b6b6b)
 // Figma component: SideBar Expand/Collapse, Type=Collapse, node 40006793:3783
-function RightPanelOpenIcon({ size = 12, color = T.icon.actionSecondary }) {
+function RightPanelOpenIcon({ size = 12, color = T.foreground.actionSecondary }) {
   return (
     <svg width={size} height={size} viewBox="0 0 12 12" fill="none">
       <path d="M5.66667 7.86667V4.13333C5.66667 3.97778 5.6 3.87222 5.46667 3.81667C5.33333 3.76111 5.21111 3.78889 5.1 3.9L3.46667 5.53333C3.33333 5.66667 3.26667 5.82222 3.26667 6C3.26667 6.17778 3.33333 6.33333 3.46667 6.46667L5.1 8.1C5.21111 8.21111 5.33333 8.23889 5.46667 8.18333C5.6 8.12778 5.66667 8.02222 5.66667 7.86667ZM1.33333 12C0.966667 12 0.652778 11.8694 0.391667 11.6083C0.130556 11.3472 0 11.0333 0 10.6667V1.33333C0 0.966667 0.130556 0.652778 0.391667 0.391667C0.652778 0.130556 0.966667 0 1.33333 0H10.6667C11.0333 0 11.3472 0.130556 11.6083 0.391667C11.8694 0.652778 12 0.966667 12 1.33333V10.6667C12 11.0333 11.8694 11.3472 11.6083 11.6083C11.3472 11.8694 11.0333 12 10.6667 12H1.33333ZM8.66667 10.6667H10.6667V1.33333H8.66667V10.6667ZM7.33333 10.6667V1.33333H1.33333V10.6667H7.33333Z" fill={color} />
@@ -786,7 +857,7 @@ function RightPanelOpenIcon({ size = 12, color = T.icon.actionSecondary }) {
 // left_panel_open — used on the collapse button when sidebar is COLLAPSED (click to expand)
 // Token: Foreground/Action/Secondary/Rest (#6b6b6b)
 // Figma component: SideBar Expand/Collapse, Type=Expand, node 40006793:3783
-function LeftPanelOpenIcon({ size = 12, color = T.icon.actionSecondary }) {
+function LeftPanelOpenIcon({ size = 12, color = T.foreground.actionSecondary }) {
   return (
     <svg width={size} height={size} viewBox="0 0 12 12" fill="none">
       <path d="M6.33333 4.13333V7.86667C6.33333 8.02222 6.4 8.12778 6.53333 8.18333C6.66667 8.23889 6.78889 8.21111 6.9 8.1L8.53333 6.46667C8.66667 6.33333 8.73333 6.17778 8.73333 6C8.73333 5.82222 8.66667 5.66667 8.53333 5.53333L6.9 3.9C6.78889 3.78889 6.66667 3.76111 6.53333 3.81667C6.4 3.87222 6.33333 3.97778 6.33333 4.13333ZM1.33333 12C0.966667 12 0.652778 11.8694 0.391667 11.6083C0.130556 11.3472 0 11.0333 0 10.6667V1.33333C0 0.966667 0.130556 0.652778 0.391667 0.391667C0.652778 0.130556 0.966667 0 1.33333 0H10.6667C11.0333 0 11.3472 0.130556 11.6083 0.391667C11.8694 0.652778 12 0.966667 12 1.33333V10.6667C12 11.0333 11.8694 11.3472 11.6083 11.6083C11.3472 11.8694 11.0333 12 10.6667 12H1.33333ZM3.33333 10.6667V1.33333H1.33333V10.6667H3.33333ZM4.66667 10.6667H10.6667V1.33333H4.66667V10.6667Z" fill={color} />

package/dist/README.md

@@ -0,0 +1,96 @@
+# Pathway design tokens
+
+**The colour contract is 169 names.** Your full working vocabulary is
+**278**. If you add up every declaration in this folder you get
+827 — that number is not the contract, and the table below says why.
+
+## Link these, in this order
+
+```html
+<link rel="stylesheet" href="primitives.css">
+<link rel="stylesheet" href="themes/light.css">
+<link rel="stylesheet" href="themes/midnight.css">
+<link rel="stylesheet" href="type.css">
+<link rel="stylesheet" href="layout.css">
+<link rel="stylesheet" href="motion.css">
+<link rel="stylesheet" href="layout-responsive.css">
+<link rel="stylesheet" href="breakpoints.css">
+```
+
+`primitives.css` must come first. Every semantic token resolves through it, so if it is
+missing all colour resolves to nothing and the page renders unstyled **with no console
+error**.
+
+## The files
+
+| File | Names | Safe to name? | Must load? | What it is |
+|---|---|---|---|---|
+| `primitives.css` | 352 | **no** | yes | Raw colour ramps. Load it; do not name it. |
+| `themes/light.css` | 169 | yes | yes | Colour contract, Light Mode. |
+| `themes/midnight.css` | 169 | yes | yes | Colour contract, Midnight Mode. Same names as light. |
+| `type.css` | 41 | yes | yes | Type scale. Compose from these. |
+| `layout.css` | 40 | yes | yes | Spacing, radii, border widths. |
+| `layout-contextual.css` | 28 | **no** | **no** | Per-component metrics. This repo's components use these. |
+| `motion.css` | 17 | yes | yes | Durations and easings. |
+| `layout-responsive.css` | 6 | yes | yes | Sheet and TopNav padding. The only layout tokens with media queries. |
+| `breakpoints.css` | 5 | yes | yes | Breakpoint values. |
+
+Each file repeats this in its own header.
+
+## Can I use a primitive?
+
+Yes. Nothing stops you and nothing should. But `Primitive: Color` has exactly **one
+mode** and `themes/midnight.css` declares **zero** primitives, so a primitive holds one
+value forever:
+
+```css
+color: var(--primitive-color-brand-400);               /* stays this blue in Midnight */
+color: var(--semantic-color-fill-action-primary-strong-rest);  /* flips with the theme */
+```
+
+Use one when you specifically want a value that does not respond to the theme.
+
+## Theming
+
+One name, two values, resolved by selector. Set `data-theme="midnight"` on `<html>`
+to flip the page, or on any element to flip just that subtree — it composes both ways,
+so a light island can sit inside a dark island.
+
+Never put a mode in a property name. `--semantic-color-light-mode-*` came from
+`tokens.css`, retired 2026-09-03, and resolves to nothing.
+
+## Type
+
+No composite styles and no `.pw-type-*` classes. Name five properties:
+
+```css
+font-family:    var(--semantic-type-family-brand);
+font-size:      var(--semantic-type-font-size-m);
+font-weight:    var(--semantic-type-weight-semibold);
+line-height:    var(--semantic-type-line-height-m-single);
+letter-spacing: var(--semantic-type-letter-spacing-compact);
+```
+
+## Layout units carry their unit
+
+```css
+border-radius: var(--semantic-layout-units-cornerradius-small);             /* correct */
+border-radius: calc(var(--semantic-layout-units-cornerradius-small) * 1px);  /* WRONG */
+```
+
+The second is `calc(4px * 1px)`, which is not a length, so the browser drops it silently.
+
+## Machine-readable
+
+`contract.json` lists every consumable name plus the per-file counts, so you can lint
+against it if you want the boundary enforced.
+
+## Motion is not in Figma
+
+The Variables panel has zero motion variables; `motion.css` is generated from
+`docs/design-system-spec.md` §2. Anyone rebuilding tokens from a Figma export gets no
+motion at all and no warning — consume the package instead.
+
+---
+
+Repo: https://github.com/helloimjolopez-collab/pathway-ds

package/dist/breakpoints.css

@@ -1,11 +1,18 @@
-/**
- * Do not edit directly, this file was auto-generated.
- */
+/*
+ ==========================================================================
+ PATHWAY DESIGN TOKENS — CONTRACT
+ ==========================================================================
 
+ The breakpoint values. Name these freely.
+
+ Declares 5 custom properties.
+ Generated — do not edit. Run `npm run build-tokens`.
+ ==========================================================================
+*/
 :root {
+  --breakpoints-desktop-1920px: 1920px;
   --breakpoints-desktop-1440px: 1440px;
   --breakpoints-tablet-1024px: 1024px;
   --breakpoints-tablet-768px: 768px;
   --breakpoints-mobile-393px: 393px;
-  --breakpoints-desktop-1920px: 1920px;
 }