building-frontend-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Frontend Components

构建前端组件

Iron Law

铁律

NO COMPONENT CODE WITHOUT PRE-IMPLEMENTATION CHECKLIST FIRST.

Wrote JSX before checking for existing design system components? Delete it. Styled before planning keyboard interaction? Delete it. These aren't optional steps.

编写组件代码前必须完成预实现检查清单，没有例外。

还没检查现有设计系统组件就写了JSX？删掉它。还没规划键盘交互就做了样式？删掉它。这些步骤不是可选项。

Pre-Implementation Checklist

预实现检查清单

Before writing ANY component code:

Check for existing design system — tokens, components, patterns already in repo
Document component requirements — states (loading, error, empty), variants, accessibility needs
Plan keyboard interaction — focus order, shortcuts, trap requirements

Do NOT skip this for "simple" components. Simple components have accessibility bugs too.

New project with no design system? See

references/patterns.md

→ "Design Thinking" for direction-setting.

Framework selection guidance: See

references/patterns.md

→ "Framework Selection".

在编写任何组件代码之前：

检查现有设计系统——仓库中已有的令牌、组件、模式
记录组件需求——状态（加载、错误、空状态）、变体、无障碍需求
规划键盘交互——焦点顺序、快捷键、焦点陷阱需求

即使是“简单”组件也不要跳过这一步。简单组件同样可能存在无障碍漏洞。

没有设计系统的新项目？ 查看

references/patterns.md

→ “设计思路”获取方向指引。

框架选择指南： 查看

references/patterns.md

→ “框架选择”。

Accessibility Essentials (Non-Negotiable)

无障碍要点（不可协商）

Modal/Dialog Components

模态框/对话框组件

typescript

// REQUIRED attributes
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title-id"
  ref={dialogRef}
>
  <h2 id="modal-title-id">{title}</h2>
</div>

// REQUIRED behaviors
// 1. Focus first interactive element on open
// 2. Trap focus within modal (Tab cycles inside)
// 3. Restore focus to trigger element on close
// 4. Close on Escape key

Modals MUST implement focus trap. See

references/patterns.md

→ "Focus Trap Implementation" for copy-paste hook.

typescript

// REQUIRED attributes
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title-id"
  ref={dialogRef}
>
  <h2 id="modal-title-id">{title}</h2>
</div>

// REQUIRED behaviors
// 1. 打开时聚焦第一个可交互元素
// 2. 在模态框内捕获焦点（Tab键在内部循环）
// 3. 关闭时将焦点恢复到触发元素
// 4. 按Esc键关闭

模态框必须实现焦点陷阱。查看

references/patterns.md

→ “焦点陷阱实现”获取可直接复制的钩子。

Form Components

表单组件

typescript

// REQUIRED: Link errors to fields
<input
  id="email"
  aria-invalid={errors.email ? 'true' : 'false'}
  aria-describedby={errors.email ? 'email-error' : undefined}
/>
{errors.email && (
  <span id="email-error" role="alert">
    {errors.email.message}
  </span>
)}

// REQUIRED: Form identification
<form aria-label="Login form">
  {/* or aria-labelledby pointing to a heading */}
</form>

typescript

// REQUIRED: Link errors to fields
<input
  id="email"
  aria-invalid={errors.email ? 'true' : 'false'}
  aria-describedby={errors.email ? 'email-error' : undefined}
/>
{errors.email && (
  <span id="email-error" role="alert">
    {errors.email.message}
  </span>
)}

// REQUIRED: Form identification
<form aria-label="Login form">
  {/* or aria-labelledby pointing to a heading */}
</form>

Interactive Elements

可交互元素

Element	Requirements
Button	Visible focus indicator, disabled state styling
Link	Underline or clear affordance, focus visible
Custom control	`role` , `aria-*` attributes, keyboard handler
Menu/Dropdown	`aria-expanded` , `aria-haspopup` , roving tabindex

元素	要求
按钮	可见的焦点指示器、禁用状态样式
链接	下划线或清晰的交互提示、焦点可见
自定义控件	`role` 、 `aria-*` 属性、键盘处理器
菜单/下拉框	`aria-expanded` 、 `aria-haspopup` 、流动tabindex

Component State Checklist

组件状态检查清单

Every component MUST handle:

Default — Normal display state
Loading — Skeleton or spinner (avoid for <500ms operations)
Empty — Meaningful empty state, not blank
Error — Actionable message with recovery path
Disabled — Visual indication +
```
aria-disabled
```
or
```
disabled
```
Focus — Visible focus indicator (never
```
outline: none
```
without replacement)

每个组件必须处理：

