setup

收集此项目的设计背景信息，然后将其保存，以供所有未来会话使用。

setup 会将内容写入 .better-react-web-ui.md，这是规范目标文件。.better-web-ui.md、.better-ui.md 和 .impeccable.md 等旧文件仅用作迁移输入，不应再作为新工作的保存位置。

写入前，请遵循项目背景信息，确定所属应用并继承默认设置。现有的 DESIGN.md 文件仍是设计系统的输入。请链接到其中的设计令牌，不要将其复制到另一个与之竞争的清单中。

将产品价值观、语气和反复出现的权衡转化为可长期沿用的设计原则时，请参阅设计原则，以便后续工作可以直接复用这些原则，而不必重新讨论相同的问题。 如果项目需要更清晰的战略框架来明确目标成果、用户重点、优先级、可行性或主要风险，请参阅 UX 策略。

第 1 步：探索代码库

请遵循背景信息收集协议。复用明确的指示、记录在案的受众和品牌背景信息，以及之前的回答。在询问尚未明确的信息前，先检查相关项目文件：

• README 和文档：项目用途、目标受众，以及任何已说明的目标
• Package.json / 配置文件：React 框架、依赖项、现有设计库
• shadcn 项目配置：components.json、shadcn schema 用法、CLI 生成的配置、预设线索、Radix 与 Base UI 的选择
• 样式系统：Tailwind 版本、Tailwind 配置、主题变量、工具类约定和设计令牌
• 组件库：shadcn/ui、ReUI、shadcncraft、Kibo UI、Basecn、Tailark、shadcnblocks、React Bits、Animate UI、Animata、Magic UI、Motion Primitives、Efferd、Billing SDK、blocks.so、coss/ui、Better Auth UI、Smooth UI、TripleD UI、shadcn-map、mapcn、c15t、PatternCraft、自定义 React UI 包、内部系统
• 表单架构：TanStack Form、React Hook Form、Formik、自定义 React 验证／状态连接方式
• 表格／数据网格架构：TanStack Table、AG Grid、框架原生表格、自定义表格状态连接方式
• 长列表／虚拟化架构：TanStack Virtual、react-window、react-virtualized、框架原生虚拟化、自定义窗口化逻辑
• 现有组件：当前使用的设计模式、间距和排版
• 品牌素材：Logo、网站图标、已定义的颜色值
• Tailwind 主题令牌／变量：现有的调色板、字体系列、间距比例
• 任何样式指南或品牌文档

记录已了解到的信息以及仍不明确的内容。

第 2 步：提出以 UX 为重点的问题

只询问影响重大的信息缺口。以下问题供挑选参考，并非必须逐项询问。如果用户将创意决策交由你处理，请记录你的假设并继续。不要编造用户引言：

用户与目的

• 谁会使用它？他们在什么情境下使用？
• 它是否面向某个特定年龄段、人生阶段或受众群体，其习惯或需求会影响 UX 设计？
• 是否还有需要兼顾的次要受众或把关人，例如家长、教师、管理员或照护者？
• 他们想完成什么任务？
• 界面应唤起哪些情绪？（信心、愉悦、平静、紧迫感等）

品牌与个性

• 用 3 个词描述品牌个性，你会怎么说？
• 有没有能体现理想风格的参考网站或应用？它们具体有哪些特点？
• 哪些风格明确不应采用？有没有反面参考？
• 界面应该更严肃、活泼、优雅、实用、编辑风，还是其他风格？
• 语言风格应该正式、中性还是轻松自然？

审美偏好

• 对视觉风格有强烈偏好吗？（极简、大胆、优雅、活泼、技术感、自然等）
• 使用浅色模式、深色模式，还是两者都支持？
• 有必须使用或应避免的颜色吗？
• 圆角应以直角为主、略微圆润，还是柔和活泼？
• 配色应偏暖色、冷色，还是中性色？

无障碍与包容性

• 有具体的无障碍要求吗？（WCAG 等级、已知用户需求）
• 对减少动态效果、色盲或其他辅助需求有何考虑？

如果从代码库探索中已经能明确答案，请跳过相关问题。

实现默认设置

