UI Polish

UI Polish

为 AI 产品打造精致的 UI：React 组件已考虑好每一种状态、过渡和边缘情况，以及与之配套的设计规则，并以便于编码 Agent 遵循的方式编写。文档和在线演示请见 uipolish.com。

此仓库为免费版本，采用 MIT 许可证：包含 45 个组件、10 个 agent-kit 部件和区块、设计令牌与主题生成器、设计规则以及 Agent 技能。

设计理念

每个组件都遵循相同的设计取舍，规则也要求 Agent 编写的周边 UI 遵循相同原则。其中三条：

• 忙碌状态会等待 300ms 后再显示。 快速完成的操作不会闪现加载指示器。加载指示器一旦出现，就至少停留 400ms，确保用户看得清。
• 每个异步操作都有四种状态。 空闲、忙碌、完成和失败，每种状态都经过设计，失败状态会说明接下来该怎么做。
• 布局不会发生偏移。 变化的标签会保持宽度，数字使用等宽数字，加载的内容会预留空间。

全部十条设计理念见 foundation/opinions.md。

三种接入方式

1. MCP 服务。 连接一次后，就可以让 Agent 按名称请求组件（“添加日期选择器”）。它会将文件写入你的项目，并在编写 UI 时遵循这些规则。

claude mcp add --transport http uipolish https://uipolish.com/mcp

Cursor、VS Code、Codex 及其他客户端的设置说明见 uipolish.com/docs。

2. shadcn CLI。 每个条目都有一个注册表文件，位于 r/。将 CLI 指向其中一个文件，可从 uipolish.com 获取，也可使用此仓库的原始文件：

npx shadcn@latest add https://uipolish.com/r/date-picker.json

npx shadcn@latest add https://raw.githubusercontent.com/cortez/uipolish/main/r/date-picker.json

所有条目都可以用相同的方式获取：https://uipolish.com/r/<name>.json 或 https://raw.githubusercontent.com/cortez/uipolish/main/r/<name>.json。

组件会一并引入其依赖的组件，并只安装一次设计令牌。 r/theme.json 则会将设计令牌映射到现有的 shadcn/ui 主题。

3. 规则文件。 skills/ui-polish/ 是以 Agent 技能形式提供的设计规则：将该文件夹复制到 Agent 的技能目录中（Claude Code 对应 .claude/skills/），或者在 AGENTS.md 中让 Agent 参考 SKILL.md。同一套规则也按主题拆分为单独文件，位于 foundation/rules/。

你也可以手动复制 registry/ 中的文件夹，并只需添加一次 foundation/tokens.css。交互式组件需要 @base-ui/react。

仓库内容

• registry/<name>/：一个组件，包含 React 组件、CSS 模块 （仅读取 --ui-* 设计令牌）、供 Agent 使用的 guide.md 和 meta.json。 animated-size、field、icons、listbox、text 和 text-morph 是其他组件导入的构建模块。
• foundation/：设计理念、规则、tokens.css、Tailwind v4 桥接层、 shadcn 映射和检查清单。
• theme/theme.ts：输入一种色相，即可生成完整的浅色和深色 --ui-* 调色板， 并解决所有文本颜色的对比度问题。将其 CSS 粘贴到 tokens.css 之后。
• skills/ui-polish/：基于 foundation/ 构建的 Agent 技能。
• r/：基于 registry/ 和 foundation/ 构建的 shadcn 注册表。

UI Polish Pro 还提供完整的产品界面、模板和更多 agent-kit 部件： uipolish.com/pricing。

组件

