# Agent Guidelines for Claude Design System (CDS) Welcome, AI Agent! This repository ([`open-claude-ui`](https://github.com/Caho1/open-claude-ui)) contains the production-grade, clean-room reverse-engineered implementation of Anthropic's **Claude Design System (CDS)** and its interaction physics. When assisting users with building, modifying, or reviewing frontend components, interfaces, or animations based on this repository, you **MUST** strictly follow the design tokens, physics laws, component guidelines, and quality gates detailed below. --- ## 🧭 Quick Reference: Core Philosophy & Rules 1. **Editorial Warmth, Not Cyberpunk**: - Main brand accent is warm **Clay / Terracotta (`#d97757` in light mode, `#cc6b49` in dark mode)**. - Surfaces use subtle warm grays (`#fcfcfb`, `#f7f7f5`, `#1b1b19`), never stark pure black `#000` (except code blocks `#0d0d0c`) or harsh pure white `#fff`. - Never use neon blues, magenta, or cold purple gradients. 2. **Low-Contrast Surface Layering**: - Differentiate layers using micro-luminance contrast (`Surface 0 ~ 3`) and hairline borders (`border-subtle`: `rgba(0,0,0,0.06)` / `rgba(255,255,255,0.08)`). - Single-stroke border discipline: inside bordered containers (such as cards or the chat composer), secondary buttons and chips must NOT have redundant borders (`border-none`). 3. **Organic Motion Physics**: - Never use generic `linear` or exaggerated bouncy CSS transitions. - Use the 4 calibrated Framer Motion spring presets from [`code-examples/ClaudeMotionPresets.ts`](code-examples/ClaudeMotionPresets.ts). 4. **Pure Code & Zero Copyright Violations**: - Zero proprietary binary fonts (`.otf`/`.ttf`) or audio files (`.mp3`/`.wav`). - Use the calibrated font stacks and procedural Web Audio API oscillator synthesis. **v5.11492.5 实测**:CDS 语义层把 `--cds-font-sans` 覆盖为 `var(--font-anthropic-sans, …)`,即 Anthropic Sans 优先、系统字体兜底;`--cds-font-voice` 为 Anthropic Serif 优先。品牌物料另有一套(`'Anthropic Sans', system-ui, …` + 七档字号),见 `docs/v5.11492.5/09` §9.2–9.3。 5. **Strict Edge-Case Guards**: - Always guard chat/composer inputs against CJK IME composition accidents (`!(e.nativeEvent.isComposing || e.keyCode === 229)`). - Latch scroll pinning with a 150ms cooldown timestamp to prevent LLM streaming from hijacking manual user scrolling. 6. **Version-Named Documentation Volumes**: - Every Claude Desktop version gets its own `docs/v/` volume — never a date-, topic- or workflow-named directory. See §7. --- ## 🎨 1. Design Tokens & Styling Architecture All tokens are defined in [`code-examples/cds-theme.css`](code-examples/cds-theme.css) and exposed through Tailwind classes via [`code-examples/tailwind.config.js`](code-examples/tailwind.config.js). ### Surface & Background Tokens | Token | Light Mode Value | Dark Mode Value | Usage | | :--- | :--- | :--- | :--- | | `--cds-surface-0` | `#f9f9f7` | `#0b0b0b` | Base application background, page canvas (alias: `--cds-bg-surface-0`, `--cds-bg-primary`) | | `--cds-surface-1` | `#fcfcfb` | `#151515` | Sidebar panels, secondary cards (alias: `--cds-bg-surface-1`, `--cds-bg-secondary`) | | `--cds-surface-2` | `#ffffff` | `#1a1a19` | Input bars, dialog backdrops, floating popovers (alias: `--cds-bg-surface-2`, `--cds-bg-surface`) | | `--cds-surface-3` | `#ffffff` | `#20201f` | Active states, hover fills, elevated tags (alias: `--cds-bg-surface-3`, `--cds-bg-surface-elevated`) | | `--cds-surface-popover` | `#ffffff` | `#262624` | Floating popovers, dropdown menus | | `--cds-bg-input` | `var(--cds-surface-3)` | `var(--cds-surface-3)` | Text fields, chat input background | ### Text & Border Tokens | Token | Light Mode Value | Dark Mode Value | Usage | | :--- | :--- | :--- | :--- | | `--cds-text-primary` | `var(--cds-neutral-900)` → `#0b0b0b` | `#f0efec` (gray-50) | Headings, primary body text, active labels (v3 运行时实证) | | `--cds-text-secondary` | `var(--cds-neutral-600)` → `#52514e` | `#c3c2b7` (gray-200) | Timestamps, subtitles, secondary actions (v3) | | `--cds-text-muted` | `var(--cds-neutral-400)` → `#898781` | `#898781` (双模同值) | Placeholders, disabled text, hotkey hints (alias: `--cds-text-tertiary`) (v3) | | `--cds-text-accent` | `var(--cds-role-accent-600)` → `#184f95` | `#6da7ec` | Accent role is **blue**, not clay (v3 运行时实证) | | `--cds-border` | `var(--cds-alpha-2)` | `var(--cds-alpha-2)` | Dividers, subtle list borders (alias: `--cds-border-subtle`, `--cds-border-card`) | | `--cds-border-strong` | `var(--cds-alpha-3)` | `var(--cds-alpha-3)` | Emphasized component borders | | `--cds-border-subtle` | `var(--cds-alpha-2)` | `var(--cds-alpha-2)` | Fine hairline dividers | | `--cds-border-accent` | `var(--cds-clay)` | `var(--cds-clay)` | Focus and active borders | ### Skeleton & Motion Tokens | Token | Light Mode Value | Dark Mode Value | Usage | | :--- | :--- | :--- | :--- | | `--cds-skel-i` | `0` | `0` | Cascading index for skeleton wave delay (`calc(var(--cds-skel-i, 0) * 90ms)`) | | `--cds-skeleton-base` | `var(--cds-alpha-1)` → `hsl(from neutral-900 / 5%)` | `hsl(from neutral-900 / 7.5%)` (白) | Base skeleton placeholder container surface (v3 运行时实证:base 与 sheen 同值) | | `--cds-skeleton-sheen` | `var(--cds-alpha-1)`(同 base) | 同 base(白 7.5%) | 105° linear sweep band highlight (2s linear) | ### v5 Token Contract (5.11492.5 实测) 4.x 的令牌是约定,5.x 是**带版本号的契约**。新代码必须遵守以下四条: 1. **声明 API 版本**:根样式表首行写 `--cds-theme-api: 1`。 2. **四层结构**:原始阶(9 色相 × 35 级)→ 角色层(`--cds-role-accent-*` / `-danger-*` / `-success-*` / `-warning-*` / `-pro-*`)→ 语义层(`--cds-surface-*` / `--cds-text-*` / `--cds-fill-*` / `--cds-border`)→ 组件层。跨层引用只能向下,不得反向。 3. **反相别名**:正文用 `--cds-neutral-*`(明暗自动翻转),透明度用 `--cds-alpha-*`(`hsl(from var(--cds-neutral-900) …)`),暗色只覆盖颜色层,不重建几何。 4. **作用域开关**:`data-mode`(light/dark/system)、`data-density`(comfortable…)、`data-size`(xs/sm/lg,需 `--*--xs` 族支撑)、`data-step`(1–5)、`data-font`、`data-window-active`(false 时角色层整体降灰)。组件身份用 `data-cds="Name"` 暴露(5.11492.5 共 48 个)。 > 卷内权威清单:[`docs/v5.11492.5/02-CDS设计令牌总谱.md`](docs/v5.11492.5/02-CDS设计令牌总谱.md)、[`03-作用域与组件属性契约.md`](docs/v5.11492.5/03-作用域与组件属性契约.md),以及**官方规范原文摘录** [`11-CDS官方规范文档.md`](docs/v5.11492.5/11-CDS官方规范文档.md)。 > > **官方六层模型**(优先于任何反推):原始阶 `--{hue}-{stop}` → 主题别名 `--neutral-*` / `--alpha-*` → 高度 `--surface-{0..3}` → 用途 `--text-*` / `--fill-*` / `--bg-*` / `--border-*` / `--on-*` → 密度 → 动效。**组件只读第 4 层(尺寸读第 5 层),前 3 层是接线。** > > **六条官方硬规则**:① 只用用途层令牌,禁止裸 hex;② 暗色只靠 `data-mode`,永不手写暗色覆盖;③ 文字永不使用 `opacity`(用 `--text-secondary` / `--text-muted`);④ 每视图最多一个 primary 按钮,陶土 `brand` 仅限 Claude 发起的动作;⑤ 同屏最多两个浮层高度(第三层用 `Dialog`);⑥ 边框官方写法是 `0.5px solid var(--border)`。 > > ⚠️ `--cds-role-*` 是**内部接线**(官方原文 `never reference them`),对外请用 `--fill-*` / `--bg-*` / `--border-*` / `--text-*` / `--on-*`。 ### Brand Clay Palette * `--brand`: `#c6613f` (Official desktop brand primary color; = `--cds-clay-emphasized` = 品牌页 `clay-emphasized`) * **品牌物料色板(v5.11492.5 随包 `brand-colors.md` 实证)**:Ivory `#FAF9F5`、Slate `#141413`、Clay `#D97757`、Oat `#E3DACC`、Blue `#2A78D6`;棱镜色 Fig `#C46686` / Sky `#6A9BCC` / Olive `#788C5D` / Coral `#EBCECE` / Heather `#CBCADB` / Cactus `#BCD1CA`;21 阶暖灰 `#000000 → #FAF9F5 → #FFFFFF`。产品 UI 用 CDS 35 阶灰,品牌物料用这 21 阶,**两套不可互换**(见 `docs/v5.11492.5/09` §9.1、§9.4)。 * `--cds-clay`: `#d97757` (Light / pulse indicator) / `#cc6b49` (Dark) * **官方佐证 (v3 取证)**:Claude 桌面端 3.6556.2 内置的官方 `frontend-design` skill 原文确认 #D97757 为 "Anthropic's own Claude-interaction accent"(见 `docs/v4.29.0-4.4212.0/06` §6.10.4),与 REA 运行时实测一致 * 角色区分 (运行时实证 3.6556.2):`brand`=陶土(Claude 发起的动作,如发送/生成);`accent`=**蓝色**(`--cds-text-accent: #184f95`、`--cds-border-accent: #86b6ef`)——二者是不同角色,不可互换 * Focus shadow: `var(--cds-focus-shadow)` (`inset 0 0 0 1px var(--cds-page-bg), 0 0 0 1px var(--cds-fill-accent), 0 0 6px 1px var(--cds-bg-accent)`, 即蓝色 ring + 蓝色 glow,运行时实证) ### Geometric Corner Radii * `var(--cds-radius)`: `8px` (Base component radius) * `var(--radius-card)` / `--cds-card-radius`: `calc(var(--cds-radius, 8px) + calc(.25rem * var(--cds-rem-scale, 1)))` (12px standard / concentric card radius, alias: `--cds-radius-card`) * `--cds-radius-composer`: `calc(.75rem * var(--cds-rem-scale, 1))` ≈ 11.3px (Main chat composer terminal; `data-density=comfortable` raises it to `calc(.875rem * …)` ≈ 13.2px). **v5.11492.5 实测**:4.x 文档中的固定 `20px` 已不存在。 * `--cds-panel-radius`: `calc(.625rem * var(--cds-rem-scale, 1))` ≈ 9.4px (Panels, attachment cards; comfortable 档 `calc(.75rem * …)` ≈ 11.3px) * `--df-radius-pill` / `--cds-radius-pill`: `999px` / `9999px` (Pill buttons, segmented control tracks) * `--cds-message-bubble-radius`: `calc(var(--cds-radius, 8px) + calc(.25rem * var(--cds-rem-scale, 1)))` (User message bubble radius, alias: `--cds-radius-message-bubble`)。**v5.11492.5 未观测到该派生量**:5.x 用户气泡直接消费 `--cds-radius`,复刻时应以实测令牌为准。 * Precision scale: `--radius-xs` (2px), `--radius-sm` (4px), `--radius-md` (6px, alias: `--cds-radius-btn-xs`), `--radius-lg` (8px, alias: `--cds-radius-btn-md`), `--radius-xl` (12px, alias: `--cds-radius-code`), `--radius-2xl` (16px, alias: `--cds-radius-dialog`), `--radius-3xl` (24px) --- ## ⚡ 2. Motion Physics & Spring Presets > **v5.11492.5 新增 CSS 动效令牌**(不再只依赖 Framer Motion):`--cds-dur-fast` 60ms / `--cds-dur-snap` .12s / `--cds-dur-base` .2s / `--cds-dur-sheet` .3s / `--cds-dur-slow` .45s;`--cds-ease-out` `cubic-bezier(.165,.84,.44,1)`、`--cds-ease-snap` `cubic-bezier(.32,.72,0,1)`、`--cds-ease-overshoot` `cubic-bezier(.34,1.3,.64,1)`;以及 `--cds-btn-spring` 的 CSS `linear()` 15 点弹簧采样(峰值 1.0915,反解 ζ ≈ 0.594)。纯 CSS 场景优先用这组令牌,React 场景仍用下方四套弹簧预设。 Always import canonical spring presets from [`code-examples/ClaudeMotionPresets.ts`](code-examples/ClaudeMotionPresets.ts) instead of hardcoding random transition parameters. ```typescript import { SPRING_BOUNCY, SPRING_SNAPPY, SPRING_GENTLE, SPRING_HEAVY_SNAP, } from './ClaudeMotionPresets'; ``` ### The 4 Canonical Spring Presets Presets 1, 2 and 4 are observed values extracted from `Claude.app` `ion-dist`. Preset 3 (`SPRING_GENTLE`) is a project-local addition, not a CDS observation — no client release checked here contains `stiffness:380` or `damping:18`. Values below are recomputed from the exported constants, not copied from prose. `Observed use` lines record call sites found in the shipped bundle, not inferred intent. > **Provenance and version scope.** `Observed use` and the client inventory in > this section were verified against **`/Applications/Claude.app` 2.42304.2**. > The `docs/v1` chapters describe **v1.28** and are deliberately left as the > historical record of that release; the `docs/v2` chapters describe > **v2.37337.1** but do not carry a spring table. Constant values are stable > across these releases; call sites are not. 1. **`SPRING_BOUNCY`** (`stiffness: 600, damping: 30, mass: 1.0`, $\zeta = 0.612$): - **Overshoot**: `+8.8%`. - **Observed use**: Microphone button mount/unmount `scale`+`opacity`, voice-bar `width: 0 → 32` expansion, button padding morphs, and `popLayout` icon swaps. - **Source**: `ion-dist/assets/v1/shared-8-PHXy9B6B.js`. 2. **`SPRING_SNAPPY`** (`stiffness: 320, damping: 28, mass: 1.0`, $\zeta = 0.783$): - **Overshoot**: `+1.9%`. - **Observed use**: Drag-release rebound — paired `animate(dx|dy, target, {...preset, velocity})` calls that settle a dragged element onto its slot using the release velocity. Not an entrance animation. Guarded by `prefers-reduced-motion`, which snaps instead. - **Source**: `ion-dist/assets/v1/c427176b2-DuM09fKk.js`. 3. **`SPRING_GENTLE`** (`stiffness: 380, damping: 18, mass: 1.0`, $\zeta = 0.462$): - **Overshoot**: `+19.5%`. - **Observed use**: none — this preset has no client call site. - **Source**: none. Project-local preset filling the gap between the near-critically-damped pair and the high-frequency pop; do not present it as a Claude reading. - **Do not equate it with `duration .32 / bounce .15`.** That real client config (`shared-9-Co0ph6Xn.js`, dictation↔rest state swap) resolves through framer-motion `tn()` to `stiffness ≈ 244, damping ≈ 26.6, ζ ≈ 0.85` — `+0.6%` overshoot, not `+19.5%`. 4. **`SPRING_HEAVY_SNAP`** (`stiffness: 1200, damping: 80, mass: 0.1`, $\zeta = 3.652$, overdamped): - **Overshoot**: `0%` (Zero overshoot). - **Observed use**: `file_viewer` panel width animation — `animate(width, 384, preset)` on open and back to the computed initial width on close. In the same module `kt = 320` is the minimum width and `At = 480` the default width. - **Source**: `ion-dist/assets/v1/c8ad300b7-07P9B-v4.js`. ### Other spring presets observed in the client The four names above are a project convention, not a complete client inventory. The shipped bundle contains 14 distinct spring configs; these three are missing from the preset file and are worth knowing about: | Config | ζ | Overshoot | Observed use | Source | | :--- | :--- | :--- | :--- | :--- | | `420 / 28` | 0.683 | `+5.3%` | Draggable capture popover, `scale .25 → 1` entrance with `dragElastic: .05` | `c0447db9a-KKfDTbDr.js` | | `260 / 16` | 0.496 | `+16.6%` | Capture-selection handle rotation, `-90°` arrow marker; exit `scale .6` | `c0447db9a-KKfDTbDr.js` | | `300 / 35 / mass 1` | 1.01 | `0%` | Staggered list entrance, `translateY 32 → 0` with `staggerChildren: .15` and a separate `opacity` ease-out | `ccd647019-DrnyijvI.js` | Two more appear as timing variants rather than reusable presets: `320 / 30` (`delay: 1`, credits controls row) and `500 / 30 / mass .7`. ### v5.11492.5 复核(2026-11) 在 5.11492.5 上重新提取:客户端共 **22 组**独立弹簧(2.42304.2 为 14 组),但**四套预设的调用点未变** —— `600/30` 仍是麦克风与语音条、`320/28` 仍是拖拽释放回弹、`420/28` 仍是捕获浮层(`scale .25→1`、`dragElastic .05`)、`1200/80/mass .1` 仍是 `file_viewer` 面板宽度(同文件常量 `320/480/384`)。新增的 16 组属于业务侧自建(表单滑入、进度、庆祝粒子、轮播、chips),**不应当作 CDS 规范**。完整清单见 `docs/v5.11492.5/04` §4.7。 ### Version caveat `docs/v1` records the matrix as it appeared in client **v1.28**, labelling `600 / 30` as "buttons" and `1200 / 80 / .1` as "sidebar drag damping". That mapping was correct for that release. In **2.42304.2** both constants survive unchanged but their call sites moved: `600 / 30` now drives the microphone and voice bar, and `1200 / 80 / .1` drives the `file_viewer` panel width. Neither `docs/v1` nor `docs/v2` covers 2.42304.2, so the table above is the only current-version record in this repo. When a scenario label matters, re-derive it from the bundle rather than trusting either volume. ### 7-Stop Non-Linear Fade Mask Never use a linear gradient for scroll fading. Use the calibrated 7-stop non-linear mask (v3 forensic note: the 3.6556.2 client drives scroll fading through `@property` variables + `animation-timeline: scroll()` with no hardcoded multi-stop mask; keep the stops below only as a static fallback for engines without scroll-driven animation): ```css mask-image: linear-gradient( to bottom, transparent 0%, rgba(0, 0, 0, 0.05) 15%, rgba(0, 0, 0, 0.18) 32%, rgba(0, 0, 0, 0.38) 50%, rgba(0, 0, 0, 0.64) 68%, rgba(0, 0, 0, 0.88) 85%, black 100% ); ``` See [`code-examples/ScrollFadeContainer.tsx`](code-examples/ScrollFadeContainer.tsx) for dynamic top/bottom edge zeroing logic. --- ## 🧩 3. Component Directory: 30 Production Modules Refer to or import from [`code-examples/`](code-examples/) when composing UI: ### Atomic Controls (5) * [`CdsButton.tsx`](code-examples/CdsButton.tsx): 4-tier ladder (XS: 24/6px, SM: 28/8px, MD: 32/8px, LG: 40/12px), 5 variants (Primary, Secondary, Ghost, Outline, Danger). * [`SegmentedControl.tsx`](code-examples/SegmentedControl.tsx): 9999px rounded pill track, 2px geometric padding, CSS & Framer Motion dual-mode. * [`StatusIndicators.tsx`](code-examples/StatusIndicators.tsx): Clay 2.4s breathing light, 1.2s active run pulse, 3-dot wave, skeleton sweep. * [`ConfirmationDialog.tsx`](code-examples/ConfirmationDialog.tsx): 16px corner radius, dual-ring popover shadow, focus trap. * [`AttachmentCard.tsx`](code-examples/AttachmentCard.tsx): 10px panel radius, desktop card grid (128×96px) and inline composer pill dual-mode. ### Conversation Stream & Input (6) * [`ChatComposer.tsx`](code-examples/ChatComposer.tsx): 20px core input terminal, dual-ring focus shadow, `field-sizing: content` auto-resize. * [`ChatMessageBubbles.tsx`](code-examples/ChatMessageBubbles.tsx): User 18px radius with soft tint vs Assistant zero-border transparent layout. * [`ThinkingAccordion.tsx`](code-examples/ThinkingAccordion.tsx): Framer Motion height spring expansion, single clay breathing pulse dot, active generation mutex. * [`RichComposerWithMentions.tsx`](code-examples/RichComposerWithMentions.tsx): CJK IME composition guard, `/` command & `@` context dual triggers, token budget estimator. * [`ModelSwitcherWithTokenGauge.tsx`](code-examples/ModelSwitcherWithTokenGauge.tsx): 3-tier model switcher, Extended Thinking toggle, Prompt Caching 4-color memory SVG gauge. * [`McpToolDecisionCard.tsx`](code-examples/McpToolDecisionCard.tsx): 3-state authorization lifecycle (`pending_approval` → `running` → `success`/`error`), 3-tier action array. ### Atmosphere & Motion (3) * [`ClaudeMotionPresets.ts`](code-examples/ClaudeMotionPresets.ts): 4 calibrated physics presets. * [`ReasoningAmbientGlow.tsx`](code-examples/ReasoningAmbientGlow.tsx): Warm Clay diffuse light field, `cds-shimmer-text-shine` asymmetric sweep, caustic canvas. * [`ScrollFadeContainer.tsx`](code-examples/ScrollFadeContainer.tsx): 7-stop non-linear mask with edge sensors. ### Audiovisual & Media (8) * [`ClaudeAudioPlayer.ts`](code-examples/ClaudeAudioPlayer.ts): Procedural Web Audio API oscillator synthesis, 30% gentle volume standard, anti-pop gain ramp smoothing. * [`LiveMicActivityBars.tsx`](code-examples/LiveMicActivityBars.tsx): 6-band speech spectrum visualizer (85Hz-4.8kHz), 8% noise floor gate, `Math.pow(energy, 0.7)` non-linear Gamma power compression. * [`MediaLightboxViewer.tsx`](code-examples/MediaLightboxViewer.tsx): 75vw runway viewport, cursor-anchored affine pan/zoom equation, 4px drag deadzone, Ctrl + wheel zooming. * [`useClaudeSharedElementTransition.ts`](code-examples/useClaudeSharedElementTransition.ts): `startViewTransition` wrapper with dynamic corner radius detection and `object-fit: contain` clip calculation. * [`ArtifactsSplitPaneResizer.tsx`](code-examples/ArtifactsSplitPaneResizer.tsx): Iframe pointer shield, 4px deadzone, double-click 50/50 spring snap, collapse thresholds. * [`EpitaxyIframeBridge.tsx`](code-examples/EpitaxyIframeBridge.tsx): Strict Origin validation & channel-isolated postMessage RPC, user-gesture gating (`navigator.userActivation`). * [`StreamingDiffViewer.tsx`](code-examples/StreamingDiffViewer.tsx): Table line-number alignment with `tabular-nums`, incremental streaming pipeline, unified/split view, 2.5s copy cooldown. * [`CodeBlock.tsx`](code-examples/CodeBlock.tsx): 12px radius, `#0d0d0c` solid black background, inline optical alignment for language tags. ### Desktop & System Architecture (8) * [`createClaudeMainWindow.ts`](code-examples/createClaudeMainWindow.ts): Electron host window factory: `hiddenInset` titlebar, macOS Vibrancy (`under-window`) glass blending, 1200×800 default, 600×400 min. * [`ClaudeDesktopHeader.tsx`](code-examples/ClaudeDesktopHeader.tsx): macOS traffic light 74px inverse zoom compensation slot (`ew = 74`), 45px global drag band. * [`DraggableSessionList.tsx`](code-examples/DraggableSessionList.tsx): `pinnedOrder` optimistic topological reordering, 4px deadzone, tilted ghost shadow. * [`CoworkAgentCanvas.tsx`](code-examples/CoworkAgentCanvas.tsx): Multi-agent task delegation state machine, team-shared artifact asset pool, cross-window `BroadcastChannel` sync. * [`useClaudeScrollPinning.ts`](code-examples/useClaudeScrollPinning.ts): 150ms cooldown latch against scroll hijacking, 40px bottom-tolerance scroll pin, GPU subpixel blur elimination. * [`ContainerResponsiveBar.tsx`](code-examples/ContainerResponsiveBar.tsx): `@container`-driven 4-tier fluid compression matrix (>=576px / <480px / <384px / <320px), preventing glyph breaks. * [`useClaudeRovingFocus.ts`](code-examples/useClaudeRovingFocus.ts): W3C WAI-ARIA compliance: 1D & 2D arrow key grid navigation, Home/End boundary jumps. * [`useRateLimitBackoff.ts`](code-examples/useRateLimitBackoff.ts): 429/503 truncated exponential backoff (`t = min(t_max, t_base * 2^a) * (1 ± J)`), full jitter, circuit breaker. --- ## 🛡️ 4. Agent Coding Invariants (Do's and Don'ts) ### ✅ DO 1. **Always use semantic tokens**: Use `var(--cds-bg-surface-0)` or Tailwind classes (`bg-surface-0`, `text-primary`, `bg-clay-500`) instead of arbitrary hardcoded HEX values. 2. **Apply `tabular-nums` for dynamic numbers**: Every timer, countdown, token counter, audio frequency indicator, and line number MUST use `tabular-nums` (or `font-mono`) to prevent layout jitter. 3. **Guard CJK IME inputs**: ```typescript const handleKeyDown = (e: React.KeyboardEvent) => { if (e.nativeEvent.isComposing || e.keyCode === 229) return; if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); handleSendMessage(); } }; ``` 4. **Support Dark Mode**: Always test that UI looks correct under both light (`:root`) and dark mode (`.dark`). 5. **Enforce Single-Stroke Borders**: If a container has a border, its internal action buttons or chips should have `border-none`. ### ❌ DON'T 1. **Never introduce raw linear jumps**: Do not write `transition: all 0.3s linear` or `transition: all 0.5s ease`. Use Framer Motion springs or the calibrated cubic-bezier curves (`[0.16, 1, 0.3, 1]`). 2. **Never commit binary assets**: Never introduce `.ttf`, `.otf`, `.mp3`, or `.wav` files into the repository. 3. **Never bypass Sandbox Security**: Never add `allow-same-origin` to an iframe bridge running arbitrary LLM-generated HTML. 4. **Never hijack scroll during streaming**: Do not force-scroll to bottom if `Date.now() - lastUserScrollTime < 150ms`. 5. **Never open or update a Pull Request without explicit user approval**: Local edits, commits and branch pushes are fine on their own, but creating a PR, editing an existing PR's title/body, or pushing commits to a branch that already has an open PR requires the user to say so first. When the work is done, report the local state and wait; do not call `gh pr create` / `gh pr edit` / `gh pr comment` unprompted. --- ## 🧪 5. Verification & Quality Gates Whenever you write or modify code in this repository, you **MUST** run the following verification commands to ensure zero regressions: ```bash # 1. Typecheck the entire project npm run typecheck # 2. Verify design token consistency npm run check:tokens # 3. Build library output npm run build ``` Both commands must exit with code 0 and output **0 errors**. --- ## 🔌 6. Runtime Portability & Host Bridging (运行时分层与宿主桥接) To maximize consumption surface across different host environments (e.g. non-React web apps, Electron desktop harnesses like DSH, or custom plugin shells), the repository assets are structured into 3 portability tiers: ### 1. The Three Portability Tiers * 🎨 **Pure CSS (Tokens & Shaders)**: Zero JavaScript runtime dependency. Includes `code-examples/cds-theme.css`, CSS-driven scroll fade (`.cds-scroll-fade`), breathing lights (`.cds-dot-breathe`), and skeleton sweeps. Can be consumed by any HTML/CSS project directly. * ⚡ **Pure Logic / Headless**: Pure math and browser APIs without React UI bindings. Includes `code-examples/ClaudeMotionPresets.ts` (spring formulas), `code-examples/ClaudeAudioPlayer.ts` (Web Audio synthesis), `code-examples/useClaudeScrollPinning.ts`, and `code-examples/useRateLimitBackoff.ts`. * ⚛️ **React Components**: Stateful, interactive UI controls relying on React hooks/refs. Includes `MediaLightboxViewer.tsx`, `DraggableSessionList.tsx`, `McpToolDecisionCard.tsx`, `ChatComposer.tsx`, etc. ### 2. Host Bridge Mapping Pattern (宿主别名桥接) If your host application uses a custom design token prefix (e.g., `--app-*` or `--dsw-*`), bridge to CDS by defining aliases in your host stylesheet: ```css /* Host application stylesheet */ :root { --app-brand-primary: var(--brand); /* #c6613f */ --app-brand-accent: var(--cds-clay); /* #d97757 */ --app-bg-canvas: var(--cds-surface-0); /* #f9f9f7 / #0b0b0b */ --app-bg-card: var(--cds-surface-2); /* #ffffff / #1a1a19 */ --app-border-base: var(--cds-border); /* hairline divider */ --app-radius-card: var(--radius-card); /* concentric card radius */ --app-shadow-composer: var(--cds-shadow-composer); /* composer diffuse shadow */ } ``` --- ## 📐 7. Documentation Versioning Convention (文档版本卷约定) **Every Claude Desktop release gets its own version-named documentation volume.** This is a repository invariant, not a suggestion. ### 7.1 Naming - New forensics go into `docs/v/` — e.g. `docs/v4.16336.0/`. - A volume may cover a range when it re-checks earlier baselines: `docs/v4.29.0-4.4212.0/` means primary forensics on 4.29.0 with incremental re-checks through 4.4212.0. - `docs/v1/` and `docs/v2/` keep their names as historical snapshots; their token values are superseded. - **Never** name a volume after a date, a topic, an investigation phase, or a workflow step ("audit", "remaining items", "live observation", "round 2"). ### 7.2 Structure — chapters by feature, not by investigation flow Each volume follows the `docs/v1/` format: | Requirement | Detail | | :--- | :--- | | Frontmatter | `title`, `part`, `category`, `domain` per chapter | | Navigation | top/bottom `

