---
name: ui-react
description: 使用 @ug666/ui-react 构建、修改或审查 React UI 时应用。
source: https://ui.ug666.top/ai/react/llms.txt
---

# @ug666/ui-react AI 使用协议

## 组件发现协议

1. 先理解用户要完成的任务、交互行为和信息结构，不只按字面组件名匹配。
2. 从当前适配器的真实组件目录中筛选多个候选组件。
3. 选择存在歧义时，先读取所有候选组件的机器文档，再做决定。
4. 对照用途、禁止场景、公开结构、Props/事件/插槽和无障碍规则。
5. 只从当前包公开入口导入，并严格使用当前类型声明存在的 API。
6. 组合完成后检查响应式、长文本、键盘、焦点、禁用、加载和错误状态。

## 全局使用规则

- 优先使用已有 UG 组件；不要用原生元素和临时样式重造已存在的公共组件。
- 组件视觉使用公开 variant、tone、size、Theme、Surface 和语义 Token，不写固定调色板。
- className/class 只负责页面布局、内容排版和业务语义，不穿透 data-ug-slot 重画组件。
- 不从 src、dist、内部目录或旧项目深路径导入。
- 不根据 React API 推导 Vue API，也不根据 Web API 推导 UniApp API。
- 业务请求、权限、Cookie、路由和持久化留在业务项目，通过 Props、状态、事件和插槽接入。
- 图标操作必须有可访问名称；表单、弹层和导航必须保留组件的键盘与焦点合同。
- 受控值使用当前组件声明的 value/onValueChange 或公开回调。
- 涉及 Hook、Portal 或浏览器状态时保留 client boundary。

## 组件目录

### 基础原语

