第八篇：AI Agent 前端 UI 与动效开发指南 (AI Agent Frontend UI & Motion Guidelines)

/* Agent 编写组件时应使用的背景颜色映射 */
:root {
  --cds-surface-0: var(--cds-gray-20); /* #f9f9f7 侧边栏/画布底层 Canvas */
  --cds-surface-1: var(--cds-gray-10); /* #fcfcfb 页面主聊天画布背景 */
  --cds-surface-2: var(--cds-gray-0);  /* #ffffff 消息卡片表面 */
  --cds-surface-3: var(--cds-gray-0);  /* #ffffff 输入框容器/高层浮层 */
  --cds-surface-popover: var(--cds-gray-0); /* #ffffff 悬浮 Popover 表面 */
}

[data-mode="dark"], .dark {
  --cds-surface-0: var(--cds-gray-900); /* #0b0b0b 暗色侧边栏/底色 */
  --cds-surface-1: var(--cds-gray-850); /* #151515 暗色主聊天背景 */
  --cds-surface-2: var(--cds-gray-830); /* #1a1a19 暗色卡片表面 */
  --cds-surface-3: var(--cds-gray-800); /* #20201f 暗色输入框与高层浮层 */
  --cds-surface-popover: var(--cds-gray-750); /* #2c2c2a 悬浮气泡表面 */
}

--cds-text-primary:   #151515; /* 一级主要正文、标题 / [Dark]: #f5f5f5 */
--cds-text-secondary: #525252; /* 二级辅助文字、副标题 / [Dark]: #a3a3a3 */
--cds-text-muted:     #8a8a8a; /* 三级微弱文字、快捷键、占位符 / [Dark]: #666666 */

--cds-focus-shadow: inset 0 0 0 1px var(--cds-surface-1), 0 0 0 1.5px var(--cds-clay), 0 0 6px 1px rgba(217, 119, 87, 0.25);

graph TD
    Trigger["用户交互触发"]
    
    Trigger --> Type{"交互类型判断"}
    
    Type -->|"按钮点击 / Pill 切换 / Tab 移动"| Snappy["SPRING_SNAPPY<br/>stiffness: 600, damping: 30<br/>超调 +8.8%, 时延 0.22s"]
    Type -->|"开关切换 / Badge 入场 / 成功微反馈"| Bouncy["SPRING_BOUNCY<br/>stiffness: 380, damping: 18<br/>超调 +19.4%, 时延 0.58s"]
    Type -->|"对话框打开 / Thinking 展开 / 气泡进入"| Gentle["SPRING_GENTLE<br/>stiffness: 320, damping: 28<br/>超调 +1.8%, 时延 0.35s"]
    Type -->|"拖拽占位线碰撞 / 边缘吸附 / 抽屉关闭"| HeavySnap["SPRING_HEAVY_SNAP<br/>stiffness: 1200, damping: 80<br/>严格 0% 超调, 时延 0.14s"]

mask-image: linear-gradient(
  to bottom,
  transparent,
  #0000000d calc(var(--cds-scroll-fade-top) * .15),
  #00000026 calc(var(--cds-scroll-fade-top) * .3),
  #0000004d calc(var(--cds-scroll-fade-top) * .45),
  #00000080 calc(var(--cds-scroll-fade-top) * .6),
  #000000b3 calc(var(--cds-scroll-fade-top) * .75),
  #000000d9 calc(var(--cds-scroll-fade-top) * .87),
  #000 var(--cds-scroll-fade-top),
  #000 calc(100% - var(--cds-scroll-fade-bottom)),
  #000000d9 calc(100% - var(--cds-scroll-fade-bottom) * .87),
  #000000b3 calc(100% - var(--cds-scroll-fade-bottom) * .75),
  #00000080 calc(100% - var(--cds-scroll-fade-bottom) * .6),
  #0000004d calc(100% - var(--cds-scroll-fade-bottom) * .45),
  #00000026 calc(100% - var(--cds-scroll-fade-bottom) * .3),
  #0000000d calc(100% - var(--cds-scroll-fade-bottom) * .15),
  transparent
);

