add-ui

必须的准备工作

用户使用 /add-ui 启动此工作流。add-ui 是此存储库中的规范技能名称。有些宿主可能会提供友好的 /add 别名，但文档、封装和源文件仍应使用技能名称 add-ui。

阅读 frontend-design，并遵循其中的上下文收集协议。复用已有上下文，仅询问重要信息缺失之处。

如果请求是创建全新的落地页、营销页面或几个不同方向，且尚未确定审美风格，请使用 frontend-design 中 design directions 所列的获准风格选择规则。选择符合产品创意和品牌背景的方向，不要凭空杜撰模糊的风格标签。

如果是在具有成熟视觉体系的现有项目中工作，应优先保留该体系，并让各个选项有明显区别，同时避免悄悄重塑产品品牌。

对于落地页变体，请使用 landing-page storytelling，在用户设定的结构限制内比较开场、导航、证据顺序和结尾。

此外，还要收集生成可用代码所需的最少实现细节：

• React 框架 / 运行时（React、Next.js、React Router、TanStack Start、Vite React 或使用 React islands 的 Astro）
• Tailwind 配置和主题令牌约定
• 目标插入位置（新路由、现有页面、共享组件文件夹、设计系统区域）
• 这是全新产物还是对现有产物进行重新设计
• 用户需要的是区块、页面、流程、外壳还是独立组件
• 质量标准（快速草稿、可用于生产环境、旗舰级）

如果请求是重新设计现有产物，还要确认：

• 哪些部分必须保留辨识度（内容区块、区块顺序、交互模型、熟悉的操作方式、品牌元素）
• 哪些部分可以调整（风格、颜色、文案、字体排版、媒体呈现方式、信息密度、细节风格）
• 用户希望主要进行稳妥的迭代、广泛探索并比较，还是尝试一两个突破性方向

确定实现默认值时，请按以下优先级顺序操作：

1. 优先检测并匹配现有项目的 React 框架、Tailwind 配置和组件库
2. 如果是全新项目，且用户明确指定了受支持的 React 组件库，则使用该组件库
3. 如果是全新项目，且用户未作指定，则使用 frontend-design 中定义的框架默认值

另请参阅 component library integration，以判断所请求的产物应以基础组件、可复用模式还是区块加速器为主导。

只询问缺失的信息。如果能从代码库推断出技术栈，就直接推断。

根据需要参阅以下参考资料：

• artifact taxonomy
• component library integration
• variation quality bar
• preview and apply patterns
• request mapping heuristics
• examples and command naming

在有助于提升不同宿主和 Agent 之间的一致性时，请使用以下确定性辅助资源：

• comparison table template
• component library integration checklist
• variant naming scheme
• preview page checklist
• apply / cleanup checklist

---

直接实现用户请求的产物。用户要求提供备选方案时，应生成有实质差异的方向，并帮助用户进行比较和整合。

这包括新增 UI和重新设计现有 UI。 当请求是重新设计现有页面、区块、流程、外壳或组件时，默认应保留该作品可识别的基本结构，除非用户明确要求重新构建结构。实际操作中，通常意味着：

• 如果核心信息架构、内容区块和顺序已经能满足目标，就保持不变
• 除非交互方式明显存在问题，或用户要求进行更大幅度的 UX 调整，否则保留熟悉的交互和操作提示
• 通过字体、颜色、文案表达方式、媒体呈现、细节风格、间距节奏和重点策略来演进视觉系统
• 清楚说明各个方案中哪些内容保持不变，哪些内容有所改变

如果某个变体有意在结构上进行更大幅度的尝试，应明确标注为突破性方案，而不是悄然彻底推翻现有页面。

此技能适用于以下类型的请求：

• 营销与变现界面：主视觉区、功能介绍、定价、用户评价、常见问题、行动号召、品牌 Logo 墙、图库、博客、关于我们、联系方式、套餐选择器、升级弹窗、付费墙
• 导航与外壳：导航栏、页脚、仪表板外壳、新手引导动态流、设置、卡片式导航
• 身份验证与账户：登录、注册、忘记密码、重置密码、验证邮箱、双重身份验证
• 电商：产品概览、产品分类、产品列表、筛选器、购物车、结账、评价、订单摘要、礼品卡
• 数据界面：图表、小组件、数据表格、表单、对比视图、便当盒网格、时间线、仪表板

