setup

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

setup 会将内容写入 .better-web-ui.md，作为规范保存位置。.better-ui.md 和 .impeccable.md 等旧文件仅用于迁移，不应继续作为新工作的保存位置。

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

第 1 步：探索代码库

在提问之前，先全面扫描项目，尽可能了解以下信息：

• README 和文档：项目用途、目标受众，以及明确说明的目标
• Package.json / 配置文件：技术栈、依赖项和现有设计库
• shadcn 项目配置：components.json、shadcn schema 的使用方式、CLI 生成的配置、预设线索，以及 Radix 与 Base UI 的选择
• 样式系统：Tailwind、CSS modules、CSS-in-JS、原生 CSS、工具类系统、tokens
• 组件库：shadcn/ui、Nuxt UI、Angular Material、自定义 UI 包、内部系统
• 表单架构：TanStack Form、React Hook Form、Formik、vee-validate、Angular forms、自定义验证／状态处理
• 表格／数据网格架构：TanStack Table、AG Grid、框架原生表格、自定义表格状态处理
• 长列表／虚拟化架构：TanStack Virtual、react-window、react-virtualized、框架原生虚拟化、自定义窗口化逻辑
• 现有组件：当前使用的设计模式、间距和字体排版
• 品牌素材：Logo、favicon、已定义的颜色值
• 设计 tokens / CSS 变量：现有的调色板、字体栈、间距比例
• 任何样式指南或品牌文档

记录你了解到的信息，以及尚不明确的内容。

第 2 步：提出以 UX 为核心的问题

直接向用户提问，澄清无法推断的信息。只关注无法从代码库中推断的问题：

用户与目的

• 谁会使用这个产品？他们使用时处于什么情境？
• 这个产品是否面向特定年龄段、人生阶段或受众群体，需要根据他们的习惯或需求来设计 UX？
• 是否还有需要兼顾的次要受众或把关者，例如家长、教师、管理员或照护者？
• 他们想完成什么任务？
• 界面应带来什么感受？（自信、愉悦、平静、紧迫感等）

品牌与个性

• 用 3 个词描述品牌个性。
• 有没有能体现理想感觉的参考网站或应用？具体喜欢它们哪些方面？
• 明确不希望界面呈现什么样子？有没有反面参考？
• 界面应更偏严肃、活泼、优雅、实用、编辑风格，还是其他风格？
• 文案应采用正式、中性还是对话式的语气？

美学偏好

• 对视觉方向有没有明确偏好？（极简、大胆、优雅、活泼、技术感、自然感等）
• 采用浅色模式、深色模式，还是两者都支持？
• 有没有必须使用或应避免的颜色？
• 圆角应以直角为主、略带圆润，还是柔和活泼？
• 调色板应偏暖、偏冷还是中性？

无障碍与包容性

• 有没有特定的无障碍要求？（WCAG 级别、已知用户需求）
• 是否需要考虑减少动态效果、色盲或其他适配需求？

对于在代码库探索中已经能明确回答的问题，跳过不问。

实现默认项

• 后续 UI 工作默认应采用什么框架／运行时？
• 如果这是一个全新项目，用户是否希望使用特定的样式系统？
• 如果这是一个全新项目，用户是否希望使用特定的组件库或区块系统？
• 项目是否已经在使用表单库或验证方案，后续 UI 工作应予以保留？
• 项目是否已经在使用表格或数据网格库，后续 UI 工作应予以保留？
• 项目是否已经在使用虚拟化或窗口化库来处理长列表，后续 UI 工作应予以保留？
• 如果项目已经在使用 shadcn/ui，它主要是直接使用上游基础组件，还是使用基于这些组件构建的本地封装／组合组件？
• 如果相关，项目是否已经在使用 shadcn/ui Blocks 或 re-ui 来加速构建常见区块或流程？
• 如果相关，项目的无头基础组件和组合组件主要遵循 Radix 风格还是 Base UI 风格的生态？
• 如果项目使用 shadcn，是否已有 components.json 文件，或存在 shadcn create／shadcn apply 自定义配置的迹象，这些都应视为当前基线？

如果项目已经有样式系统、组件库、表单方案或表格／数据网格方案，就将其视为默认选项，除非用户明确希望更改。

如果项目是新的，且用户没有指定实现偏好，请采用 framework defaults 中的框架默认项矩阵，并记录结果。如果在新的 React、Vue、Angular、Solid 或 Svelte 项目中，表单架构尚未确定，则默认使用 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 framework, styling system, 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-web-ui.md。如果该文件已存在，则原位更新 Design Context 部分。如果存在旧版 .better-ui.md 或 .impeccable.md 文件，则将 Design Context 部分迁移或镜像到 .better-web-ui.md，确保今后 .better-web-ui.md 是唯一的规范项目上下文文件。

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

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

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

如果 React 风格的组件生态之间的区别会产生影响，还应记录项目实际采用的是 Radix 风格、Base UI 风格还是混合风格，以免后续设计工作凭空猜测。

如果存在 shadcn 特定的项目配置，则将其记录为基线，而不是让后续会话默认采用通用回退默认项。

然后询问用户是否也希望将 Design Context 添加到 AGENTS.md 中。如果用户同意，则在那里追加或更新该部分。

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