specsfy-specialist-shadcn-ui

shadcn/ui

对于 Promovaweb 的 React 和 Tailwind 界面，此技能负责准备 primitives、components.json、别名和主题。当页面需要 CRUD 或产品组合时，请同时加载 $specsfy-specialist-reui：它会先在此基础上安装免费的 ReUI 组件。

适用场景

• 当项目包含 components.json 或已集成 shadcn 组件，或用户明确要求使用 shadcn/ui 组件（Data Table、Sidebar、Dialog、Form、Chart）时启用。
• 在组合模式（dashboard、表单、overlay）之前，也应启用此技能，以确认项目中的 shadcn/ui 使用的是 Base UI、Radix 还是 React Aria。
• 不要仅为 Tailwind 的 tokens/工具类系统启用此技能；请与 $specsfy-specialist-tailwind-css 搭配使用。
• 当项目使用其他视觉组件库（非 Radix 的可复制组件库）时不要启用；此时请评估是否与 $specsfy-specialist-react-ui-components 和 $specsfy-specialist-ui-design 搭配使用。
• 若要对 Radix primitive 已保障的无障碍能力进行深入审查，请与 $specsfy-specialist-web-accessibility 搭配使用。

流程

1. 在添加任何组件之前，确认框架、shadcn/ui 版本、components.json（导入别名、样式、CSS variables）以及已配置的 registry。
2. 确认正在使用的 primitives 基础：先查看已集成 shadcn 组件的 imports，再通过 manifest 确认。将 @base-ui/react 归类为 Base UI，将 radix-ui 或 @radix-ui/react-* 归类为 Radix，将 react-aria-components 或 @react-aria/* 归类为 React Aria。如果组件使用了多个基础库，或现有线索不足，请按文件记录基础库；在弄清差异之前，不要添加、迁移或重写 primitives。
3. 添加新组件之前，审查项目中已集成的组件及其本地自定义内容，避免重复添加或与已有等效组件产生偏差。
4. 根据所需行为和语义选择已确认基础库中的 primitive（modal dialog、popover 或侧边 sheet），不要根据它与设计的外观相似度来选择。
5. 仅添加必要的最小组件集，并逐行审查生成的代码——这些代码会被复制到项目中，之后由添加者维护。
6. 在适配项目设计时调整 tokens、变体（cva）和组合方式，但不要移除已确认基础库提供的 roles、aria-*、焦点管理或键盘快捷键。
7. 构建组件的所有真实状态（loading、empty、error、disabled、permission denied），而不只是文档中展示的常规状态。
8. 在认为组件已就绪之前，测试键盘操作、焦点、响应式布局、表单提交以及两种主题（浅色/深色）。
9. 对每个新建、修改或复用的 primitive 或区块，更新 INTERFACE.md，包括文件、来源、用途、API、状态、无障碍能力、使用方和扩展指南。

规范

• 不要将 shadcn/ui 视为封装在某个版本化包中的不透明依赖；复制来的代码属于项目，代码中的任何 bug 或无障碍偏差都由团队负责，而不是“库负责”。
• 只使用所识别基础所提供的 API、状态属性和组合方式。Base UI、Radix 和 React Aria 暴露的契约相似，但它们的导入项、props 和属性不能互换。
• 保留基础提供的 ARIA 角色、标签、焦点管理（初始焦点、焦点陷阱和返回触发元素）以及 Escape 行为；视觉自定义不能移除这些行为。
• 在一个位置集中管理主题 token（CSS variables）；切换品牌颜色或调整主题时，绝不要逐个修改几十个组件。
• 在 Promovaweb 的 React 项目中，将 shadcn/ui 与 ReUI 搭配使用：前者提供 primitives，后者提供免费的产品组合。每个页面都是 React 组件的组合，而不是一个单体文件。
• 根据实际用例组合 Data Table（所需的列、排序、筛选、选择、分页），而不是为了“以防万一”导入一个具备所有可能功能的通用组件。
• 让 Sidebar 根据视口调整（在 mobile 上折叠）、适应导航密度，并以明显的方式突出显示当前路由。
• 也要在服务端验证所有表单（客户端验证是 UX，而不是安全措施），并通过 aria-describedby/label 将每条错误消息关联到相应字段。
• 只有在比较 registry 新版本与本地自定义内容之间的 diff 后，才能更新已自定义的组件——不加判断地执行 add 可能会覆盖之前修复的无障碍问题。

反模式

• 因为组件具有相同的公共 API，就认定所有 shadcn/ui 都使用 Radix。这会导致导入项和 props 与 Base UI 或 React Aria 不兼容。
• 导入 shadcn/ui 的 Dialog 后，因认为标题或 aria-describedby“在视觉上多余”而将其删除——这会破坏屏幕阅读器对话框用途的播报。
• 为了“修复”样式而编辑生成的组件文件，而不是调整集中管理的 token/variant——下一个更新组件的人会在不知情的情况下丢失修复。
• 将 Data Table 当作系统中所有表格的通用单一组件，不断累积条件 props，直到组件难以理解——应根据用例，使用 registry 中的构建块组合表格。
• 只在客户端验证表单（在前端使用 schema），而从不在服务端重复验证——任何直接发送到 endpoint 的请求都能绕过表单验证。
• 未事先检查 diff 就对已自定义的组件运行 shadcn add，导致本地所做的无障碍或业务调整被悄然覆盖。

验证

• 添加或修改组件后，运行项目的 typecheck、lint、测试和 build。
• 使用键盘完成完整的导航流程：打开/关闭 overlay、在 Dialog/Sheet 内设置焦点陷阱，以及将焦点返回到打开它的元素。
• 在 mobile 和 desktop、浅色和深色主题、高缩放比例下进行测试，并检查表格单元格和标签中的长内容或截断内容。
• 实际验证页面中使用的表格状态（空、加载中、错误、有数据）、图表状态（无数据、有数据）、表单状态（待处理、错误、成功、失败后重新打开并保留值）以及 sidebar 状态（折叠、展开、路由激活）。
• 不要仅仅因为组件来自 shadcn/ui 就宣称它“无障碍”；任何自定义都必须先通过上述验证，才能作出这种声明。

相关技能

• $specsfy-specialist-astro 负责在将 React primitive 用作 Astro 岛屿时进行集成和水合。
• $specsfy-specialist-tailwind-css 负责支撑组件主题的令牌系统和实用工具。
• $specsfy-specialist-react 负责每个 shadcn/ui primitive 背后的 React 组件的状态逻辑、effects 和测试。
• $specsfy-specialist-typescript 负责为 cva 变体和表单 schema（zod + react-hook-form）提供类型。
• $specsfy-specialist-nextjs 适用于表单提交到 Server Action 的情况——服务端验证和授权属于该技能的职责范围。
• $specsfy-specialist-react-ui-components 和 $specsfy-specialist-ui-design 适用于项目需要更丰富的视觉参考库或页面组合定义的情况。
• $specsfy-specialist-web-accessibility 负责审计已安装基础组件默认提供的功能之外的无障碍支持。
• $specsfy-specialist-application-security 负责服务端表单验证，以及对通过 Server Actions/端点公开的 mutations 进行授权。

修改 shadcn/ui 组件前，请先阅读 references/primitives.md，以确定已安装的基础组件。请阅读 references/standards.md，了解 registry、仪表板、Data Table、表单、overlay 和 chart 的标准及官方来源。