UI组件模式选型与主题

解决了什么

组件化做到一半很容易陷入泥潭：一个 Card 同时处理布局、样式、拖拽和表单联动，props 堆到十五个；颜色写死在 JSX 里，换肤只能逐个替换；键盘支持和 ARIA 在验收前才想起补。问题不在"没有组件"，而在缺少一套贯穿选型、组合与主题的约束。

技能如何工作

这套指南把 UI 设计拆成五个可执行的原则：组合优于继承——用 props 配置、children 传内容、slot 做变体，而不是层层继承；服务端优先——Server Components 为默认，只有需要状态和事件时才下沉到 Client；token 驱动主题——所有颜色、间距、字号走 CSS Custom Properties，禁止硬编码；可访问性即架构——ARIA 角色、键盘导航、焦点管理写进组件定义而非后补；可组合原语——Button、Input、Text 保持无样式，设计系统组件在其上构建。

落到具体规则：每个组件单文件、单一职责，props 用 TypeScript 显式定义并以 Zod 校验；复杂 UI 拆成复合组件（Card / Dialog / Tabs）；变体用 cva 而非条件类名；超过 10 个 props 就拆分。主题采用三层 token：全局 token（color.blue.500）承载原始值，语义 token（color.primary）绑定用途，组件 token（button.bg）做细粒度控制；切换通过 html 上的 data-* 属性完成，不走 JS 运行时。表单以 Zod schema 为单一数据源，配合 React Hook Form 走非受控渲染；字段结构固定为 Label > Input > Helper Text > Error。响应式优先容器查询，移动端为聊天面板、侧边栏提供专用变体，触控目标不小于 44×44px。

适用边界

• 仅作设计指南，不安装依赖、不改系统权限、不创建持久任务。
• 涉及发送、发布、删除、付款或部署时，先展示目标与影响并等待确认。
• 凭据只用于用户指定的官方服务，不回显、不记录、不转发。
• 命令与代码默认仅供参考，需用户明确要求且目标清晰时才执行。