agents-design-language

Agent design language

This document defines reusable Agent interface patterns in this module. Add patterns as the interface develops.

Scope

• Keep Agent-specific components and behavior in this module.
• Use Design System components and CSS variables.
• Do not add or change a global Design System primitive for an Agent-only need.
• Put all user-facing text in i18n.
• Test responsive layouts at 375 by 667 pixels and in light and dark themes.

Breadcrumbs

Show the project icon before the project name in Agent builder and session timeline breadcrumbs. Use the same icon as the owning project. Show the user icon for a personal project.

History entry points

Put `Version history` in the Agent actions menu. Put `View timeline` in the Publish dropdown. Each action opens its tab, including when the panel is already open. Keep history available for saved Agents during edits and with read-only access. Hide these entry points in embedded Agent artifacts.

Builder tabs

Show Build, Knowledge, Sessions, and Settings from the first visit to a new Agent. Let users switch tabs before they save or configure the Agent. Keep persistence tied to edits and actions that need a saved Agent. Keep optional tabs under their existing feature flags.

Configuration add actions

Show a leading `plus` icon beside empty-state configuration add labels. Use the ghost button variant for skills, channels, schedules, and capabilities. Keep the icon visible before hover so users can identify each action. Use the existing icon-only add button when the row contains items.

Narrow builder panels

Keep a chip and its adjacent add action inside the available row width. Truncate the chip text before the action moves outside the panel.

Show session details on separate lines when the session list is narrow. Keep the title, origin, date, token count, and actions visible without overlap.

Stack a setting label above its control when the row is narrow. Give the label the full row width. Give a wide control, such as a model picker, the full row width. Keep a short control at its natural width. Keep the control inside the row. The model menu uses the control width, so the menu stays inside the editor column.

Reduce the editor column side padding when the column is narrow.

Builder Assistant default

Open the Assistant on each visit to an unpublished Agent when the user can edit the Agent and Assistant setup is complete. Let users close it during the visit. Keep the panel state when the Agent is saved or published. For published or read-only Agents, use the saved panel preference. Apply these defaults in the control layout. Keep the experiment layouts unchanged.

Builder side panel widths

Start the Assistant and Preview panels at 30% of the builder container width. Limit this default to 320–720 pixels. Use 480 pixels before measurement. Keep saved Assistant widths and user resize choices. Double-click a resize handle to reset its panel to the current default. Reserve 480 pixels for the editor. When both panels are open, share the remaining width in proportion to each panel's requested extra width above 320 pixels. Do not save automatic layout adjustments as user resize choices.

Disable Test entry points while the Assistant works. Show the same working warning beside the Agent title, in the Triggers section, and in the task modal. Keep the action to close an open preview available. Restore Test availability when the Assistant finishes.

Chat-first builder

The Build/Test experiment variants use one chat area in the standalone Agents UI. Keep the full Assistant and its Agent artifacts unchanged. Users outside the experiments keep the current layout. Keep each chat mounted when the mode changes. Preserve each draft, session, and active response. Put the grouped Build/Test selector first in the composer toolbar. Use wrench and flask icons. Show a purple active state in both themes. Stop the discovery pulse after the first message. Disable the pulse for reduced motion.

In the wide variants, start chat at 65% and configuration at 35% of the workspace beside the sidebar. Apply this ratio only to the standalone Agents UI. Save manual resize choices as a ratio. Keep this preference separate from the saved Assistant dock width and the previous fixed configuration width. Keep the ratio when the window or sidebar changes size. Double-click the standalone divider to reset to 65/35. Reserve at least 360 pixels for configuration and 320 pixels for chat. When the ratio would break a minimum, the minimum wins. Do not cap configuration at a fixed maximum width. Below 680 pixels of available workspace, fill the viewport with one panel at a time, above the sidebar. Measure the original workspace to keep this layout stable when the sidebar is open. Close either chat to show the full-width configuration. Use Chat to reopen the selected mode. Keep both panels mounted. Keep the mode selector and composer actions inside the input at narrow widths. Show the same preview disclaimer below both composers, including empty chats. Use the same footer spacing.

Keep both composers at the same fixed height. Put the placeholder and prompt text at the top left. Show the attachment row only when it has content. Put attached agents and files above the text. Scroll long prompts and attachment lists inside the composer. Use a plus icon for the Test file picker, in the same position as the Build menu.

Keep chat width and test placement independent. The control layout keeps its existing docks. In toggle variants, always show the selector in the standalone builder. Test readiness does not control visibility. Disable Test when the Agent cannot run. Use the same validation tooltip as the Test button beside the Agent title to explain the setup issues. Show one readiness heading. Put missing instructions, model, and credential in a bulleted list under `Add:`. Put other blockers in a bulleted list under `Fix:`. Keep the selector visible during lat