用途：为 packages/* 下的 React 前端代码（Workshop SPA、gatekeeper 管理 SPA、@gadgets/ui）提供统一约定，覆盖创建、修改、移动和评审场景。包级 AGENTS.md 可补充产品专属规则，但不替代本约定。
主要能力： 一、组织与归属。按产品归属而非实现类型组织代码；功能目录承载产品行为，可包含组件、Hook、测试和工具。目录先保持扁平，不要为分类而新增 components/、hooks/、helpers/、tests/ 子目录；只有当多个文件形成连贯单元或扁平目录难以浏览时，才引入按职责命名的子系统目录。组件文件用 PascalCase，Hook 和非组件模块用 camelCase，*.test.ts(x) 与被测对象同目录，仍保持一文件一组件。代码只在归属需要时才上提：功能内共享放最近公共功能目录；与功能无关且跨同应用不相关区域共享可放该应用的 components/ 或 hooks/；独立前端共享的运行时 UI 放 @gadgets/ui。 二、组件与 Hook。当组件拥有有意义的状态、副作用、交互、无障碍行为或可复用职责，或代表独立 UI 关注点，或使父组件主流程难以阅读时，才拆分为独立组件；小型无状态渲染辅助保持私有。Hook 用于拥有连贯行为或外部同步生命周期，而非单纯缩短文件。优先使用具名箭头函数组件与 Hook，直接标注 props 类型而非 React.FC；memo、forwardRef 等包装需保留稳定的 DevTools 名称。 三、组件 API。仅在同时有效时用对象或可辨识联合表示 props；受控值需配变更回调，否则暴露非受控初始值，不要用 Effect 把受控 prop 拷贝进本地状态。回调命名为 on<Action>，传领域值而非 React setter 或浏览器事件。children、slots、variants、className、DOM 透传和命令式 ref 仅按当前调用方需要添加。上下文用于认证、主题、提示等应用级值，实例级数据与操作通过 props 传递。 四、Kumo 与样式。默认使用 Kumo 组件和语义 token；创建控件或交互模式前先查 Kumo 和 @gadgets/ui。除非用户明确要求，不要添加自定义颜色字面量、任意 Tailwind 颜色、功能局部 token 系统或对 Kumo 表面、边框、文本、状态、焦点等 token 的本地替代。Tailwind 适用于结构、间距、尺寸、定位、响应式和排版；仅在 Kumo 与工具无法表达技术行为时用自定义 CSS。全局 Kumo token 主题属应用级决策，普通功能工作不得改动。 五、React。Effect 仅用于与外部系统同步，不用于派生状态或编排交互；渲染数据在渲染期间计算，状态靠近所有者，身份重置优先用 key，合适的外部存储用 useSyncExternalStore。取数或订阅的 Effect 必须清理过期工作并可在重启后保持正确，避免 Effect 链，也不要用 Effect 同步两份可派生的状态。没有具体身份或性能需求时不要加 useMemo 或 useCallback。保持键盘行为、焦点管理、可访问名称、播报以及鼠标、触摸、混合输入一致；RPC 桩遵循根 AGENTS.md 的释放与 React 状态规则。 六、注释与测试。注释应说明非显然约束、安全或性能原因及有意偏离约定的地方，不叙述下一行代码，约束变化时更新或删除。测试应保护可观察行为、产品规则、无障碍、状态转换、竞态和失败路径，不为覆盖率测试框架自身行为，避免只耦合实现细节的断言；仅保持行为的移动应只改导入，仅在拆分暴露重要未测逻辑时补聚焦覆盖。
限制：上述内容为约定性指导，不包含自动执行工具、代码生成命令或平台兼容性说明；未提供具体项目路径示例、版本要求或性能基准。