frontend-implementation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Implementation Skill

前端实现技能

When to Apply

适用场景

Apply this skill when the request involves:

UI implementation, design-to-code, Figma to code, component implementation, styling, responsive design, fixing broken UI
UI実装、デザインから実装、Figmaから実装、コンポーネント実装、スタイル調整、レスポンシブ対応、UIの崩れ修正
Translating any design tool output (Figma/Pencil/Canva/sketches) to code

当需求涉及以下内容时，可应用此技能：

UI实现、设计转代码、Figma转代码、组件实现、样式调整、响应式设计、修复故障UI
UI实现、从设计到开发、从Figma到开发、组件实现、样式调整、响应式适配、修复UI布局错乱
将任意设计工具输出（Figma/Pencil/Canva/草图）转换为代码

Core Principles

核心原则

Goal is not pixel-perfect copying, but maintaining ratios, alignment, resilience, and consistency.
Translate, don't transcribe. Design tool values (px) are references; implementation uses scales, ratios, and structure.
Fixed values are exceptions. If using fixed values, articulate why (spec requirement, media, tap target, etc.).

目标并非像素级复刻，而是保持比例、对齐、健壮性和一致性。
转化而非转录。 设计工具中的数值（px）仅作参考；实现时应使用比例、比率和结构化方案。
固定数值是例外情况。 若使用固定数值，需说明原因（如规格要求、媒体元素、点击目标等）。

Design Philosophy (Decision Rules)

设计理念（决策规则）

UI is a set of constraints, not a picture. Include states (loading/error/empty/disabled) to be complete.
Don't create alignment with margin tweaks. Use structure (flex/grid) and
```
gap
```
.
Avoid fixed heights. Consider
```
min/max/overflow
```
first.
Typography is role-based. Don't proliferate by copying values.
Handle exceptions upfront. Long text, zero items, failures, delays—no afterthoughts.
Articulate design intent first (what to emphasize, how to guide the eye), then create structure that preserves it.
Width follows the viewport. UI should adapt to screen width (SCALE/FILL intent); don't just crop from the left.

UI是一组约束，而非静态图片。 需包含完整的状态（加载/错误/空态/禁用）。
不要通过调整margin来实现对齐。 使用结构化布局（flex/grid）和
```
gap
```
属性。
避免固定高度。 优先考虑
```
min/max/overflow
```
属性。
排版基于角色定义。 不要通过直接复制数值来滥用样式。
提前处理异常情况。 长文本、空列表、加载失败、延迟等情况需提前考虑，而非事后补救。
先明确设计意图（需突出什么、如何引导用户视线），再构建能保留该意图的结构。
宽度适配视口。 UI应根据屏幕宽度调整（遵循缩放/填充原则）；不要仅从左侧裁剪内容。

Translation Process (Design Tool → Code)

转换流程（设计工具 → 代码）

1) Read Intent Before Numbers

1) 先理解意图，再关注数值

Purpose (what should users understand/do first on this screen)
Visual flow (first → second → last thing to see)
Emphasis (hero / supporting / background elements)
Hierarchy (parent-child, groupings)
Stretch/state intent (Auto Layout / Constraints / Variants)
Spacing rules (gap/padding patterns)
Alignment (what aligns to what)
Variable elements (text length, list count, image ratio, input values)

用途（用户在该页面应首先理解/完成什么）
视觉流（用户视线的先后顺序）
重点突出（核心/辅助/背景元素）
层级结构（父子关系、分组）
伸缩/状态意图（Auto Layout/约束/变体）
间距规则（gap/padding模式）
对齐方式（元素间的对齐关系）
可变元素（文本长度、列表数量、图片比例、输入值）

2) Convert to Implementation

2) 转化为实现方案

px → Round to scale (e.g., 4/8/12/16/24/32/40/48)
font-size → Map to roles (heading/body/caption)
Local margin tweaks → Convert to layout structure (flex/grid/gap, clarify parent-child responsibilities)
Fixed width/height → Convert to constraints (min/max, wrap, ellipsis, overflow)
Width design → Separate background/container/content responsibilities

px → 取整到标准刻度（如4/8/12/16/24/32/40/48）
font-size → 映射到角色定义（标题/正文/说明文字）
局部margin调整 → 转换为布局结构（flex/grid/gap，明确父子元素的职责）
固定宽高 → 转换为约束规则（min/max、自动换行、省略号、溢出处理）
宽度设计 → 区分背景/容器/内容的职责

3) Alignment Decisions

3) 对齐决策

When to align:

Repeated elements (cards/lists/forms) for comparison
Main column (body/primary input/CTA) for clear visual path
Reducing confusion (admin panels, settings, heavy input screens)

When breaking alignment is acceptable:

Intentionally floating a hero element
Emphasizing section boundaries
Media/decoration as the focus (but ensure resilience)

