Back to Details

setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Gather design context for this project, then persist it for all future sessions.
setup
writes to 
.better-web-ui.md
as the canonical destination. Older files such as 
.better-ui.md
and 
.impeccable.md
are legacy migration inputs only, not the place new work should keep using.
Consult design principles when turning product values, tone, and repeated tradeoffs into durable design principles that later work can reuse without reopening the same debates. Consult ux strategy when the project needs a clearer strategic frame for target outcomes, user focus, priorities, feasibility, or major risks.
收集当前项目的设计上下文，并将其留存以供后续所有会话使用。
setup
会将内容写入 
.better-web-ui.md
作为标准存储位置。
.better-ui.md
和 
.impeccable.md
等旧文件仅作为遗留迁移输入，不应再用于新的工作内容。
在将产品价值、风格基调及反复权衡的结果转化为持久化设计原则（供后续工作复用，避免重复讨论）时，请参考设计原则。 当项目需要为目标成果、用户关注点、优先级、可行性或重大风险建立更清晰的战略框架时，请参考UX策略。

Step 1: Explore the Codebase

步骤1：探索代码库

Before asking questions, thoroughly scan the project to discover what you can:
  • README and docs: Project purpose, target audience, any stated goals
  • Package.json / config files: Tech stack, dependencies, existing design libraries
  • shadcn project config: 
    components.json
    , shadcn schema usage, CLI-generated configuration, preset clues, Radix vs Base UI choice
  • Styling system: Tailwind, CSS modules, CSS-in-JS, vanilla CSS, utility systems, tokens
  • Component libraries: shadcn/ui, Nuxt UI, Angular Material, custom UI packages, in-house systems
  • Form architecture: TanStack Form, React Hook Form, Formik, vee-validate, Angular forms, custom validation/state wiring
  • Table / data-grid architecture: TanStack Table, AG Grid, framework-native tables, custom table state wiring
  • Long-list / virtualization architecture: TanStack Virtual, react-window, react-virtualized, framework-native virtualization, custom windowing logic
  • Existing components: Current design patterns, spacing, typography in use
  • Brand assets: Logos, favicons, color values already defined
  • Design tokens / CSS variables: Existing color palettes, font stacks, spacing scales
  • Any style guides or brand documentation
Note what you've learned and what remains unclear.
在提问前，彻底扫描项目以挖掘可用信息：
  • README与文档：项目用途、目标受众、已明确的目标
  • Package.json / 配置文件：技术栈、依赖项、现有设计库
  • shadcn项目配置：
    components.json
    、shadcn schema使用情况、CLI生成的配置、预设线索、Radix vs Base UI选择
  • 样式系统：Tailwind、CSS modules、CSS-in-JS、原生CSS、工具类系统、设计令牌
  • 组件库：shadcn/ui、Nuxt UI、Angular Material、自定义UI包、内部系统
  • 表单架构：TanStack Form、React Hook Form、Formik、vee-validate、Angular表单、自定义验证/状态管理
  • 表格/数据网格架构：TanStack Table、AG Grid、框架原生表格、自定义表格状态管理
  • 长列表/虚拟化架构：TanStack Virtual、react-window、react-virtualized、框架原生虚拟化、自定义窗口逻辑
  • 现有组件：当前使用的设计模式、间距、排版
  • 品牌资产：已定义的Logo、图标、颜色值
  • 设计令牌/CSS变量：现有调色板、字体栈、间距尺度
  • 任何风格指南或品牌文档
记录已了解的信息和仍不明确的点。

Step 2: Ask UX-Focused Questions

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

ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
直接询问用户以澄清无法从代码库中推断的信息，仅聚焦于无法从代码库中获取的内容：

Users & Purpose