• 后续 UI 工作默认应采用什么 React 框架 / 运行时？
• 如果这是一个全新项目，用户是否希望使用特定的 Tailwind 设置？
• 如果这是一个全新项目，用户是否希望使用 shadcn/ui、ReUI、shadcncraft、Kibo UI、Basecn、Tailark、shadcnblocks、React Bits、Animate UI、Animata、Magic UI、Motion Primitives、Efferd、Billing SDK、blocks.so、coss/ui、Better Auth UI、Smooth UI、TripleD UI、shadcn-map、mapcn、c15t、PatternCraft 或其他 React 组件库？
• 项目是否已使用表单库或验证技术栈，后续 UI 工作应予以保留？
• 项目是否已使用表格或数据网格库，后续 UI 工作应予以保留？
• 项目是否已使用虚拟化或窗口化库来处理长列表，后续 UI 工作应予以保留？
• 如果项目已使用 shadcn/ui，主要是直接使用上游基础组件，还是使用基于它们构建的本地封装 / 组合组件？
• 如果适用，项目是否已使用 shadcn/ui Blocks、ReUI、shadcncraft、Kibo UI、Basecn、Tailark、shadcnblocks、React Bits、Animate UI、Animata、Magic UI、Motion Primitives、Efferd、Billing SDK、blocks.so、coss/ui、Better Auth UI、Smooth UI、TripleD UI、shadcn-map、mapcn、c15t 或 PatternCraft，来加速常见页面区块或流程的开发？
• 如果适用，项目的无头基础组件和组合组件主要采用 Radix 风格还是 Base UI 风格的生态？
• 如果项目使用 shadcn，是否已有 components.json 文件，或有 shadcn create / shadcn apply 自定义配置的迹象，应将其视为当前基线？

如果项目已有 Tailwind 设置、受支持的组件库、表单技术栈或表格 / 网格技术栈，除非用户明确希望更换，否则将其视为默认设置。

如果项目是新项目，且用户未指定实现偏好，请采用 framework defaults 中的框架默认设置矩阵，并记录结果。在受支持的 React 项目中，如果表单架构尚未确定，默认采用 TanStack Form，并记录下来。如果表格或数据网格架构尚未确定，默认采用 TanStack Table，并记录下来。如果长列表或虚拟化架构尚未确定，默认采用 TanStack Virtual，并记录下来。

步骤 3：编写设计上下文

综合你的调查结果和用户的回答，在 ## Design Context 部分中写入：

## Design Context

### Users
[Who they are, their context, the job to be done]

### Brand Personality
[Voice, tone, 3-word personality, emotional goals]

### Aesthetic Direction
[Visual tone, references, anti-references, theme]

### Implementation Defaults
[Detected or chosen React framework, Tailwind setup, component library defaults, form library / validation defaults, table/data-grid defaults, virtualization defaults, any block accelerators in use, any relevant Radix-vs-Base-UI ecosystem preference, any important `components.json` / `shadcn create` / `shadcn apply` customizations, and whether they came from the existing codebase, explicit user preference, or framework fallback defaults]

### Design Principles
[3-5 principles derived from the conversation that should guide all design decisions]

从具体的可调整因素中提炼原则，而不是空泛的愿景。优先考虑以下内容：

• “先通过间距和字重建立层级，再添加颜色”
• “使用温暖的中性色，并克制地运用强调色”
• “采用编辑式排版，边角大多保持方正”
• “每个屏幕只保留一个明确的主要操作”

最有力的原则既说明该怎么做，也说明应避免什么。将这些原则视为可酌情调整的默认决策，而非装饰性的口号。

将此部分写入所属应用根目录下的 .better-react-web-ui.md。对于单应用仓库，该目录就是仓库根目录。在原位置更新已有的 Design Context 部分，并保留无关部分。从同一应用范围内迁移相关的旧版上下文，但不要删除原内容。将共享默认设置保留在仓库根目录，并将应用特有的差异放在子文件中。

旧版文件仅作为迁移时的备用输入。新工作应将 .better-react-web-ui.md 作为规范目标文件。

确保持久化的上下文清楚体现以下优先顺序：

1. 检测到的现有项目技术栈
2. 用户对新项目的明确偏好
3. 基于框架的回退默认设置

如果这一区别会影响面向 React 的组件生态系统设计，还应记录项目实际采用的是 Radix 风格、Base UI 风格，还是混合风格，以免后续设计工作靠猜测。

如果项目中存在 shadcn 专属配置，应将其记录为基线，而不是让后续会话误以为应使用通用回退默认设置。

将 .better-react-web-ui.md 作为其所属应用的上下文入口。保留指向现有权威设计文档的链接。仅在用户要求持久化页面决策时，才添加可选的页面简报。只有在用户提出要求时才更新 AGENTS.md，并使用指针，而不是重复上下文。

确认已完成，并总结今后所有工作将遵循的关键设计原则。