building-ui-bundle-frontend

UI Bundle UI

确定任务类型

确定请求属于以下哪一类：

类别	示例	实现指南
页面	新增路由页面（联系人、仪表盘、设置）	implementation/page.md
页眉 / 页脚	全站导航栏、页脚、品牌标识	implementation/header-footer.md
组件	小组件、卡片、表格、表单、对话框	implementation/component.md

---

布局和导航

appLayout.tsx 是导航和布局的唯一依据。每个页面都共用此外壳。

进行任何会影响导航、页眉、页脚、侧边栏、主题或布局的更改时：

1. 编辑 src/appLayout.tsx——这是 routes.tsx 使用的布局
2. 将所有默认 / 模板导航项和标签替换为应用专属的链接和名称
3. 在所有位置替换占位应用名称：页眉、导航品牌标识、页脚、index.html 中的 <title>

完成前，请确认：我是否已在 appLayout.tsx 中更新了实际导航项和品牌标识？

内容	位置
布局、导航、品牌标识	src/appLayout.tsx
文档标题	index.html
根页面内容	routes.tsx 中根路由对应的组件

---

React 和 TypeScript 标准

路由

使用单一的路由器包。使用 createBrowserRouter / RouterProvider 时，所有导入都必须来自 react-router（而不是 react-router-dom）。

如果应用使用客户端路由器（React Router、Remix Router、Vue Router 等），始终在运行时从文档的 <base href> 标签获取 basename / basepath / base。切勿将 basename 硬编码：

const basename = document.querySelector('base')
  ? new URL(document.querySelector('base').href).pathname.replace(/\/$/, '')
  : '/';
const router = createBrowserRouter(routes, { basename });

组件库和样式

• shadcn/ui 用于组件：import { Button } from '@/components/ui/button';
• Tailwind CSS 实用类

URL 和路径处理

应用运行在动态基础路径下。路由器导航（<Link to>、navigate()）使用绝对路径（/x）。非路由器属性（<img src>）使用点相对路径（./x）。静态资源优先使用 Vite import。

TypeScript

• 切勿使用 any——使用恰当的类型、泛型，或配合类型守卫使用 unknown
• 事件处理器：(event: React.FormEvent<HTMLFormElement>): void
• 状态：useState<User | null>(null)——始终提供类型参数
• 不要使用不安全的类型断言（obj as User）——改用类型守卫

模块限制

React UI 包不得导入 lightning/* 或 @wire 等 Salesforce 平台模块（仅限 LWC）。如需访问数据，请使用 using-ui-bundle-salesforce-data 技能。

---

设计思路

编写代码前，先确定鲜明的美学方向：

• 用途： 此界面解决什么问题？由谁使用？
• 基调： 选择明确的方向——极简主义、繁复主义、复古未来主义、有机、奢华、活泼、编辑风、粗野主义、装饰艺术、柔和 / 粉彩、工业风。可将这些作为灵感，但设计应忠于具体场景。
• 差异化： 有什么特点能令人难忘？人们会记住哪一点？

选择明确的概念方向，并精准执行。大胆繁复与精致极简都可行——关键在于有意识地设计，而非一味追求强烈。

---

前端美学

• 字体排印： 选择别具一格、富有个性的字体。将展示字体与精致的正文字体搭配。切勿默认使用 Inter、Roboto、Arial、Space Grotesk 或系统字体。

• 色彩： 使用 CSS 变量构建协调统一的配色方案。大胆的主色搭配鲜明的强调色，效果胜过平淡且均匀分布的配色。避免使用俗套的白底紫色渐变。

• 动效： 聚焦于影响力大的时刻——通过错落展开（animation-delay）精心编排一次页面加载，比零散的微交互更能带来惊喜。使用滚动触发效果和出人意料的悬停状态。优先采用纯 CSS 方案；如果可用，在 React 中使用 Motion 库。

• 空间构图： 采用出人意料的布局——不对称、重叠、对角流动、打破网格的元素。留出充裕的负空间，或精心控制信息密度。

• 背景与层次： 营造氛围，而不是默认使用纯色。采用渐变网格、噪点纹理、几何图案、多层透明效果、醒目的阴影、装饰性边框、颗粒叠加效果。

• 移动端响应式： 所有生成的 UI 都必须适配移动端。使用 Tailwind 响应式前缀（sm:、md:、lg:）调整不同断点下的布局。在小屏幕上将列纵向堆叠，使用灵活的网格，并确保触控目标至少为 44px。测试导航、字体排印和间距在移动端视口上的表现。

让实现复杂度与美学构想相匹配。极繁主义设计需要复杂的动画和效果；极简主义设计则需要克制、精确，并仔细处理间距和字体排印。每种设计都应独具特色——在不同生成结果中变换主题、字体和美学风格。

---

澄清问题

每次只问一个问题；在获得足够信息后停止提问。

对于页面

1. 名称和用途是什么？
2. URL 路径是什么？
3. 是否应在导航中显示？
4. 访问控制要求是什么？（公开、通过 PrivateRoute 进行身份验证，或通过 AuthenticationRoute 不进行身份验证）
5. 包含哪些内容区块？（列表、表单、表格、详情视图）
6. 是否需要获取数据？

对于页眉 / 页脚

1. 需要页眉、页脚，还是两者都需要？
2. 包含哪些内容？（徽标、导航链接、用户头像、版权信息、社交图标）
3. 页眉是否固定？
4. 配色方案或风格方向是什么？

对于组件

1. 组件应实现什么功能？
2. 它属于哪个页面？
3. 是共享 / 可复用组件，还是仅用于某项功能？
4. 需要哪些数据或属性？
5. 是否包含内部状态？（加载、切换、表单状态）
6. 要使用哪些具体的 shadcn 组件？

---

验证

完成前，从 UI bundle 目录运行 lint 和 build。Lint 必须达到 0 个错误，build 必须成功。