frontend-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Development

前端开发

Overview

概述

Build production-quality user interfaces that are accessible, performant, and visually polished. The goal is UI that looks like it was built by a design-aware engineer at a top company — not like it was generated by an AI. This means real design system adherence, proper accessibility, thoughtful interaction patterns, and no generic "AI aesthetic."

构建具备可访问性、高性能且视觉精致的生产级用户界面。目标是打造出如同顶尖公司中懂设计的工程师所构建的UI——而非AI生成的风格。这意味着要严格遵循真实的设计系统、确保良好的可访问性、采用经过深思熟虑的交互模式，且摒弃通用的"AI审美"。

When to Use

使用场景

Building new UI components or pages
Modifying existing user-facing interfaces
Implementing responsive layouts
Adding interactivity or state management
Fixing visual or UX issues

构建新的UI组件或页面
修改现有面向用户的界面
实现响应式布局
添加交互功能或状态管理
修复视觉或UX问题

Coding Standards

编码规范

You must always read the frontend coding standards stored in the repo
```
nicolasances/sdlc-agent-specs/coding-standards/frontend-coding-standards.md
```
and you MUST follow these when coding a frontend
[ ] Always use tailwind classes.
[ ] Make sure to use the
```
toto-react
```
library whenever possible. Always check first what the toto-react library provides before implementing from scratch UI components.

你必须始终阅读存储在仓库
```
nicolasances/sdlc-agent-specs/coding-standards/frontend-coding-standards.md
```
中的前端编码规范，并且在编写前端代码时严格遵循这些规范
始终使用tailwind类。
尽可能使用
```
toto-react
```
库。在从零开始实现UI组件之前，务必先查看
```
toto-react
```
库提供了哪些组件。

Wireframe and design system

线框图与设计系统

If a wireframe or design system exist for the interfaces use it.
If you cannot easily find a wireframe or design system, you need to quit.

如果界面存在对应的线框图或设计系统，请遵循使用。
如果无法轻松找到线框图或设计系统，你需要停止操作。

Avoid the AI Aesthetic

避免AI审美

AI-generated UI has recognizable patterns. AVOID all of them:

AI Default	Why It Is a Problem	Production Quality
Purple/indigo everything	Models default to visually "safe" palettes, making every app look identical	Use the project's actual color palette
Excessive gradients	Gradients add visual noise and clash with most design systems	Flat or subtle gradients matching the design system
Rounded everything (rounded-2xl)	Maximum rounding signals "friendly" but ignores the hierarchy of corner radii in real designs	Consistent border-radius from the design system
Generic hero sections	Template-driven layout with no connection to the actual content or user need	Content-first layouts
Lorem ipsum-style copy	Placeholder text hides layout problems that real content reveals (length, wrapping, overflow)	Realistic placeholder content
Oversized padding everywhere	Equal generous padding destroys visual hierarchy and wastes screen space	Consistent spacing scale
Stock card grids	Uniform grids are a layout shortcut that ignores information priority and scanning patterns	Purpose-driven layouts
Shadow-heavy design	Layered shadows add depth that competes with content and slows rendering on low-end devices	Subtle or no shadows unless the design system specifies

AI生成的UI具有可识别的模式。请避免所有这些模式：

AI默认风格	问题所在	生产级标准
全紫/靛蓝色调	模型默认使用视觉"安全"的调色板，导致所有应用看起来千篇一律	使用项目实际的调色板
过度使用渐变	渐变会增加视觉噪音，且与大多数设计系统冲突	使用符合设计系统的扁平化或细微渐变
所有元素都圆角（rounded-2xl）	最大圆角传达"友好"感，但忽略了真实设计中圆角半径的层级关系	遵循设计系统中统一的圆角半径规范
通用英雄区（Hero Section）	模板化布局与实际内容或用户需求脱节	以内容为核心的布局
Lorem ipsum类占位文本	占位文本会掩盖真实内容暴露出的布局问题（如长度、换行、溢出）	使用真实感的占位内容
所有区域都使用超大内边距	均等的大内边距会破坏视觉层级，浪费屏幕空间	遵循统一的间距尺度
通用卡片网格	统一网格是布局捷径，但忽略了信息优先级和用户浏览模式	基于需求设计的布局
重度阴影设计	多层阴影会增加视觉深度，与内容产生竞争，且在低端设备上会降低渲染速度	除非设计系统明确要求，否则使用细微阴影或不添加阴影

Color

颜色

Use semantic color tokens:
```
text-primary
```
,
```
bg-surface
```
,
```
border-default
```
— not raw hex values
Ensure sufficient contrast (4.5:1 for normal text, 3:1 for large text)

使用语义化颜色标记：
```
text-primary
```
、
```
bg-surface
```
、
```
border-default
```
——而非原始十六进制值
确保足够的对比度（普通文本4.5:1，大文本3:1）

Loading and Transitions

加载与过渡效果

Use skeleton shapes to represent loading content — not spinners. Skeleton elements should mirror the dimensions and layout of the real content they stand in for.

Always mark the skeleton container with

aria-busy="true"

and a descriptive

aria-label

for accessibility.

For the skeleton animation itself, use whatever the project already defines (e.g. a custom shimmer class in

globals.css

). Do NOT introduce a new animation class (such as

animate-pulse

) if the project already has one — check

globals.css

and existing components first. Only fall back to a Tailwind utility like

animate-pulse

if no project-level skeleton style exists.

使用骨架屏（Skeleton）来表示加载中的内容——而非加载动画（Spinner）。骨架元素应与它们所替代的真实内容的尺寸和布局保持一致。

务必为骨架容器添加

aria-busy="true"

属性以及描述性的

aria-label

属性，以确保可访问性。

对于骨架屏的动画效果，请使用项目中已定义的样式（例如

globals.css

中的自定义闪烁类）。如果项目已有相关样式，请勿引入新的动画类（如

animate-pulse

）——请先查看

globals.css

和现有组件。只有当项目级别的骨架屏样式不存在时，才使用Tailwind工具类如

animate-pulse

作为备选。

Red Flags

警示信号

Components with more than 200 lines (split them)
Inline styles or arbitrary pixel values
Missing error states, loading states, or empty states
No keyboard navigation testing
Color as the sole indicator of state (red/green without text or icons)
Generic "AI look" (purple gradients, oversized cards, stock layouts)

组件代码超过200行（应拆分组件）
内联样式或任意像素值
缺少错误状态、加载状态或空状态
未进行键盘导航测试
仅使用颜色作为状态标识（仅用红/绿而无文本或图标）
通用"AI风格"（紫色渐变、超大卡片、模板化布局）