refactor: simplify UI component patterns and polish styling

This commit overhauls several UI patterns across the codebase:
1.  Replace text-based action buttons with icon-only ShellIconButton across session, workbench, shell header and composer areas, add appropriate tooltips
2.  Restructure session card actions into a dropdown menu instead of inline delete button
3.  Add tooltips for timestamps, top bar metadata and message markers
4.  Clean up unused imports and types (remove FocusedThemeToken, DropdownMenuSeparator/Label)
5.  Fix runtime preview server config and add node modules symlinking for runtime template
6.  Refactor message card logic to use better role-based labeling with tooltips
7.  Add comprehensive CSS custom property theming for shell UI components
8.  Update DESIGN.md to document preferred primitive usage patterns

Author: Sayhi-bzb

apps/agent-html-app/DESIGN.md

@@ -60,6 +60,7 @@
 具体要求：
 
 - `Button`、`Input`、`Textarea`、`Tabs`、`Badge`、`Card`、`ScrollArea` 等交互 primitive 直接使用 shadcn 生成的组件。
+- `Tooltip`、`DropdownMenu`、`ContextMenu`、`Popover` 等收纳型 primitive 也优先使用 shadcn / Radix 入口，把低频操作和解释性内容收纳起来。
 - 不复制一份自制基础控件来替代 shadcn。
 - 需要变化时，优先通过 token、variant、组合方式、语义 wrapper 调整。
 - feature 层允许封装 `ShellActionButton`、`ShellPaneHeader` 这类语义组件，但底层 primitive 仍应来自 shadcn。
@@ -357,6 +358,7 @@ header 默认只包含：
 - 页面层不新增解释性 `description`、caption、help copy
 - 标题优先用名词或短动作
 - 状态优先用短标签
+- 冗余说明、低频动作、实现细节优先移入 `tooltip`、`dropdown menu`、`context menu`，不常驻上屏
 - 文案必须看起来像产品语言，而不是实现日志
 
 ### 7.2 不应作为主内容的信息

apps/agent-html-app/src/components/ui/dropdown-menu.tsx

@@ -7,8 +7,6 @@ const DropdownMenu = DropdownMenuPrimitive.Root
 const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger
 const DropdownMenuGroup = DropdownMenuPrimitive.Group
 const DropdownMenuPortal = DropdownMenuPrimitive.Portal
