building-ui-bundle-frontend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UI Bundle UI

Identify the Task

确定任务类型

Determine which category the request falls into:

Category	Examples	Implementation Guide
Page	New routed page (contacts, dashboard, settings)	`implementation/page.md`
Header / Footer	Site-wide nav bar, footer, branding	`implementation/header-footer.md`
Component	Widget, card, table, form, dialog	`implementation/component.md`

判断请求所属的类别：

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

Layout and Navigation

布局与导航

appLayout.tsx

is the source of truth for navigation and layout. Every page shares this shell.

When making any change that affects navigation, header, footer, sidebar, theme, or layout:

Edit
```
src/appLayout.tsx
```
— the layout used by
```
routes.tsx
```
Replace all default/template nav items and labels with app-specific links and names
Replace placeholder app name everywhere: header, nav brand, footer,
```
<title>
```
in
```
index.html
```

Before finishing, confirm: Did I update

appLayout.tsx

with real nav items and branding?

What	Where
Layout, nav, branding	`src/appLayout.tsx`
Document title	`index.html`
Root page content	Component at root route in `routes.tsx`

appLayout.tsx

是导航和布局的唯一权威来源。所有页面共享这个框架。

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

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

完成前，请确认：是否已使用真实的导航项和品牌信息更新了

appLayout.tsx

？

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

React and TypeScript Standards

React与TypeScript标准

Routing

路由

Use a single router package. With

createBrowserRouter

RouterProvider

, all imports must come from

react-router

(not

react-router-dom

If the app uses a client-side router (React Router, Remix Router, Vue Router, etc.), always derive basename / basepath / base from the document's

<base href>

tag at runtime. Never hardcode the basename:

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

使用单一路由包。使用

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 });

Component Library and Styling

组件库与样式

shadcn/ui for components:

import { Button } from '@/components/ui/button';

Tailwind CSS utility classes

使用shadcn/ui作为组件库：

import { Button } from '@/components/ui/button';

使用Tailwind CSS工具类

URL and Path Handling

URL与路径处理

Apps run behind dynamic base paths. Router navigation (

<Link to>

navigate()

) uses absolute paths (

/x

). Non-router attributes (

<img src>

) use dot-relative (

./x

). Prefer Vite

import

for static assets.

应用运行在动态基础路径下。路由导航（

<Link to>

、

navigate()

）使用绝对路径（

/x

）。非路由属性（

<img src>

）使用点相对路径（

./x

）。优先使用Vite

import

导入静态资源。

TypeScript

Never use
```
any
```
— use proper types, generics, or
```
unknown
```
with type guards

Event handlers:

(event: React.FormEvent<HTMLFormElement>): void

State:
```
useState<User | null>(null)
```
— always provide the type parameter
No unsafe assertions (
```
obj as User
```
) — use type guards instead

切勿使用
```
any
```
类型——使用正确的类型、泛型，或结合类型守卫使用
```
unknown
```

事件处理器：

(event: React.FormEvent<HTMLFormElement>): void

状态：
```
useState<User | null>(null)
```
—— 始终提供类型参数
避免不安全的类型断言（
```
obj as User
```
）——改用类型守卫

Module Restrictions

模块限制

React UI bundles must not import Salesforce platform modules like

