项目简介
open-claude-ui 是一个面向现代桌面 AI 客户端的开源 UI 组件库与动效引擎。项目基于 REA 逆向工程框架完成静态 AST 分析、闭包代码反混淆、运行时跟踪与 ASAR 资源解构，并将研究结果整理为可复用的 React 组件、Hooks、主题样式和技术文档。
它并不只是复刻界面外观，还重点还原了影响交互质感的工程机制，例如物理弹簧参数、CJK 输入法保护、滚动边缘渐隐、流式消息滚动控制、光标锚定缩放、拖拽死区和 Web Audio 合成提示音。
合规说明：项目不分发商业字体、录音文件等专有二进制资产，而是使用系统字体回退栈和 Web Audio API 纯代码音效。项目采用 MIT License，相关成果用于学习、研究与工程交流。
适合哪些项目
如果你正在开发 AI 聊天客户端、模型控制台、工具调用审批界面、桌面端助手、媒体查看器或多代理协作空间，可以从该仓库中按需引入组件，而不必自行重新调试视觉令牌和复杂交互。
- Web AI 应用：使用会话气泡、富文本输入框、模型切换器和 Token 仪表盘。
- 流式生成界面：使用滚动图钉、思考过程折叠和渐隐遮罩。
- 桌面应用：使用 Electron 窗口工厂、macOS 标题栏和 Vibrancy 材质方案。
- Artifacts 与多媒体应用：使用分栏拖拽、媒体灯箱、共享元素转场和 iframe 沙箱桥接器。
- 无障碍应用：使用符合 WAI-ARIA 思路的 Roving TabIndex 焦点漫游 Hook。
核心特性
设计令牌与视觉体系
项目提供 Surface 0 至 Surface 3 的低对比表面阶梯、陶土橙 #d97757、高分屏发丝细边补偿、系统字体回退栈，以及针对按钮、面板、气泡和输入框设置的圆角矩阵。全局主题变量和关键帧集中在 code-examples/cds-theme.css 中。
30 个独立代码模块
仓库包含 11 个基础原子控件和 19 个架构或交互模块。组件源码位于 code-examples，统一 TypeScript 导出入口位于 src/index.ts。这些模块覆盖按钮、分段选择、输入框、会话气泡、MCP 决策卡片、媒体查看器、流式 Diff、桌面窗口和多代理画布等场景。
生产级交互机制
- 4 套物理弹簧预设，包括 Bouncy、Snappy、Gentle 和 Heavy Snap。
- 滚动区域使用 7 档非线性 Alpha 遮罩，并根据是否触顶或触底动态调整。
- 输入框通过
isComposing与keyCode === 229双重条件保护 CJK 输入法。 - 流式输出使用 40px 底部容差和 150ms 人工滚动冷却，避免自动滚动抢夺视口。
- 麦克风波形使用 8% 噪声门限和 0.7 次幂 Gamma 压缩。
- 拖拽与画廊交互加入 4px 指针移动死区，过滤手部轻微抖动。
离线组件预览
仓库附带单文件交互式故事书 docs/claude-components-storybook.html。无需启动本地开发服务器即可查看陶土色彩体系、暗色模式、按钮反馈、分段胶囊、弹簧动效、附件磁贴和复制状态动画。
安装与环境准备
确认技术栈
根据仓库标注，建议项目具备以下环境：
- React 18 或更高版本。
- TypeScript 5.5 或更高版本。
- Tailwind CSS 3.4 或更高版本。
- Framer Motion 11 或更高版本。
README 没有给出特定包管理器的安装命令。开始前，应按照你的工作区、Git 依赖或包发布方式，使项目能够通过 open-claude-ui 路径访问，并确保上述对等技术栈已经配置完成。
先查看离线故事书
如果已经取得仓库源码，可以先直接打开预览文件：
open docs/claude-components-storybook.html在不修改业务工程的情况下，这一步可以帮助你确认组件视觉效果、暗色主题和交互动效是否符合项目需求。
配置主题样式
引入全局 CSS
在应用的全局样式入口中引入 CDS 主题文件。它包含 CSS 自定义属性与组件所需的关键帧：
@import "open-claude-ui/code-examples/cds-theme.css";该主题提供表面颜色、陶土品牌色、边框、阴影和动效基础。为了保持组件之间的一致性，建议优先使用现有 CSS 变量，不要在每个组件中重复硬编码颜色。
扩展 Tailwind 配置
在项目的 tailwind.config.js 中加载仓库提供的主题扩展：
const cdsTheme = require("open-claude-ui/code-examples/tailwind.config.js");
module.exports = {
content: [
"./src/**/*.{js,ts,jsx,tsx}",
"./node_modules/open-claude-ui/**/*.{js,ts,jsx,tsx}"
],
theme: {
extend: {
...cdsTheme.theme.extend
}
}
};content 数组需要覆盖你的应用源码以及 open-claude-ui 中包含 Tailwind 类名的文件。否则，生产构建时可能无法生成组件使用的工具类。
基础用法：搭建模型控制与聊天输入区
下面的示例组合三个核心模块：
ScrollFadeContainer为可滚动区域添加上下边缘渐隐。ModelSwitcherWithTokenGauge展示模型选择、Extended Thinking 状态和 Token 预算。ChatComposer提供核心消息输入与发送回调。
import React, { useState } from 'react';
import {
ChatComposer,
ModelSwitcherWithTokenGauge,
ScrollFadeContainer
} from 'open-claude-ui';
export function App() {
const [model, setModel] = useState<
'sonnet-3.5' | 'haiku-3.5' | 'opus-3'
>('sonnet-3.5');
const [thinking, setThinking] = useState(true);
return (
<div className="flex h-screen w-full bg-[var(--cds-surface-1)]">
<ScrollFadeContainer
axis="vertical"
fadeSize={32}
className="flex-1 p-6"
>
<div className="mx-auto max-w-3xl space-y-4">
<ModelSwitcherWithTokenGauge
currentModel={model}
onModelChange={setModel}
extendedThinking={thinking}
onThinkingChange={setThinking}
tokenBudget={{
inputTokens: 12400,
outputTokens: 3200,
cacheReadTokens: 48000,
cacheWriteTokens: 16000,
maxContextWindow: 200000
}}
/>
<ChatComposer
onSend={(text) => console.log('Send message:', text)}
/>
</div>
</ScrollFadeContainer>
</div>
);
}理解状态管理
currentModel 和 extendedThinking 都由应用层管理，因此模型切换器可以与真实的模型请求配置同步。示例中的 tokenBudget 将输入、输出、缓存读取、缓存写入和最大上下文窗口分别传入仪表盘。
ChatComposer 的 onSend 在示例中只输出日志。接入实际项目时，可以在该回调中调用你的会话服务、更新消息列表，并触发流式响应状态。
常用组件选择指南
基础控件
CdsButton：提供 XS、SM、MD、LG 四种尺寸，以及 Primary、Secondary、Ghost、Outline、Danger 五种变体。SegmentedControl：用于模式切换，支持纯几何定位和 Framer MotionlayoutId动画方案。StatusIndicators：包含陶土呼吸灯、实时活动脉冲、思考三点动画和骨架扫光。ConfirmationDialog：用于默认或危险操作确认，包含模糊遮罩和键盘焦点约束。AttachmentCard：支持桌面磁贴与输入框行内胶囊两种附件展示方式。
会话与工具调用
ChatMessageBubbles：区分用户气泡和助手透明排版。ThinkingAccordion：展示可折叠思考过程，并可在生成期间保持强制展开。RichComposerWithMentions：适合需要/指令、@上下文和 Token 预测的输入终端。McpToolDecisionCard：用于工具授权流程，覆盖pending_approval、running、success和error状态。
媒体、代码与 Artifacts
MediaLightboxViewer：提供 75vw 画廊跑道、光标锚定 Pan/Zoom、拖拽死区和 Ctrl 滚轮缩放。ArtifactsSplitPaneResizer：处理双栏缩放、边缘折叠、双击 50/50 吸附和 iframe 指针事件干扰。EpitaxyIframeBridge：通过 Origin 校验和隔离的postMessageRPC 协议连接预览沙箱。StreamingDiffViewer：支持增量流式追加，以及统一和分屏两种 Diff 模式。CodeBlock：提供代码容器和 2.5 秒复制状态衰减。
进阶实践
保护中日韩输入法
如果聊天输入框需要自行扩展键盘事件，必须保留输入法合成保护。用户在拼音或假名候选窗口中按 Enter 时，不应该提交消息。项目采用双重判断：
const composing =
event.nativeEvent.isComposing || event.keyCode === 229;
if (event.key === 'Enter' && !composing) {
// 提交消息
}对于 Escape 键，也应避免在关闭输入法候选层时让事件继续冒泡，从而意外关闭对话窗口。
避免流式输出抢夺滚动位置
可使用 useClaudeScrollPinning 管理持续追加的 Token。其核心策略包括 40px 底部容差、150ms 人工滚动冷却以及 35vh 弹性缓冲。当用户停留在底部附近时，界面可以跟随输出；一旦用户主动向上浏览历史消息，自动滚动就不应立即把视口拉回底部。
统一使用动效预设
项目在 ClaudeMotionPresets.ts 中提供四套经过调校的弹簧方案。开发新组件时，优先复用 Bouncy、Snappy、Gentle 或 Heavy Snap，而不是为每个动画随意设置刚度和阻尼。这样可以让按钮、面板、拖拽吸附和共享元素转场保持一致的物理语言。
正确处理 iframe 分栏拖拽
拖动分割条经过 iframe 时，iframe 可能截获指针事件并造成拖拽中断。ArtifactsSplitPaneResizer 会在拖拽激活时启用事件防吞噬机制，并结合 4px 移动死区、边缘约束和双击居中吸附。如果应用包含 Artifacts 预览，应优先复用该模块，而不是只监听分割条自身的鼠标事件。
为键盘用户保留完整导航
useClaudeRovingFocus 支持一维或二维方向键导航、Home 和 End 边界跳转以及 RTL 镜像翻转。构建模型网格、附件列表或工具卡片阵列时，应同时维护正确的 ARIA 语义和可见焦点状态。
处理模型限流与服务异常
useRateLimitBackoff 面向 429 和 503 响应，提供截断指数退避、抖动注入以及三次自动熔断恢复机制。它适合用于模型请求层，但业务仍需根据自己的 API 返回结构决定何时重试、何时显示错误，以及何时允许用户手动恢复。
使用技术手册深入学习
除了组件源码，仓库还提供超过 3,000 行的设计系统技术手册。建议按以下顺序阅读：
- 先阅读设计哲学、Surface 色彩阶梯、圆角矩阵和发丝边框规则。
- 再学习按钮、分段控件、状态指示器和确认对话框。
- 随后研究会话输入、CJK 守卫、模型切换与 MCP 状态机。
- 需要复杂动效时，再查看弹簧参数、环境光和滚动遮罩。
- 开发桌面端、媒体工具或协作空间时，阅读对应的系统架构章节。
完整手册位于 docs/Claude Design System (CDS).md。项目的逆向分析工作依托 REA 完成。
与 AI Coding Agent 协作
仓库提供 AGENTS.md、CLAUDE.md、.cursorrules 和 Copilot 指令文件。使用 Cursor、Claude Code、GitHub Copilot 等工具生成新界面时，可以要求 Agent 遵循仓库现有令牌、弹簧预设、边框原则和输入法保护规则。
示例提示词：请严格遵循本仓库中的 AGENTS.md 规范，使用 CDS 陶土设计令牌与 ClaudeMotionPresets 弹簧预设构建当前组件。
总结
open-claude-ui 将 AI 客户端中的视觉令牌、会话控件、动效物理、多媒体交互和桌面架构整理为可复用模块。最稳妥的接入方式是先通过离线故事书确认效果，再引入主题 CSS 和 Tailwind 扩展，最后从聊天输入框、模型切换器和滚动容器等核心组件开始组合。对于流式输出、CJK 输入、iframe 拖拽和键盘导航等复杂场景，应尽量复用仓库已有 Hooks 与状态机，而不是只复制表层样式。