-const DropdownMenuSeparator = DropdownMenuPrimitive.Separator
-const DropdownMenuLabel = DropdownMenuPrimitive.Label
 
 function DropdownMenuContent({
   className,
@@ -98,7 +96,6 @@ export {
   DropdownMenuGroup,
   DropdownMenuItem,
   DropdownMenuLabel,
-  DropdownMenuSeparator,
   DropdownMenuShortcut,
   DropdownMenuTrigger,
 }

apps/agent-html-app/src/features/app-shell/components/top-bar.tsx

@@ -1,9 +1,17 @@
-import { FileCode2Icon } from "lucide-react"
+import {
+  FileCode2Icon,
+  MonitorIcon,
+  TriangleAlertIcon,
+} from "lucide-react"
 
 import {
   ShellStatusBadge,
-  ShellSectionLabel,
 } from "@/features/app-shell/components/shell-content"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
 import { isTauriRuntime } from "@/lib/tauri"
 import type { WorkbenchView } from "@/lib/types"
 
@@ -22,22 +30,47 @@ export function TopBar({
     <header className="app-shell-topbar">
       <div className="app-shell-topbar-row">
         <div className="app-shell-topbar-group">
-          <FileCode2Icon className="app-shell-inline-icon app-shell-brand-icon" />
-          <div className="app-shell-topbar-brand">
-            <span className="app-shell-topbar-copy">agent-html</span>
-            <span className="app-shell-panel-title">review studio</span>
-          </div>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <div className="app-shell-topbar-brand">
+                <FileCode2Icon className="app-shell-inline-icon app-shell-brand-icon" />
+                <span className="app-shell-topbar-copy">agent-html</span>
+              </div>
+            </TooltipTrigger>
+            <TooltipContent side="bottom">review studio</TooltipContent>
+          </Tooltip>
         </div>
         <div className="app-shell-topbar-center">
           <p className="app-shell-session-title">{sessionName}</p>
         </div>
         <div className="app-shell-status-group">
-          <ShellStatusBadge
-            label={isTauriRuntime() ? "desktop" : "local"}
-            variant="outline"
-          />
-          <ShellSectionLabel>{activeView}</ShellSectionLabel>
-          {hasError ? <ShellStatusBadge label="error" variant="destructive" /> : null}
+          <ShellStatusBadge label={activeView} variant="outline" />
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <span
+                aria-label={isTauriRuntime() ? "Desktop runtime" : "Local runtime"}
+                className="app-shell-topbar-meta-icon"
+              >
+                <MonitorIcon className="app-shell-inline-icon" />
+              </span>
+            </TooltipTrigger>
+            <TooltipContent side="bottom">
+              {isTauriRuntime() ? "desktop runtime" : "local runtime"}
+            </TooltipContent>
+          </Tooltip>
+          {hasError ? (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <span
+                  aria-label="Error"
+                  className="app-shell-topbar-meta-icon app-shell-topbar-meta-icon-error"
+                >
+                  <TriangleAlertIcon className="app-shell-inline-icon" />
+                </span>
+              </TooltipTrigger>
+              <TooltipContent side="bottom">error</TooltipContent>
+            </Tooltip>
+          ) : null}
         </div>
       </div>
     </header>

apps/agent-html-app/src/features/sessions/components/session-card.tsx

@@ -1,14 +1,26 @@
-import { Trash2Icon } from "lucide-react"
+import { EllipsisIcon, Trash2Icon } from "lucide-react"
 
 import { Button } from "@/components/ui/button"
 import {
-  ShellActionGroup,
-  ShellIconButton,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+import {
   ShellMetaRow,
   ShellSessionStatusBadge,
   ShellSplitRow,
 } from "@/features/app-shell/components/shell-content"
-import { formatSessionTimestampLabel } from "@/lib/time"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+import {
+  formatSessionTimestampLabel,
+  formatTimestampLabel,
+} from "@/lib/time"
 import type { SessionSummary } from "@/lib/types"
 import { cn } from "@/lib/utils"
 
@@ -27,6 +39,9 @@ export function SessionCard({
   onDelete,
   onOpen,
 }: SessionCardProps) {
+  const shortTimestamp = formatSessionTimestampLabel(session.updatedAt)
+  const fullTimestamp = formatTimestampLabel(session.updatedAt)
+
   return (
     <section
       className={cn(
@@ -56,22 +71,37 @@ export function SessionCard({
         </ShellSplitRow>
         <ShellMetaRow
           action={
-            <ShellActionGroup>
-              {!active ? (
-                <ShellIconButton
-                  ariaLabel="Delete session"
-                  className="app-shell-session-card-action"
-                  disabled={disabled}
-                  onClick={() => onDelete(session.id)}
-                  size="icon-xs"
-                  variant="ghost"
-                >
-                  <Trash2Icon data-icon="inline-start" />
-                </ShellIconButton>
-              ) : null}
-            </ShellActionGroup>
+            !active ? (
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                  <Button
+                    aria-label="Session actions"
+                    className="app-shell-session-card-action"
+                    disabled={disabled}
+                    size="icon-xs"
+                    type="button"
+                    variant="ghost"
+                  >
+                    <EllipsisIcon data-icon="inline-start" />
+                  </Button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="end">
+                  <DropdownMenuItem onClick={() => onDelete(session.id)}>
+                    <Trash2Icon />
+                    Delete
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            ) : null
+          }
+          copy={
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <span>{shortTimestamp}</span>
+              </TooltipTrigger>
+              <TooltipContent side="bottom">{fullTimestamp}</TooltipContent>
+            </Tooltip>
           }
-          copy={formatSessionTimestampLabel(session.updatedAt)}
         />
       </div>
     </section>

apps/agent-html-app/src/features/sessions/components/session-rail-header.tsx

@@ -40,6 +40,7 @@ export function SessionRailHeader({
           className="border-0"
           disabled={disabled}
           onClick={onCreateSession}
+          tooltip="New session"
         >
           <PlusIcon data-icon="inline-start" />
         </ShellIconButton>

apps/agent-html-app/src/features/sessions/components/session-rail.tsx

@@ -1,11 +1,9 @@
 import { useMemo, useState } from "react"
-import { Settings2Icon } from "lucide-react"
 
 import type { SessionSummary } from "@/lib/types"
 
 import {
   ShellEmptyCard,
-  ShellIconButton,
   ShellLoadingRow,
   ShellSectionLabel,
   ShellPaneScaffold,
@@ -104,15 +102,6 @@ export function SessionRail({
           {loading ? <ShellLoadingRow>Load</ShellLoadingRow> : null}
         </ShellScrollSurface>
       }
-      footer={
-        <ShellIconButton
-          ariaLabel="Session settings"
-          disabled={disabled}
-          variant="ghost"
-        >
-          <Settings2Icon data-icon="inline-start" />
-        </ShellIconButton>
-      }
     />
   )
 }

apps/agent-html-app/src/features/shell/components/message-card.tsx

@@ -1,9 +1,15 @@
+import { BotIcon, UserIcon } from "lucide-react"
+
 import type { AgentShellMessage } from "@/lib/types"
 
 import {
   ShellSectionLabel,
-  ShellStatusBadge,
 } from "@/features/app-shell/components/shell-content"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
 import { cn } from "@/lib/utils"
 import { MessageBody } from "./message-body"
 
@@ -14,23 +20,11 @@ function getMessageLines(message: AgentShellMessage): string[] {
     .filter(Boolean)
 }
 
-function getMessageLabel(message: AgentShellMessage): string {
-  if (message.role === "user") {
-    return "You"
-  }
-
-  if (message.proposalSnapshot) {
-    return "Proposal"
-  }
-
-  return "Review"
-}
-
 function getMessageTone(message: AgentShellMessage): "default" | "secondary" {
   return message.role === "user" ? "secondary" : "default"
 }
 
-function getMessageTitle(message: AgentShellMessage): string {
+function getMessageTitle(message: AgentShellMessage): string | undefined {
   if (message.proposalSnapshot) {
     return getMessageLines(message)[0] ?? "Proposal"
   }
@@ -39,7 +33,7 @@ function getMessageTitle(message: AgentShellMessage): string {
     return "Context"
   }
 
-  return "Note"
+  return undefined
 }
 
 function getMessageItems(message: AgentShellMessage): string[] {
@@ -64,6 +58,12 @@ type MessageCardProps = {
 
 export function MessageCard({ message }: MessageCardProps) {
   const proposal = Boolean(message.proposalSnapshot)
+  const title = getMessageTitle(message)
+  const genericMessage = !proposal && !title
+  const markerIcon = message.role === "user"
+    ? <UserIcon className="app-shell-inline-icon" />
+    : <BotIcon className="app-shell-inline-icon" />
+  const markerLabel = message.role === "user" ? "Your note" : "Review note"
 
   return (
     <section
@@ -76,14 +76,21 @@ export function MessageCard({ message }: MessageCardProps) {
             : "app-shell-message-card app-shell-message-card-agent",
       )}
     >
-      <div className="app-shell-split-row">
-        <p className="app-shell-message-heading">{getMessageTitle(message)}</p>
-        {proposal ? (
-          <ShellSectionLabel>Proposal</ShellSectionLabel>
-        ) : (
-          <ShellStatusBadge label={getMessageLabel(message)} variant="outline" />
-        )}
-      </div>
+      {!genericMessage ? (
+        <div className="app-shell-split-row">
+          <p className="app-shell-message-heading">{title}</p>
+          {proposal ? <ShellSectionLabel>Proposal</ShellSectionLabel> : null}
+        </div>
+      ) : (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <div aria-label={markerLabel} className="app-shell-message-marker">
+              {markerIcon}
+            </div>
+          </TooltipTrigger>
+          <TooltipContent side="right">{markerLabel}</TooltipContent>
+        </Tooltip>
+      )}
       <MessageBody
         items={getMessageItems(message)}
         text={getMessageText(message)}

apps/agent-html-app/src/features/shell/components/shell-composer.tsx

@@ -1,5 +1,7 @@
+import { SendHorizontalIcon } from "lucide-react"
+
 import {
-  ShellActionButton,
+  ShellIconButton,
   ShellStatusBadge,
 } from "@/features/app-shell/components/shell-content"
 import { ComposerField } from "./composer-field"
@@ -28,18 +30,20 @@ export function ShellComposer({
         <ComposerField
           disabled={interactionLocked}
           onChange={(event) => onDraftChange(event.target.value)}
-          placeholder="Note"
+          placeholder="Reply"
           value={draft}
         />
       </div>
-      <ShellActionButton
-        className="app-shell-plain-action app-shell-composer-send"
+      <ShellIconButton
+        ariaLabel="Send note"
+        className="app-shell-plain-icon app-shell-composer-send"
         disabled={!draft.trim() || interactionLocked}
         onClick={onSend}
+        tooltip="Send"
         variant="ghost"
       >
-        Send
-      </ShellActionButton>
+        <SendHorizontalIcon data-icon="inline-start" />
+      </ShellIconButton>
     </div>
   )
 }