Rules when breaking alignment:

Keep at least one baseline
Limit offset patterns to 1-2
On narrow viewports, favor alignment

何时需要对齐：

重复元素（卡片/列表/表单），便于用户比较
主列（正文/主要输入框/CTA按钮），确保清晰的视觉路径
减少混淆（管理面板、设置页面、输入密集型页面）

何时可打破对齐：

有意突出核心悬浮元素
强调区块边界
媒体/装饰元素为视觉焦点时（但需保证健壮性）

打破对齐的规则：

至少保留一条基准线
偏移模式限制为1-2种
在窄视口下，优先选择对齐

4) Preserve Width Distribution (Weights)

4) 保留宽度分配权重

Width distribution IS visual guidance. Column weights (primary/secondary/tertiary) are intentional.
Don't accidentally equalize. Applying
```
flex: 1
```
to everything makes supporting elements as prominent as heroes.
Separate baseline alignment from width distribution. They can differ.

宽度分配是视觉引导的一部分。 列的权重（主/次/三级）是有意设计的。
不要随意均等分配。 对所有元素应用
```
flex: 1
```
会导致辅助元素和核心元素同样突出。
将基准线对齐与宽度分配分离。 两者可以独立设置。

Implementation Guidelines

实现指南

Typography

排版

Use
```
rem
```
(or
```
clamp()
```
). Use
```
em
```
only when relating to parent size.
```
line-height
```
should be unitless (e.g., 1.5–1.7).
Body text readability: aim for
```
max-width: 60ch
```
.

使用
```
rem
```
（或
```
clamp()
```
）。仅在需要相对于父元素大小时使用
```
em
```
。
```
line-height
```
应使用无单位值（如1.5–1.7）。
正文可读性：目标设置
```
max-width: 60ch
```
。

Spacing

间距

Round to scale (avoid fractional values).
Prefer parent's
```
gap/padding
```
over scattering margins on children.

取整到标准刻度（避免使用小数）。
优先使用父元素的
```
gap/padding
```
，而非在子元素上零散设置margin。

Proportions

比例

Maintain look through ratios, not exact numbers (column width ratios, spacing steps, type scale).
Prefer max-width + spacing rules over fixed widths.

通过比例而非精确数值来保持视觉效果（列宽比例、间距步长、字体刻度）。
优先使用max-width + 间距规则，而非固定宽度。

Layout

布局

One-dimensional: flex. Two-dimensional: grid. Spacing: gap.
```
position: absolute
```
only for overlays/decorations with clear purpose.
Images: preserve aspect ratio by default; use
```
aspect-ratio
```
when needed.

一维布局：使用flex。二维布局：使用grid。间距：使用gap。
```
position: absolute
```
仅用于有明确用途的覆盖层/装饰元素。
图片：默认保留宽高比；必要时使用
```
aspect-ratio
```
属性。

Fixed Values (Exceptions)

固定数值（例外情况）

Icons, thumbnails, tap targets, spec-defined header heights, etc.
Even for breakage prevention, consider
```
min/max
```
before going fixed.

图标、缩略图、点击目标、规格定义的头部高度等。
即使是为了防止布局错乱，也应优先考虑
```
min/max
```
属性，再使用固定数值。

States and Resilience (Required)

状态与健壮性（必填项）

Include: default / hover / active / focus / disabled / loading / error / empty
Handle long text, zero items, network failure, delays from the start—no afterthoughts.

需包含：默认/悬停/激活/聚焦/禁用/加载/错误/空态
从一开始就处理长文本、空列表、网络故障、延迟等情况，而非事后补救。

Output Format (Follow This Order)

输出格式（按以下顺序）

Purpose (what this UI achieves)
Prerequisites (design input type, existing conventions, constraints)
Translation results (hierarchy, alignment, spacing rules, variable elements)
Implementation approach (layout structure, scale, exception conditions)
State design (default/hover/active/focus/disabled/loading/error/empty)
Checklist self-assessment (OK / needs work)

用途（该UI的实现目标）
前置条件（设计输入类型、现有规范、约束条件）
转换结果（层级结构、对齐方式、间距规则、可变元素）
实现方案（布局结构、刻度标准、异常场景）
状态设计（默认/悬停/激活/聚焦/禁用/加载/错误/空态）
自检清单（符合/需改进）

Checklist

自检清单

Common Pitfalls

常见误区

Pixel-perfect copying from design data, breaking on edge states and responsiveness
Margin tweaks proliferating, becoming unmaintainable
Prioritizing "visual match" while states (loading/error/empty) become afterthoughts

从设计数据中进行像素级复刻，导致在边缘状态和响应式场景下布局错乱
滥用margin调整，导致代码难以维护
优先追求“视觉匹配”，而将状态（加载/错误/空态）作为事后补救的内容