@helloimjolopez-pathway/pathway-tokens 10.0.0 → 10.0.2

package/components/sidenav/sidenav.jsx

@@ -47,12 +47,17 @@ import ReactDOM from "react-dom";
  * Token names verified against the Figma Variables panel on 2026-09-02.
  */
 const c = (name) => `var(--semantic-color-${name})`;
-const u = (name, fallback) => `var(--semantic-layout-units-${name}, ${fallback}px)`;
+// Elevation is its own collection and already carries the whole shadow string,
+// theme-resolved: light casts rgba(24,27,43,0.08), midnight casts
+// rgba(0,1,19,0.70). A hand-written rgba(0,0,0,0.03) is invisible on a dark
+// canvas, which is exactly how dark mode ended up looking flat.
+const c2 = (name) => `var(${name})`;
+const u = (name) => `var(--semantic-layout-units-${name})`;
 // Component metrics live in the CONTEXTUAL collection, not the semantic one, so
 // they need their own prefix. SideNav's two widths moved there on 2026-09-16:
 // they were numeric literals with a "no token in Figma" comment, which was true
 // until the tokens were created.
-const x = (name, fallback) => `var(--contextual-layout-units-${name}, ${fallback}px)`;
+const x = (name) => `var(--contextual-layout-units-${name})`;
 
 // Negate a length that may be either a number or a var() reference. Used for the
 // scroll-region edge bleed, where `-value` on a string would give NaN.
@@ -94,7 +99,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-strong-pressed"),
-  radius:    u("cornerradius-base", 8),
+  radius:    u("cornerradius-base"),
 };
 
 /*
@@ -111,27 +116,27 @@ export const L = {
   // collapsed rail 12, vertical 8, item gap 6. These were on the generic
   // semantic scale until 2026-09-17, which meant a change to Padding/Base
   // would silently move the nav.
-  navPadH:     x("sidenav-padding-horizontal-expanded", 16),
-  navColPadH:  x("sidenav-padding-horizontal-collapsed", 12),
-  navPadTop:   x("sidenav-padding-vertical", 8),
+  navPadH:     x("sidenav-padding-horizontal-expanded"),
+  navColPadH:  x("sidenav-padding-horizontal-collapsed"),
+  navPadTop:   x("sidenav-padding-vertical"),
   // Read from SideNav.Container in Figma on 2026-09-16: every expanded variant
   // is 250 wide (Base, Stroked, Mobile.Base, Mobile.Stroked) and every
   // collapsed one is 72. Was 240, which no longer matched the component.
-  navW:        x("sidenav-width-expanded", 250),
-  navWcol:     x("sidenav-width-collapsed", 72),
-  menuGap:     x("sidenav-gap-vertical", 6),
-  menuPadT:    u("padding-tight", 8),
-  menuPadB:    u("padding-xxwide", 56),
-  itemH:       u("accessibility-touch-target-aa-height", 44),
+  navW:        x("sidenav-width-expanded"),
+  navWcol:     x("sidenav-width-collapsed"),
+  menuGap:     x("sidenav-gap-vertical"),
+  menuPadT:    u("padding-tight"),
+  menuPadB:    u("padding-xxwide"),
+  itemH:       u("accessibility-touch-target-aa-height"),
   iconWrap:    24,   // no token in Figma — leading icon wrapper
   iconInner:   16,   // Material Symbols Rounded frame size, per design-system-spec §7.2
-  rowPadH:     u("padding-tight", 8),
-  textPad:     u("padding-xtight", 6),
+  rowPadH:     u("padding-tight"),
+  textPad:     u("padding-xtight"),
   childIndent: 24,   // no token in Figma — level-1 left indent
   stripeW:     4,    // no token in Figma — indicator stripe width
-  colPadL:     u("padding-medium", 12),
-  colPadR:     u("padding-tight", 8),
-  collapseGap: u("padding-xxtight", 4),
+  colPadL:     u("padding-medium"),
+  colPadR:     u("padding-tight"),
+  collapseGap: u("padding-xxtight"),
 };
 
 // ─── IndicatorStripe ──────────────────────────────────────────────────────────
@@ -313,7 +318,7 @@ export function SideNavTooltip({ label, anchorRect, onMouseEnter, onMouseLeave }
         top: anchorRect.top + anchorRect.height / 2,
         zIndex: 1000, backgroundColor: T.surface.navLight,
         border: `0.5px solid ${c("stroke-static-neutral-faint")}`, borderRadius: 8,
-        boxShadow: "2px 2px 8px 0px rgba(0,0,0,0.03)",
+        boxShadow: c2("--elevation-widget"),
         padding: "6px 8px", whiteSpace: "nowrap", pointerEvents: "auto",
         animation: "popoverInCentered var(--motion-duration-3) var(--motion-easing-spring) forwards" }}>
       <span style={{ fontFamily: "'Red Hat Text',sans-serif", fontWeight: 400,
@@ -352,7 +357,7 @@ export function CollapsedPopover({ item, onClick, anchorRect, onMouseEnter, onMo
       style={{ position: "fixed", left: anchorRect.right + 8, top: anchorRect.top,
         zIndex: 1000, backgroundColor: T.surface.navElevated,
         border: `0.5px solid ${c("stroke-static-neutral-faint")}`, borderRadius: 8,
-        boxShadow: "2px 2px 8px 4px rgba(0,0,0,0.03)",
+        boxShadow: c2("--elevation-widget"),
         padding: 6, minWidth: 200, pointerEvents: "auto",
         animation: "popoverIn var(--motion-duration-3) var(--motion-easing-spring) forwards" }}>
       {/* Section label — Figma component 40006794-5977 */}