用户与用途

  • Who uses this? What's their context when using it?
  • Is this aimed at a specific age range, life stage, or audience segment whose habits or needs should shape the UX?
  • Is there a secondary audience or gatekeeper we also need to satisfy, such as parents, teachers, admins, or caregivers?
  • What job are they trying to get done?
  • What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.)
  • 谁会使用该产品？他们使用时的场景是什么？
  • 产品是否针对特定年龄层、人生阶段或受众群体，其习惯或需求应影响UX设计？
  • 是否存在需要兼顾的次要受众或把关人，如家长、教师、管理员或护理人员？
  • 用户希望通过该产品完成什么任务？
  • 界面应唤起用户何种情绪？（如自信、愉悦、平静、紧迫感等）

Brand & Personality

品牌与个性

  • How would you describe the brand personality in 3 words?
  • Any reference sites or apps that capture the right feel? What specifically about them?
  • What should this explicitly NOT look like? Any anti-references?
  • Should the interface feel more serious, playful, elegant, utilitarian, editorial, or something else?
  • Should the language be formal, neutral, or conversational?
  • 用3个词描述品牌个性？
  • 是否有能体现正确风格的参考网站或应用？具体哪些方面符合？
  • 产品明确不能呈现出什么风格？是否有反面参考？
  • 界面应更偏向严肃、活泼、优雅、实用、编辑风格还是其他？
  • 文案语言应正式、中性还是口语化？

Aesthetic Preferences

审美偏好

  • Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
  • Light mode, dark mode, or both?
  • Any colors that must be used or avoided?
  • Should corners feel mostly square, gently rounded, or soft and playful?
  • Should the palette lean warm, cool, or neutral?
  • 对视觉方向有强烈偏好吗？（如极简、大胆、优雅、活泼、科技感、自然风等）
  • 浅色模式、深色模式还是两者兼顾？
  • 必须使用或避免哪些颜色？
  • 边角应主要为方形、微圆角还是柔和活泼的圆角？
  • 调色板应偏向暖色调、冷色调还是中性色调？

Accessibility & Inclusion

无障碍与包容性

  • Specific accessibility requirements? (WCAG level, known user needs)
  • Considerations for reduced motion, color blindness, or other accommodations?
Skip questions where the answer is already clear from the codebase exploration.
  • 有特定的无障碍要求吗？（如WCAG级别、已知用户需求）
  • 是否需要考虑减少动画、色盲适配或其他特殊需求？
跳过从代码库探索中已明确答案的问题。

Implementation Defaults

实现默认配置

  • What framework / runtime should future UI work assume by default?
  • If this is a brand-new project, does the user want a specific styling system?
  • If this is a brand-new project, does the user want a specific component library or block system?
  • Does the project already use a form library or validation stack that later UI work should preserve?
  • Does the project already use a table or data-grid library that later UI work should preserve?
  • Does the project already use a virtualization or windowing library for long lists that later UI work should preserve?
  • If the project already uses 
    shadcn/ui
    , is it mostly using the upstream primitives directly or local wrappers / compositions built on top of them?
  • If relevant, does the project already use 
    shadcn/ui Blocks
    or 
    re-ui
    as accelerators for common sections or flows?
  • If relevant, is the project primarily following a Radix-flavored or Base UI-flavored ecosystem for its headless primitives and composed components?
  • If the project uses shadcn, does it already have a 
    components.json
    file or signs of 
    shadcn create
    / 
    shadcn apply
    customizations that should be treated as the current baseline?
If the project already has a styling system, component library, form stack, or table/grid stack, treat that as the default unless the user explicitly wants to change it.
If the project is new and the user does not specify implementation preferences, use the framework-default matrix from 
framework defaults
 and record the result. When the form architecture is still open in a new React, Vue, Angular, Solid, or Svelte project, default to TanStack Form and record that too. When the table or data-grid architecture is still open in those ecosystems, default to TanStack Table and record that too. When the long-list or virtualization architecture is still open in those ecosystems, default to TanStack Virtual and record that too.
  • 后续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并记录。

