@ds-mo/ui 11.0.0 → 12.0.0

package/dist/agent.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "11.0.0",
+  "packageVersion": "12.0.0",
   "kind": "components",
   "entries": [
     {
@@ -335,127 +335,6 @@
         "text"
       ]
     },
-    {
-      "id": "component:ds-app-shell",
-      "tag": "ds-app-shell",
-      "name": "app-shell",
-      "title": "AppShell",
-      "summary": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
-      "intentStatus": "complete",
-      "intent": {
-        "audience": "specialized",
-        "status": "stable",
-        "summary": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
-        "useWhen": [
-          "Building any standard authenticated product or workspace page with CompoMo.",
-          "PanelNav, BarNav, PanelTools, page content, shared chrome, responsive behavior, and shell shortcuts must be composed as one application frame.",
-          "Future application templates need the supported base-page composition boundary."
-        ],
-        "avoidWhen": [
-          "Building authentication, onboarding, public, marketing, print, error, or intentionally focused full-screen experiences that require a different layout.",
-          "Another AppShell already exists in the page; applications must render exactly one and must never nest AppShells.",
-          "Building content inside an existing AppShell; render the page content rather than another shell."
-        ],
-        "commonlyComposedWith": [
-          "component:ds-panel-nav",
-          "component:ds-bar-nav",
-          "component:ds-panel-tools",
-          "component:ds-swatch-picker"
-        ],
-        "patterns": [
-          "pattern:application-shell"
-        ],
-        "accessibility": [
-          "Keep primary destinations in PanelNav and secondary route sections in BarNav.",
-          "Ensure the default content region contains the page's single main landmark.",
-          "Keep PanelNav, BarNav, and PanelTools chrome available in the shell's supported desktop and tablet compositions.",
-          "Do not override browser keyboard chords when enabling shell shortcuts.",
-          "Require Search and Help as the minimum PanelTools actions and provide accessible labels for every tool.",
-          "Preserve focus and accessible names across navigation, collapse, overflow, and responsive presentation changes."
-        ],
-        "states": [
-          "Render exactly one AppShell as the workspace root and never nest it.",
-          "PanelNav, BarNav, and PanelTools are required shell regions; PanelTools contains at least Search and Help even when no additional product tools apply.",
-          "The application router owns the current route, authorization filtering, Dashboard or Settings context, destination collections, section collections, and localized content labels.",
-          "AppShell propagates navStyle and coordinates layout, gradient alignment, transitions, metrics, shortcuts, and responsive composition.",
-          "Set gradientPreset to the single resolved global chrome preference: neutral by default, none for solid chrome, or cool, neutral, warm, and fresh for token-based washes.",
-          "The application owns gradient preference persistence, cross-tab synchronization, and server or account precedence; AppShell owns rendering the resolved preset across authenticated routes.",
-          "Dashboard represents day-to-day operational work while Settings represents administrative and configuration work; route state selects the context.",
-          "Update PanelNav groups, BarNav tabs and heading, navStyle, basePath, and currentUrl atomically from one resolved route state.",
-          "BarNav remains present: it shows route-section tabs when available and the active PanelNav destination label as heading otherwise.",
-          "The application filters unauthorized destinations, sections, and tools before passing them into shell components."
-        ],
-        "responsiveBehavior": [
-          "AppShell owns the fixed system breakpoints and resolves desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
-          "On desktop, PanelNav defaults expanded, permits user collapse or expansion, and respects the locally persisted desktop preference.",
-          "On tablet, AppShell keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
-          "On mobile, AppShell remains the page root but replaces PanelNav and desktop navigation composition with a future dedicated mobile navigation design.",
-          "Keep PanelNav width, BarNav height, PanelTools chrome, and main-content origin stable except during intentional responsive or collapse transitions.",
-          "The current runtime does not yet implement the complete desktop, tablet, and mobile composition contract; consuming applications must enforce missing breakpoint behavior until AppShell provides it."
-        ],
-        "frameworkCaveats": {
-          "customElements": [
-            "Assign complex navigation and tool collections as JavaScript properties on the slotted components.",
-            "Stamp route-derived nav-style before components connect when deterministic first paint is required."
-          ],
-          "react": [
-            "Use generated wrappers and preserve native slot names for PanelNav, BarNav, PanelTools, and main content.",
-            "Resolve all shell inputs from one router state before rendering the composition."
-          ],
-          "angular": [
-            "Use generated standalone adapters and preserve slot attributes in templates.",
-            "Bind complex inputs as properties and update navigation inputs atomically from one resolved router state.",
-            "Bind both nav-style attributes and properties when deterministic first paint is required."
-          ]
-        },
-        "references": [
-          {
-            "label": "Component guide",
-            "path": "src/wc/components/AppShell/AppShell.mdx"
-          },
-          {
-            "label": "Executable Storybook composition",
-            "path": "src/wc/components/AppShell/AppShell.stories.ts"
-          },
-          {
-            "label": "Framework integration",
-            "path": "docs/framework-integration.md"
-          },
-          {
-            "label": "Application shell contract",
-            "path": "agent/patterns/application-shell/pattern.agent.json"
-          }
-        ]
-      },
-      "api": {
-        "props": {
-          "gradientPreset": {
-            "type": "ShellGradientPreset",
-            "required": false
-          },
-          "navStyle": {
-            "type": "NavChromeStyle",
-            "required": false
-          },
-          "shortcutsEnabled": {
-            "type": "boolean",
-            "required": false
-          }
-        },
-        "events": [],
-        "slots": []
-      },
-      "exports": {
-        "customElement": "ds-app-shell",
-        "react": "DsAppShell",
-        "angular": "DsAppShell"
-      },
-      "dependencies": [
-        "@ds-mo/ui",
-        "@ds-mo/tokens"
-      ],
-      "componentDependencies": []
-    },
     {
       "id": "component:ds-attachment-list",
       "tag": "ds-attachment-list",
@@ -649,7 +528,7 @@
           "Badge keeps one brand treatment; semantic severity belongs to another component or adjacent content.",
           "Use the ring only when Badge overlaps an icon or other content. Disable it in a reserved safe-area slot.",
           "When enabled, the ring matches the immediate backing surface for both variants. Use a direct ring override only for a component-local fill that no surface preset represents.",
-          "Enabled shell gradient rings align automatically inside active AppShell gradient chrome and may be explicitly enabled or disabled when composition requires it."
+          "Enabled shell gradient rings align automatically inside active ShellApp gradient chrome and may be explicitly enabled or disabled when composition requires it."
         ],
         "responsiveBehavior": [
           "The owning control or layout positions Badge and decides whether notification indicators remain visible, condense, or move at responsive breakpoints.",
@@ -729,14 +608,14 @@
       "tag": "ds-bar-nav",
       "name": "bar-nav",
       "title": "BarNav",
-      "summary": "Required secondary route navigation within AppShell, showing peer sections of the active PanelNav destination or its destination label when no section tabs apply.",
+      "summary": "Required secondary route navigation within ShellApp, showing peer sections of the active PanelNav destination or its destination label when no section tabs apply.",
       "intentStatus": "complete",
       "intent": {
         "audience": "specialized",
         "status": "stable",
-        "summary": "Required secondary route navigation within AppShell, showing peer sections of the active PanelNav destination or its destination label when no section tabs apply.",
+        "summary": "Required secondary route navigation within ShellApp, showing peer sections of the active PanelNav destination or its destination label when no section tabs apply.",
         "useWhen": [
-          "Rendering the required secondary navigation region inside AppShell.",
+          "Rendering the required secondary navigation region inside ShellApp.",
           "The active primary destination has peer route sections that users can navigate between.",
           "The active primary destination has no route sections or is showing a detail route and its destination label must preserve the BarNav region."
         ],
@@ -745,7 +624,7 @@
           "A third navigation level is needed; BarNav is never tertiary navigation.",
           "The choices switch local content without navigating routes; use TabGroup instead.",
           "Document-style tabs need reordering, pinning, closing, or user customization.",
-          "BarNav would be mounted outside the application's single AppShell."
+          "BarNav would be mounted outside the application's single ShellApp."
         ],
         "alternatives": [
           {
@@ -765,7 +644,7 @@
           }
         ],
         "commonlyComposedWith": [
-          "component:ds-app-shell",
+          "component:ds-shell-app",
           "component:ds-panel-nav",
           "component:ds-panel-tools"
         ],
@@ -794,7 +673,7 @@
           "Keep the BarNav region present so shell height and main-content origin remain stable across routes.",
           "Allow the built-in overflow behavior to move trailing sections into Menu when the available width is insufficient.",
           "The active section does not need to remain visible in the tab row when it moves into overflow because page content supplies the page title.",
-          "Do not infer mobile navigation behavior from desktop BarNav; future AppShell mobile composition may use a different navigation design."
+          "Do not infer mobile navigation behavior from desktop BarNav; future ShellApp mobile composition may use a different navigation design."
         ],
         "frameworkCaveats": {
           "customElements": [
@@ -883,6 +762,187 @@
         "text"
       ]
     },
