specsfy-specialist-react

React

适用场景

• 当请求涉及纯 React 中的组件、Hook、Context、表单、列表、effect 或状态时使用（CRA、Vite、与 RSC 无关）。
• 也适用于检查组件为何频繁重新渲染、effect 为何陷入循环，或判断状态应由谁持有。
• 不适用于决定使用 Server Component 还是 Client Component、数据缓存或框架路由；这类情况使用 $specsfy-specialist-nextjs。
• 不适用于选择或调整现成的视觉组件库；这类情况使用 $specsfy-specialist-react-ui-components 和 $specsfy-specialist-ui-design。
• 当组件暴露公共 props 或使用判别联合类型建模状态时，与 $specsfy-specialist-typescript 配合；需要深入审查键盘和屏幕阅读器支持时，与 $specsfy-specialist-web-accessibility 配合。

流程

1. 对于页面或表单，先阅读 INTERFACE.md 和 spec 中的界面章节，再编写代码。确认页面、信息流、字段、校验、打开方式和状态。如果相关材料不存在，返回 $specsfy-specialist-ux-design 和 $specsfy-specialist-ui-design；不要用端点或空组件替代所请求的界面。
2. 确认 React 版本、渲染器、框架（如有）、项目约定以及现有测试策略。如果页面使用 shadcn/ui，先按照 $specsfy-specialist-shadcn-ui 确认已安装的基础 primitives；切勿根据组件外观推断使用 Radix 还是 Base UI。 如果 .specsfy/STACK.md 未声明 React，或项目没有此依赖，请勿开始此实现：转交给与已观察到的技术栈相对应的专家。
3. 对可见状态（常规、加载、空、错误、过时、乐观更新）、产生这些状态的事件，以及每项数据的所有者进行建模。
4. 设计组件树，明确职责并保持 props 精简；优先采用组合（children、插槽），而不是包含数十个布尔标记的组件。
5. 将每项状态放在能够处理它的最近所有者处；在渲染期间推导值，而不是通过 useEffect 同步。
6. 仅在需要与外部系统（DOM、订阅、网络、存储）同步时使用 effects；切勿用它从已有的 props 和 state 计算值。
7. 先实现 HTML 语义和键盘导航，再完善视觉效果；随后通过测试覆盖可观察到的行为。
8. 仅在出现实际性能问题时（profiler、生产指标）衡量性能；然后根据已记录的测量结果使用 memoization 或拆分组件，而不是出于预防目的。
9. 在 INTERFACE.md 中记录每个新建、修改或复用的模块：职责、文件、props、事件、状态、无障碍支持及使用该模块的页面。

规范

• 优先采用组合方式，而不是使用带有大量配置 props 的通用组件；当内部决策树变得复杂时，应拆分组件。
• 在 Laravel 搭配 React 的项目中，使用 shadcn/ui 提供基础组件，使用 ReUI 提供免费的组合组件。页面和路由负责组合 React 区块；网格、表单、筛选器、浮层和可复用卡片应作为自定义组件，并在 INTERFACE.md 中记录。
• 切勿仅为了“保存初始值”而将 prop 复制到 state 中；这会导致数据不同步。应直接读取 prop，或在渲染时派生。
• 不要用 useEffect 计算可从现有 props/state 派生的值；应使用普通变量，或在计算成本较高时使用 useMemo。
• 将 loading、empty、error、stale 和 success 设为明确的 UI 状态，不要用单个 loading 布尔值隐式控制分支。
• 列表中使用来自数据且稳定的 key（id）；如果顺序可能变化、条目可能删除或重排，切勿使用数组索引。
• 根据变化频率和职责隔离每个 Context.Provider——每次按键都会变化的 context 不应包裹整棵组件树。
• 未经事先测量，不要进行 memo 化（memo/useMemo/useCallback）；memo 化会产生比较成本，只有在渲染成本高或已证实渲染频繁时才有收益。
• 根据用户可观察到的行为（文本、角色、状态）编写测试，绝不要测试内部 hook 的实现细节。

反模式

• 使用 effect 将本地状态与 prop 同步 （useEffect(() => setX(prop), [prop])）——这是状态重复的征兆；prop 本身已经是真实数据源。
• 通过 state 变化触发另一个 effect 的 effect 链（“effect chain”）——通常可以合并为单个事件处理器，或直接在渲染时计算。
• useEffect 的依赖数组不完整，却用 // eslint-disable 将警告“屏蔽”——这只是掩盖陈旧闭包的 bug，而非解决问题。
• 用单个 Context 保存应用的所有全局状态（“god context”）——任何变化都会导致整棵组件树重新渲染；优先使用更小的 contexts，或在依赖图变得复杂时使用专门的状态库。
• 将此范围与 $specsfy-specialist-nextjs 的范围混淆：不要为了“解决” hook 错误而级联添加 "use client"，应将交互功能移至正确的叶子组件。

验证

• 使用键盘遍历所有变更部分；当新增角色、焦点行为或播报内容时，使用屏幕阅读器测试。
• 为流程第 2 步中建模的每种状态（nominal、loading、empty、error、stale、optimistic）以及错误恢复编写测试。
• 检查控制台中的 React 警告（key、hook 调用顺序错误、组件卸载后的状态更新），并在使用 SSR 时检查 hydration 警告。
• 仅当存在明确的性能假设时，才运行性能分析或 bundle 分析；附上前后测量结果。
• 没有上述证据，不得宣称组件“无障碍”或“高性能”；没有证据的绝对化表述一律禁止。

相关技能

• $specsfy-specialist-reui，用于免费目录中的 React 和 Tailwind 组合。
• $specsfy-specialist-astro 管理岛屿边界，$specsfy-specialist-shadcn-ui 识别 primitives 基础并管理视觉组件；此技能负责这些组件内部的 React 行为。
• $specsfy-specialist-tailwind-css 负责组件样式，不承担状态、effect 或并发的所有权。
• $specsfy-specialist-nextjs 用于 server/client 边界、数据缓存和路由——此专家负责与框架无关的 React。
• $specsfy-specialist-react-ui-components 和 $specsfy-specialist-ui-design 用于选择并组合现成的视觉库；此专家随后负责状态、effects 和测试的所有权。
• $specsfy-specialist-typescript 用于穷尽地为 props、状态和判别联合类型。
• $specsfy-specialist-web-accessibility 用于深入审核，超出此处验证的基础键盘操作范围。

阅读 references/standards.md，了解状态建模、effects、组合、列表、context、测试和性能，并查看官方来源。