默认状态——正常显示状态
加载状态——骨架屏或加载动画（操作耗时<500ms时避免使用）
空状态——有意义的空状态，而非空白
错误状态——可操作的提示信息及恢复路径
禁用状态——视觉提示 +
```
aria-disabled
```
或
```
disabled
```
属性
焦点状态——可见的焦点指示器（永远不要在没有替代方案的情况下使用
```
outline: none
```
）

Anti-Patterns (Stop If You See These)

反模式（遇到请立即停止）

Generic AI Aesthetics

通用AI风格陷阱

❌ Purple-on-white gradients with no context
❌ Cookie-cutter card layouts (centered hero + three icons)
❌ Flat solid backgrounds lacking atmosphere
✅ Honor existing design system OR establish distinctive direction

❌ 无上下文的紫白渐变
❌ 千篇一律的卡片布局（居中 hero + 三个图标）
❌ 缺乏氛围的纯色背景
✅ 遵循现有设计系统或确立独特风格方向

Technical Debt

技术债务

❌ Inline styles scattered throughout (use CSS modules, Tailwind, or tokens)
❌ Magic numbers instead of design tokens
❌ Hardcoded colors like
```
#2563eb
```
without token reference
✅ Use CSS custom properties or design tokens

❌ 分散的内联样式（使用CSS modules、Tailwind或设计令牌）
❌ 使用魔法数字而非设计令牌
❌ 硬编码颜色如
```
#2563eb
```
而不引用令牌
✅ 使用CSS自定义属性或设计令牌

Accessibility Oversights

无障碍疏漏

❌ Missing
```
role="dialog"
```
and
```
aria-modal
```
on modals
❌ No focus trap in modals/drawers
❌ Error messages without
```
role="alert"
```
❌ Form fields without
```
aria-invalid
```
/
```
aria-describedby
```
❌ Interactive elements without visible focus indicators

❌ 模态框缺少
```
role="dialog"
```
和
```
aria-modal
```
属性
❌ 模态框/抽屉未实现焦点陷阱
❌ 错误消息缺少
```
role="alert"
```
属性
❌ 表单字段未使用
```
aria-invalid
```
/
```
aria-describedby
```
❌ 可交互元素没有可见的焦点指示器

Common Mistakes from Baseline Testing

基线测试中发现的常见错误

What Agent Did	What Was Missing
Modal with Escape handling	No `role="dialog"` , no focus trap, no focus restoration
Form with labels	No `aria-invalid` , no `aria-describedby` for errors
Error message display	No `role="alert"` for screen reader announcement
Inline styles	No design tokens, creates maintenance burden

Agent的操作	缺失的内容
实现了Esc键关闭的模态框	缺少 `role="dialog"` 、焦点陷阱、焦点恢复
带标签的表单	缺少 `aria-invalid` 、错误提示的 `aria-describedby`
错误消息展示	缺少 `role="alert"` 以便屏幕阅读器播报
内联样式	未使用设计令牌，增加维护负担

When NOT to Use This Skill

何时不使用此技能

Pure backend/API work with no UI
Static content pages (use Astro or static HTML instead)
Design system documentation (use the design system's own tooling)

无UI的纯后端/API工作
静态内容页面（改用Astro或静态HTML）
设计系统文档（使用设计系统自身的工具）

Additional References

额外参考资料

For error handling, styling standards, performance, and testing → see

references/patterns.md

关于错误处理、样式标准、性能和测试 → 查看

references/patterns.md

。

Definition of Done

完成定义

Before marking work complete:

Pre-implementation checklist completed (design system check, requirements, keyboard plan)
All states implemented (default, loading, empty, error, disabled)
Keyboard navigation works (Tab, Shift+Tab, Enter, Escape, arrows)
Screen reader announces all interactive elements
Color contrast meets WCAG AA (4.5:1 text, 3:1 UI)
Responsive at 360px, 768px, 1280px
Works with 200% browser zoom
```
prefers-reduced-motion
```
respected
Error boundaries catch render failures
No
```
any
```
types, console logs, or TODOs remain
Tests pass (unit, a11y, visual if applicable)

标记工作完成前需确认：

已完成预实现检查清单（设计系统检查、需求确认、键盘交互规划）
已实现所有状态（默认、加载、空、错误、禁用）
键盘导航正常工作（Tab、Shift+Tab、Enter、Esc、方向键）
屏幕阅读器可播报所有可交互元素
颜色对比度符合WCAG AA标准（文本4.5:1，UI元素3:1）
在360px、768px、1280px分辨率下响应式正常
支持200%浏览器缩放
遵循
```
prefers-reduced-motion
```
设置
错误边界可捕获渲染失败
无
```
any
```
类型、控制台日志或TODO项残留
测试通过（单元测试、无障碍测试、视觉测试<如适用>）",