@@ -398,7 +403,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.foreground.actionSecondary; // #6b6b6b — always static, no hover change
+  const actionIconColor = T.icon.actionSecondary; // #6b6b6b — always static, no hover change
   return (
     <div style={{ width: "100%" }}>
       <div style={{ height: 1, backgroundColor: T.fill.infoSubtle, marginBottom: L.collapseGap }} />
@@ -458,7 +463,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.foreground.actionSecondary; // #6b6b6b — always static
+  const actionIconColor = T.icon.actionSecondary; // #6b6b6b — always static
   return (
     <div style={{ width: "100%", flexShrink: 0 }}>
       <div onClick={onToggle} onMouseEnter={() => setH(true)} onMouseLeave={() => setH(false)}
@@ -503,7 +508,7 @@ export function NavSectionLabel({ label }) {
       flexShrink: 0 }}>
       <span style={{ fontFamily: "'Red Hat Text',sans-serif", fontWeight: 600,
         fontSize: 11, lineHeight: "16px", letterSpacing: "0.6px",
-        textTransform: "uppercase", color: T.text.secondarySubtle || "#606060",
+        textTransform: "uppercase", color: T.text.secondarySubtle,
         whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
         {label}
       </span>
@@ -863,7 +868,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.foreground.actionSecondary }) {
+function RightPanelOpenIcon({ size = 12, color = T.icon.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} />
@@ -874,7 +879,7 @@ function RightPanelOpenIcon({ size = 12, color = T.foreground.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.foreground.actionSecondary }) {
+function LeftPanelOpenIcon({ size = 12, color = T.icon.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

@@ -2,7 +2,7 @@
 
 **The colour contract is 210 names.** Your full working vocabulary is
 **360**. If you add up every declaration in this folder you get
-1152 — that number is not the contract, and the table below says why.
+1152. That number is not the contract, and the table below says why.
 
 ## Link these, in this order
 
@@ -53,7 +53,7 @@ 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,
+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
@@ -80,16 +80,106 @@ border-radius: calc(var(--semantic-layout-units-cornerradius-small) * 1px);  /*
 
 The second is `calc(4px * 1px)`, which is not a length, so the browser drops it silently.
 
+## How to choose a token
+
+Most of the cost of adopting this package is not installing it. It is deciding
+which of the colour names belongs on something you already built. This is the
+rule.
+
+Both tiers carry a family (`neutral`, `brand`, `negative`) and an emphasis rung
+(`faint`, `subtle`, `base`, `bold`, `strong`). Only one of them carries state.
+
+| | what it means | example |
+|---|---|---|
+| Emphasis | how loud this element is. Chosen once, never changes. | a divider is `stroke-static-neutral-faint`, permanently |
+| State | where an element is in an interaction right now. One element moves through all of them. | a button is `rest`, then `hover`, then `pressed` |
+
+So the question is not how many values exist. `Static` has six rungs and is
+still single-valued per element. The question is:
+
+> Does this element's colour change because of something the user does to it?
+
+Yes means **Action**, and you need its whole state set. No means **Static**, and
+you pick one emphasis rung and stop.
+
+As a procedure:
+
+1. Interactive? Action. Otherwise Static.
+2. Tier: a background is `fill`, text or an icon is `foreground`, a border or
+   outline is `stroke`.
+3. Family: `neutral`, `brand`, `negative`, `positive`, `info`, `attention`,
+   `severe`, or an `accent` hue.
+4. Emphasis rung, quietest to loudest: `faint`, `subtle`, `base`, `bold`,
+   `strong`.
+5. If Action, take `-rest`, `-hover`, `-pressed` together, plus `-disabled`.
+
+## What the names do not promise
+
+The names are deliberately legible so they can assist mapping. The cost of that
+legibility is that a name can read like a promise it is not making.
+
+- **`primary` is not your primary button.** It means *a* primary action. This
+  package ships no button and has no opinion about yours. If your main call to
+  action is visually quiet, the loud primary token is the wrong one for it
+  however well the words line up.
+- **A component-shaped name is not a component contract.** `fill-action-field-*`
+  describes a field-like surface. Nothing here constrains component anatomy.
+- **Two names resolving to the same value are not interchangeable.** Some pairs
+  currently share a value in some themes. They mean different things and are
+  free to diverge in the next release. Choose by the rule above, not by which
+  value looks right today.
+- **`-on-strong` and `-on-subtle` are pairing constraints, not shades.**
+  `foreground-static-brand-on-strong` means the foreground to use ON a strong
+  fill. It is a contrast guarantee about a combination. Using it on a light
+  surface is an accessibility failure, not a quiet variant.
+- **Absence is sometimes deliberate.** There is no foreground rung lighter than
+  `#484848`, because everything lighter fails WCAG AA on white. A missing grey
+  is a refusal, not a gap. Report it rather than reaching for a primitive.
+
+## Why the architecture is shaped this way
+
+Worth knowing, because it explains the shape rather than just stating it.
+
+**One token library skins several codebases, products and UI libraries, and
+there is no shared component library yet.** That single constraint sets the
+whole design. The names have to be self-explanatory enough to help a developer
+map an existing product onto them, without being so granular that the set
+bloats and nobody adopts it. Everything below follows from that.
+
+**Action and Static are separate tiers because state is the only axis Action
+adds.** Both carry family and emphasis. When a component library exists, the
+component will carry the context and this fork will stop being something anyone
+picks by hand. Until then, the tier is what tells you whether a value has to
+respond to a pointer.
+
+**Modes live on the semantic tier, never in a name.** One name resolves to a
+different value per brand theme (Amplify, NewCo) and per mode (Light, Dark), so
+the colour contract is a few hundred names carrying several times that many
+values. A brand or a mode in a property name means something has gone wrong;
+`--semantic-color-light-mode-*` is retired and resolves to nothing.
+
+**Primitives are published so that bindings resolve, not so that they get
+applied.** Every primitive carries "Do not apply directly" in its own
+description. If you find yourself naming a `--primitive-color-*`, the token you
+want either exists under a semantic name or does not exist yet.
+
+**If two names still look equally right, say which two.** A name that cannot be
+chosen between is a defect here, not in your understanding. It is also the most
+useful feedback a consuming team can send, because a mapping is invisible from
+this side until someone reports it.
+
 ## 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.
+against it if you want the boundary enforced. It also carries a `guidance` block with
+the choosing rule above in structured form, for a tool resolving a design onto these
+names without a human in the loop.
 
 ## 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.
+motion at all and no warning, so consume the package instead.
 
 ---
 

package/dist/brands/newco/primitives.css

@@ -349,16 +349,16 @@
   --primitive-color-saffron-75: #fee2b3;
   --primitive-color-saffron-100: #fed897;
   --primitive-color-saffron-150: #ffc864;
-  --primitive-color-saffron-200: #eab655;
-  --primitive-color-saffron-250: #d6a549;
-  --primitive-color-saffron-300: #bf9342;
-  --primitive-color-saffron-350: #aa843e;
-  --primitive-color-saffron-400: #91723b;
-  --primitive-color-saffron-500: #6d5936;
-  --primitive-color-saffron-600: #4e422d;
-  --primitive-color-saffron-700: #342d21;
-  --primitive-color-saffron-800: #1d1912;
-  --primitive-color-saffron-900: #050301;
+  --primitive-color-saffron-200: #efb44d;
+  --primitive-color-saffron-250: #dfa23e;
+  --primitive-color-saffron-300: #cb8e31;
+  --primitive-color-saffron-350: #b97e2b;
+  --primitive-color-saffron-400: #a26b26;
+  --primitive-color-saffron-500: #7c5324;
+  --primitive-color-saffron-600: #583e24;
+  --primitive-color-saffron-700: #3d2a19;
+  --primitive-color-saffron-800: #23170b;
+  --primitive-color-saffron-900: #0a0200;
   --primitive-color-saffron-150-16: rgba(255, 200, 100, 0.16);
   --primitive-color-saffron-150-24: rgba(255, 200, 100, 0.24);
   --primitive-color-saffron-150-36: rgba(255, 200, 100, 0.36);

package/dist/brands/newco/themes/dark.css

@@ -68,11 +68,11 @@
   --semantic-color-fill-static-info-subtle: var(--primitive-color-amethyst-350-16);
   --semantic-color-fill-static-negative-strong: var(--primitive-color-red-400);
   --semantic-color-fill-static-negative-subtle: var(--primitive-color-red-300-16);
-  --semantic-color-fill-static-neutral-base: var(--primitive-color-cool-neutral-600);
-  --semantic-color-fill-static-neutral-faint: var(--primitive-color-cool-neutral-800);
+  --semantic-color-fill-static-neutral-base: var(--primitive-color-midnight-800);
+  --semantic-color-fill-static-neutral-faint: var(--primitive-color-midnight-900);
   --semantic-color-fill-static-neutral-mono: var(--primitive-color-cool-neutral-0);
-  --semantic-color-fill-static-neutral-strong: var(--primitive-color-cool-neutral-400);
-  --semantic-color-fill-static-neutral-subtle: var(--primitive-color-cool-neutral-700);
+  --semantic-color-fill-static-neutral-strong: var(--primitive-color-midnight-350);
+  --semantic-color-fill-static-neutral-subtle: var(--primitive-color-midnight-850);
   --semantic-color-fill-static-positive-strong: var(--primitive-color-green-250);
   --semantic-color-fill-static-positive-subtle: var(--primitive-color-green-350-16);
   --semantic-color-fill-static-severe-strong: var(--primitive-color-orange-200);

package/dist/brands/newco/themes/light.css

@@ -68,11 +68,11 @@
   --semantic-color-fill-static-info-subtle: var(--primitive-color-amethyst-50);
   --semantic-color-fill-static-negative-strong: var(--primitive-color-red-400);
   --semantic-color-fill-static-negative-subtle: var(--primitive-color-red-50);
-  --semantic-color-fill-static-neutral-base: var(--primitive-color-cool-neutral-25);
-  --semantic-color-fill-static-neutral-faint: var(--primitive-color-cool-neutral-5);
+  --semantic-color-fill-static-neutral-base: var(--primitive-color-warm-neutral-50);
+  --semantic-color-fill-static-neutral-faint: var(--primitive-color-warm-neutral-0);
   --semantic-color-fill-static-neutral-mono: var(--primitive-color-cool-neutral-0);
-  --semantic-color-fill-static-neutral-strong: var(--primitive-color-cool-neutral-150);
-  --semantic-color-fill-static-neutral-subtle: var(--primitive-color-cool-neutral-10);
+  --semantic-color-fill-static-neutral-strong: var(--primitive-color-warm-neutral-75);
+  --semantic-color-fill-static-neutral-subtle: var(--primitive-color-warm-neutral-25);
   --semantic-color-fill-static-positive-strong: var(--primitive-color-green-500);
   --semantic-color-fill-static-positive-subtle: var(--primitive-color-green-25);
   --semantic-color-fill-static-severe-strong: var(--primitive-color-orange-200);

package/dist/brands/newco/tokens.js

@@ -3834,7 +3834,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-200": {
-    "value": "#eab655",
+    "value": "#efb44d",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3844,7 +3844,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-250": {
-    "value": "#d6a549",
+    "value": "#dfa23e",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3854,7 +3854,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-300": {
-    "value": "#bf9342",
+    "value": "#cb8e31",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3864,7 +3864,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-350": {
-    "value": "#aa843e",
+    "value": "#b97e2b",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3874,7 +3874,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-400": {
-    "value": "#91723b",
+    "value": "#a26b26",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3884,7 +3884,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-500": {
-    "value": "#6d5936",
+    "value": "#7c5324",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3894,7 +3894,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-600": {
-    "value": "#4e422d",
+    "value": "#583e24",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3904,7 +3904,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-700": {
-    "value": "#342d21",
+    "value": "#3d2a19",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3914,7 +3914,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-800": {
-    "value": "#1d1912",
+    "value": "#23170b",
     "type": "color",
     "path": [
       "primitive-color",
@@ -3924,7 +3924,7 @@ const tokens = {
     ]
   },
   "primitive-color-saffron-900": {
-    "value": "#050301",
+    "value": "#0a0200",
     "type": "color",
     "path": [
       "primitive-color",
@@ -5508,7 +5508,7 @@ const tokens = {
     ]
   },
   "semantic-color-light-fill-static-neutral-base": {
-    "value": "#f6f6f6",
+    "value": "#f3f0ec",
     "type": "color",
     "path": [
       "semantic-color",
@@ -5520,7 +5520,7 @@ const tokens = {
     ]
   },
   "semantic-color-light-fill-static-neutral-faint": {
-    "value": "#fdfdfd",
+    "value": "#fefefd",
     "type": "color",
     "path": [
       "semantic-color",
@@ -5544,7 +5544,7 @@ const tokens = {
     ]
   },
   "semantic-color-light-fill-static-neutral-strong": {
-    "value": "#b5b5b5",
+    "value": "#e6e2dc",
     "type": "color",
     "path": [
       "semantic-color",
@@ -5556,7 +5556,7 @@ const tokens = {
     ]
   },
   "semantic-color-light-fill-static-neutral-subtle": {
-    "value": "#fafafa",
+    "value": "#f9f7f5",
     "type": "color",
     "path": [
       "semantic-color",
@@ -6388,7 +6388,7 @@ const tokens = {
     ]
   },
   "semantic-color-light-foreground-static-attention-on-subtle": {
-    "value": "#342d21",
+    "value": "#3d2a19",
     "type": "color",
     "path": [
       "semantic-color",
@@ -7068,7 +7068,7 @@ const tokens = {
     ]
   },
   "semantic-color-light-stroke-static-attention-strong": {
-    "value": "#aa843e",
+    "value": "#b97e2b",
     "type": "color",
     "path": [
       "semantic-color",
@@ -8092,7 +8092,7 @@ const tokens = {
     ]
   },
   "semantic-color-dark-fill-static-neutral-base": {
-    "value": "#313131",
+    "value": "#353a52",
     "type": "color",
     "path": [
       "semantic-color",
@@ -8104,7 +8104,7 @@ const tokens = {
     ]
   },
   "semantic-color-dark-fill-static-neutral-faint": {
-    "value": "#161616",
+    "value": "#181b2b",
     "type": "color",
     "path": [
       "semantic-color",
@@ -8128,7 +8128,7 @@ const tokens = {
     ]
   },
   "semantic-color-dark-fill-static-neutral-strong": {
-    "value": "#606060",
+    "value": "#868bad",
     "type": "color",
     "path": [
       "semantic-color",
@@ -8140,7 +8140,7 @@ const tokens = {
     ]
   },
   "semantic-color-dark-fill-static-neutral-subtle": {
-    "value": "#202020",
+    "value": "#262a3e",
     "type": "color",
     "path": [
       "semantic-color",
@@ -9664,7 +9664,7 @@ const tokens = {
     ]
   },
   "semantic-color-dark-stroke-static-attention-subtle": {
-    "value": "#bf9342",
+    "value": "#cb8e31",
     "type": "color",
     "path": [
       "semantic-color",

package/dist/contract.json

@@ -1,6 +1,6 @@
 {
-  "$comment": "The names a consumer may use. Generated from the emitted CSS by scripts/build-contract.js — do not hand-edit. Lint against `contract` if you want the boundary enforced; nothing here blocks a primitive.",
-  "version": "10.0.0",
+  "$comment": "The names a consumer may use. Generated from the emitted CSS by scripts/build-contract.js, do not hand-edit. Lint against `contract` if you want the boundary enforced; nothing here blocks a primitive.",
+  "version": "10.0.2",
   "generated": "2026-09-30",
   "counts": {
     "contract": 360,
@@ -73,6 +73,55 @@
       "role": "Breakpoint values."
     }
   },
+  "guidance": {
+    "why": "One token library skins several codebases, products and UI libraries, and there is no shared component library yet. The names must be legible enough to assist mapping without being so granular that the set bloats and adoption fails. Every other choice below follows from that constraint.",
+    "decide": {
+      "question": "Does this element's colour change because of something the user does to it?",
+      "yes": "Action. Take the whole state set: -rest, -hover, -pressed, plus -disabled.",
+      "no": "Static. Pick one emphasis rung and stop.",
+      "note": "Not how many values exist. Static has six rungs and is still single-valued per element: the rungs are a menu you choose from once, the states are a sequence one element walks through."
+    },
+    "axes": {
+      "tier": {
+        "fill": "a background",
+        "foreground": "text or an icon",
+        "stroke": "a border or outline"
+      },
+      "family": [
+        "neutral",
+        "brand",
+        "negative",
+        "positive",
+        "info",
+        "attention",
+        "severe",
+        "accent"
+      ],
+      "emphasisQuietestFirst": [
+        "faint",
+        "subtle",
+        "base",
+        "bold",
+        "strong"
+      ],
+      "stateOnlyOnAction": [
+        "rest",
+        "hover",
+        "pressed",
+        "disabled"
+      ]
+    },
+    "doesNotPromise": [
+      "`primary` means A primary action, not your primary button. This package ships no components.",
+      "A component-shaped name such as fill-action-field-* describes a surface, not a component contract.",
+      "Two names sharing a value today are not interchangeable and may diverge in the next release.",
+      "`-on-strong` and `-on-subtle` are contrast pairing constraints, not lightness variants. The prefix names what must be behind the foreground.",
+      "No foreground rung is lighter than #484848 because everything lighter fails WCAG AA on white. A missing grey is a refusal, not a gap."
+    ],
+    "modes": "One name resolves per brand theme (Amplify, NewCo) and per mode (Light, Dark). Never put a brand or a mode in a property name; --semantic-color-light-mode-* is retired and resolves to nothing.",
+    "primitives": "Published so that bindings resolve, not so that they get applied. Every primitive carries \"Do not apply directly\" in its own description.",
+    "ifAmbiguous": "If two names look equally right, that is a defect here rather than in your understanding. Report which two: a consumer's mapping is invisible from this side until someone says so."
+  },
   "contract": [
     "--breakpoints-desktop-1440px",
     "--breakpoints-desktop-1920px",

package/dist/primitives.css

@@ -369,16 +369,16 @@
   --primitive-color-saffron-75: #fee2b3;
   --primitive-color-saffron-100: #fed897;
   --primitive-color-saffron-150: #ffc864;
-  --primitive-color-saffron-200: #eab655;
-  --primitive-color-saffron-250: #d6a549;
-  --primitive-color-saffron-300: #bf9342;
-  --primitive-color-saffron-350: #aa843e;
-  --primitive-color-saffron-400: #91723b;
-  --primitive-color-saffron-500: #6d5936;
-  --primitive-color-saffron-600: #4e422d;
-  --primitive-color-saffron-700: #342d21;
-  --primitive-color-saffron-800: #1d1912;
-  --primitive-color-saffron-900: #050301;
+  --primitive-color-saffron-200: #efb44d;
+  --primitive-color-saffron-250: #dfa23e;
+  --primitive-color-saffron-300: #cb8e31;
+  --primitive-color-saffron-350: #b97e2b;
+  --primitive-color-saffron-400: #a26b26;
+  --primitive-color-saffron-500: #7c5324;
+  --primitive-color-saffron-600: #583e24;
+  --primitive-color-saffron-700: #3d2a19;
+  --primitive-color-saffron-800: #23170b;
+  --primitive-color-saffron-900: #0a0200;
   --primitive-color-saffron-150-16: rgba(255, 200, 100, 0.16);
   --primitive-color-saffron-150-24: rgba(255, 200, 100, 0.24);
   --primitive-color-saffron-150-36: rgba(255, 200, 100, 0.36);
@@ -453,10 +453,10 @@
   --primitive-color-warm-neutral-500-70: rgba(87, 83, 78, 0.7);
   --primitive-color-warm-neutral-500-8: rgba(87, 83, 78, 0.08);
   --primitive-type-family-brand: Red Hat Text;
-  --primitive-type-fontstyle-normal: Normal;
-  --primitive-type-fontstyle-italic: Italic;
-  --primitive-type-textdecoration-none: None;
-  --primitive-type-textdecoration-underline: Underline;
+  --primitive-type-fontstyle-normal: normal;
+  --primitive-type-fontstyle-italic: italic;
+  --primitive-type-textdecoration-none: none;
+  --primitive-type-textdecoration-underline: underline;
   --primitive-type-size-10: 10px;
   --primitive-type-size-11: 11px;
   --primitive-type-size-12: 12px;