Step 3: Write Design Context

步骤3：撰写设计上下文

Synthesize your findings and the user's answers into a 
## Design Context
section:
markdown
undefined
将你的发现和用户的回答整合为
## Design Context
部分：
markdown
undefined

Design Context

Design Context

Users

Users

[Who they are, their context, the job to be done]
[用户群体、使用场景、待完成任务]

Brand Personality

Brand Personality

[Voice, tone, 3-word personality, emotional goals]
[语气、风格、3词品牌个性、情感目标]

Aesthetic Direction

Aesthetic Direction

[Visual tone, references, anti-references, theme]
[视觉基调、参考案例、反面参考、主题]

Implementation Defaults

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]
[检测到或选定的框架、样式系统、组件库默认配置、表单库/验证默认配置、表格/数据网格默认配置、虚拟化默认配置、正在使用的板块加速工具、相关的Radix-vs-Base-UI生态系统偏好、重要的
components.json
/
shadcn create
/
shadcn apply
自定义内容，以及这些配置来自现有代码库、用户明确偏好还是框架默认回退选项]

Design Principles

Design Principles

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

Derive the principles from concrete levers, not vague aspirations. Prefer things like:
- "Establish hierarchy with spacing and weight before adding color"
- "Use warm neutrals and restrained accent color"
- "Favor editorial typography and mostly square corners"
- "Keep one obvious primary action per screen"

The strongest principles explain both what to do and what to avoid. Treat them as default decisions with judgment, not as decorative slogans.

Write this section to `.better-web-ui.md` in the project root. If that file already exists, update the Design Context section in place. If a legacy `.better-ui.md` or `.impeccable.md` file exists, migrate or mirror the Design Context section into `.better-web-ui.md` so better-web-ui has a single canonical project context file going forward.

Legacy files are fallback inputs for migration only. New work should keep `.better-web-ui.md` as the canonical destination.

Make sure the persisted context captures this precedence clearly:

1. detected existing project stack
2. explicit user preference for a new project
3. framework-based fallback defaults

When the distinction matters for React-oriented component ecosystems, also record whether the project is effectively Radix-flavored, Base UI-flavored, or mixed so later design work does not guess.

If shadcn-specific project configuration exists, record it as part of the baseline instead of letting later sessions assume the generic fallback defaults.

Then ask the user whether they'd also like the Design Context appended to `AGENTS.md`. If yes, append or update the section there as well.

Confirm completion and summarize the key design principles that will now guide all future work.
[从对话中提炼的3-5条指导所有设计决策的原则]

从具体可落地的维度提炼原则，而非模糊的愿景。例如：
- "优先通过间距和字重建立层级，再添加颜色"
- "使用暖中性色和克制的强调色"
- "偏好编辑式排版和以方形边角为主"
- "每个页面保留一个清晰的主要操作"

最有效的原则应同时说明要做什么和避免什么。将其视为带有判断空间的默认决策，而非装饰性口号。

将该部分写入项目根目录下的`.better-web-ui.md`文件。若该文件已存在，则更新其中的Design Context部分。若存在遗留的`.better-ui.md`或`.impeccable.md`文件，将Design Context部分迁移或同步至`.better-web-ui.md`，以便better-web-ui拥有唯一的标准项目上下文文件。

遗留文件仅作为迁移的回退输入。新工作应始终将`.better-web-ui.md`作为标准存储位置。

确保留存的上下文明确体现以下优先级：

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

当涉及React相关组件生态系统的区分时，还需记录项目实际是Radix风格、Base UI风格还是混合风格，避免后续设计工作猜测。

若存在shadcn特定的项目配置，将其记录为基准，而非让后续会话采用通用默认回退选项。

随后询问用户是否希望将Design Context附加到`AGENTS.md`中。若同意，在该文件中追加或更新相应部分。

确认完成并总结将指导所有后续工作的关键设计原则。