@actioneer/ads 0.5.5 → 0.5.7

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@actioneer/ads",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "importPath": "@actioneer/ads",
   "styleImport": "@import \"@actioneer/ads/styles.css\";",
   "families": [
@@ -16,9 +16,9 @@
     "Chat"
   ],
   "counts": {
-    "total": 782,
-    "component": 352,
-    "type": 342,
+    "total": 792,
+    "component": 357,
+    "type": 347,
     "hook": 10,
     "util": 78
   },
@@ -148,7 +148,7 @@
         "text-brand",
         "border-brand"
       ],
-      "description": "Brand (Sage green) — used for solid fills / primary actions, not body text"
+      "description": "Compatibility action role — neutral ink, never a colored primary hue."
     },
     {
       "name": "--color-brand-foreground",
@@ -157,7 +157,7 @@
         "text-brand-foreground",
         "bg-brand-foreground"
       ],
-      "description": "Brand (Sage green) — used for solid fills / primary actions, not body text"
+      "description": "Compatibility action role — neutral ink, never a colored primary hue."
     },
     {
       "name": "--color-brand-hover",
@@ -167,7 +167,7 @@
         "text-brand-hover",
         "border-brand-hover"
       ],
-      "description": "Brand (Sage green) — used for solid fills / primary actions, not body text"
+      "description": "Compatibility action role — neutral ink, never a colored primary hue."
     },
     {
       "name": "--color-brand-text",
@@ -177,7 +177,7 @@
         "text-brand-text",
         "border-brand-text"
       ],
-      "description": "Brand (Sage green) — used for solid fills / primary actions, not body text"
+      "description": "Compatibility action role — neutral ink, never a colored primary hue."
     },
     {
       "name": "--color-fill",
@@ -2068,6 +2068,63 @@
         "kind"
       ]
     },
+    {
+      "name": "AnswerSourceChip",
+      "family": "Data display",
+      "kind": "component",
+      "importPath": "@actioneer/ads",
+      "module": "answer-sources",
+      "description": "Use the blue connector/source chip inside AnswerSources to open only the referenced nodes represented by that chip in the shell's inspector.",
+      "showcaseUrl": "https://ads.actioneer.dev/#/ai/sources",
+      "props": [
+        "icon",
+        "count",
+        "children"
+      ]
+    },
+    {
+      "name": "AnswerSourceInspector",
+      "family": "Data display",
+      "kind": "component",
+      "importPath": "@actioneer/ads",
+      "module": "answer-sources",
+      "description": "Render as a separate white shell-level panel beside the answer when a source chip is selected; close and unmount it when the selection clears.",
+      "showcaseUrl": "https://ads.actioneer.dev/#/ai/sources",
+      "props": [
+        "description",
+        "title",
+        "children"
+      ]
+    },
+    {
+      "name": "AnswerSourceItem",
+      "family": "Data display",
+      "kind": "component",
+      "importPath": "@actioneer/ads",
+      "module": "answer-sources",
+      "description": "Use as an outlined clickable row inside AnswerSourceInspector for one referenced table or node, including its parent source, read state, and optional status.",
+      "showcaseUrl": "https://ads.actioneer.dev/#/ai/sources",
+      "props": [
+        "name",
+        "source",
+        "description",
+        "status",
+        "icon"
+      ]
+    },
+    {
+      "name": "AnswerSources",
+      "family": "Data display",
+      "kind": "component",
+      "importPath": "@actioneer/ads",
+      "module": "answer-sources",
+      "description": "Place immediately above an answer's follow-up questions to summarize the referenced nodes and group them into clickable AnswerSourceChips.",
+      "showcaseUrl": "https://ads.actioneer.dev/#/ai/sources",
+      "props": [
+        "count",
+        "label"
+      ]
+    },
     {
       "name": "AreaChart",
       "family": "Data display",
@@ -3042,6 +3099,7 @@
         "actionColumnWidth",
         "sortDescriptor",
         "onSortChange",
+        "allowsSorting",
         "isStatic"
       ]
     },