const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
  // 1. 标准合成标志位与 229 键码
  if (e.nativeEvent.isComposing || e.keyCode === 229) return;
  // 2. WebKit 500ms 延迟守卫拦截
  if (isWebKit && Math.abs(e.timeStamp - lastCompositionEndTime) < 500) return;

  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    submitMessage();
  }
};

const handleUserScroll = () => {
  lastUserScrollTimestamp.current = performance.now();
};

const shouldAutoScroll = () => {
  const isWithinBottomTolerance = scrollHeight - scrollTop - clientHeight <= 40;
  const isCooldownExpired = performance.now() - lastUserScrollTimestamp.current > 150;
  return isWithinBottomTolerance && isCooldownExpired;
};

code-examples/
├── CdsButton.tsx                    # 5 级尺寸 5 大变体标准按钮 (15 阶 linear 弹簧)
├── SegmentedControl.tsx             # 999px 全圆角滑动分段胶囊 (2px 轨道几何)
├── StatusIndicators.tsx             # 6px 状态指示灯与骨架屏扫光
├── ConfirmationDialog.tsx           # 16px 模态确认对话框 (双环弥散投影)
├── AttachmentCard.tsx               # 7.5rem 磁贴与行内附件芯片
├── ChatComposer.tsx                 # 20px 核心输入终端
├── ChatMessageBubbles.tsx           # 会话流双态气泡 (18px 圆角与 clamp 文本 stop)
├── ThinkingAccordion.tsx            # 思考过程状态机折叠组件 (Grid 0fr<->1fr)
├── RichComposerWithMentions.tsx     # 指令与提及富文本编辑器 (WebKit 500ms 守卫)
├── ModelSwitcherWithTokenGauge.tsx  # 模型切换与四色 Token 显存表
├── McpToolDecisionCard.tsx          # MCP 决策与授权卡片
├── ClaudeMotionPresets.ts           # 4 套物理弹簧预设
├── ReasoningAmbientGlow.tsx         # 陶土漫反射光效 (wl-glow & 1.1s epitaxy-sweep)
├── ScrollFadeContainer.tsx          # 原生 CSS Scroll-Driven 7 档非线性遮罩容器
├── ClaudeAudioPlayer.ts             # Web Audio 纯代码合成音效
├── LiveMicActivityBars.tsx          # 6 频段非线性麦克风波形柱 (0.7 Gamma)
├── MediaLightboxViewer.tsx          # 仿射变换光标锚点画廊 (75vw 跑道)
├── useClaudeSharedElementTransition.ts # View Transitions 共享元素变形 Hook
├── ArtifactsSplitPaneResizer.tsx    # 50/50 居中吸附双栏分割条 (4px 死区)
├── EpitaxyIframeBridge.tsx          # 沙箱隔离双向通信桥 (null-origin 隔离)
├── StreamingDiffViewer.tsx          # 等宽流式代码差异对比 (--diffs-* 变量)
├── CodeBlock.tsx                    # 12px 纯黑底色高亮代码块
├── createClaudeMainWindow.ts        # Electron 桌面窗口工厂 (WebContentsView 解耦)
├── ClaudeDesktopHeader.tsx          # macOS 74px 避让沉浸式顶栏
├── DraggableSessionList.tsx         # 拓扑重排与微倾斜投影
├── CoworkAgentCanvas.tsx            # 多 Agent 协同网格看板
├── useClaudeScrollPinning.ts        # 视口图钉防抢夺 Hook (150ms 冷却)
├── ContainerResponsiveBar.tsx       # 4 阶容器查询响应栏
├── useClaudeRovingFocus.ts          # W3C WAI-ARIA 焦点漫游 Hook
└── useRateLimitBackoff.ts           # 指数退避与全抖动重试 (3 次上限保护)