Candor UI docs

Candor UI：免费层

用于 Agent 应用的界面组件：对话线程、消息、输入框、工具调用、推理和引用，以及它们所依赖的构建块；提供浅色、深色和高对比度主题，以及适用于 Vercel AI SDK、Claude Agent SDK 和 AG-UI 的适配器。基于 shadcn 构建，通过其 CLI 安装，采用 MIT 许可证。

此仓库包含 Candor UI 的 69 个免费项目（版本 2.4.0）、供编码 Agent 使用的技能和插件，以及三个起始应用。文档和在线示例：**https://candor.themethodic.com**。

安装

npx candor-ui init
npx candor-ui add thread message composer

candor-ui init 会将 @candor 注册表添加到 components.json，并将主题添加到 CSS；如果项目还没有 shadcn，它会先运行 shadcn 的设置流程（--yes 会使用 Radix 和 shadcn 的 nova 预设完成设置，不会提问）。或者手动添加注册表："@candor": "https://candor.themethodic.com/r/{name}.json"。如果 shadcn 询问是否覆盖某个原始组件（例如 ui/button.tsx），请回答 yes：Candor 的按钮样式会锁定操作；如果没有终端，请传入 --overwrite。

面向编码 Agent

llms-install.md 会告诉 Agent 如何在项目中自行设置 Candor：包括 CLI、文档 MCP 服务、技能，以及需要遵守的诚实原则。单独安装技能：

npx skills add MethodicDev/candor

会安装两项技能：skills/candor-ui（说明各组件适用于什么任务、适配器及组件遵循的规则，并提供从随附 CSS 中读取的设计系统参考）和 skills/candor-agent-ui（为 AI Agent 执行任务的界面提供设计基础知识，并附带一份每个界面完成后运行的审查清单；无论是否使用 Candor 都适用）。

插件会同时安装技能和文档 MCP 服务。Claude Code：先运行 claude plugin marketplace add MethodicDev/candor，再运行 claude plugin install candor-ui@candor（或在会话中运行 /plugin install candor-ui --marketplace MethodicDev/candor）。GitHub Copilot CLI：先运行 copilot plugin marketplace add MethodicDev/candor，再运行 copilot plugin install candor-ui@candor。VS Code 从此仓库的 URL 安装 candor-ui； Cursor 会读取 .cursor-plugin/marketplace.json；Codex 包位于 plugins/codex/candor-ui。

位于 https://candor.themethodic.com/mcp 的 MCP 服务仅提供文档和组件建议：只读、无需密钥，且不提供付费源码。.mcp/server.json 描述了该服务，供 MCP 注册表使用。Agent 也可以读取 https://candor.themethodic.com/llms.txt。

起始应用

三个基于这些组件构建、可正常使用 Agent 聊天功能的应用。每个应用都可以单独安装和构建：

文件夹	技术栈	Agent
starter/	Next.js 16	/ 使用 Vercel AI SDK，/claude 使用 Claude Agent SDK
starter-vite-ag-ui/	Vite 和 React，无服务端	任意 AG-UI Agent（LangGraph、CrewAI……），或页面中编写的脚本 Agent
starter-tanstack-start-claude/	TanStack Start	Claude Agent SDK

npx degit MethodicDev/candor/starter my-agent-app
npx degit MethodicDev/candor/starter-vite-ag-ui my-agent-app
npx degit MethodicDev/candor/starter-tanstack-start-claude my-agent-app

内容概览