+    {
+      "id": "component:ds-bar-title",
+      "tag": "ds-bar-title",
+      "name": "bar-title",
+      "title": "BarTitle",
+      "summary": "Page-level title chrome with optional Back navigation, supporting description, inline active-section menu, one primary action, grouped overflow actions, and explicit expanded, compact, or constrained variants.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Page-level title chrome with optional Back navigation, supporting description, inline active-section menu, one primary action, grouped overflow actions, and explicit expanded, compact, or constrained variants.",
+        "useWhen": [
+          "A top-level page needs one h1 above its content.",
+          "A list or detail page has multiple route-level sections that belong in the inline active-section menu.",
+          "A detail, create, or edit page needs a page-level Back action.",
+          "A page needs one primary action plus optional secondary or destructive overflow commands."
+        ],
+        "avoidWhen": [
+          "The title belongs to a PanelTools drawer or fullscreen pane; use PanelToolHeader through PanelTools instead.",
+          "The choices are primary application destinations or BarNav destinations rather than sections within the current page.",
+          "The heading belongs to a card, modal, or other bounded region rather than the page.",
+          "Local panels inside page content should remain directly selectable; use TabGroup instead.",
+          "Automatic sticky or responsive page orchestration is required; compose BarTitle in ShellPage rather than implementing it in the header."
+        ],
+        "alternatives": [
+          {
+            "when": "The header belongs to a PanelTools product view.",
+            "component": "component:ds-panel-tool-header",
+            "reason": "PanelToolHeader owns pane-level Back and actions without creating page chrome."
+          },
+          {
+            "when": "A small set of inner-page panels should remain visible as tabs.",
+            "component": "component:ds-tab-group",
+            "reason": "TabGroup is the local content-view control rather than route-level page title chrome."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-shell-page",
+          "component:ds-button-filled",
+          "component:ds-button-unfilled",
+          "component:ds-menu",
+          "component:ds-text"
+        ],
+        "patterns": [
+          "pattern:shell-page"
+        ],
+        "accessibility": [
+          "Provide one concise heading; BarTitle renders exactly one h1 and changes only its visual recipe between variants.",
+          "Give Back a destination-specific accessible name such as Back to Drivers, provide the concise parent label such as Drivers for the expanded breadcrumb, and handle dsBack in the route owner.",
+          "Keep value synchronized with the current child route; dsSectionChange returns the selected section id.",
+          "Section and overflow triggers expose menu relationships and restore focus after selection or dismissal.",
+          "Use one filled primary action in the page decision area and mark destructive overflow actions explicitly."
+        ],
+        "states": [
+          "Omitting Back, sections, primaryAction, and actions produces the top-level title-only header.",
+          "Two or more selectable sections add the inline section trigger; one section does not render a redundant menu.",
+          "Dividers in sections or actions create separate Menu groups without becoming selectable rows.",
+          "expanded renders the larger heading, optional description, inset divider, and an xs icon-label Back breadcrumb above a flush-left h1; compact renders 48px chrome with inline Back; constrained uses compact chrome and moves an auto-collapse primary action into overflow.",
+          "primaryAction collapse defaults to auto. Use never for Save-like actions whose hierarchy must remain visible in constrained layouts."
+        ],
+        "responsiveBehavior": [
+          "BarTitle does not observe viewport, shell, scroll, or container state. Its owner selects an explicit variant.",
+          "ShellPage is the standard owner for automatic expanded, compact, and constrained selection.",
+          "Compact titles use the shared md control inset so top-level headings align with BarNav and inline Back geometry aligns with PanelToolHeader. Long headings and section labels truncate independently while Back and action controls retain complete hit targets and accessible names.",
+          "A never-collapse primary action remains visible in constrained mode; the title and section label yield space first."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign sections, primaryAction, and actions as JavaScript properties and replace array or object identities when controlled state changes.",
+            "Handle dsBack in the router owner, update value after dsSectionChange, and execute product commands from dsAction."
+          ],
+          "react": [
+            "Pass arrays and objects directly to DsBarTitle and keep value controlled from route state.",
+            "Place DsBarTitle in DsShellPage with slot=header when automatic page behavior is required."
+          ],
+          "angular": [
+            "Bind complex values on the standalone DsBarTitle adapter and handle the three intent events in the route shell.",
+            "Place ds-bar-title in ds-shell-page with slot=header; do not render router-outlet inside BarTitle."
+          ]
+        },
+        "references": [
+          {
+            "label": "Explicit variant examples",
+            "path": "src/wc/components/BarTitle/BarTitle.stories.ts"
+          },
+          {
+            "label": "ShellPage composition and responsive examples",
+            "path": "src/wc/components/ShellPage/ShellPage.stories.ts"
+          },
+          {
+            "label": "Cross-browser shell-page and header coverage",
+            "path": "tests/e2e/bar-title.spec.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "actions": {
+            "type": "BarTitleActionItem[]",
+            "required": false
+          },
+          "actionsAriaLabel": {
+            "type": "string",
+            "required": false
+          },
+          "backAriaLabel": {
+            "type": "string",
+            "required": false
+          },
+          "backLabel": {
+            "type": "string",
+            "required": false
+          },
+          "description": {
+            "type": "string",
+            "required": false
+          },
+          "heading": {
+            "type": "string",
+            "required": true
+          },
+          "primaryAction": {
+            "type": "BarTitlePrimaryAction | null",
+            "required": false
+          },
+          "sections": {
+            "type": "BarTitleSectionItem[]",
+            "required": false
+          },
+          "sectionsAriaLabel": {
+            "type": "string",
+            "required": false
+          },
+          "showBack": {
+            "type": "boolean",
+            "required": false
+          },
+          "value": {
+            "type": "string",
+            "required": false
+          },
+          "variant": {
+            "type": "BarTitleVariant",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsAction",
+            "detail": "string"
+          },
+          {
+            "name": "dsBack",
+            "detail": "MouseEvent"
+          },
+          {
+            "name": "dsSectionChange",
+            "detail": "string"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-bar-title",
+        "react": "DsBarTitle",
+        "angular": "DsBarTitle"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "button-filled",
+        "button-unfilled",
+        "icon",
+        "menu",
+        "text",
+        "tooltip"
+      ]
+    },
     {
       "id": "component:ds-button-filled",
       "tag": "ds-button-filled",
@@ -933,6 +993,8 @@
           "Use only one filled action per local decision area; render all secondary actions with ButtonUnfilled.",
           "Choose brand or neutral for general commands. Reserve positive, negative, warning, and caution for matching action consequences, and AI, guide, or walkthrough for actions that enter those feature experiences.",
           "Contrast serves both surface adaptation and hierarchy, but never permits a second filled action in the same decision area.",
+          "The optional inset border is off by default. Enable it only when the filled action needs an explicit edge against its parent surface.",
+          "Parent surface context changes only the optional inset border color. Contrast continues to own the button fill, foreground, hover, pressed, and focus treatments; never use surface context to change action hierarchy.",
           "Rounded changes only the control radius to the half-radius treatment; it does not change hierarchy, size, variant, intent, or interaction semantics.",
           "Loading prevents duplicate activation without applying inactive opacity or removing the current keyboard focus.",
           "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width."
@@ -964,10 +1026,18 @@
             "type": "string | null",
             "required": false
           },
+          "background": {
+            "type": "ButtonFilledBackground | undefined",
+            "required": false
+          },
           "contrast": {
             "type": "ButtonFilledContrast",
             "required": false
           },
+          "hasBorder": {
+            "type": "boolean",
+            "required": false
+          },
           "icon": {
             "type": "string",
             "required": false
@@ -1237,9 +1307,78 @@
       "tag": "ds-card-data-viz-donut",
       "name": "card-data-viz-donut",
       "title": "CardDataVizDonut",
-      "summary": "Donut data-viz card on dedicated ds-card-shell-data-viz chrome — fill chart region, content-sized legend, header filter action, and chart↔legend hover sync.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Canonical donut-plus-legend dashboard card with shared data-viz chrome, a filter action, fill chart region, content-sized legend, and built-in hover synchronization.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Canonical donut-plus-legend dashboard card with shared data-viz chrome, a filter action, fill chart region, content-sized legend, and built-in hover synchronization.",
+        "useWhen": [
+          "A dashboard widget needs the standard donut and visible legend composition in one data-viz card.",
+          "Chart slices and legend rows should cross-highlight without application hover wiring.",
+          "The card needs the shared header filter action while the application owns filter state and menu content."
+        ],
+        "avoidWhen": [
+          "The visualization is a bar, line, metric, or custom chart; compose CardShellDataViz directly.",
+          "The product needs a custom legend treatment such as chips, external stat callouts, or selectable filters.",
+          "The surface is a settings section or generic content card."
+        ],
+        "alternatives": [
+          {
+            "when": "The visualization needs shared data-viz chrome without the canonical donut layout.",
+            "component": "component:ds-card-shell-data-viz",
+            "reason": "CardShellDataViz owns only the header, actions, width, and body boundary."
+          },
+          {
+            "when": "A donut and legend need a custom layout without card chrome.",
+            "component": "component:ds-chart-donut",
+            "reason": "Compose the chart and ChartLegend directly and own their layout and hover synchronization."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-card-shell-data-viz",
+          "component:ds-chart-donut",
+          "component:ds-chart-legend",
+          "component:ds-empty-state",
+          "component:ds-skeleton"
+        ],
+        "accessibility": [
+          "Provide a concise card heading and a localized filter label for the icon-only header action.",
+          "Keep essential values available through the chart and visible legend rather than encoding meaning through slice color alone.",
+          "The application owns meaningful loading, empty, and error status copy when either content region is temporarily replaced or absent."
+        ],
+        "states": [
+          "The chart region fills remaining card height while the legend remains content-sized.",
+          "Chart and legend regions render only when their corresponding slots contain content, allowing the owner to substitute loading, empty, or error presentations without dangling region padding.",
+          "Hover synchronization changes highlight only; it never represents selection, filtering, or navigation.",
+          "The filter action emits intent while the parent owns popup content, applied constraints, and data updates."
+        ],
+        "responsiveBehavior": [
+          "Select the token-based card width appropriate to the parent grid; the matching minimum height preserves the chart region.",
+          "The parent dashboard owns wrapping and column changes while the internal chart-over-legend arrangement remains stable."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign chart data and legend items as JavaScript properties and place the components in the chart and legend slots."
+          ],
+          "react": [
+            "Keep filter and dataset state in the owner; the card handles hover synchronization for the canonical slotted pair."
+          ],
+          "angular": [
+            "Keep filter and dataset state in the owner; the card handles hover synchronization for the canonical slotted pair."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/CardDataVizDonut/CardDataVizDonut.stories.ts"
+          },
+          {
+            "label": "Dashboard review examples",
+            "path": "src/wc/stories/DataViz/OverviewReview.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "cardWidth": {
@@ -1526,9 +1665,73 @@
       "tag": "ds-chart-bar",
       "name": "chart-bar",
       "title": "ChartBar",
-      "summary": "ChartBar component from @ds-mo/ui.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Single-series bar chart for comparing discrete categories or evenly spaced time buckets on a band-scaled axis.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Single-series bar chart for comparing discrete categories or evenly spaced time buckets on a band-scaled axis.",
+        "useWhen": [
+          "Users need to compare one numeric measure across a small set of categories.",
+          "Values are grouped into ordered time buckets such as hours, days, weeks, or months and equal visual spacing is appropriate.",
+          "A data-viz card needs a compact magnitude comparison rather than a continuous trend."
+        ],
+        "avoidWhen": [
+          "Timestamp positions must reflect irregular elapsed time; pre-bucket the data or use a future continuous time-scale chart.",
+          "The visualization needs stacked, grouped, or multi-series bars.",
+          "The interaction requires selection, drill-down, brushing, or zoom.",
+          "The data communicates a part-to-whole relationship."
+        ],
+        "alternatives": [
+          {
+            "when": "Users need to follow one or more trends across ordered categories.",
+            "component": "component:ds-chart-line",
+            "reason": "ChartLine connects ordered observations and supports multiple named series."
+          },
+          {
+            "when": "The data communicates parts of a total.",
+            "component": "component:ds-chart-donut",
+            "reason": "ChartDonut provides the part-to-whole composition and center aggregate."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-card-shell-data-viz",
+          "component:ds-tooltip-data-viz"
+        ],
+        "accessibility": [
+          "Keep category labels concise and provide an adjacent textual summary when exact values are critical to completing a task.",
+          "Do not rely on bar color alone to communicate category meaning.",
+          "A future interactive tooltip must supplement rather than replace the chart's accessible value representation."
+        ],
+        "states": [
+          "The chart is currently a static single-series rendering without hover, selection, loading, or empty-state policy.",
+          "An empty dataset renders no bars; the owning card or product supplies meaningful empty-state messaging.",
+          "Use one consistent bar color across time buckets when every bar is the same measure at a different interval; categorical color changes are for genuinely distinct categories.",
+          "Authored datum colors override the shared categorical palette."
+        ],
+        "responsiveBehavior": [
+          "The owner supplies dimensions and updates them with its layout; the chart does not measure its container.",
+          "Limit or pre-format long category labels so they remain legible at the chosen width.",
+          "Time labels remain ordered, pre-formatted buckets with equal spacing rather than raw continuous timestamps."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign data as a JavaScript property; arrays are not supported as HTML attributes."
+          ],
+          "react": [
+            "Pass a stable data array and dimensions derived from the containing layout."
+          ],
+          "angular": [
+            "Bind data as a property and update dimensions from the containing layout."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/ChartBar/ChartBar.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "data": {
@@ -1563,9 +1766,75 @@
       "tag": "ds-chart-donut",
       "name": "chart-donut",
       "title": "ChartDonut",
-      "summary": "ChartDonut component from @ds-mo/ui.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Part-to-whole donut chart with a center aggregate, responsive fill sizing, local slice tooltip feedback, and externally controlled legend highlighting.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Part-to-whole donut chart with a center aggregate, responsive fill sizing, local slice tooltip feedback, and externally controlled legend highlighting.",
+        "useWhen": [
+          "Users need to understand a small part-to-whole breakdown with a prominent total or status in the center.",
+          "A standalone donut needs pointer and keyboard-focus value feedback through a chart-owned data-viz tooltip.",
+          "A donut and visible ChartLegend should cross-highlight by matching stable labels."
+        ],
+        "avoidWhen": [
+          "The data is a trend, time sequence, or independent magnitude comparison.",
+          "The category count creates slices too small to understand reliably.",
+          "Hover is intended to select, filter, or navigate rather than temporarily highlight data."
+        ],
+        "alternatives": [
+          {
+            "when": "The product needs the canonical card, filter action, visible legend, and built-in hover synchronization.",
+            "component": "component:ds-card-data-viz-donut",
+            "reason": "The dedicated card owns that complete composition and suppresses redundant slice tooltips."
+          },
+          {
+            "when": "Users need to compare independent category magnitudes.",
+            "component": "component:ds-chart-bar",
+            "reason": "Bars make category magnitude differences easier to compare."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-chart-legend",
+          "component:ds-tooltip-data-viz",
+          "component:ds-card-data-viz-donut"
+        ],
+        "accessibility": [
+          "Every non-empty slice remains keyboard focusable and exposes its label and value without depending on the visual tooltip.",
+          "Use a visible legend when the full set of labels, values, or percentages must remain continuously available.",
+          "Provide localized no-data text for the neutral empty ring.",
+          "Center text is a visual summary and must not be the only source of essential category detail."
+        ],
+        "states": [
+          "Genuine local pointer or keyboard focus may show a chart-owned tooltip; externally synchronized highlight never opens it.",
+          "When a visible legend already owns label and value detail, suppress the redundant donut tooltip. CardDataVizDonut does this automatically.",
+          "Local hover and external highlight remain separate while both may dim non-matching slices.",
+          "Zero or negative totals render a neutral empty ring without interactive slices.",
+          "Center value and caption truncate when they exceed the safe inner-circle measure."
+        ],
+        "responsiveBehavior": [
+          "Prefer container-fill sizing inside data-viz cards and explicit sizing only in layouts that own a stable diameter.",
+          "Fill sizing remains centered and constrained to the shared donut size band.",
+          "The owner adapts category count and legend placement for available space."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign data as a JavaScript property and wire slice-hover detail to a sibling legend only when not using CardDataVizDonut."
+          ],
+          "react": [
+            "Keep synchronized highlight controlled by the composition and disable slice tooltips when a sibling legend continuously shows the same details."
+          ],
+          "angular": [
+            "Keep synchronized highlight controlled by the composition and disable slice tooltips when a sibling legend continuously shows the same details."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/ChartDonut/ChartDonut.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "activeLabel": {
@@ -1600,6 +1869,10 @@
             "type": "string",
             "required": false
           },
+          "showTooltip": {
+            "type": "boolean",
+            "required": false
+          },
           "size": {
             "type": "number | undefined",
             "required": false
@@ -1626,16 +1899,88 @@
         "@ds-mo/ui",
         "@ds-mo/tokens"
       ],
-      "componentDependencies": []
+      "componentDependencies": [
+        "tooltip-data-viz"
+      ]
     },
     {
       "id": "component:ds-chart-legend",
       "tag": "ds-chart-legend",
       "name": "chart-legend",
       "title": "ChartLegend",
-      "summary": "Base legend for `ds-chart-*` components. Webapp's Overview widgets each style\nlegends differently (list w/ values, compact chips, bare swatches, external\nstat callouts) — this covers the common \"swatch + label + optional value\" case.\nConsumers who need a different treatment skip this component entirely and\nrender their own markup against the same `ChartDatum[]` data.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Display-first chart legend with swatches, labels, optional values and percentages, explicit deep links, and highlight-only chart synchronization.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Display-first chart legend with swatches, labels, optional values and percentages, explicit deep links, and highlight-only chart synchronization.",
+        "useWhen": [
+          "A chart needs the standard swatch, label, and optional numeric-detail legend.",
+          "Donut slices or line series need a continuously visible key beside or below the visualization.",
+          "A category has an explicit deep-link destination and should render as an accessible link."
+        ],
+        "avoidWhen": [
+          "The design calls for chips, bare swatches, external stat callouts, or another custom legend treatment.",
+          "Rows need to toggle visibility, filter data, or represent selection.",
+          "The content is a command menu or navigation list unrelated to chart data."
+        ],
+        "alternatives": [
+          {
+            "when": "The product needs a nonstandard legend treatment.",
+            "component": "component:ds-text",
+            "reason": "Compose product-owned semantic markup from the same chart data rather than forcing it into this row recipe."
+          },
+          {
+            "when": "The donut belongs in the canonical dashboard card.",
+            "component": "component:ds-card-data-viz-donut",
+            "reason": "The dedicated card places the legend and handles bidirectional highlight synchronization."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-chart-donut",
+          "component:ds-chart-line",
+          "component:ds-card-data-viz-donut",
+          "component:ds-card-shell-data-viz"
+        ],
+        "accessibility": [
+          "Rows remain non-interactive unless the item supplies an actual link destination.",
+          "Synced highlight changes opacity only and never moves focus or announces selection.",
+          "Keep full labels available when visible text truncates, and retain stable tabular numeric columns.",
+          "Do not rely on swatch color alone; every entry requires a meaningful visible label."
+        ],
+        "states": [
+          "Local pointer or focus interaction and external chart highlight remain separate; both may dim peers, but only a real link row receives interactive affordances.",
+          "Hover synchronization is temporary emphasis, never filtering, toggling, or selected state.",
+          "Percentage values use one consistent precision across the complete legend.",
+          "The list owns pointer leave so moving across row gaps does not clear and reapply highlight."
+        ],
+        "responsiveBehavior": [
+          "Vertical legends let the label yield width and truncate before right-aligned value and percentage columns.",
+          "Horizontal legends wrap complete entries and suit compact series keys below a chart.",
+          "The parent constrains width and decides when a custom condensed treatment is necessary."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign items as a JavaScript property and set href only for genuine navigation."
+          ],
+          "react": [
+            "Intercept the item-click event only when application routing must replace native link navigation."
+          ],
+          "angular": [
+            "Intercept the item-click event only when application routing must replace native link navigation."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/ChartLegend/ChartLegend.stories.ts"
+          },
+          {
+            "label": "Rendered interaction tests",
+            "path": "tests/e2e/chart-legend.spec.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "activeLabel": {
@@ -1663,39 +2008,103 @@
             "required": false
           }
         },
-        "events": [
-          {
-            "name": "dsItemClick",
-            "detail": "{ item: ChartLegendItem; originalEvent: MouseEvent }"
-          },
+        "events": [
+          {
+            "name": "dsItemClick",
+            "detail": "{ item: ChartLegendItem; originalEvent: MouseEvent }"
+          },
+          {
+            "name": "dsItemHover",
+            "detail": "ChartLegendItem | null"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-chart-legend",
+        "react": "DsChartLegend",
+        "angular": "DsChartLegend"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-chart-line",
+      "tag": "ds-chart-line",
+      "name": "chart-line",
+      "title": "ChartLine",
+      "summary": "Static single- or multi-series line chart for trends across ordered, evenly spaced categories, including preformatted time-period labels.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Static single- or multi-series line chart for trends across ordered, evenly spaced categories, including preformatted time-period labels.",
+        "useWhen": [
+          "Users need to follow one or more numeric trends across a shared ordered x-axis.",
+          "Time periods are already grouped into equally spaced labels such as months, weeks, or days.",
+          "A horizontal ChartLegend should identify multiple series."
+        ],
+        "avoidWhen": [
+          "Pixel position must reflect irregular elapsed time or continuous timestamps.",
+          "The primary task is comparing unrelated category magnitudes rather than following a trend.",
+          "The chart needs built-in zoom, brushing, selection, or drill-down.",
+          "Series lengths do not align with the shared category list."
+        ],
+        "alternatives": [
+          {
+            "when": "Users need to compare one measure across discrete categories or time buckets.",
+            "component": "component:ds-chart-bar",
+            "reason": "Bars emphasize independent bucket magnitudes."
+          },
+          {
+            "when": "The data communicates parts of a total.",
+            "component": "component:ds-chart-donut",
+            "reason": "Donut provides the part-to-whole and center-summary treatment."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-chart-legend",
+          "component:ds-card-shell-data-viz",
+          "component:ds-tooltip-data-viz"
+        ],
+        "accessibility": [
+          "Provide a visible legend or adjacent textual summary when exact series values are important; the chart image name alone is not a complete data table.",
+          "Do not rely on series color alone to communicate meaning.",
+          "A future point tooltip must supplement rather than replace accessible series and value context."
+        ],
+        "states": [
+          "The chart is currently static and does not own hover, selection, loading, or empty-state policy.",
+          "Point markers may be shown or hidden without changing the underlying series meaning.",
+          "Authored series colors override the shared categorical palette."
+        ],
+        "responsiveBehavior": [
+          "The owner supplies dimensions and updates them when its layout changes.",
+          "Category positions are always equally spaced, even when labels represent time.",
+          "Reduce or pre-format dense labels before passing them; the chart renders authored labels without a continuous time scale."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign series and categories as JavaScript properties and keep every series aligned to the category count."
+          ],
+          "react": [
+            "Pass stable series and category arrays with dimensions derived from the containing layout."
+          ],
+          "angular": [
+            "Bind series and categories as properties with dimensions derived from the containing layout."
+          ]
+        },
+        "references": [
           {
-            "name": "dsItemHover",
-            "detail": "ChartLegendItem | null"
+            "label": "Storybook examples",
+            "path": "src/wc/components/ChartLine/ChartLine.stories.ts"
           }
-        ],
-        "slots": []
-      },
-      "exports": {
-        "customElement": "ds-chart-legend",
-        "react": "DsChartLegend",
-        "angular": "DsChartLegend"
+        ]
       },
-      "dependencies": [
-        "@ds-mo/ui",
-        "@ds-mo/tokens"
-      ],
-      "componentDependencies": [
-        "text"
-      ]
-    },
-    {
-      "id": "component:ds-chart-line",
-      "tag": "ds-chart-line",
-      "name": "chart-line",
-      "title": "ChartLine",
-      "summary": "ChartLine component from @ds-mo/ui.",
-      "intentStatus": "migration-pending",
-      "intent": null,
       "api": {
         "props": {
           "categories": {
@@ -2038,7 +2447,7 @@
           "component:ds-button-unfilled"
         ],
         "accessibility": [
-          "The copy action has explicit status wording and the code remains selectable text.",
+          "The copy action has matching accessible-name and visible-tooltip status wording, and the code remains selectable text.",
           "Language and filename labels supplement rather than replace the code content."
         ],
         "responsiveBehavior": [
@@ -2080,7 +2489,8 @@
       ],
       "componentDependencies": [
         "button-unfilled",
-        "text"
+        "text",
+        "tooltip"
       ]
     },
     {
@@ -3546,16 +3956,16 @@
           "pattern:conversation"
         ],
         "accessibility": [
-          "Always provide a localized textarea label and submit or stop action names.",
+          "Always provide a localized textarea label and submit or stop action names; the built-in icon action exposes the same name in its tooltip.",
           "Shift plus Enter inserts a newline while Enter submits non-empty content.",
           "Streaming and error states remain perceivable without relying on icon shape alone."
         ],
         "states": [
           "The owner controls draft value and transport state; the composer emits intent without performing transport.",
-          "Use the tools slot for leading actions such as add and the actions slot for trailing actions such as dictation; the built-in submit or stop action remains last with an 8px gap from the preceding action. These icon buttons use the standard non-rounded control radius.",
+          "Use the tools slot for leading actions such as add and the actions slot for trailing actions such as dictation; the built-in submit or stop action remains last with an 8px gap from the preceding action. These icon buttons use the standard non-rounded control radius, and the application supplies tooltips for slotted icon actions.",
           "The composer surface uses the 10px --dimension-radius-125 token.",
           "Mouse or keyboard focus on the textarea gives the complete composer surface the same bold-brand inset stroke width and color as an active Input; the native textarea never draws a separate outline.",
-          "The submit action defaults to brand for both agent and person-to-person conversations; change submitIntent only when the action consequence has a different semantic intent."
+          "The empty or otherwise inactive submit action is a disabled bordered ButtonUnfilled. Ready submit actions use submitIntent, while the streaming stop action remains a bold-brand ButtonFilled."
         ],
         "responsiveBehavior": [
           "The textarea begins at two body-medium lines, grows one line at a time through six lines, and then scrolls internally."
@@ -3624,7 +4034,9 @@
         "@ds-mo/tokens"
       ],
       "componentDependencies": [
-        "button-filled"
+        "button-filled",
+        "button-unfilled",
+        "tooltip"
       ]
     },
     {
@@ -3654,7 +4066,7 @@
         "accessibility": [
           "Give each transcript a concise localized label.",
           "New content is exposed through log semantics without stealing focus.",
-          "The scroll-to-latest control remains keyboard accessible when follow behavior is released."
+          "The scroll-to-latest control remains keyboard accessible when follow behavior is released and exposes its action name in a tooltip."
         ],
         "states": [
           "Selection and transcript interaction release automatic following.",
@@ -3709,7 +4121,8 @@
         "@ds-mo/tokens"
       ],
       "componentDependencies": [
-        "button-unfilled"
+        "button-unfilled",
+        "tooltip"
       ]
     },
     {
@@ -3761,7 +4174,7 @@
         "accessibility": [
           "Provide a concise visible heading; the component uses it as the dialog's accessible name.",
           "Give the primary explanatory copy a stable id and pass it through aria-describedby so assistive technology receives the decision context.",
-          "Opening the native modal dialog moves focus to the header Close action, traps Tab navigation inside the top layer, and makes outside content inert.",
+          "Opening the native modal dialog moves focus to the header Close action, whose visible tooltip matches its accessible name, traps Tab navigation inside the top layer, and makes outside content inert.",
           "Close, Escape, and backdrop activation emit dsClose with close-button, escape, or backdrop reason before beginning dismissal; use the component only when every dismissal path is safe.",
           "After exit motion completes, the native dialog leaves the top layer, focus returns to the previously focused element, and dsAfterClose emits.",
           "Use visible label-only footer buttons. Keep at most two actions: one bold filled primary action followed by one bordered unfilled action, or two bordered unfilled actions.",
@@ -3859,7 +4272,8 @@
       ],
       "componentDependencies": [
         "button-unfilled",
-        "text"
+        "text",
+        "tooltip"
       ]
     },
     {
@@ -3903,7 +4317,7 @@
           }
         ],
         "commonlyComposedWith": [
-          "component:ds-app-shell",
+          "component:ds-shell-app",
           "component:ds-bar-nav",
           "component:ds-panel-tools",
           "component:ds-menu"
@@ -3934,7 +4348,7 @@
           "At 1200px and wider, default to expanded, allow the user to expand or collapse, and restore the locally persisted desktop preference when available.",
           "From 768px through 1199px, present PanelNav permanently collapsed and do not allow user expansion.",
           "Below 768px, the consuming application replaces PanelNav with a dedicated mobile navigation component; PanelNav does not own mobile navigation.",
-          "AppShell permanently owns responsive composition: it determines shell mode, enforces tablet collapse, and replaces PanelNav with future mobile navigation below 768px.",
+          "ShellApp permanently owns responsive composition: it determines shell mode, enforces tablet collapse, and replaces PanelNav with future mobile navigation below 768px.",
           "When the viewport is below breakpoint, PanelNav locks collapsed, disables its header toggle affordance, and preserves the persisted desktop collapse preference.",
           "Collapsed presentation must preserve destination ordering, active state, notification status, and accessible names."
         ],
@@ -3945,12 +4359,12 @@
           ],
           "react": [
             "Pass groups as an array through the generated React wrapper and synchronize currentUrl with the host router.",
-            "AppShell owns mobile replacement; PanelNav enforces its configured breakpoint expansion lock."
+            "ShellApp owns mobile replacement; PanelNav enforces its configured breakpoint expansion lock."
           ],
           "angular": [
             "Import DsPanelNav from @ds-mo/ui/angular/ds-panel-nav and bind groups as a property.",
             "Bind both the nav-style attribute and navStyle property when first-paint route styling must be deterministic.",
-            "AppShell owns mobile replacement; PanelNav enforces its configured breakpoint expansion lock."
+            "ShellApp owns mobile replacement; PanelNav enforces its configured breakpoint expansion lock."
           ]
         },
         "references": [
@@ -4133,7 +4547,7 @@
           {
             "when": "The choices are secondary application routes.",
             "component": "component:ds-bar-nav",
-            "reason": "BarNav owns route sections inside AppShell."
+            "reason": "BarNav owns route sections inside ShellApp."
           },
           {
             "when": "The choices are transient actions or options.",
@@ -4245,7 +4659,7 @@
           "component:ds-button-unfilled"
         ],
         "accessibility": [
-          "Leading navigation or dismiss actions and trailing icon actions require concise localized names.",
+          "Leading navigation or dismiss actions and trailing icon actions require concise localized names; the header reuses each name as the action tooltip.",
           "The visible heading names the active panel or subview."
         ],
         "states": [
@@ -4336,7 +4750,8 @@
       ],
       "componentDependencies": [
         "button-unfilled",
-        "text"
+        "text",
+        "tooltip"
       ]
     },
     {
@@ -4366,13 +4781,13 @@
         ],
         "accessibility": [
           "Provide an aria-label that names the searched domain, such as Search agent chats or Search messages.",
-          "The standard search clear action restores focus and emits both the empty query and dsClear.",
-          "When showFilter is enabled, provide stable filterTriggerId and filterControls values, synchronize filterExpanded with the controlled menu, and restore focus after selection."
+          "The standard search clear action restores focus, exposes its localized name in a tooltip, and emits both the empty query and dsClear.",
+          "When showFilter is enabled, provide stable filterTriggerId and filterControls values, synchronize filterExpanded with the controlled menu, and restore focus after selection; filterAriaLabel also labels its tooltip."
         ],
         "states": [
           "The row is always 48px high with 8px outer padding and a complete md search recipe: 32px control, text-body-medium at 14px/20px, and a 20px md search icon.",
           "The search icon stays foreground-secondary at rest, hover, focus, active, and while the query is filled.",
-          "The row and control surface remain transparent so the AppShell chrome wash is visible behind them.",
+          "The row and control surface remain transparent so the ShellApp chrome wash is visible behind them.",
           "The row divider remains the same tertiary 1px boundary while the input is focused because it belongs to the 48px container rather than the input control.",
           "With filtering enabled, the md search control, decorative vertical divider, and borderless md Filter action are separated by 8px; filterActive promotes only the trigger foreground without adding a selected fill."
         ],
@@ -4477,7 +4892,8 @@
         "button-unfilled",
         "divider",
         "icon",
-        "text"
+        "text",
+        "tooltip"
       ]
     },
     {
@@ -4485,14 +4901,14 @@
       "tag": "ds-panel-tools",
       "name": "panel-tools",
       "title": "PanelTools",
-      "summary": "Required AppShell utility rail and persistent drawer host for the fixed set of global Search, Agents, Messages, Stacks, Activity, and Help products.",
+      "summary": "Required ShellApp utility rail and persistent drawer host for the fixed set of global Search, Agents, Messages, Stacks, Activity, and Help products.",
       "intentStatus": "complete",
       "intent": {
         "audience": "specialized",
         "status": "stable",
-        "summary": "Required AppShell utility rail and persistent drawer host for the fixed set of global Search, Agents, Messages, Stacks, Activity, and Help products.",
+        "summary": "Required ShellApp utility rail and persistent drawer host for the fixed set of global Search, Agents, Messages, Stacks, Activity, and Help products.",
         "useWhen": [
-          "Composing the required global tools region inside the application's single AppShell.",
+          "Composing the required global tools region inside the application's single ShellApp.",
           "Users need to move between application-wide utilities without losing each tool's in-progress state.",
           "Search, AI conversations, user messages, review stacks, notifications, or help content must remain available alongside route content."
         ],
@@ -4500,8 +4916,8 @@
           "The action is specific to the current page or selected content rather than globally available across the application.",
           "The item navigates to a primary or secondary route; use PanelNav or BarNav instead.",
           "A consumer wants to add arbitrary tools, reorder fixed tools, or repurpose a semantic tool id.",
-          "Building the mobile tools experience; future mobile AppShell composition uses a different bottom-bar and panel pattern.",
-          "PanelTools would be mounted outside the application's single AppShell."
+          "Building the mobile tools experience; future mobile ShellApp composition uses a different bottom-bar and panel pattern.",
+          "PanelTools would be mounted outside the application's single ShellApp."
         ],
         "alternatives": [
           {
@@ -4521,7 +4937,7 @@
           }
         ],
         "commonlyComposedWith": [
-          "component:ds-app-shell",
+          "component:ds-shell-app",
           "component:ds-panel-nav",
           "component:ds-bar-nav"
         ],
@@ -4549,7 +4965,7 @@
           "Each tool supplies its current header title, base-versus-detail Back state, and right-side actions through the headers property. Base views omit Back; deeper views expose Back and update the same header in place.",
           "Header Back and action events express intent only; the owning tool changes product navigation, menus, and data state. PanelTools keeps the final header action exactly 8px from the drawer edge.",
           "Menus opened from a right-side header action use PANEL_TOOLS_HEADER_MENU_PLACEMENT: bottom/end choice-cell alignment and a 12px side offset, placing the popup 4px below the 48px header while aligning the final menu item edge with the trigger.",
-          "Tool view roots stay transparent so AppShell's chrome wash remains visible; only explicitly designed child surfaces introduce a fill.",
+          "Tool view roots stay transparent so ShellApp's chrome wash remains visible; only explicitly designed child surfaces introduce a fill.",
           "Tools with search compose ds-panel-tool-search immediately below the shared header. Its 48px row always contains the md search control and must not be reduced to sm or xs.",
           "If an active optional tool becomes unavailable, PanelTools closes the drawer, clears activeTool, and emits its deselection.",
           "Use isInactive only for a temporarily unavailable visible tool; omit tools the user is not authorized to access.",
@@ -4560,8 +4976,8 @@
         ],
         "responsiveBehavior": [
           "The open drawer reduces main-content width and uses --dimension-panel-width-xs (300px) on every supported desktop and tablet viewport.",
-          "AppShell owns the fixed drawer-width variable; consumers must not hardcode alternate drawer widths.",
-          "Below 768px, do not reuse desktop PanelTools: future AppShell mobile composition uses a bottom bar for Search, Agents, Notifications, and Stacks, while Help moves into mobile primary navigation.",
+          "ShellApp owns the fixed drawer-width variable; consumers must not hardcode alternate drawer widths.",
+          "Below 768px, do not reuse desktop PanelTools: future ShellApp mobile composition uses a bottom bar for Search, Agents, Notifications, and Stacks, while Help moves into mobile primary navigation.",
           "Keep named-slot content mounted while tools switch or the drawer closes so users can return to in-progress global work.",
           "Conversation products may use fullscreenHeaderMode split for a 300px history rail beside a flexible detail pane, each with its own canonical header; the application owns that internal split layout.",
           "Use fixed drawer widths for now; do not add user resizing or width persistence."
@@ -4570,10 +4986,10 @@
           "customElements": [
             "Assign items as a JavaScript property for structured data; items-json is the string fallback.",
             "Assign headers as a JavaScript property and replace its object identity whenever an active tool changes title, depth, or actions.",
-            "Keep PanelTools mounted at AppShell scope across route changes and provide each product through its matching named slot."
+            "Keep PanelTools mounted at ShellApp scope across route changes and provide each product through its matching named slot."
           ],
           "react": [
-            "Pass the fixed item collection through the generated React wrapper and keep named-slot product content mounted at AppShell scope.",
+            "Pass the fixed item collection through the generated React wrapper and keep named-slot product content mounted at ShellApp scope.",
             "Use storageKey only for same-browser last-tool continuity; do not persist the open drawer."
           ],
           "angular": [
@@ -5094,7 +5510,8 @@
         "empty-state",
         "icon",
         "loader",
-        "text"
+        "text",
+        "tooltip"
       ]
     },
     {
@@ -5354,25 +5771,150 @@
         "empty-state",
         "icon",
         "loader",
-        "text"
+        "text",
+        "tooltip"
       ]
     },
+    {
+      "id": "component:ds-shell-app",
+      "tag": "ds-shell-app",
+      "name": "shell-app",
+      "title": "ShellApp",
+      "summary": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "stable",
+        "summary": "The single required workspace root for standard authenticated application pages, coordinating primary and secondary navigation, tools chrome, responsive composition, content geometry, shared styling, and shell behavior.",
+        "useWhen": [
+          "Building any standard authenticated product or workspace page with CompoMo.",
+          "PanelNav, BarNav, PanelTools, page content, shared chrome, responsive behavior, and shell shortcuts must be composed as one application frame.",
+          "Future application templates need the supported base-page composition boundary."
+        ],
+        "avoidWhen": [
+          "Building authentication, onboarding, public, marketing, print, error, or intentionally focused full-screen experiences that require a different layout.",
+          "Another ShellApp already exists in the page; applications must render exactly one and must never nest ShellApps.",
+          "Building content inside an existing ShellApp; render the page content rather than another shell."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-panel-nav",
+          "component:ds-bar-nav",
+          "component:ds-panel-tools",
+          "component:ds-shell-page",
+          "component:ds-swatch-picker"
+        ],
+        "patterns": [
+          "pattern:application-shell",
+          "pattern:shell-page"
+        ],
+        "accessibility": [
+          "Keep primary destinations in PanelNav and secondary route sections in BarNav.",
+          "Ensure the default content region contains the page's single main landmark.",
+          "Keep PanelNav, BarNav, and PanelTools chrome available in the shell's supported desktop and tablet compositions.",
+          "Do not override browser keyboard chords when enabling shell shortcuts.",
+          "Require Search and Help as the minimum PanelTools actions and provide accessible labels for every tool.",
+          "Preserve focus and accessible names across navigation, collapse, overflow, and responsive presentation changes."
+        ],
+        "states": [
+          "Render exactly one ShellApp as the workspace root and never nest it.",
+          "PanelNav, BarNav, and PanelTools are required shell regions; PanelTools contains at least Search and Help even when no additional product tools apply.",
+          "The application router owns the current route, authorization filtering, Dashboard or Settings context, destination collections, section collections, and localized content labels.",
+          "ShellApp propagates navStyle and coordinates layout, gradient alignment, transitions, metrics, shortcuts, and responsive composition.",
+          "Set gradientPreset to the single resolved global chrome preference: neutral by default, none for solid chrome, or cool, neutral, warm, and fresh for token-based washes.",
+          "The application owns gradient preference persistence, cross-tab synchronization, and server or account precedence; ShellApp owns rendering the resolved preset across authenticated routes.",
+          "Dashboard represents day-to-day operational work while Settings represents administrative and configuration work; route state selects the context.",
+          "Update PanelNav groups, BarNav tabs and heading, navStyle, basePath, and currentUrl atomically from one resolved route state.",
+          "BarNav remains present: it shows route-section tabs when available and the active PanelNav destination label as heading otherwise.",
+          "Render one ShellPage as the default-slot child for each standard routed page; ShellApp owns the content scroller while ShellPage owns page header stickiness and content inset.",
+          "The application filters unauthorized destinations, sections, and tools before passing them into shell components."
+        ],
+        "responsiveBehavior": [
+          "ShellApp owns the fixed system breakpoints and resolves desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
+          "On desktop, PanelNav defaults expanded, permits user collapse or expansion, and respects the locally persisted desktop preference.",
+          "On tablet, ShellApp keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
+          "On mobile, ShellApp remains the page root but replaces PanelNav and desktop navigation composition with a future dedicated mobile navigation design.",
+          "Keep PanelNav width, BarNav height, PanelTools chrome, and main-content origin stable except during intentional responsive or collapse transitions.",
+          "The current runtime does not yet implement the complete desktop, tablet, and mobile composition contract; consuming applications must enforce missing breakpoint behavior until ShellApp provides it."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign complex navigation and tool collections as JavaScript properties on the slotted components.",
+            "Stamp route-derived nav-style before components connect when deterministic first paint is required."
+          ],
+          "react": [
+            "Use generated wrappers and preserve native slot names for PanelNav, BarNav, PanelTools, and main content.",
+            "Resolve all shell inputs from one router state before rendering the composition."
+          ],
+          "angular": [
+            "Use generated standalone adapters and preserve slot attributes in templates.",
+            "Bind complex inputs as properties and update navigation inputs atomically from one resolved router state.",
+            "Bind both nav-style attributes and properties when deterministic first paint is required."
+          ]
+        },
+        "references": [
+          {
+            "label": "Component guide",
+            "path": "src/wc/components/ShellApp/ShellApp.mdx"
+          },
+          {
+            "label": "Executable Storybook composition",
+            "path": "src/wc/components/ShellApp/ShellApp.stories.ts"
+          },
+          {
+            "label": "Framework integration",
+            "path": "docs/framework-integration.md"
+          },
+          {
+            "label": "Application shell contract",
+            "path": "agent/patterns/application-shell/pattern.agent.json"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "gradientPreset": {
+            "type": "ShellGradientPreset",
+            "required": false
+          },
+          "navStyle": {
+            "type": "NavChromeStyle",
+            "required": false
+          },
+          "shortcutsEnabled": {
+            "type": "boolean",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-shell-app",
+        "react": "DsShellApp",
+        "angular": "DsShellApp"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": []
+    },
     {
       "id": "component:ds-shell-gradient-picker",
       "tag": "ds-shell-gradient-picker",
       "name": "shell-gradient-picker",
       "title": "ShellGradientPicker",
-      "summary": "Deprecated compatibility wrapper that maps the fixed AppShell wash presets into SwatchPicker.",
+      "summary": "Deprecated compatibility wrapper that maps the fixed ShellApp wash presets into SwatchPicker.",
       "intentStatus": "complete",
       "intent": {
         "audience": "specialized",
         "status": "deprecated",
         "replacedBy": "component:ds-swatch-picker",
         "replacementReason": "SwatchPicker now owns the same accessible interaction with a generic option model that supports both flat colors and gradients.",
-        "summary": "Deprecated compatibility wrapper that maps the fixed AppShell wash presets into SwatchPicker.",
+        "summary": "Deprecated compatibility wrapper that maps the fixed ShellApp wash presets into SwatchPicker.",
         "useWhen": [
           "Adding the Appearance or Theme section to the application's user or account menu.",
-          "Users must choose the global AppShell chrome treatment from none, cool, neutral, warm, or fresh."
+          "Users must choose the global ShellApp chrome treatment from none, cool, neutral, warm, or fresh."
         ],
         "avoidWhen": [
           "Choosing semantic intent, page background, chart, content, or brand colors.",
@@ -5388,7 +5930,7 @@
           }
         ],
         "commonlyComposedWith": [
-          "component:ds-app-shell",
+          "component:ds-shell-app",
           "component:ds-menu"
         ],
         "patterns": [
@@ -5402,7 +5944,7 @@
         "states": [
           "Neutral is the default preset; none renders solid shell chrome without a wash.",
           "Cool, neutral, warm, and fresh use design tokens and automatically adapt to the active light or dark color theme.",
-          "Apply dsChange immediately to AppShell.gradientPreset and keep the containing account menu open.",
+          "Apply dsChange immediately to ShellApp.gradientPreset and keep the containing account menu open.",
           "The application owns local persistence, cross-tab synchronization, and server or account preference precedence; the picker owns only selection UI and events.",
           "Treat the fixed preset union as the only supported values and do not construct custom gradients."
         ],
@@ -5412,7 +5954,7 @@
         ],
         "frameworkCaveats": {
           "customElements": [
-            "Listen for dsChange, resolve application preference precedence, and assign the result to the single AppShell gradientPreset property."
+            "Listen for dsChange, resolve application preference precedence, and assign the result to the single ShellApp gradientPreset property."
           ],
           "react": [
             "Use the generated wrapper and handle onDsChange without closing the containing account menu."
@@ -5427,8 +5969,8 @@
             "path": "src/wc/components/SwatchPicker/SwatchPicker.stories.ts"
           },
           {
-            "label": "AppShell gradient contract",
-            "path": "src/wc/components/AppShell/AppShell.mdx"
+            "label": "ShellApp gradient contract",
+            "path": "src/wc/components/ShellApp/ShellApp.mdx"
           },
           {
             "label": "Application shell composition",
@@ -5473,14 +6015,14 @@
       "tag": "ds-shell-gradient-swatch",
       "name": "shell-gradient-swatch",
       "title": "ShellGradientSwatch",
-      "summary": "Deprecated internal compatibility component for one legacy AppShell gradient swatch.",
+      "summary": "Deprecated internal compatibility component for one legacy ShellApp gradient swatch.",
       "intentStatus": "complete",
       "intent": {
         "audience": "internal",
         "status": "deprecated",
         "replacedBy": "component:ds-swatch-picker",
         "replacementReason": "SwatchPicker renders its option buttons internally so an individually published radio swatch is no longer needed.",
-        "summary": "Deprecated internal compatibility component for one legacy AppShell gradient swatch.",
+        "summary": "Deprecated internal compatibility component for one legacy ShellApp gradient swatch.",
         "useWhen": [
           "Maintaining or extending ShellGradientPicker inside CompoMo."
         ],
@@ -5568,6 +6110,120 @@
       ],
       "componentDependencies": []
     },
+    {
+      "id": "component:ds-shell-page",
+      "tag": "ds-shell-page",
+      "name": "shell-page",
+      "title": "ShellPage",
+      "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle placement, container-aware header variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "The standard routed-page boundary inside ShellApp, owning sticky BarTitle placement, container-aware header variants, stable scroll compaction, and optional page-content inset without creating a nested scroll container.",
+        "useWhen": [
+          "Rendering a standard routed page inside ShellApp's default content region.",
+          "BarTitle should expand at a roomy page top, compact after scroll, or use constrained action layout when the page column narrows.",
+          "Pages need consistent content gutters with an explicit full-bleed option."
+        ],
+        "avoidWhen": [
+          "Building authentication, onboarding, public, modal, drawer, or intentionally focused fullscreen layouts outside the standard ShellApp page region.",
+          "Another ShellPage already owns the routed page; never nest ShellPages.",
+          "A bounded card or pane needs its own header rather than a page-level main landmark."
+        ],
+        "alternatives": [
+          {
+            "when": "The composition is a persistent application-wide workspace frame.",
+            "component": "component:ds-shell-app",
+            "reason": "ShellApp owns global navigation, tools, and the content scroll region; ShellPage belongs inside it."
+          },
+          {
+            "when": "Only static page title chrome is required without sticky or responsive orchestration.",
+            "component": "component:ds-bar-title",
+            "reason": "BarTitle can be used standalone with an explicit variant."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-shell-app",
+          "component:ds-bar-title",
+          "component:ds-tab-group"
+        ],
+        "patterns": [
+          "pattern:shell-page"
+        ],
+        "accessibility": [
+          "ShellPage exposes the routed page as the main landmark; render exactly one active ShellPage inside ShellApp.",
+          "Provide exactly one BarTitle through the header slot so the page has one h1.",
+          "Keep loading, empty, validation, error, progress, success, and failure communication in the default product-content slot.",
+          "Responsive variant changes preserve the same heading, controls, accessible names, and keyboard focus targets."
+        ],
+        "states": [
+          "headerPresentation=auto selects expanded, compact, or constrained from ShellPage's own inline capacity and scroll position.",
+          "expanded, compact, and constrained are explicit overrides for exceptional layouts and deterministic examples.",
+          "contentInset=default supplies standard page gutters; none permits maps, canvases, and other full-bleed content.",
+          "The required header slot accepts one BarTitle. The default slot owns router output and all page product content."
+        ],
+        "responsiveBehavior": [
+          "ShellPage observes its own rendered width instead of viewport media queries or ShellApp desktop/tablet modes.",
+          "Roomy pages expand at the top and compact after scroll; medium-capacity pages start compact; narrow pages use the constrained header variant.",
+          "Token-based capacity bands use hysteresis so opening tools or resizing navigation cannot oscillate near a boundary.",
+          "Scroll compaction preserves the expanded page flow offset so content never jumps beneath the sticky header.",
+          "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Import ShellPage and BarTitle, place one ds-bar-title in slot=header, and render route content as default children.",
+            "Do not set BarTitle.variant while ShellPage owns headerPresentation."
+          ],
+          "react": [
+            "Render DsBarTitle with slot=header inside DsShellPage and keep routed content as the remaining children.",
+            "Use contentInset none only for deliberately full-bleed page products."
+          ],
+          "angular": [
+            "Import the generated standalone DsShellPage and DsBarTitle adapters, preserve slot=header, and place router-outlet in the ShellPage default slot.",
+            "Do not add another overflow auto wrapper around the routed page."
+          ]
+        },
+        "references": [
+          {
+            "label": "Page-family and responsive examples",
+            "path": "src/wc/components/ShellPage/ShellPage.stories.ts"
+          },
+          {
+            "label": "Cross-browser geometry and interaction coverage",
+            "path": "tests/e2e/bar-title.spec.ts"
+          },
+          {
+            "label": "Reusable framework composition",
+            "path": "agent/patterns/shell-page/pattern.agent.json"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "contentInset": {
+            "type": "ShellPageContentInset",
+            "required": false
+          },
+          "headerPresentation": {
+            "type": "ShellPageHeaderPresentation",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-shell-page",
+        "react": "DsShellPage",
+        "angular": "DsShellPage"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": []
+    },
     {
       "id": "component:ds-skeleton",
       "tag": "ds-skeleton",
@@ -5966,7 +6622,7 @@
         ],
         "commonlyComposedWith": [
           "component:ds-menu",
-          "component:ds-app-shell"
+          "component:ds-shell-app"
         ],
         "accessibility": [
           "Provide a localized groupLabel describing the complete choice.",
@@ -6953,9 +7609,73 @@
       "tag": "ds-tooltip-data-viz",
       "name": "tooltip-data-viz",
       "title": "TooltipDataViz",
-      "summary": "Positioned value/label callout for chart hover interactions (bar, line point, …).\nDonut charts skip this — legend sync already surfaces the hovered slice.\nUnlike `ds-tooltip`, this doesn't bind to a slotted anchor element —\ncharts hover-highlight data that lives inside an SVG, so the chart itself computes\nthe anchor point (e.g. the cursor position while hovering) and passes it in as `x`/`y`.\n\nRenders `position: absolute` — place inside a `position: relative` chart wrapper,\nwith `x`/`y` as pixel coordinates within that wrapper. Defaults to sitting below-right\nof the anchor (matching cursor-following tooltips), flipping to whichever side/edge\nkeeps it on-screen.\n\nMount (or remount) when a hover session starts so `delay` applies once per hover;\nkeep the instance mounted while the cursor moves so tracking stays instant.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Chart-owned, non-interactive label and value callout positioned from pointer or focused-mark coordinates inside a visualization wrapper.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Chart-owned, non-interactive label and value callout positioned from pointer or focused-mark coordinates inside a visualization wrapper.",
+        "useWhen": [
+          "A chart needs immediate visual value feedback for a genuinely hovered or keyboard-focused mark.",
+          "The anchor lives inside SVG or chart coordinates rather than on a slotted HTML trigger.",
+          "The owning chart can mount the callout for one interaction session and update its coordinates while tracking."
+        ],
+        "avoidWhen": [
+          "A normal control or text trigger needs supplemental explanation; use Tooltip.",
+          "The content needs links, actions, focus, or touch-primary disclosure.",
+          "An externally synchronized highlight has no genuine local pointer or keyboard interaction.",
+          "The callout would be the only accessible source of an essential value."
+        ],
+        "alternatives": [
+          {
+            "when": "A slotted control or text trigger needs a conventional tooltip.",
+            "component": "component:ds-tooltip",
+            "reason": "Tooltip owns trigger semantics, focus behavior, and anchored overlay lifecycle."
+          },
+          {
+            "when": "Donut details should remain continuously visible beside the chart.",
+            "component": "component:ds-chart-legend",
+            "reason": "A visible legend avoids redundant transient slice callouts."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-chart-bar",
+          "component:ds-chart-line",
+          "component:ds-chart-donut"
+        ],
+        "accessibility": [
+          "The callout is presentation-only and never replaces the owning chart mark's accessible label or an adjacent data summary.",
+          "Keyboard-focused marks receive the same visual feedback as pointer-hovered marks.",
+          "The callout never receives focus or contains interactive descendants."
+        ],
+        "states": [
+          "The owning chart mounts the callout when a local interaction starts and unmounts it when that interaction ends.",
+          "Coordinate updates track within one mounted interaction session without restarting the show delay.",
+          "Placement flips horizontally or vertically when the rendered callout approaches a viewport edge.",
+          "Reduced motion preserves the final visible state without an opacity transition."
+        ],
+        "responsiveBehavior": [
+          "Render inside a positioned chart wrapper and pass coordinates relative to that wrapper.",
+          "Keep labels concise enough for the single-line callout; persistent or long explanations belong outside the chart."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "The owning chart computes coordinates and conditionally mounts the component; applications should not use it as a standalone overlay."
+          ],
+          "react": [
+            "Keep callout lifecycle and coordinates inside the chart wrapper rather than application-global tooltip state."
+          ],
+          "angular": [
+            "Keep callout lifecycle and coordinates inside the chart wrapper rather than application-global tooltip state."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook example",
+            "path": "src/wc/components/TooltipDataViz/TooltipDataViz.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "delay": {