lightning/*

@wire

(LWC-only). For data access, use the

using-ui-bundle-salesforce-data

skill.

React UI Bundle不得导入Salesforce平台模块，如

lightning/*

或

@wire

（仅LWC可用）。如需数据访问，请使用

using-ui-bundle-salesforce-data

Skill。

Design Thinking

设计思路

Before coding, commit to a bold aesthetic direction:

Purpose: What problem does this interface solve? Who uses it?
Tone: Pick a clear direction — brutally minimal, maximalist, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, soft/pastel, industrial. Use these as inspiration but design one true to the context.
Differentiation: What makes this unforgettable? What's the one thing someone will remember?

Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.

编码前，确定明确的美学方向：

目的：该界面解决什么问题？用户是谁？
风格基调：选择清晰的方向——极致极简、极致繁复、复古未来主义、有机风格、奢华风格、趣味风格、编辑风格、粗野主义、装饰艺术、柔和/马卡龙色、工业风。可以这些为灵感，但要设计符合上下文的专属风格。
差异化：什么让这个界面令人难忘？用户会记住的核心点是什么？

选择清晰的概念方向并精准执行。极致繁复和精致极简都可行——关键在于目的性，而非强度。

Frontend Aesthetics

前端美学

Typography: Choose distinctive, characterful fonts. Pair a display font with a refined body font. Never default to Inter, Roboto, Arial, Space Grotesk, or system fonts.
Color: Commit to a cohesive palette using CSS variables. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Avoid cliched purple gradients on white.
Motion: Focus on high-impact moments — one well-orchestrated page load with staggered reveals (
```
animation-delay
```
) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. Prefer CSS-only solutions; use Motion library for React when available.
Spatial Composition: Unexpected layouts — asymmetry, overlap, diagonal flow, grid-breaking elements. Generous negative space OR controlled density.
Backgrounds & Depth: Create atmosphere rather than defaulting to solid colors. Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, grain overlays.
Mobile Responsiveness: All generated UI MUST be mobile-responsive. Use Tailwind responsive prefixes (
```
sm:
```
,
```
md:
```
,
```
lg:
```
) to adapt layouts across breakpoints. Stack columns on small screens, use flexible grids, and ensure touch targets are at least 44px. Test that navigation, typography, and spacing work on mobile viewports.

Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate animations and effects. Minimalist designs need restraint, precision, and careful spacing/typography. No two designs should look the same — vary themes, fonts, and aesthetics across generations.

排版：选择独特、有个性的字体。将展示字体与精致的正文字体搭配。切勿默认使用Inter、Roboto、Arial、Space Grotesk或系统字体。
色彩：使用CSS变量打造连贯的调色板。主色调搭配鲜明的强调色，效果优于平淡、均匀分布的调色板。避免在白色背景上使用俗套的紫色渐变。
动效：聚焦高影响力时刻——一次精心编排的页面加载动画（使用
```
animation-delay
```
实现 staggered reveals）比零散的微交互更能带来愉悦感。使用滚动触发和令人惊喜的悬停状态。优先使用纯CSS方案；若有可用的React Motion库，可使用它。
空间布局：打破常规的布局——不对称、重叠、斜向流动、突破网格的元素。充足的留白或可控的密度。
背景与层次感：营造氛围，而非默认使用纯色。渐变网格、噪点纹理、几何图案、分层透明度、戏剧性阴影、装饰边框、颗粒叠加层。
移动端响应式：生成的所有UI必须支持移动端响应式。使用Tailwind响应式前缀（
```
sm:
```
、
```
md:
```
、
```
lg:
```
）在不同断点适配布局。小屏幕上堆叠列，使用灵活网格，确保触摸目标至少为44px。测试导航、排版和间距在移动视口中是否正常工作。

实现复杂度要与美学愿景匹配。繁复风格的设计需要精细的动画和效果。极简风格的设计需要克制、精准，以及精心的间距/排版。任意两个设计都不应雷同——在不同版本中变换主题、字体和美学风格。

Clarifying Questions

澄清问题

Ask one question at a time and stop when you have enough context.

一次只提一个问题，获取足够上下文后停止。

For a Page

针对页面

Name and purpose?
URL path?
Should it appear in navigation?
Access control? (public, authenticated via
```
PrivateRoute
```
, or unauthenticated via
```
AuthenticationRoute
```
)
Content sections? (list, form, table, detail view)
Data fetching needs?

名称和用途？
URL路径？
是否应出现在导航中？
访问控制？（公开、通过
```
PrivateRoute
```
认证、或通过
```
AuthenticationRoute
```
未认证）
内容区块？（列表、表单、表格、详情视图）
数据获取需求？

For a Header / Footer

针对页眉/页脚

Header, footer, or both?
Contents? (logo, nav links, user avatar, copyright, social icons)
Sticky header?
Color scheme or style direction?

页眉、页脚，还是两者都要？
内容？（logo、导航链接、用户头像、版权信息、社交图标）
是否需要粘性页眉？
配色方案或风格方向？

For a Component

针对组件

What should it do?
Which page does it belong to?
Shared/reusable or specific to one feature?
Data or props needed?
Internal state? (loading, toggle, form state)
Specific shadcn components to use?

功能是什么？
属于哪个页面？
是共享/可复用的还是特定于某个功能？
需要哪些数据或props？
是否有内部状态？（加载、切换、表单状态）
是否需要使用特定的shadcn组件？

Verification

验证

Before completing, run lint and build from the UI bundle directory. Lint must result in 0 errors and build must succeed.

完成前，从UI Bundle目录运行lint和构建命令。lint必须零错误，构建必须成功。