• theme：Candor 的默认主题：浅色、深色和高对比度，并经过对比度检查。在 Tailwind 之后导入 styles/candor.css。
• font-inter：Inter，Candor 的默认字体，采用自托管方式（OFL-1.1）。可选：不使用时，主题会采用系统字体。在 candor.css 旁导入 styles/candor-font-inter.css。
• font-source-sans：Source Sans 3，采用自托管方式（OFL-1.1），作为 Inter 的替代字体。在 candor.css 之后导入 styles/candor-font-source-sans.css；它会将 --cd-font 指向该字体。
• font-ibm-plex：IBM Plex Sans，采用自托管方式（OFL-1.1），作为 Inter 的替代字体。在 candor.css 之后导入 styles/candor-font-ibm-plex.css；它会将 --cd-font 指向该字体。
• theme-slate：Slate，一款主题画廊主题。采用冷调蓝灰色中性色和蓝色强调色；深色模式为深海军蓝石板色。和默认主题一样经过对比度检查。在 candor.css 之后导入 styles/candor-theme-slate.css。
• theme-paper：Paper，一款主题画廊主题。采用暖调米白底色、蓝黑色文字和赤陶色强调色；深色模式为暖调棕褐色。和默认主题一样经过对比度检查。在 candor.css 之后导入 styles/candor-theme-paper.css。
• theme-console：Console，一款主题画廊主题。以深色为主，布局紧凑：采用近黑色底色、绿色强调色和紧凑密度。浅色模式为柔和的浅色控制台风格。和默认主题一样经过对比度检查。在 candor.css 之后导入 styles/candor-theme-console.css。
• theme-signal：Signal，一款主题画廊主题。采用无色调的纯灰色，并以一种高饱和度靛蓝色突出关键操作。和默认主题一样经过对比度检查。在 candor.css 之后导入 styles/candor-theme-signal.css。
• ag-ui：将 AG-UI 事件转换为 Candor 消息、等待审批和用量信息，并支持 AG-UI 1.0 的共享状态与活动。
• ai-sdk：将 Vercel AI SDK（v7）的 UI 消息转换为 Candor 消息：文本、推理、工具调用、来源和数据卡片。
• claude-agent-sdk：将 Claude Agent SDK 事件转换为 Candor 消息、等待审批（以及 Agent 的问题）、用量和来源，并将用户的回答传回 SDK 作为结果。
• claude-agent-server：Claude Agent SDK 适配器的服务端部分：将一次运行流式传输给 useClaudeAgent，将其权限请求保存在你自己的路由可响应的存储中，并允许浏览器在重新加载后重新连接到运行。
• use-ag-ui：将 AG-UI Agent 接入 Candor：为 / 提供消息，为 提供属性，以及等待用户处理的中断。
• use-candor-chat：将 useChat() 的结果接入 Candor：为 / 提供消息，为 提供属性，以及等待用户处理的工具调用。
• use-claude-agent：将 Claude Agent SDK 服务端路由接入 Candor：为 / 提供消息，为 提供属性，以及等待用户处理的工具调用，并在重新加载后重新连接到运行。
• copy-field：供用户复制到其他位置的值（回调 URL、作用域列表）。
• degraded-panel：无法完成某项操作时显示的面板。
• locale：界面的文字、语言和方向。
• locked：如实说明状态的规则：无法使用的控件会说明原因。
• relative-time：以人们常用的方式显示时间（“5 分钟前”），悬停时显示准确时间，可安全地在服务端渲染。
• status-dot：小型状态标记。
• step-list：以标记显示步骤状态。
• streaming-text：仍在持续传入的文本。
• surface：Candor 的卡片：提供纯色、柔和、带边框或浮起的表面样式，避免各个屏幕自行重复实现。
• terms：应用中用于描述自身概念的词语，让组件符合产品用语：一个应用称其为“组织”，另一个则称为“项目”或“工作区”。
• agent-avatar：根据角色为 Agent 显示字形和色调，让用户一眼就能区分不同 Agent。
• ai-disclosure：简明告知用户正在与 AI 系统交互：可在对话线程首行显示（variant="line"），或在对话线程标题中显示精简的“AI”徽标（variant="badge"），点击后会打开应用自己的说明。
• attachment-preview：等待发送的文件，在撰写框中显示为标签：先显示文件名，随后显示上传进度、错误或文件大小，并提供移除按钮。
• card-registry：Agent 的回复可以携带的卡片。
• citation：行内的 [n]，点击后会在弹出层中打开来源，无需离开对话线程即可查看证据。
• composer：用户向 Agent 发送消息的地方：@ 提及可附加内容作为参考，/ 可启动已知操作，范围则说明请求会在哪个范围内执行。
• context-meter：显示模型上下文预算的占用情况，在撰写框中以圆环呈现，点击后可查看明细：系统、指令、Know、对话线程、工具、文件。
• entity-chip：用户系统中的事物（表、记录、流程），以带类型图标的标签显示，并可打开该事物。
• folded-turns：将一组轮次折叠为一行，适用于读者无需逐步查看的长时间 Agent 工作：“起草了三个版本并进行比较”。
• message-actions：在 Agent 回复下方提供复制、重试和评分操作。
• message-content：消息中按类型分类的内容块（段落、列表、代码、工具调用、卡片），以文本形式渲染，绝不渲染为 Markdown 或 HTML。
• message：对话线程中的一条消息。
• payload：Agent 提供的一段代码或查询文本：执行过的查询、编写的代码或配置文件。
• permission-prompt：等待用户批准的工具调用：说明将执行什么操作、为何向用户发出请求，以及当前运行所处的权限模式。
• prompt-suggestions：可供用户选择并开始使用的提示词。
• reasoning：Agent 在回答上方展示的推理内容。
• thread-divider：贯穿对话线程并在中间带有标签的分隔线：可以是日期（“今天”“昨天”“2026 年 11 月 5 日”），也可以是对话章节（“起草”“审阅”）。
• thread-event：对话线程中居中的简短提示，用于显示发生的事情而非对话内容：“Sam 已加入”“已切换到暂存环境”“运行已被防护机制停止”。
• thread：可滚动的消息列。
• tool-call：以紧凑行显示一次工具调用：用通俗语言说明其执行的操作、状态和耗时。
• chat：Candor 对话线程渲染的数据。
• highlight：用于高亮 Agent 展示代码的小型语法高亮器：将文本拆分为带类型的标记（关键字、字符串、注释……），由 Payload 将每个标记渲染为 span。
• know：Agent 知识库和 Agent 设置背后的数据。
• mcp-input：将 MCP 的“需要输入”结果（spec 2026-07-28，多轮往返请求）转换为 Candor 数据：服务端表单会转为供 ClarifyingQuestions 使用的问题；简单确认或用于打开页面的链接会转为供 ApprovalDecision 使用的双选项 Decision；用户的回答会转为客户端在重试调用时发送的 inputResponses。
• motion：Candor 的动效层，即在组件中运行的部分。
• render-prop：让基于 Radix 的 Candor 原语也能接受 Base UI 的 render 属性。
• safe-markdown：将模型文本作为安全的 Markdown 读取：支持段落、列表和围栏代码块。
• sound：Candor 音效层的名称和读取部分。
• status：所有 Candor Agent 组件共用的状态词汇。
• use-copy：复制文本并报告实际发生的情况。
• use-shortcut：按应显示的格式呈现组合快捷键：“mod+k” → 在 Mac 上显示为 ["⌘", "K"]，在其他平台上显示为 ["Ctrl", "K"]。
• use-virtual-list：仅渲染长列表中位于可视区域内或附近的项目，供 Thread 和 SessionList 的 virtualize 使用。
• accordion：一组标题，每个标题都可展开以显示更多内容。
• alert：关于页面或工作的信息，在不再适用之前始终显示在原处：更改前的警告、失败提示，或用户应该知道的事实。
• button：使用 Candor 主题的 shadcn 按钮，带有供 使用的锁定状态（变暗并说明原因）。
• checkbox：供用户勾选的方框。
• collapsible：使用 Candor 主题的 shadcn 可折叠组件（Radix）。
• label：控件的名称。
• popover：使用 Candor 主题的 shadcn 弹出层（Radix）。
• progress：用于显示可测量进度的工作的进度条：上传、导入、索引。
• skeleton：以即将显示内容的形状呈现的加载占位符。
• slider：用于设置范围内数值的控件，可带一个滑块；当数值包含两个数字时，也可用于设置范围。
• switch：用于切换开关状态的设置。
• tooltip：使用 Candor 主题的 shadcn 工具提示（Radix）。

Pro 和 Premium

计划、审批、差异、运行、评估、应用外壳、管理界面、全栈模块和模板均属于付费 套餐：https://candor.themethodic.com/#pricing。

贡献

此仓库会在每次发布时从 Candor UI 的主仓库生成。欢迎在此提交问题；我们会阅读拉取请求并 手动将其应用到上游，因此它们会在下一次发布中出现，而不是直接合并。

许可证

MIT，© Methodic LLC。详见 LICENSE。该许可证适用于此仓库中的免费项目；Candor UI 的付费项目遵循 Candor UI Commercial Licence。