此列表仅作示例，并非详尽无遗。

核心操作规则

1. 生成真正不同的方案，而非只换颜色

   • 各个变体必须在变体质量标准所列的相关维度中，至少有两项不同。同时保留固定结构和品牌约束。
   • 只更改调色板、圆角或图标集，不算新的设计方向。

2. 从用户要完成的任务出发

   • 定价区块不只是几张卡片。
   • 登录页面不只是几个输入框。
   • 仪表板外壳不只是界面装饰。
   • 每个变体都应围绕用户的主要任务和产品调性展开。
   • 对于宽泛的新项目营销请求，应选择符合公司／产品构想的获批设计方向，并说明其适配之处。

3. 优先使用基于源码的预览，而非临时 DOM 技巧

   • 如果宿主支持预览，应生成真实的组件／页面／路由，供用户检查和选择。
   • 不要将类似浏览器扩展的 DOM 注入作为主要工作流。这种方式很脆弱，也无法生成易于维护的源代码。

4. 坚持鲜明的设计主张

   • better-react-web-ui 致力于打造独特且品味出众的 React 和 Tailwind 输出。
   • 不要退回到最稳妥、最普通的 SaaS 通用布局。
   • 使用前端设计指导来发现具体的质量问题，同时保留明确的品牌选择。

5. 考虑集成

   • 遵循项目现有的代码规范和文件夹结构。
   • 如果项目已有共享 UI 系统，应接入该系统，而不是随意创建一次性基础组件。
   • 如果各个变体中出现重复结构，应提取合理的共享组件。

6. 尊重保留精髓的要求

   • 如果用户说要保留精髓，就应保留可识别的结构、关键部分和叙事流程，除非用户明确允许更彻底的改造。
   • 设计方向依然可以通过字体、颜色、文案、信息密度、佐证呈现、表面样式、媒体方向和行动重点实现真正的差异化。
   • 不要把“给我几个选项”误解为允许舍弃现有架构。

选择交付模式

当用户只要求一个产物、指定方向、要求应用已选方案，或将设计决策交由你处理时，默认直接实现。对下面的请求进行分类，然后在目标位置实现并验证结果。跳过备选文件、对比表和预览选择器。报告已更改的文件和检查结果。

仅当用户要求提供备选方案或进行比较时，才进行探索。遵循用户要求的数量。如果未指定数量，则提供五种方向。其余工作流介绍探索流程。

探索工作流

1. 对请求进行分类

使用产物分类法判断用户要求的是一个区块、页面、流程、外壳，还是数据／内容组件。

还要确定这是：

• 全新的产物
• 基本保留现有结构的重新设计
• 允许适度调整结构的重新设计
• 可以彻底重新构思的重新设计

然后确定：

• 用户的主要目标
• 核心内容区块
• 关键状态（加载、空状态、错误、成功、验证、响应式布局）
• 所处位置（新页面、现有页面内、仪表板内、营销网站内）
• 哪些结构元素是固定的，哪些是灵活的
• 哪些现有特点应保留辨识度，哪些应改变

2. 定义所需方向

生成用户要求数量的候选方向；如果探索请求未指定数量，则生成五种。

使用方向差异质量标准，确保所需方向之间具有实质性差异，而非仅做表面换色。

当请求要求保留现有结构或精髓时，应将当前产物视为基准骨架。未经许可，不应通过删除或重新排序页面内容来区分方向，而应主要通过视觉系统和文案决策来体现差异。

此类重新设计的不同方案可以通过以下方面的组合来区分：

• 字体和字体搭配
• 配色方案和对比策略
• 文案语气和标题构思
• 证明材料的位置和强调方式
• 内容密度和间距节奏
• 图像或插画处理方式
• 表面样式、边框、层次感和细节风格
• 操作层级和 CTA 呈现方式

每个方向都必须包含：