@@ -3086,7 +3144,8 @@
       "showcaseUrl": "https://ads.actioneer.dev/#/table",
       "props": [
         "align",
-        "sticky"
+        "sticky",
+        "sortValue"
       ]
     },
     {
@@ -3099,7 +3158,9 @@
       "props": [
         "align",
         "sticky",
-        "sortKey"
+        "sortKey",
+        "allowsSorting",
+        "_sortColumnIndex"
       ]
     },
     {
@@ -3466,6 +3527,34 @@
       "importPath": "@actioneer/ads",
       "module": "answer"
     },
+    {
+      "name": "AnswerSourceChipProps",
+      "family": "Data display",
+      "kind": "type",
+      "importPath": "@actioneer/ads",
+      "module": "answer-sources"
+    },
+    {
+      "name": "AnswerSourceInspectorProps",
+      "family": "Data display",
+      "kind": "type",
+      "importPath": "@actioneer/ads",
+      "module": "answer-sources"
+    },
+    {
+      "name": "AnswerSourceItemProps",
+      "family": "Data display",
+      "kind": "type",
+      "importPath": "@actioneer/ads",
+      "module": "answer-sources"
+    },
+    {
+      "name": "AnswerSourcesProps",
+      "family": "Data display",
+      "kind": "type",
+      "importPath": "@actioneer/ads",
+      "module": "answer-sources"
+    },
     {
       "name": "AnswerSpec",
       "family": "Data display",
@@ -4766,6 +4855,7 @@
         "mask",
         "motion",
         "motionMode",
+        "interactionColor",
         "hero"
       ]
     },
@@ -5090,7 +5180,7 @@
       "kind": "component",
       "importPath": "@actioneer/ads",
       "module": "sidebar",
-      "description": "Use as the app's left navigation rail — compose it from SidebarHeader/SidebarBrand, SidebarNav (sections of SidebarItems), optional SidebarHistory, and a SidebarFooter with SidebarAccount, with an opt-in collapsed icon-rail mode (⌘B/Ctrl-B) that every sub-part reads automatically.",
+      "description": "Use as the app's left navigation rail. The canonical Actioneer shell composes SidebarBrand with persistent header actions, SidebarAction above grouped SidebarItems, optional attention counts and SidebarHistory, then SidebarAccount in a pinned footer. Its opt-in collapsed icon-rail mode (⌘B/Ctrl-B) is shared automatically by every sub-part.",
       "showcaseUrl": "https://ads.actioneer.dev/#/sidebar",
       "props": [
         "collapsed",
@@ -7649,6 +7739,17 @@
       "note": "Vendored assistant-ui component. Props follow upstream assistant-ui, not ADS conventions; the chat family needs an <AssistantRuntimeProvider> (chat runtime) and a <TooltipProvider> ancestor. Import from \"@actioneer/ads\" like any ADS export.",
       "showcaseUrl": "https://ads.actioneer.dev/#/demo/ask"
     },
+    {
+      "name": "FollowUpQuestion",
+      "family": "Chat",
+      "kind": "component",
+      "importPath": "@actioneer/ads",
+      "module": "follow-up-suggestions",
+      "vendored": true,
+      "note": "Vendored assistant-ui component. Props follow upstream assistant-ui, not ADS conventions; the chat family needs an <AssistantRuntimeProvider> (chat runtime) and a <TooltipProvider> ancestor. Import from \"@actioneer/ads\" like any ADS export.",
+      "description": "Use for the two or three full-width next-question rows that close a structured answer, immediately after its source strip; show the exact prompt that clicking will send.",
+      "showcaseUrl": "https://ads.actioneer.dev/#/ai/follow-up-suggestions"
+    },
     {
       "name": "FollowUpSuggestion",
       "family": "Chat",
@@ -7657,7 +7758,8 @@
       "module": "follow-up-suggestions",
       "vendored": true,
       "note": "Vendored assistant-ui component. Props follow upstream assistant-ui, not ADS conventions; the chat family needs an <AssistantRuntimeProvider> (chat runtime) and a <TooltipProvider> ancestor. Import from \"@actioneer/ads\" like any ADS export.",
-      "showcaseUrl": "https://ads.actioneer.dev/#/demo/ask"
+      "description": "Use only for compact runtime suggestion chips above the composer; use FollowUpQuestion for the larger answer-ending question rows.",
+      "showcaseUrl": "https://ads.actioneer.dev/#/ai/follow-up-suggestions"
     },
     {
       "name": "Image",
@@ -8184,6 +8286,15 @@
       "vendored": true,
       "note": "Vendored assistant-ui component. Props follow upstream assistant-ui, not ADS conventions; the chat family needs an <AssistantRuntimeProvider> (chat runtime) and a <TooltipProvider> ancestor. Import from \"@actioneer/ads\" like any ADS export."
     },
