{
"schemaVersion": "1.0.0",
"package": "@ds-mo/ui",
"packageVersion": "14.17.0",
"kind": "patterns",
"entries": [
{
"id": "pattern:agent-chat",
"status": "experimental",
"summary": "Compose provider-neutral agent turns from serializable or slotted response content, normalized tool lifecycle, pending human input, inline sources, and reader-respecting transcript movement.",
"useWhen": [
"A conversation presents rich agent output and may pause for structured participant input before the agent continues."
],
"avoidWhen": [
"The channel is person-to-person or the design-system layer would be expected to own models, provider schemas, transport, persistence, tool execution, approval consequences, or private reasoning."
],
"components": [
{
"component": "component:ds-message-scroller",
"role": "Positions new turn anchors, preserves reader-controlled live-edge behavior, and measures pending interaction with composer clearance.",
"required": true
},
{
"component": "component:ds-message",
"role": "Renders participant turns with channel-neutral semantics and marks application-owned outgoing turn anchors.",
"required": true
},
{
"component": "component:ds-message-bubble",
"role": "Renders user-sent prompts with the shared message baseline.",
"required": true
},
{
"component": "component:ds-agent-response",
"role": "Renders ordered normalized parts or an application-composed ordered response body.",
"required": true
},
{
"component": "component:ds-agent-tool-call",
"role": "Presents a normalized provider-neutral tool lifecycle and optional custom result or diagnostic detail.",
"required": false
},
{
"component": "component:ds-agent-questionnaire",
"role": "Collects a temporary local answer draft above the composer and renders a quiet answered history record.",
"required": false
},
{
"component": "component:ds-agent-source-list",
"role": "Presents stable deduplicated sources inline after discovery is complete.",
"required": false
},
{
"component": "component:ds-message-actions",
"role": "Provides completed-response Copy and controlled feedback without owning response data or consequences.",
"required": false
},
{
"component": "component:ds-message-composer",
"role": "Emits participant submission and stop intent while keeping visible recoverable submission errors adjacent to the draft.",
"required": true
}
],
"stateOwnership": [
"The application normalizes every provider-specific tool and human-input state before rendering, and owns transport, immutable response parts, stop, retry, persistence, generated titles, permissions, and consequences.",
"Pending questionnaires render through the scroller interaction surface; the questionnaire owns only its current step and unsaved draft, while the application submits answers, resumes the agent, preserves failures, and replaces a successful interaction with an answered response record.",
"Tool calls display lifecycle only. Custom summary, result, and detail content must remain user-safe; execution, approval, retry, and authorization stay application-owned.",
"Choose response parts when ordered content must be serializable and registry-friendly. Choose composed mode when application-specific components must interleave with CompoMo primitives; the application owns that slotted content and its serialization.",
"Applications append stable deduplicated sources once retrieval settles. Active source discovery is an activity or tool state rather than a changing source list.",
"Applications mark only outgoing prompts that begin new turns as turn anchors. Saved transcript entry points may independently choose the last stored anchor.",
"Composer error actions are application-owned. The component presents failure above the editable box as one attached, measured support unit, and recovery never discards the participant draft.",
"Prompt suggestions and model selection are optional product composition. Suggestion selection normally fills and focuses the draft; model selection remains an application-owned tool-region control.",
"Markdown parsing and safe node creation belong to the renderer; the renderer-neutral public prose stylesheet owns semantic-tree styling and text measure without owning response ordering or streaming state.",
"TokoMo owns the semantic interface and code font-family tokens, CompoMo assigns text or diagnostic-code intent, and the application loads Inter and Fira Code assets once at its root; agent components never fetch font assets.",
"Agent activity is concise user-safe progress and never reveals private model reasoning or chain-of-thought."
],
"accessibility": [
"Tool lifecycle, questionnaire progress and validation, composer failure, and streaming state remain meaningful as text without relying on motion or color.",
"Applications move focus into a pending questionnaire only when context makes that shift appropriate; the component never steals focus on mount.",
"Source links use descriptive external-link names, derived hostnames, and noninteractive rendering for malformed or unsafe schemes.",
"Reader wheel, touch, keyboard, selection, and jump actions release live-edge following until Scroll to latest explicitly restores it."
],
"responsiveBehavior": [
"Let structured response content use the available lane while direct prose uses its readable measure, code and tables retain local overflow, questionnaire actions stack on narrow screens, and the combined interaction and composer stack remains fully measured."
],
"implementations": {
"customElements": {
"status": "verified",
"recipes": [
{
"id": "pending-questionnaire",
"title": "Pending questionnaire above a conversation composer",
"summary": "Mark the outgoing turn, normalize the paused tool state, place temporary human input in the interaction surface, and keep submission transport in application code.",
"files": [
{
"path": "agent-conversation.html",
"language": "html",
"content": "\n \n Prepare the maintenance follow-up.\n \n \n \n \n \n \n
\n \n \n
\n"
},
{
"path": "agent-conversation.ts",
"language": "typescript",
"content": "const questionnaire = document.querySelector('ds-agent-questionnaire')!;\nquestionnaire.questions = [{\n id: 'priority',\n type: 'single',\n question: 'Which issue should be first?',\n required: true,\n choices: [\n { value: 'battery', label: 'Repeated battery failures' },\n { value: 'tires', label: 'Overdue tire inspections' },\n ],\n}];\nquestionnaire.addEventListener('dsAnswer', async event => {\n questionnaire.status = 'submitting';\n try {\n await submitAgentAnswers(event.detail);\n questionnaire.status = 'answered';\n } catch {\n questionnaire.status = 'error';\n questionnaire.errorMessage = 'Your answers could not be sent. Try again.';\n }\n});\n\ndeclare function submitAgentAnswers(detail: { requestId: string; answers: unknown[] }): Promise;"
}
],
"notes": [
"On successful transport, remove the pending interaction and append an answered questionnaire response part to durable history rather than leaving the interactive surface in place."
]
}
],
"references": [
"src/wc/components/MessageScroller/AgentChatReview.stories.ts",
"src/wc/components/MessageScroller/MessageScroller.stories.ts",
"src/docs/AgentConversations.mdx"
]
},
"react": {
"status": "planned",
"references": [
"docs/framework-integration.md"
]
},
"vue": {
"status": "planned",
"references": [
"docs/framework-integration.md"
]
},
"angular": {
"status": "planned",
"references": [
"docs/framework-integration.md"
]
}
},
"references": [
"agent/patterns/conversation/pattern.agent.json",
"src/docs/AgentConversations.mdx",
"src/wc/components/MessageScroller/AgentChatReview.stories.ts",
"src/wc/components/AgentResponse/AgentResponse.tsx"
]
},
{
"id": "pattern:application-shell",
"status": "stable",
"summary": "Standard authenticated application architecture: one managed ShellApp receives router-owned navigation and page data plus product-owned tool data and persistent slotted content.",
"useWhen": [
"Building a standard authenticated application or workspace with CompoMo.",
"Navigation, page chrome, global tools, and routed content must adapt across desktop, tablet, and mobile without parallel implementations.",
"Tool owners and routed content must preserve element identity while their responsive presentation changes."
],
"avoidWhen": [
"Building authentication, onboarding, public, marketing, print, error, or intentionally focused full-screen experiences.",
"The content is already rendered inside a ShellApp.",
"A specialized product has a verified reason to own every chrome component through composition=\"slotted\"."
],
"components": [
{
"component": "component:ds-shell-app",
"role": "Standard managed owner of responsive application chrome, global-surface state, focus restoration, and stable application content slots.",
"required": true
},
{
"component": "component:ds-panel-nav",
"role": "Managed desktop and tablet primary-navigation presentation; remains public for advanced slotted shells.",
"required": false
},
{
"component": "component:ds-bar-nav",
"role": "Managed desktop and tablet route-section presentation; remains public for advanced slotted shells.",
"required": false
},
{
"component": "component:ds-shell-tools",
"role": "Managed responsive adapter that presents persistent product-owned tool views through PanelTools or the mobile stage.",
"required": false
},
{
"component": "component:ds-shell-page",
"role": "Managed routed-page boundary with desktop BarTitle and mobile MobileHeader presentations.",
"required": false
},
{
"component": "component:ds-mobile-sheet-nav",
"role": "Managed mobile browser for Dashboard and Settings destinations.",
"required": false
},
{
"component": "component:ds-mobile-bar-nav",
"role": "Managed persistent mobile destinations for Menu, current area, Search, Inbox, Messages, Agents, and Help.",
"required": false
},
{
"component": "component:ds-banner",
"role": "Optional application-owned global message placed in the single shell banner lane.",
"required": false
}
],
"stateOwnership": [
"Lab or the consuming application supplies navigation, pageChrome, and tools objects to managed ShellApp.",
"The application router owns authorization, current URLs, history, route changes, and the routed content placed in ShellApp's default slot.",
"ShellApp emits stable navigation and page intent events; it never mutates router history.",
"ShellApp owns responsive mode, PanelNav presentation, tool open state, active tool, mobile Inbox grouping, Menu state, fullscreen presentation, focus restoration, and breakpoint state preservation.",
"Tool products and routed content are instantiated once by the application in named tool-view and default slots; ShellApp changes presentation without recreating those owners.",
"The application owns account menus, tool product data, page actions, and the consequences of every emitted intent event.",
"The application owns viewport and theme-color metadata, the dynamic-viewport framework root, and containing document overscroll so body never becomes a second application scroller; ShellApp fills that owner and keeps its existing internal scrollers.",
"The application resolves competing global messages to one Banner and owns its actions, controlled open state, orientation for the available shell capacity, dismissal persistence, and removal after exit motion.",
"Use composition=\"slotted\" only when a team intentionally needs to assemble the public lower-level chrome components itself."
],
"accessibility": [
"Render exactly one managed ShellApp and one active routed main landmark.",
"Provide visible labels and accessible names in navigation, pageChrome, and tool definitions before passing them to ShellApp.",
"Handle ShellApp intent events without replacing focusable owners during responsive or fullscreen transitions.",
"Keep the canonical Search and Help tools available and preserve Inbox unread state when Stacks and Activity are grouped on mobile; Messages remains directly reachable.",
"Do not override browser keyboard chords when enabling shell shortcuts."
],
"responsiveBehavior": [
"ShellApp automatically resolves desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
"Desktop and tablet use PanelNav, BarNav, PanelTools through ShellTools, and ShellPage chrome.",
"Mobile uses MobileSheetNav, MobileBarNav, MobileHeader, ShellTools mobile presentation, and the same routed content owner. MobileBarNav paints its primary surface through the bottom safe-area inset so light browser chrome and application chrome meet without a secondary-surface seam.",
"Below 768px the application root owns a 100dvh fixed stage with a 100vh fallback while ShellApp continues to fill its owner with height 100%; JavaScript viewport measurement synchronizes only the chrome wash and does not own layout height.",
"With viewport-fit=cover, ShellApp consumes the shared top safe-area inset once and MobileBarNav consumes the persistent bottom inset; nested routed, tool, sheet, and consumer headers do not duplicate either inset.",
"An optional Banner spans the complete application above desktop navigation, workspace, tools, and mobile global surfaces while remaining below the operating-system top safe area.",
"Switching breakpoints changes presentation and inert state without recreating route or tool elements.",
"Messages uses its own mobile destination; Stacks and Activity use explicit mobile Inbox grouping metadata."
],
"implementations": {
"customElements": {
"status": "verified",
"recipes": [
{
"id": "managed-shell",
"title": "Managed application shell",
"summary": "Supply typed data and persistent application-owned content to one ShellApp.",
"files": [
{
"path": "app-shell.html",
"language": "html",
"content": "\n \n \n \n \n \n \n \n"
},
{
"path": "app-shell.ts",
"language": "typescript",
"content": "import '@ds-mo/ui/components/ds-shell-app.js'\nimport { PANEL_TOOLS_DEFAULT_ITEMS } from '@ds-mo/ui/shell'\nimport type { ShellNavigationConfig, ShellPageChromeConfig, ShellToolsConfig } from '@ds-mo/ui/shell'\n\nconst shell = document.querySelector('#shell')!\nconst navigation: ShellNavigationConfig = {\n groups: [{ items: [{ id: 'overview', icon: 'Home', label: 'Overview', href: '/dashboard/overview' }] }],\n dashboardGroups: [{ items: [{ id: 'overview', icon: 'Home', label: 'Overview', href: '/dashboard/overview' }] }],\n currentUrl: location.pathname,\n browseContext: 'dashboard',\n routerMode: 'event',\n userName: 'User Name',\n userInitial: 'U',\n}\nconst pageChrome: ShellPageChromeConfig = {\n heading: 'Overview',\n tabs: [{ id: 'overview', label: 'Overview', href: '/dashboard/overview' }],\n value: 'overview',\n currentUrl: location.pathname,\n}\nconst tools: ShellToolsConfig = { items: PANEL_TOOLS_DEFAULT_ITEMS }\nshell.navigation = navigation\nshell.pageChrome = pageChrome\nshell.tools = tools\nshell.addEventListener('dsNavSelect', event => appRouter.navigate(event.detail))\nshell.addEventListener('dsTabChange', event => appRouter.navigate(event.detail))"
}
],
"notes": [
"Update navigation and pageChrome together after router navigation.",
"Keep every tool owner and the router-owned page mounted in its slot."
]
}
],
"references": [
"src/wc/components/ShellApp/ShellApp.stories.ts",
"docs/framework-integration.md"
]
},
"react": {
"status": "verified",
"recipes": [
{
"id": "managed-shell",
"title": "Managed React application shell",
"summary": "Use the generated ShellApp wrapper with memoized router-owned configuration and stable children.",
"files": [
{
"path": "AppShell.tsx",
"language": "tsx",
"content": "import { useMemo } from 'react'\nimport { DsShellApp } from '@ds-mo/ui/react'\nimport { PANEL_TOOLS_DEFAULT_ITEMS } from '@ds-mo/ui/shell'\nimport type { ShellNavigationConfig, ShellPageChromeConfig } from '@ds-mo/ui/shell'\n\nexport function AppShell({ route, navigate, children }) {\n const navigation = useMemo(() => ({ groups: route.groups, dashboardGroups: route.dashboardGroups, settingsGroups: route.settingsGroups, currentUrl: route.url, browseContext: route.context, routerMode: 'event', userName: route.user.name, userInitial: route.user.initial }), [route])\n const pageChrome = useMemo(() => ({ heading: route.heading, tabs: route.sections, value: route.section, currentUrl: route.url }), [route])\n return navigate(event.detail)} onDsTabChange={event => navigate(event.detail)}>\n \n \n \n \n {children}\n \n}"
}
],
"notes": [
"Memoize structured configuration so unrelated product renders do not produce artificial shell input changes.",
"Do not conditionally recreate routed or tool children when responsive mode changes."
]
}
],
"references": [
"src/wc/components/ShellApp/ShellApp.mdx",
"docs/framework-integration.md"
]
},
"vue": {
"status": "planned",
"references": [
"docs/framework-integration.md"
]
},
"angular": {
"status": "verified",
"recipes": [
{
"id": "managed-shell",
"title": "Managed Angular application shell",
"summary": "Bind router-derived object properties to the generated standalone ShellApp adapter.",
"files": [
{
"path": "app-shell.component.html",
"language": "html",
"content": "\n \n \n \n \n \n"
},
{
"path": "app-shell.component.ts",
"language": "typescript",
"content": "import { Component } from '@angular/core'\nimport { Router, RouterOutlet } from '@angular/router'\nimport { DsShellApp } from '@ds-mo/ui/angular/ds-shell-app'\nimport { PANEL_TOOLS_DEFAULT_ITEMS } from '@ds-mo/ui/shell'\nimport type { ShellNavigationConfig, ShellPageChromeConfig, ShellToolsConfig } from '@ds-mo/ui/shell'\n\n@Component({ selector: 'app-shell', standalone: true, imports: [DsShellApp, RouterOutlet], templateUrl: './app-shell.component.html' })\nexport class AppShellComponent {\n navigation: ShellNavigationConfig = { groups: [], dashboardGroups: [], settingsGroups: [], routerMode: 'event' }\n pageChrome: ShellPageChromeConfig = { heading: '' }\n tools: ShellToolsConfig = { items: PANEL_TOOLS_DEFAULT_ITEMS }\n constructor(private router: Router) {}\n navigate(target: string) { void this.router.navigateByUrl(target) }\n}"
}
],
"notes": [
"Resolve and replace navigation and pageChrome on completed router navigation.",
"The router outlet and tool components remain application-owned slots."
]
}
],
"references": [
"scripts/verify-package-imports.mjs",
"docs/framework-integration.md"
]
}
},
"references": [
"src/wc/components/ShellApp/ShellApp.mdx",
"docs/framework-integration.md",
"docs/migrations/v13.md"
]
},
{
"id": "pattern:conversation",
"status": "experimental",
"summary": "Compose channel-neutral history, transcript, message surfaces, attachments, and composer behavior for reusable conversations.",
"useWhen": [
"A product needs threaded conversation UX that may serve agent or person-to-person channels."
],
"avoidWhen": [
"The experience is a static activity feed or form without conversational turns."
],
"components": [
{
"component": "component:ds-conversation-list",
"role": "Owns history scrolling, empty layout, and floating action placement.",
"required": true
},
{
"component": "component:ds-panel-tool-search",
"role": "Collects a product-owned conversation history search query when the conversation is presented as a PanelTools product.",
"required": false
},
{
"component": "component:ds-message-scroller",
"role": "Owns transcript position and live-edge following.",
"required": true
},
{
"component": "component:ds-message",
"role": "Owns each turn's direction, grouping, and metadata.",
"required": true
},
{
"component": "component:ds-message-bubble",
"role": "Owns plain user-sent and received person-to-person surfaces and their body-medium default independently of row semantics.",
"required": true
},
{
"component": "component:ds-message-actions",
"role": "Provides optional message Copy and controlled response-feedback actions in the Message metadata region.",
"required": false
},
{
"component": "component:ds-typing-indicator",
"role": "Presents transient participant typing status without representing it as persisted message content.",
"required": false
},
{
"component": "component:ds-message-composer",
"role": "Emits draft, submit, and stop intent without transport ownership.",
"required": true
},
{
"component": "component:ds-attachment-list",
"role": "Displays existing attachment metadata when present.",
"required": false
}
],
"stateOwnership": [
"The application owns conversations, messages, selection, drafts, persistence, transport, unread policy, and any history search query or matching policy. ConversationListItem presents every positive unreadCount as one dot aligned with the title row; unread titles are emphasized and primary while read titles use regular weight and secondary foreground.",
"The application owns contextual row-menu commands such as pin, rename, members, and delete; ConversationListItem supplies the sibling actions slot and hover/focus/touch presentation.",
"When history search is present, distinguish an empty history from a populated history with no matching conversations.",
"Plain user-sent and received person-to-person copy uses MessageBubble's body-medium regular default; user bubbles use secondary foreground, and the application must not promote ordinary conversation turns to body-large.",
"TypingIndicator owns transient participant typing status and is composed directly in an incoming Message; it is never approximated with a MessageBubble variant.",
"MessageActions owns browser Copy behavior and controlled feedback intent. The application supplies copyable content and owns feedback persistence, submission, permissions, analytics, and consequences.",
"MessageScroller owns reader-relative transcript position and follow behavior. Compose MessageComposer in its overlay slot with 8px padding on every side so transcript content moves behind the surface while measured bottom clearance keeps the latest turn readable.",
"MessageComposer emits intent while the application controls its value and status. Its submit action defaults to brand for agent and person-to-person channels; select another submitIntent only for a different semantic consequence, never merely to identify AI content."
],
"accessibility": [
"Give history and transcript regions distinct localized names.",
"Preserve message author, order, time, status, and delivery meaning in text.",
"When metadata actions use hover visibility, fade the complete reserved metadata row, preserve keyboard access, and keep the row visible for touch input.",
"Do not force the reader back to the live edge after deliberate transcript interaction."
],
"responsiveBehavior": [
"Let the containing product select drawer or full-width layout while keeping transcript measure readable and rich content horizontally scrollable.",
"When history and transcript are simultaneously visible, establish one shared master-detail layout contract for pane width, divider, transcript measure, composer containment, and empty-region placement; do not independently recreate that geometry for each conversation channel."
],
"implementations": {
"customElements": {
"status": "planned",
"references": [
"src/wc/components/MessageScroller/MessageScroller.stories.ts"
]
},
"react": {
"status": "planned",
"references": [
"docs/framework-integration.md"
]
},
"vue": {
"status": "planned",
"references": [
"docs/framework-integration.md"
]
},
"angular": {
"status": "planned",
"references": [
"docs/framework-integration.md"
]
}
},
"references": [
"src/wc/components/ConversationList/ConversationList.stories.ts",
"src/wc/components/MessageScroller/MessageScroller.stories.ts",
"docs/layout-recipe-foundation.md"
]
},
{
"id": "pattern:menu-trigger",
"status": "stable",
"summary": "Connect a button trigger to an anchored Menu for a compact command or view-selection popup without application-authored positioning.",
"useWhen": [
"A button should reveal a short contextual collection of commands.",
"A compact button should show the current view or mode and let the user choose another one from a menu.",
"A row, card, or toolbar needs an overflow or more-options menu."
],
"avoidWhen": [
"The choice is a submitted form value with a field label or validation; use Select.",
"The available local views can remain visible; use TabGroup.",
"The choices are primary or secondary application destinations; use the matching navigation component.",
"The popup contains substantial content, confirmation, or a form; use Modal."
],
"components": [
{
"component": "component:ds-button-unfilled",
"role": "Provides the visible trigger, popup relationship attributes, and focus target. Carries both shapes, and is the only component that carries the icon-only overflow role.",
"required": true
},
{
"component": "component:ds-menu",
"role": "Owns anchored placement, menu semantics, keyboard navigation, viewport clamping, selection, and close behavior.",
"required": true
},
{
"component": "component:ds-button-filled",
"role": "Substitutes for the trigger when the menu belongs to the single primary action in a local decision area, using the label or icon-label shape only.",
"required": false
}
],
"stateOwnership": [
"The application owns the selected command or view value and derives the trigger label and each item's isSelected state from it.",
"The application synchronizes one open boolean to the trigger's expanded prop and Menu.open.",
"An open popup is a transient pressed state, not a selected one. The trigger holds only its pressed wash for the popup's rendered lifecycle from expanded alone, without changing foreground, so never also set isActive to represent an open menu.",
"Menu owns popup placement and keyboard navigation; the application never calculates popup coordinates or applies positional CSS.",
"On dsSelect from a command or single-selection row, update the selected value, close the Menu, and restore focus to the trigger.",
"Switch rows and reorderable rows report dsSelect or dsReorder without closing; replace the items array from those events.",
"On dsClose, synchronize the application open state to false."
],
"accessibility": [
"A button either has a menu or is a menu, and the trigger's variant selects between the two shapes.",
"Has a menu: a label or icon-label action that opens a menu. Set hasMenu, which implies aria-haspopup of menu and renders the trailing chevron that communicates the popup. Both button primitives support this shape.",
"Is a menu: an icon-only control. Set hasMenu, which adds no chevron, so the glyph must convey the menu alone. Use Ellipses for generic more-options or overflow. Use a specific icon when the menu has a named purpose, such as Table for Customize table. Only ButtonUnfilled carries this shape, because the role is chrome rather than a primary action.",
"Set controls to the Menu id and expanded from the same open state passed to Menu.",
"Give an icon-only trigger an accessible name that states the role, such as More options or Customize table, because no visible label or chevron carries it.",
"Use haspopup directly instead of hasMenu for a non-menu popup such as a listbox or dialog; those cases get no chevron.",
"Give Menu a concise menuLabel describing the available commands or views.",
"Set Menu.initialFocusVisible only when the trigger MouseEvent detail is zero, indicating keyboard activation.",
"Keep visible selected styling synchronized with the application's selected value; Menu exposes the selected command through aria-current.",
"Return focus to the trigger after selection; Menu already restores it for Escape and outside dismissal."
],
"responsiveBehavior": [
"Keep Menu's default choice-cell anchor alignment unless deliberate custom frame geometry is required.",
"Let Menu clamp to the viewport and avoid application-authored fixed or absolute positioning.",
"Use a concise trigger label that can fit the owning layout without hiding the selected meaning."
],
"implementations": {
"customElements": {
"status": "verified",
"recipes": [
{
"id": "selected-view-menu",
"title": "Selected view menu",
"summary": "A ButtonUnfilled displays the active view and opens a Menu whose selected row updates that view.",
"files": [
{
"path": "view-menu.html",
"language": "html",
"content": "