UI 技能

构建更优 Agent 界面的约定式约束规范。

技术栈

• 在引入自定义值前，必须优先使用 Tailwind CSS 默认配置（间距、圆角、阴影）
• 当需要 JavaScript 动画时，必须使用 motion/react（原 framer-motion）
• 在 Tailwind CSS 中实现入场动画与微交互时，建议使用 tw-animate-css
• 处理类名逻辑时，必须使用 cn 工具函数（即 clsx + tailwind-merge）

组件

• 对于任何涉及键盘操作或焦点行为的元素，必须采用可访问性友好的组件基础库（如 Base UI、React Aria、Radix）
• 必须优先复用项目中已有的组件基础库
• 禁止在同一交互区域内混用不同基础库的组件原语
• 若新组件原语与当前技术栈兼容，建议优先选用 Base UI
• 仅含图标的按钮 必须添加 aria-label 属性
• 禁止手动重写键盘或焦点行为逻辑，除非明确要求

交互

• 执行破坏性或不可逆操作时，必须使用 AlertDialog
• 加载状态呈现时，建议采用结构化骨架屏（structural skeletons）
• 禁止使用 h-screen，应改用 h-dvh
• 固定定位元素 必须尊重 safe-area-inset
• 错误提示 必须紧邻对应操作位置展示
• 禁止阻止用户在 input 或 textarea 元素中粘贴内容

动画

• 禁止添加动画，除非明确要求
• 必须仅对合成器属性（transform、opacity）进行动画处理
• 禁止对布局属性（width、height、top、left、margin、padding）进行动画处理
• 除小范围局部 UI（如文字、图标）外，建议避免对绘制属性（background、color）进行动画处理
• 入场动画 建议使用 ease-out 缓动函数
• 交互反馈动画时长 禁止超过 200ms
• 循环动画在视口外时，必须暂停播放
• 必须尊重系统级偏好设置 prefers-reduced-motion
• 禁止引入自定义缓动曲线，除非明确要求
• 建议避免对大尺寸图片或全屏区域进行动画处理

排版

• 标题 必须使用 text-balance，正文/段落 必须使用 text-pretty
• 数据展示 必须启用 tabular-nums
• 信息密度较高的 UI 场景中，建议使用 truncate 或 line-clamp
• 禁止修改 letter-spacing（即 tracking- 类）——除非明确要求

布局

• 必须采用固定的 z-index 尺度体系（禁用任意值如 z-x）
• 正方形元素 建议使用 size-x，而非组合 w-x + h-x

性能

• 禁止对大面积应用 blur() 或 backdrop-filter 的元素进行动画处理
• 禁止在非活跃动画期间设置 will-change
• 禁止使用 useEffect 处理本可通过渲染逻辑表达的内容

设计

• 禁止使用渐变色，除非明确要求
• 禁止使用紫色或多种颜色混合的渐变
• 禁止将发光效果（glow effects）作为主要交互提示方式
• 如无特殊要求，建议沿用 Tailwind CSS 默认阴影尺度
• 空状态界面 必须提供一个清晰明确的下一步操作入口
• 每视图内，建议限制强调色（accent color）的使用不超过一种
• 引入新颜色前，建议优先复用现有主题色或 Tailwind CSS 颜色 Token