+    {
+      "name": "FollowUpQuestionProps",
+      "family": "Chat",
+      "kind": "type",
+      "importPath": "@actioneer/ads",
+      "module": "follow-up-suggestions",
+      "vendored": true,
+      "note": "Vendored assistant-ui component. Props follow upstream assistant-ui, not ADS conventions; the chat family needs an <AssistantRuntimeProvider> (chat runtime) and a <TooltipProvider> ancestor. Import from \"@actioneer/ads\" like any ADS export."
+    },
     {
       "name": "FollowUpSuggestionProps",
       "family": "Chat",
@@ -8682,7 +8793,7 @@
       "id": "minimal-information",
       "number": 8,
       "title": "Minimal information per screen",
-      "rule": "A screen carries ONLY what the user needs to move forward: one title, at most one short supporting line, the inputs, one primary action. Never maximalist. Promote the one message that matters typographically instead of appending muted fine print.",
+      "rule": "A screen carries ONLY what the user needs to move forward: one title, the inputs, one primary action. Page, section, panel, modal, dialog, drawer, and popover headers are title-only by default; add a description only when the user explicitly asks for one. Never maximalist.",
       "do": [
         "Prefer more, smaller steps over dense ones; ask one thing at a time.",
         "Derive instead of asking whenever possible (a name from a work email, the company from its domain).",
@@ -8690,6 +8801,7 @@
       ],
       "dont": [
         "Add section eyebrows above a title that already names the screen, or helper text that restates the obvious / duplicates a disabled button's meaning.",
+        "Add any header description unless the user explicitly requested supporting copy for that page, section, panel, modal, dialog, drawer, or popover.",
         "Nest panel/step-rail chrome inside a multi-step flow."
       ],
       "enforcedByLint": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actioneer/ads",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Actioneer Design System 1.0 — React 19 + Tailwind v4 component library.",
   "type": "module",
   "sideEffects": [

package/styles.css

@@ -31,7 +31,7 @@
 /*
  * ============================================================
  *  ADS 1.0 — Design Tokens
- *  Brand: Sage (green) · Neutrals: brand-palette grey · Typeface: Aribau Grotesk
+ *  Palette: Ink neutrals · Typeface: Aribau Grotesk
  * ============================================================
  */
 @theme {
@@ -89,29 +89,8 @@
   --color-ink-900: #636461; /* 11 · accessible text */
   --color-ink-950: #1f1f1c; /* 12 · accessible text */
 
-  /* ---- Brand ramp — the full 12-step Sage green (light section, solid row),
-     same Radix roles as the neutral ramp. All 12 present: sage-850 (#417c36,
-     step 11 = the accessible green text tone) and sage-950 (#273d23, step 12)
-     are restored. The interactive brand (--brand #3f7a34) is step 9 (solid);
-     its hover is step 10 (#316c26). NOTE: steps 9–12 are not a pure lightness
-     ramp (Radix convention) — the Tailwind name order differs from role
-     order, so read the role comment, not the number. ---- */
-  --color-sage-50: #fbfefb;  /*  1 · background      */
-  --color-sage-100: #f6fbf5; /*  2 · background      */
-  --color-sage-200: #e9f7e6; /*  3 · interactive     */
-  --color-sage-300: #dbf1d6; /*  4 · interactive     */
-  --color-sage-400: #cae8c5; /*  5 · interactive     */
-  --color-sage-500: #b6dcaf; /*  6 · border          */
-  --color-sage-600: #9ccc93; /*  7 · border          */
-  --color-sage-700: #77b76b; /*  8 · border          */
-  --color-sage-800: #3f7a34; /*  9 · solid (brand)   */
-  --color-sage-900: #316c26; /* 10 · solid (hover)   */
-  --color-sage-850: #417c36; /* 11 · accessible text */
-  --color-sage-950: #273d23; /* 12 · accessible text */
-
   /* ---- Semantic accent ramps ---- */
-  /* Success — shifted cooler (emerald/teal) so positive states stay clearly
-     distinct from the warm Sage brand green. */
+  /* Success stays a semantic state color, never a product-primary hue. */
   --color-success-50: #ecfdf5;
   --color-success-100: #d1fae5;
   --color-success-500: #10b981;
@@ -138,7 +117,7 @@
 
   /* ---- Data-viz accents ---- three small ramps for charts & illustration.
      deep = text/lines · base = fills · soft = backgrounds. Separate from the
-     semantic status ramps above; these are the "focal data" companions to Sage. */
+     semantic status ramps above; these carry data, not product identity. */
   --color-cyan-soft: #c7efe9;  /* Cyan — vivid cool contrast; 2nd series, links */
   --color-cyan-base: #12b5a5;
   --color-cyan-deep: #0a7e82;
@@ -149,15 +128,15 @@
   --color-amber-base: #f3a72e;
   --color-amber-deep: #b57414;
 
-  /* ---- Radii ---- FIVE steps only: 2 · 4 · 8 · 16 · 24 (px), plus `full`
-     for pills/circles. xs aliases sm (4px); 2xl aliases xl (24px). */
-  --radius-xs: 0.25rem;  /* 4px */
-  --radius-sm: 0.25rem;  /* 4px */
-  --radius-md: 0.5rem;   /* 8px */
-  --radius-lg: 1rem;     /* 16px */
-  --radius-xl: 1.5rem;   /* 24px */
-  --radius-2xl: 1.5rem;  /* 24px (alias xl) */
-  --radius-full: 9999px;
+  /* ---- Radii ---- TWO values only: 2px and 4px. Compact roles resolve to
+     2px; every surface and formerly pill-shaped role resolves to 4px. */
+  --radius-xs: 0.125rem;  /* 2px */
+  --radius-sm: 0.125rem;  /* 2px */
+  --radius-md: 0.25rem;   /* 4px */
+  --radius-lg: 0.25rem;   /* 4px */
+  --radius-xl: 0.25rem;   /* 4px */
+  --radius-2xl: 0.25rem;  /* 4px */
+  --radius-full: 0.25rem; /* 4px */
   /* Status/indicator dots are SQUARE with a hair of softening — echoing the
      growth-mark's square cells. Never render an indicator dot as a circle
      (`rounded-full`); radio controls are the one exception (control
@@ -302,7 +281,7 @@
   --color-card: var(--card);
   --color-card-foreground: var(--card-foreground);
 
-  /* Brand (Sage green) — used for solid fills / primary actions, not body text */
+  /* Compatibility action role — neutral ink, never a colored primary hue. */
   --color-brand: var(--brand);
   --color-brand-foreground: var(--brand-foreground);
   --color-brand-hover: var(--brand-hover);
@@ -361,10 +340,9 @@
 
 /* ---- Theme (light only) ---- */
 :root {
-  /* Every semantic token below points INTO a primitive scale step
-     (var(--color-ink-*) / var(--color-sage-*)) — the 12-step scales are the
-     single source of truth. Only pure white (#ffffff) stays literal: it is a
-     base surface, not a neutral scale step. */
+  /* Every neutral semantic token below points INTO the ink primitive scale.
+     Only pure white (#ffffff) stays literal: it is a base surface, not a
+     neutral scale step. */
   --background: var(--color-ink-100);      /* step 2  · canvas */
   --foreground: var(--color-ink-950);      /* step 12 */
 
@@ -384,11 +362,12 @@
   --card: #ffffff;                         /* pure white base */
   --card-foreground: var(--color-ink-950);
 
-  /* Sage brand (green) — solid role. brand = sage step 9, hover = step 10. */
-  --brand: var(--color-sage-800);          /* step 9  · solid */
+  /* Neutral action role. The `brand` name remains as a compatibility API,
+     but the product has no colored primary palette. */
+  --brand: var(--color-ink-950);           /* darkest action ink */
   --brand-foreground: #ffffff;
-  --brand-hover: var(--color-sage-900);    /* step 10 · hover */
-  --brand-text: var(--color-sage-850);     /* step 11 · accessible green text/links */
+  --brand-hover: var(--color-ink-900);     /* lighter hover lift */
+  --brand-text: var(--color-ink-950);      /* action text / links */
 
   /* Table interaction fills are pre-composited and opaque. Sticky edge cells
      therefore cover horizontally scrolled content while preserving the
@@ -413,7 +392,7 @@
   --input: var(--border-primary);           /* form-control edge */
 
   /* Ripple — the appearance wash that radiates from a floating surface's
-     origin corner as it opens (Dropdown/Popover/Select/Modal…). A soft brand
+     origin corner as it opens (Dropdown/Popover/Select/Modal…). A soft ink
      tint that expands + fades once on mount; see the `.ads-ripple` layer and
      the `Ripple` component. Duration stays in the sub-300ms UI band. */
   --ripple-tint: color-mix(in srgb, var(--brand) 20%, transparent);
@@ -424,7 +403,7 @@
      bottom of this file, so every `border`/`border-t|r|b|l|x|y` reads as a
      true hairline. Explicit `border-2`+ widths are unaffected. */
   --stroke-width: 0.5px;
-  --ring: color-mix(in srgb, var(--color-sage-800) 50%, transparent);   /* brand @ 50% */
+  --ring: color-mix(in srgb, var(--color-ink-950) 50%, transparent);    /* ink @ 50% */
   --overlay: color-mix(in srgb, var(--color-ink-950) 50%, transparent); /* ink-950 @ 50% */
 
   /* Functional / domain tokens — named for their RENDER role, pointing into
@@ -445,7 +424,7 @@
   /* shadcn-compat raw surfaces — so a downstream shadcn Sidebar / Popover
      (or an inline `var(--sidebar)` / `var(--popover)`) resolves to the ADS
      palette instead of shadcn's grey/black defaults. The sidebar reads as the
-     neutral canvas; its active item takes Sage. A consumer that had
+     neutral canvas; its active item takes action ink. A consumer that had
      hard-coded these can now delete its overrides and inherit from here. */
   --sidebar: var(--surface);
   --sidebar-foreground: var(--foreground);
@@ -530,6 +509,22 @@
   display: none;
 }
 
+/* Artifact widgets are positioned by GridStack; ADS cards own the visible
+   surface while the library content wrapper only clips during interaction.
+   The subtle elevation lives on the wrapper (not the inner card) because the
+   wrapper's own `overflow: hidden` would clip a shadow drawn on its child. */
+.artifact-grid-stack > .grid-stack-item > .grid-stack-item-content {
+  overflow: hidden;
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-elevation);
+}
+
+.artifact-grid-stack > .grid-stack-placeholder > .placeholder-content {
+  border: 1px dashed var(--color-border-strong);
+  border-radius: var(--radius-sm);
+  background: var(--color-muted);
+}
+
 /* BrandTexture entrance (src/components/brand-texture.tsx): a radial bloom —
    the halftone reveals from the centre out to the corners (clip-path circle)
    while gently scaling up to rest. `from{}`-only keyframe, so it settles into
@@ -718,7 +713,7 @@
   }
   ::-webkit-scrollbar-thumb {
     background: var(--border-strong);
-    border-radius: 9999px;
+    border-radius: var(--radius-lg);
     border: 2px solid var(--background);
   }
   ::-webkit-scrollbar-thumb:hover {
@@ -1009,7 +1004,7 @@
   width: 1rem;
   border-bottom: 1px solid var(--border-strong);
   border-left: 1px solid var(--border-strong);
-  border-bottom-left-radius: 9px;
+  border-bottom-left-radius: var(--radius-lg);
 }
 /* Let the consumer's Tailwind discover the classes ADS components use. */
 @source "./**/*.{js,mjs}";

package/theme.css

@@ -2,7 +2,7 @@
 /*
  * ============================================================
  *  ADS 1.0 — Design Tokens
- *  Brand: Sage (green) · Neutrals: brand-palette grey · Typeface: Aribau Grotesk
+ *  Palette: Ink neutrals · Typeface: Aribau Grotesk
  * ============================================================
  */
 @theme {
@@ -60,29 +60,8 @@
   --color-ink-900: #636461; /* 11 · accessible text */
   --color-ink-950: #1f1f1c; /* 12 · accessible text */
 
-  /* ---- Brand ramp — the full 12-step Sage green (light section, solid row),
-     same Radix roles as the neutral ramp. All 12 present: sage-850 (#417c36,
-     step 11 = the accessible green text tone) and sage-950 (#273d23, step 12)
-     are restored. The interactive brand (--brand #3f7a34) is step 9 (solid);
-     its hover is step 10 (#316c26). NOTE: steps 9–12 are not a pure lightness
-     ramp (Radix convention) — the Tailwind name order differs from role
-     order, so read the role comment, not the number. ---- */
-  --color-sage-50: #fbfefb;  /*  1 · background      */
-  --color-sage-100: #f6fbf5; /*  2 · background      */
-  --color-sage-200: #e9f7e6; /*  3 · interactive     */
-  --color-sage-300: #dbf1d6; /*  4 · interactive     */
-  --color-sage-400: #cae8c5; /*  5 · interactive     */
-  --color-sage-500: #b6dcaf; /*  6 · border          */
-  --color-sage-600: #9ccc93; /*  7 · border          */
-  --color-sage-700: #77b76b; /*  8 · border          */
-  --color-sage-800: #3f7a34; /*  9 · solid (brand)   */
-  --color-sage-900: #316c26; /* 10 · solid (hover)   */
-  --color-sage-850: #417c36; /* 11 · accessible text */
-  --color-sage-950: #273d23; /* 12 · accessible text */
-
   /* ---- Semantic accent ramps ---- */
-  /* Success — shifted cooler (emerald/teal) so positive states stay clearly
-     distinct from the warm Sage brand green. */
+  /* Success stays a semantic state color, never a product-primary hue. */
   --color-success-50: #ecfdf5;
   --color-success-100: #d1fae5;
   --color-success-500: #10b981;
@@ -109,7 +88,7 @@
 
   /* ---- Data-viz accents ---- three small ramps for charts & illustration.
      deep = text/lines · base = fills · soft = backgrounds. Separate from the
-     semantic status ramps above; these are the "focal data" companions to Sage. */
+     semantic status ramps above; these carry data, not product identity. */
   --color-cyan-soft: #c7efe9;  /* Cyan — vivid cool contrast; 2nd series, links */
   --color-cyan-base: #12b5a5;
   --color-cyan-deep: #0a7e82;
@@ -120,15 +99,15 @@
   --color-amber-base: #f3a72e;
   --color-amber-deep: #b57414;
 
-  /* ---- Radii ---- FIVE steps only: 2 · 4 · 8 · 16 · 24 (px), plus `full`
-     for pills/circles. xs aliases sm (4px); 2xl aliases xl (24px). */
-  --radius-xs: 0.25rem;  /* 4px */
-  --radius-sm: 0.25rem;  /* 4px */
-  --radius-md: 0.5rem;   /* 8px */
-  --radius-lg: 1rem;     /* 16px */
-  --radius-xl: 1.5rem;   /* 24px */
-  --radius-2xl: 1.5rem;  /* 24px (alias xl) */
-  --radius-full: 9999px;
+  /* ---- Radii ---- TWO values only: 2px and 4px. Compact roles resolve to
+     2px; every surface and formerly pill-shaped role resolves to 4px. */
+  --radius-xs: 0.125rem;  /* 2px */
+  --radius-sm: 0.125rem;  /* 2px */
+  --radius-md: 0.25rem;   /* 4px */
+  --radius-lg: 0.25rem;   /* 4px */
+  --radius-xl: 0.25rem;   /* 4px */
+  --radius-2xl: 0.25rem;  /* 4px */
+  --radius-full: 0.25rem; /* 4px */
   /* Status/indicator dots are SQUARE with a hair of softening — echoing the
      growth-mark's square cells. Never render an indicator dot as a circle
      (`rounded-full`); radio controls are the one exception (control
@@ -273,7 +252,7 @@
   --color-card: var(--card);
   --color-card-foreground: var(--card-foreground);
 
-  /* Brand (Sage green) — used for solid fills / primary actions, not body text */
+  /* Compatibility action role — neutral ink, never a colored primary hue. */
   --color-brand: var(--brand);
   --color-brand-foreground: var(--brand-foreground);
   --color-brand-hover: var(--brand-hover);
@@ -332,10 +311,9 @@
 
 /* ---- Theme (light only) ---- */
 :root {
-  /* Every semantic token below points INTO a primitive scale step
-     (var(--color-ink-*) / var(--color-sage-*)) — the 12-step scales are the
-     single source of truth. Only pure white (#ffffff) stays literal: it is a
-     base surface, not a neutral scale step. */
+  /* Every neutral semantic token below points INTO the ink primitive scale.
+     Only pure white (#ffffff) stays literal: it is a base surface, not a
+     neutral scale step. */
   --background: var(--color-ink-100);      /* step 2  · canvas */
   --foreground: var(--color-ink-950);      /* step 12 */
 
@@ -355,11 +333,12 @@
   --card: #ffffff;                         /* pure white base */
   --card-foreground: var(--color-ink-950);
 
-  /* Sage brand (green) — solid role. brand = sage step 9, hover = step 10. */
-  --brand: var(--color-sage-800);          /* step 9  · solid */
+  /* Neutral action role. The `brand` name remains as a compatibility API,
+     but the product has no colored primary palette. */
+  --brand: var(--color-ink-950);           /* darkest action ink */
   --brand-foreground: #ffffff;
-  --brand-hover: var(--color-sage-900);    /* step 10 · hover */
-  --brand-text: var(--color-sage-850);     /* step 11 · accessible green text/links */
+  --brand-hover: var(--color-ink-900);     /* lighter hover lift */
+  --brand-text: var(--color-ink-950);      /* action text / links */
 
   /* Table interaction fills are pre-composited and opaque. Sticky edge cells
      therefore cover horizontally scrolled content while preserving the
@@ -384,7 +363,7 @@
   --input: var(--border-primary);           /* form-control edge */
 
   /* Ripple — the appearance wash that radiates from a floating surface's
-     origin corner as it opens (Dropdown/Popover/Select/Modal…). A soft brand
+     origin corner as it opens (Dropdown/Popover/Select/Modal…). A soft ink
      tint that expands + fades once on mount; see the `.ads-ripple` layer and
      the `Ripple` component. Duration stays in the sub-300ms UI band. */
   --ripple-tint: color-mix(in srgb, var(--brand) 20%, transparent);
@@ -395,7 +374,7 @@
      bottom of this file, so every `border`/`border-t|r|b|l|x|y` reads as a
      true hairline. Explicit `border-2`+ widths are unaffected. */
   --stroke-width: 0.5px;
-  --ring: color-mix(in srgb, var(--color-sage-800) 50%, transparent);   /* brand @ 50% */
+  --ring: color-mix(in srgb, var(--color-ink-950) 50%, transparent);    /* ink @ 50% */
   --overlay: color-mix(in srgb, var(--color-ink-950) 50%, transparent); /* ink-950 @ 50% */
 
   /* Functional / domain tokens — named for their RENDER role, pointing into
@@ -416,7 +395,7 @@
   /* shadcn-compat raw surfaces — so a downstream shadcn Sidebar / Popover
      (or an inline `var(--sidebar)` / `var(--popover)`) resolves to the ADS
      palette instead of shadcn's grey/black defaults. The sidebar reads as the
-     neutral canvas; its active item takes Sage. A consumer that had
+     neutral canvas; its active item takes action ink. A consumer that had
      hard-coded these can now delete its overrides and inherit from here. */
   --sidebar: var(--surface);
   --sidebar-foreground: var(--foreground);