• 手风琴：披露式分区通过网格行过渡效果展开，可一次展开一个或多个。URL 哈希中指定的项目会在首次绘制时保持展开。
• 提示框：用于显示信息、成功、警告和错误的行内横幅。它会预留好空间，或在按下时展开，因此状态延迟出现也不会推挤页面。
• 头像：照片后方带有不透明的柔和底色和姓名首字母，或显示没有姓名的人像剪影。快速加载的照片不会闪现姓名首字母，损坏的照片不会显示损坏标记，头像组会相互重叠，并用 +N 显示人数。
• 徽标：用于显示状态或计数的静态标签，与所在行等高。单数字计数为圆形，数字采用等宽字体。
• 面包屑：指向当前页面的链接路径。中间部分过长时会折叠为 …，点击后在原处展开；过长的标签会渐隐而非换行，并兼容任何路由器的链接。
• 按钮：按下时立即响应、随后弹回的胶囊按钮。忙碌状态会保持宽度不变，文本变化时标签会平滑变换。
• 复选框：Base UI 复选框，勾选标记会绘制显示或消失。混合状态的短横线会变为勾选标记，复选框与标签首行对齐。
• 筛选芯片：保持按下状态的筛选芯片，以及带有独立命名移除按钮的可移除芯片。加号会旋转变为勾选标记，宽度保持不变；移除的芯片会先淡出，其余芯片再滑动到位。
• 代码输入框：一次性验证码输入框，可通过粘贴或平台自动填充来填写，并可按 Backspace 向后退格。活动输入框显示深色边框和插入符，无效状态会显示在边框上；可选状态会将输入框折叠为居中的无边框 Verifying 胶囊，随后变为 Verified；代码错误时则会重新展开。
• 组合框：可输入筛选本地或异步结果的自动完成框。每个匹配项都会标记输入文本，加载新结果时旧结果仍会保留。
• 命令面板：支持模糊匹配、最近项目和分组结果的 ⌘K 面板。异步数据源不会闪现加载状态，面板高度会随结果变化。
• 复制字段：只读值，带有一个复制按钮；按钮图标会变为勾选标记，并向屏幕阅读器读出“已复制”。机密内容会以固定行数的圆点遮盖，不会泄露其长度。
• 数据表格：以键盘操作为先的数据网格，适用于真实数据：只有一个 Tab 停靠点，可用方向键在单元格间移动；排序状态稳定，箭头会翻转方向；可用指针或按键调整列宽、选择范围，并且无需依赖项即可虚拟化数千行。
• 日期选择器：日期字段会打开支持完整网格键盘操作的日历对话框。月份会沿着移动方向短距离滑动，在柔和边缘的面板中交叉淡入淡出；也可选择启用日期范围。
• 对话框：从触发器展开的模态框，会随步骤变化平滑调整到适合内容的大小。锁定滚动时不会发生位移，并会在丢弃编辑内容前询问确认。
• 抽屉：从末端边缘滑入的模态面板；在手机上会升起为可向下拖动关闭的底部面板，速度与手指滑动速度一致。主体可滚动，页眉和页脚则保持固定。
• 下拉菜单：带复选框、单选框和子菜单项的菜单按钮。子菜单允许指针沿对角线路径移动，指针和键盘共享同一个高亮项。
• 空状态：用于空列表或空视图的提示信息：包含简洁的等距线稿，边角清晰（堆叠、盒子、文件夹、托盘、放大镜、日历或未连接的线缆），进入视野时绘制一次，并配有标题、一句话说明和一个操作。
• 文件上传：带有固定高度文件列表的拖放区域。每一行都会随上传进度填充，列表会在其高度范围内滚动，因此页面不会移动。
• 行内编辑：文本会在原处变成输入框，字体和位置保持不变，因此字符不会移动。按 Enter 保存，按 Escape 还原，发生错误时则保持编辑状态。
• 键盘按键：按读者键盘上的标识显示按键或快捷键：Apple 设备显示 ⌘K，其他设备显示 Ctrl K。在首次绘制前确定，因此服务端和浏览器显示一致，内容不会移动。
• 列表：由同级条目组成的静态列表、链接列表或按钮列表，每行都是一个 Tab 停靠点，内部不嵌套内容。辅助操作会在悬停或聚焦时显示，不会导致任何内容移动；每行在各种状态下都保持相同高度。
• 导航栏：由图标项组成的紧凑应用导航栏。一个工具提示会在各项之间滑动，平滑调整到每个标签的宽度，并在旁边显示快捷键；凸起的胶囊会滑动到当前页面。
• 数字输入框：带有 − 和 + 按钮的数字微调框，按住按钮时会加快变化。输入超出最小值或最大值范围的数字时，会自动调整到范围内，并显示说明。
• 分页：页码使用固定数量的插槽，因此翻页时控件宽度不会变化。数字会在一个移动的胶囊下方滑动，最后一页的“下一页”仍可聚焦。
• 电话输入框：带有国家/地区选择器的电话字段。输入时号码会自动分组，且光标位置不变；粘贴 +44 号码时会自动选择对应国家/地区，表单会获得 E.164 格式的号码。
• 弹出框：由点击触发、锚定在触发器上的面板。表单会将焦点移入面板，说明内容则会让焦点留在触发器上；关闭时会将焦点移回触发器。
• 进度条：填充部分以弹簧效果移动的线性进度条。不确定状态会让一道光带扫过轨道，分段变体则会显示命名步骤。
• 提示词输入框：随文本增长、按 Enter 发送的聊天输入框，不会在输入法组合期间发送。回复流式传输时，“发送”会变为“停止”，拖入的文件会变为芯片。
• 单选框组：位于字段集中的 Base UI 单选框，可显示为列表或卡片。标记会从中心展开，方向键可进行选择，整个分组只有一个 Tab 停靠点。
• 回复操作：助手回复下方的操作行：复制、点赞、点踩和重试。点踩后可在原处打开“出了什么问题？”输入框。
• 滚动区域：滚动容器仅在仍有更多内容时，才会用蒙版让边缘渐隐。适用于任何背景，并支持键盘滚动。
• 搜索字段：搜索输入框的清除按钮会在已有的预留空间中淡入，因此文本不会移动。按 Escape 会先清除内容，再离开输入框；结果加载时，放大镜会轻轻起伏。
• 分段控件：采用 Tabs 外观的 Base UI 单选框组：清晰的细线轨道，以及一个滑向选中项的扁平胶囊。该分组支持方向键操作和表单值。
• 选择框：只能选择、不能输入的组合框，其触发器会适配所选标签，并平滑变换以显示下一个标签。触摸屏则使用原生选择器。
• 侧边栏：AI 产品的应用侧边栏：包含工作区切换器、带计数和快捷键的项目、可折叠分区、可重命名、置顶和删除的最近聊天列表，以及账户菜单。侧边栏可折叠为带有一个滑动工具提示的图标栏，在手机上则会变成抽屉。
• 骨架屏：按照即将显示的内容塑造占位符，文本行与实际文本等高，因此替换时不会移动任何内容。每块骨架仅对应一个元素；一道柔和的斜向光泽会同时扫过页面上的所有骨架；加载时间短于 300ms 时则不会显示。
• 滑块：标签行下方是宽度稳定的值，凹陷轨道上有强调色范围和凸起的胶囊滑块，滑块会平滑移至目标位置。底层的 Base UI 滑块负责处理指针、键盘和触摸操作。
• 统计项：显示数值、标签以及通过箭头和文字共同说明的变化。提示始终占两行，因此同一行的卡片会保持齐平。
• 开关：带有 role="switch" 的 Base UI 开关：迷你版分段控件，采用凹陷轨道和在其上滑动的凸起胶囊。控件缩放支持两种尺寸，并提供用于保存操作的忙碌状态。
• 标签页：基于 Base UI 构建的标签页，胶囊会从一个标签伸展到另一个标签。可选的 URL 同步支持前进和后退，面板会在原处交叉淡入淡出。
• 文本字段：带标签的输入框，离开时进行验证，值修正后立即清除错误。错误信息占用提示文本的那一行，因此布局不会移动。
• 主题切换：用于切换亮色和暗色主题的图标胶囊：通过一个图形实现太阳圆盘逐渐变为新月，同时第二个圆形滑过。会保存用户选择；尚未选择时跟随系统设置，并在首帧绘制前应用正确主题。
• 提示通知：以命令式方式调用的提示通知会叠成一组，悬停时展开。阅读时计时器会暂停，轻扫即可移除提示通知。
• 工具提示：短暂停留后打开的简短提示；在不同触发器之间移动时会立即打开。键盘焦点会立即打开提示。