` with previous / index / next links | | Chapters | **organised by feature point** (architecture & tokens, navigation, preview, security, element inspect, annotation, motion physics, host & engineering) — never by chronological discovery order | | Sections | numbered `X.Y`, each with `> **技术领域与英文指代**` and evidence tables | | Index | volume `README.md` with anchors for every section | | Merged edition | one `.full.md` for offline reading | | Reproducibility | every claim carries an ASAR path + byte offset or a REA Evidence ID; distinguish observed / inferred / unknown | ### 7.3 Registration When adding a volume, update **all four** entry points and mark the previous volume as historical: 1. `README.md` (Chinese) — current-volume section + naming convention 2. `README-en.md` — forensic baseline / convention lines 3. `docs/README.md` — volume index 4. `AGENTS.md` — this section stays the authoritative rule; the current version is recorded in §7.4 ### 7.4 Current volume | Volume | Version | Status | | :--- | :--- | :--- | | `docs/v5.11492.5/` | `@ant/desktop 5.11492.5` | **current** (verified by `Info.plist`, `app.asar/package.json` and the build stamp `commitHash 1403e2cf…` / `appVersion 5.11492.5`; Electron `45.2.1`) | | `docs/v4.16336.0/` | `@ant/desktop 4.16336.0` | historical baseline (side-browser manual) | | `docs/v4.29.0-4.4212.0/` | `4.29.0` → `4.4212.0` | historical baseline | | `docs/v2/` | `2.37337.1` | historical snapshot | | `docs/v1/` | `1.x` | historical snapshot | ### 7.5 Gates Before committing a new volume, run `npm run typecheck`, `npm run check:tokens` and `npm run build`; all three must exit 0. `check:tokens` scans `AGENTS.md` and every file under `docs/`, so any backticked `--cds-*` reference must be defined in `code-examples/cds-theme.css`.