• 名称：简短、易记、以概念为核心
• 获批方向：主要结构方向，以及适用时的辅助处理方式
• 设计主张：用一句话说明设计理念
• 有效原因：说明它如何支持用户目标
• 关键特征：层级、布局、密度、个性、媒体处理方式、操作策略
• 适用场景：说明在什么情况下应优先选择此方向，而非其他方向
• 风格成本：需要留意的主要实现、性能或状态管理成本

对于现有产物的重新设计，还应说明：

• 保留的骨架：有意保留、且仍可辨认的现有产物特征
• 主要变化：此方向着力强化的部分

3. 构建真实的候选产物

对于已批准的模拟稿或截图，请遵循参考保真度。对于较大型的页面工作，请使用可选的页面简报。直接实现请求不需要模拟稿或额外的选择环节。

为每个方向生成一套真实的产物。

优先使用：

• 真实的组件文件
• 真实的路由／页面文件
• 可在不同变体间切换的真实预览框架
• 在需要时使用真实的数据模拟或占位内容，让 UI 清晰易读

重新设计现有产物时，只要可行，就从当前的真实实现分支开始，而不是从头重建整个内容。先保留用户要求的结构，再叠加设计改动。

使用预览与应用模式来决定如何组织预览、后备比较形式和最终集成。

4. 确保变体真正可比较

每个变体都应包含相同的实际检查项：

• 响应式行为
• 无障碍要求
• 关键交互状态
• 内容占位符或示例文案
• 实现说明
• 所需的辅助组件

重新设计时，还应包含：

• 简要说明哪些结构保持一致
• 简要说明视觉或编辑方面有哪些变化

不要让一个选项只是草图，而另一个已达到生产级标准。应确保比较的是同类内容。

5. 推荐并确定选择

生成选项后：

1. 用简洁的表格总结各种取舍
2. 如果用户的目标明显更适合某个选项，则推荐该选项
3. 只有在选择仍未确定时，才询问用户。尊重用户先前的选择或授权你代为选择并应用的指示。

推荐理由应说明所选方向为何最符合以下方面：

• 受众
• 产品调性
• 信息密度
• 转化或易用性目标
• 在当前代码库中的可维护性

6. 整洁地应用选定方向

选定方向后：

• 将其集成到请求的目标位置
• 保留项目规范和导入语句
• 仅在重复的基础元素确实可复用时，才将其提取出来
• 移除明显无用的临时脚手架，除非用户希望保留其他方案
• 仅在预览产物对后续迭代仍有用时保留它们

当出现可复用模式时，请遵循 extract 的理念，但不要为了一个请求就构建臃肿的设计系统。

使用请求映射启发式，处理 Hero 区块、定价、付费墙、身份验证、仪表盘、电商流程和内容界面等产物的特定优先事项。

输出约定

在报告已实现结果经过检查之前，请先进行视觉验证。明确区分已实现的工作与未经验证的视觉或行为声明。

对于直接实现任务，请报告实现结果、改动文件和验证情况。对于探索任务，请按以下顺序呈现结果：

1. 生成内容 — 请求的产物和方向数量
2. 变体摘要表 — 每个生成方向占一行，说明其设计思路和最适用的场景；必要时使用比较表模板
3. 推荐选项 — 适用时提供
4. 预览／应用说明 — 如何检查或切换不同变体
5. 实现产物 — 创建或更新的文件

使用变体命名方案，确保标签、文件名和选择映射清晰且一致。 构建预览界面时，请使用预览页面检查清单。 用户选定方向后，请使用应用／清理检查清单。

绝不要这样做

• 用户要求直接实现时，却生成多个备选方案
• 只做外观上的细微差异，却生成几乎相同的变体
• 将临时浏览器 DOM 作为主要实现策略
• 忽略现有代码库结构和样式系统
• 用户要求保留现有作品的精髓或可辨识部分时，却大幅改动其结构
• 仅仅因为提示宽泛，就默认采用通用的初创公司美学风格
• 在此库中默认采用标新立异的美学风格
• 让每个选项都过于张扬、卡片过多、渐变过多或动画过多
• 忽略会实质影响作品的加载、错误、空状态和响应式布局状态
• 应用选定的变体，却不清楚说明改动了什么

请记住：这项技能不是用来随机生成可互换 UI 的老虎机。它既支持直接实现，也支持按需探索，并且无论哪种模式，都应产出易于维护的源代码。