Agent 工具包和模块

• Agent 设置：一整套 AI Agent 设置界面，由工具包构建而成：模型、MCP 连接、无需询问即可执行的操作、每日支出上限和记忆。每项更改都会保存到所在行中，固定的分区导航会随着你向下滚动而跟随。
• 授权：当 Agent 请求连接时，MCP 服务显示的授权界面：发起请求的一方、它将获得的权限，以及返回位置。高风险权限默认关闭。
• 代码块：适用于 AI 应用的代码块，流式显示时不会闪烁或跳动。内置复制、自动换行和柔和的令牌着色高亮，无需高亮库。
• 连接：Agent 应用中的 MCP 服务列表：每个服务占一行，配有一个开关和一条状态说明，指出问题及解决方法。通过 URL 添加服务，并交由浏览器处理登录。
• 差异视图：统一差异视图，标记每行中发生更改的部分，并折叠未更改的部分。流式模式下，新行会在出现时淡入。
• Markdown：在模型流式输出时渲染其 Markdown 回复：不会闪现原始星号、反引号或未完成的表格，代码围栏会作为实时代码块展开，回复中的 HTML 会以文本形式显示。
• 消息线程：聊天记录中仅新流式输出的词语会淡入。除非你向上滚动，否则视图会固定在底部，并在每条回复结束时播报一次。
• 模型选择器：紧凑的触发器会调整大小以适应当前模型名称。打开后会显示模型列表，每个模型都有一行说明，所选模型旁会显示手绘勾选标记。
• 登录：无密码登录和注册界面：先输入工作邮箱，再输入一次性验证码，并显示重新发送倒计时；还可选择 OAuth 提供商，并通过工作域名使用 SSO。对于错误、过期和触发速率限制的验证码、被屏蔽的域名及登录失败的提供商，界面都会说明下一步该怎么做。
• 用量计量器：在撰写框工具栏中，以环形图和百分比显示 Agent 上下文窗口或支出预算的使用量。打开后可查看明细，并会在达到上限前发出警告，还提供压缩选项。

许可证

MIT。请参阅 LICENSE。