- [UGButton · 按钮](https://ui.ug666.top/ai/react/components/button.md) — 用于触发主要操作、次级操作与危险操作的按钮组件。
- [UGInput · 输入框](https://ui.ug666.top/ai/react/components/input.md) — 带标签、错误信息与帮助文本的文本输入框。
- [UGLabel · 标签](https://ui.ug666.top/ai/react/components/label.md) — 语义化表单标签，支持控件关联、必填、禁用和尺寸继承。
- [UGCard · 卡片](https://ui.ug666.top/ai/react/components/card.md) — 用于承载模块内容、信息摘要与操作区域的卡片容器。
- [UGBadge · 徽标](https://ui.ug666.top/ai/react/components/badge.md) — 用于状态标记、分类标签与数量提示的轻量徽标。
- [UGTag · 标签](https://ui.ug666.top/ai/react/components/tag.md) — 支持语义变体和关闭操作的内联标签。
- [UGSeparator · 分割线](https://ui.ug666.top/ai/react/components/separator.md) — 用于内容分区的水平或垂直分割线。
- [UGKbd · 键盘按键](https://ui.ug666.top/ai/react/components/kbd.md) — 用于展示快捷键、组合键和键盘操作提示。
- [UGSpinner · 加载指示器](https://ui.ug666.top/ai/react/components/spinner.md) — 用于局部加载和异步等待的旋转指示器。
- [UGLink · 链接](https://ui.ug666.top/ai/react/components/link.md) — 语义化链接组件，支持下划线策略、外链与禁用状态。
- [UGText · 文本](https://ui.ug666.top/ai/react/components/text.md) — 统一正文尺寸、语义色和截断行为的文本组件。
- [UGSpace · 间距](https://ui.ug666.top/ai/react/components/space.md) — 控制子元素方向、对齐、换行和间距的轻量布局组件。
- [UGScrollbar · 滚动条](https://ui.ug666.top/ai/react/components/scrollbar.md) — 使用原生滚动行为并统一滚动条外观的内容容器。
- [UGIndicator · 角标容器](https://ui.ug666.top/ai/react/components/indicator.md) — 将状态点、徽标或操作稳定定位到内容的九个边缘锚点。
- [UGJoin · 连接容器](https://ui.ug666.top/ai/react/components/join.md) — 将按钮、输入框等控件连接为横向、纵向或响应式连续边界。
- [UGStack · 层叠容器](https://ui.ug666.top/ai/react/components/stack.md) — 将多个同尺寸内容按上下或逻辑起止方向视觉层叠。
- [UGRow · 布局](https://ui.ug666.top/ai/react/components/layout.md) — 基于 24 栅格的 Row 与 Col 页面布局组件。
- [UGContainer · 布局容器](https://ui.ug666.top/ai/react/components/container.md) — 由 Header、Aside、Main 与 Footer 组成的应用布局容器。
- [UGConfigProvider · 全局配置](https://ui.ug666.top/ai/react/components/config-provider.md) — 向组件树提供命名空间、尺寸和禁用状态等全局默认值。
- [UGSplitter · 分割面板](https://ui.ug666.top/ai/react/components/splitter.md) — 支持多面板、折叠、指针拖动和键盘调整的分割容器。
- [UGIcon · 图标](https://ui.ug666.top/ai/react/components/icon.md) — 统一尺寸、描边与语义属性的图标容器。

### 表单输入

- [UGTextarea · 文本域](https://ui.ug666.top/ai/react/components/textarea.md) — 支持错误和帮助说明的多行文本输入框。
- [UGSelect · 选择器](https://ui.ug666.top/ai/react/components/select.md) — 支持单选、多选、筛选、分组、清空、键盘操作与原生表单提交的选择器。
- [UGFileInput · 文件选择](https://ui.ug666.top/ai/react/components/file-input.md) — 保留原生文件选择与表单语义，并统一字段状态和 File 列表回调。
- [UGFieldset · 字段分组](https://ui.ug666.top/ai/react/components/fieldset.md) — 使用 fieldset 与 legend 对相关表单控件建立语义分组。
- [UGCheckbox · 复选框](https://ui.ug666.top/ai/react/components/checkbox.md) — 用于多项选择的复选框，支持受控、半选和禁用状态。
- [UGRadio · 单选框](https://ui.ug666.top/ai/react/components/radio.md) — 用于单项选择的单选框与单选框组。
- [UGSwitch · 开关](https://ui.ug666.top/ai/react/components/switch.md) — 用于切换二元状态的开关组件。
- [UGThemeController · 主题控制器](https://ui.ug666.top/ai/react/components/theme-controller.md) — 低层单项控件：将原生单选或复选控件映射到一个 UG Theme data attribute。
- [UGSlider · 滑块](https://ui.ug666.top/ai/react/components/slider.md) — 支持范围、步长和当前值显示的滑块。
- [UGRating · 评分](https://ui.ug666.top/ai/react/components/rating.md) — 使用原生单选组收集离散评分，并支持无伪交互的只读展示。
- [UGCalendar · 日历](https://ui.ug666.top/ai/react/components/calendar.md) — 提供可受控的单月日期选择、范围限制与完整键盘导航。
- [UGNumberInput · 数字输入](https://ui.ug666.top/ai/react/components/number-input.md) — 支持范围、步长和精度控制的数字输入框。
- [UGOTPInput · 验证码](https://ui.ug666.top/ai/react/components/otp-input.md) — 支持键盘导航与粘贴填充的验证码输入框。
- [UGForm · 表单](https://ui.ug666.top/ai/react/components/form.md) — 组织字段语义、布局和状态，支持跨端规则校验、提交守卫与重置的表单系统。

### 导航流程

- [UGTabs · 标签页](https://ui.ug666.top/ai/react/components/tabs.md) — 用于在同级内容之间切换的标签页。
- [UGBreadcrumb · 面包屑](https://ui.ug666.top/ai/react/components/breadcrumb.md) — 面包屑导航组件，用于表达页面层级关系。
- [UGPagination · 分页](https://ui.ug666.top/ai/react/components/pagination.md) — 支持页码、省略号和跳转的分页导航。
- [UGNavigationMenu · 导航菜单](https://ui.ug666.top/ai/react/components/navigation-menu.md) — 支持直接链接与下拉内容的顶部导航菜单。
- [UGSidebar · 侧边栏](https://ui.ug666.top/ai/react/components/sidebar.md) — 面向后台与多模块工作区的侧边导航，支持多级菜单、折叠浮层、可选上下文切换、搜索、品牌与页脚插槽、整数像素宽度、拖拽调整和移动端抽屉。
- [UGDock · 底部操作坞](https://ui.ug666.top/ai/react/components/dock.md) — 提供适配移动端安全区、尺寸与当前页状态的底部导航。
- [UGNavbar · 顶部导航栏](https://ui.ug666.top/ai/react/components/navbar.md) — 用不易偏移的 start、center、end 三段结构组织通用顶部导航。
- [UGSteps · 步骤条](https://ui.ug666.top/ai/react/components/steps.md) — 用于表达多步骤流程进度的步骤条。

### 浮层弹层

- [UGModal · 弹窗](https://ui.ug666.top/ai/react/components/modal.md) — 居中弹窗组件，支持遮罩与键盘关闭。
- [UGDialog · 对话框](https://ui.ug666.top/ai/react/components/dialog.md) — 用于确认关键操作的对话框。
- [UGDrawer · 抽屉](https://ui.ug666.top/ai/react/components/drawer.md) — 从页面边缘滑出的抽屉容器。
- [UGSheet · 抽屉面板](https://ui.ug666.top/ai/react/components/sheet.md) — 适合筛选和补充内容的侧边面板。
- [UGDropdownMenu · 下拉菜单](https://ui.ug666.top/ai/react/components/dropdown.md) — 点击触发的下拉操作菜单。
- [UGContextMenu · 右键菜单](https://ui.ug666.top/ai/react/components/context-menu.md) — 在指定位置展开的右键操作菜单。
- [UGPopover · 弹出框](https://ui.ug666.top/ai/react/components/popover.md) — 用于承载临时上下文内容的通用浮层。
- [UGTooltip · 文字提示](https://ui.ug666.top/ai/react/components/tooltip.md) — 用于补充解释控件含义的悬停提示。
- [UGFab · 浮动操作组](https://ui.ug666.top/ai/react/components/fab.md) — 提供可控的浮动主操作与纵向或扇形快捷动作组。

### 反馈状态

- [UGAlert · 提示](https://ui.ug666.top/ai/react/components/alert.md) — 强调型提示横幅，适合信息提醒、警告与错误反馈。
- [UGToaster · 消息通知](https://ui.ug666.top/ai/react/components/toast.md) — 用于全局成功、错误与提示反馈的通知系统。
- [UGProgress · 进度条](https://ui.ug666.top/ai/react/components/progress.md) — 用于展示任务完成度的线性进度条。
- [UGRadialProgress · 环形进度](https://ui.ug666.top/ai/react/components/radial-progress.md) — 用于在紧凑区域展示任务完成度或指标占比的环形进度。
- [UGSkeleton · 骨架屏](https://ui.ug666.top/ai/react/components/skeleton.md) — 用于加载阶段结构预览的骨架屏。
- [UGEmptyState · 空状态](https://ui.ug666.top/ai/react/components/empty-state.md) — 用于无数据场景的空状态组件。

### 数据展示

- [UGTable · 表格](https://ui.ug666.top/ai/react/components/table.md) — 用于后台列表和对比信息的数据表格。
- [UGDescriptions · 描述列表](https://ui.ug666.top/ai/react/components/descriptions.md) — 以键值对形式展示结构化信息。
- [UGStatistic · 统计数字](https://ui.ug666.top/ai/react/components/statistic.md) — 用于展示核心指标、趋势和变化文案。
- [UGDataPanel · 数据面板](https://ui.ug666.top/ai/react/components/data-panel.md) — 用于统一数据块的标题、操作区、内容布局以及加载、空和错误状态。
- [UGStatisticCard · 指标卡片](https://ui.ug666.top/ai/react/components/statistic-card.md) — 用于在卡片内组合核心指标、语义图标和变化说明。
- [UGTrendChart · 趋势图](https://ui.ug666.top/ai/react/components/trend-chart.md) — 用于以轻量折线和面积展示连续数据变化。
- [UGDonutChart · 环形占比图](https://ui.ug666.top/ai/react/components/donut-chart.md) — 用于展示多个分类的数量、占比和总计。
- [UGRankingList · 排名进度](https://ui.ug666.top/ai/react/components/ranking-list.md) — 用于在统一刻度下比较多项数值与排名。
- [UGBarChart · 柱状图](https://ui.ug666.top/ai/react/components/bar-chart.md) — 用于按分类比较数值，并提供悬浮与键盘明细。
- [UGGaugeChart · 仪表盘](https://ui.ug666.top/ai/react/components/gauge-chart.md) — 用于展示区间内的当前值、完成程度和目标刻度。
- [UGStackedBarChart · 堆叠条形图](https://ui.ug666.top/ai/react/components/stacked-bar-chart.md) — 用于比较多个对象的组成结构和分类占比。
- [UGHeatmapChart · 热力图](https://ui.ug666.top/ai/react/components/heatmap-chart.md) — 用于以二维色阶展示活跃度、密度和时间分布。
- [UGRadarChart · 雷达图](https://ui.ug666.top/ai/react/components/radar-chart.md) — 用于比较多个对象在同一组维度上的能力轮廓。
- [UGAvatar · 头像](https://ui.ug666.top/ai/react/components/avatar.md) — 头像组件，支持图片回退、尺寸变化与首字母占位。
- [UGAvatarGroup · 头像组](https://ui.ug666.top/ai/react/components/avatar-group.md) — 将多个头像以堆叠方式展示，超出数量时显示汇总。
- [UGAccordion · 折叠面板](https://ui.ug666.top/ai/react/components/accordion.md) — 手风琴折叠组件，支持单选与多选展开模式。
- [UGCollapsible · 单项折叠](https://ui.ug666.top/ai/react/components/collapse.md) — 基于 details 与 summary 原生语义控制单块补充内容。
- [UGList · 列表](https://ui.ug666.top/ai/react/components/list.md) — 为文件、成员、通知和对象摘要提供稳定的媒体、内容与操作列布局。
- [UGCarousel · 轮播](https://ui.ug666.top/ai/react/components/carousel.md) — 使用原生滚动吸附展示图片或内容，并提供可访问控制与受控索引。
- [UGTimeline · 时间线](https://ui.ug666.top/ai/react/components/timeline.md) — 以有序列表展示事件、审批和发布记录的先后关系。

## 高级组合

- `UGAdminShell` — 后台应用壳：侧栏、顶栏、内容容器和移动端抽屉状态。 只接收 navItems、slot、状态和回调，不读取登录态，不绑定项目路由。
- `UGAppTabs` — 应用页面标签：浏览器式当前页、关闭操作和容器内横向滚动。 只接收页签项、当前值和回调；路由、持久化、权限与页面缓存由应用负责。
- `UGDataTable` — 后台数据表格：统一加载、失败、空状态、排序、选择、操作列与分页结构。 只接收记录、列、状态与回调；请求、筛选、权限、路由和批量业务操作由应用负责。
- `UGThemeConfigurator` — 完整外观配置：人群方案、视觉主题、模式、品牌色、布局与细节。 完全受控，不访问存储、接口、Cookie、权限或业务路由；应用字段通过扩展区域插入。
- `UGThemeConfiguratorDialog` — 标准居中外观设置弹窗：组合完整配置面板、可选实时预览与重置操作。 复用 Modal 的焦点和键盘合同；主题值、打开状态、预览内容与重置行为全部由调用方控制。
- `UGPageHeader` — 后台页面页头：标题、说明、状态、元信息和操作区。 只负责布局骨架，业务文案、按钮和状态由调用方传入。
- `UGQuickAccess` — 后台首页和工作区的快捷入口：统一导航卡片、响应式网格与交互状态。 只接收标题、说明、图标、地址和选择事件；路由、权限、接口与业务行为由调用方处理。
- `UGCopyField` — 只读字段复制：URL、Token、ID 等。 用于复制浏览器端可访问的只读文本。
- `UGConfirmDialog` — 危险操作和关键流程确认。 业务层控制 open/loading/onConfirm，组件不处理 API。
- `UGPromptComposer` — 会话输入：受控输入、发送/停止、Enter 语义、工具和附件扩展位。 只处理输入与键盘合同，不调用 AI 接口、不保存附件、不包含模型或业务文案。
- `UGMessage` — 会话消息与消息列表：角色、状态、流式标识、内容插槽和跟随输出滚动。 正文完全由调用方渲染，不内置 Markdown、任务 Store 或媒体协议。
- `UGAttachmentList` — 附件预览：状态、元信息、移除和键盘可达操作。 只接收附件展示数据与回调，不读取文件、不上传、不持久化。
- `UGConversationList` — 会话导航：当前项、切换、数量、操作扩展和窄屏横向布局。 只接收会话展示数据和选择回调，不绑定路由、存储或业务状态。
- `UGLandingHero` — 展示页首屏骨架。 媒体、文案和操作入口都由业务页面传入。
- `UGFeatureGrid` — 能力点和功能模块网格骨架。 只负责结构化展示，不内置产品文案和业务跳转。