SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsbuild-frontend-ui-engineering

build-frontend-ui-engineering

Frontend & websites

View repository

Updated 10-16 09:56

About this skill

UI Engineering — Frontend Interface Engineering

Entry/Exit

  • Entry: A UI component or page is needed in build
  • Exit: Production-ready, accessibility-check-passing UI component + tests
  • Points to: Frontend changes complete → build-frontend-browser-testing perform browser verification
  • Output path: verify-frontend-accessibility(downstream verification skill)
  • Prerequisite loading: CANON.md + build-quality-tdd/SKILL.md

When not to use

  • Only making product/visual/interaction decisions, not yet at engineering implementation
  • Pure backend, script, CI, or data migration changes
  • UI is already implemented and only browser screenshots, interaction verification, or accessibility review is needed

Responsibility boundaries

Engineer the approved interaction and visual direction into a runnable UI. Do not re-decide the main flow/visual direction/information architecture during the build phase. Missing approved design → STOP, return to design-workflow-design。

Component architecture

File structure: One directory per component (main component + tests + styles + child components used only by this component).

Composition over configuration: Use children composition (<Card><Title/><Actions/></Card>), not props configuration explosion (<Card showTitle showActions actions={[...]}）。

Separation of concerns: UI logic (rendering, events) ≠ business logic (data fetching, validation). Components only handle UI.

State management — start simple

useState → useReducer → Context → Zustand/Jotai → Redux/MobX. Always start from 1, escalate as needed, never start from 5.

Avoid AI aesthetics

Anti-pattern Fix
Purple/indigo throughout the entire site Use the project brand colors. Read tailwind.config or the design system
Excessive gradients Solid color backgrounds. At most one gradient accent
All corner radii 16px+ Buttons 6-8px, cards 8-12px
Generic Hero Section Show product screenshots/data/logo, not placeholders
Lorem ipsum copy Use placeholders containing specific information
Excessive padding (py-24/32) Use different spacing for different sections, establish a spacing scale
Excessive shadows sm(cards), md(dropdowns), lg(modals). Do not create a 6th level
Three-column icon card grid The most common AI-generated pattern. Use asymmetric layouts/tables/timelines

Principles: Look at the project's existing UI to determine style. New project → simple > flashy.

Accessibility — WCAG 2.1 AA (mandatory)

Keyboard navigation: Every interactive element is keyboard accessible.<button> has support automatically,<div onClick> must add tabIndex + onKeyDown.

ARIA labels: Icon buttons must have aria-label。

Focus management: Modal opens → focus moves in; closes → returns to the trigger button; Tab cycles within the modal and does not escape.

Meaningful empty/error/loading states: Use Skeleton for Loading (not a white screen); use friendly information + action guidance for Empty; use specific information + retry button for Error; Edge cases: overly long text, 0 values, null.

Responsive Design

Mobile-first: Base styles = mobile, progressively enhance.

Breakpoints: <640px phone | 640-768 large phone/small tablet | 768-1024 tablet | 1024-1280 small desktop | >1280 desktop.

General rules: Images max-width: 100%; height: auto; tables scroll horizontally on small screens; touch targets minimum 44x44px.

Loading and Transitions

Skeleton is better than Spinner: Skeleton keeps layout stable (low CLS); Spinner + content popping in breaks CLS.

Optimistic updates: Actions immediately reflected in the UI → background sync → rollback on failure.

Common Claims

Claim Reality Consequence
"Add accessibility last" Adding it last = it won't get added. Start from the first component. 2-4h extra fix per component; missing ARIA makes the product unusable for 15-20% of users
"This gradient looks great" AI aesthetics reduce trust. Project colors > flashy effects. The product is recognized as AI-generated; later unifying the brand colors requires refactoring 50-70% of the styles
"No need to test loading/error" Users encounter empty/error states far more often than the ideal state. 30%+ of users hit a white screen; CLS score drops
"Build PC first, adapt for mobile later" Mobile-first CSS is cleaner. Going PC-first and then downward is very hard. Adapting downward requires rewriting 40-60% of the CSS
"Skeletons are too much trouble, use a spinner" Spinner + pop-in = CLS = poor experience. CLS increases by 0.1-0.3; Lighthouse drops 5-15 points

Validation Failure Handling

Failure Scenario Handling
Used colors outside the palette Replace with project brand colors
Interactive elements not keyboard accessible Add tabIndex + onKeyDown or switch to <button>
Missing Loading / Empty / Error states Fill in all three states first before continuing
Color as the only status indicator Add icon/text as a supplementary channel
Mobile layout overflow Check max-width, touch targets; no overflow at 320px

Red Flags — STOP

  • Inventing your own colors instead of using the project palette
  • onClick div with no keyboard access
  • Color as the only status indicator
  • Missing any of Loading / Empty / Error
  • Images without alt text
  • Images without width and height (CLS risk)
  • Mobile modal cannot scroll
  • px-8 py-24 Hero + generic illustration = AI aesthetics alarm

Validation Checklist

  • Every interactive element is keyboard accessible
  • Icons/images have alt or aria-label
  • Color is not the only way information is conveyed
  • Has Loading / Empty / Error states
  • Usable on mobile (320px) without overflow
  • Uses the project color/spacing system
  • The image has explicit width/height

Output template

## UI Component — [组件名称]

### 设计来源
- 交互设计: `02-design.md` → [描述]
- 视觉方向: `02-design.md` → [层级和色值]
- 项目 token: DESIGN.md → [spacing / color / rounded]

### 状态覆盖
| 状态 | UI 表现 | 数据条件 |
|------|---------|---------|
| Normal | [渲染] | data.length > 0 && !error |
| Loading | [Skeleton] | isLoading |
| Empty | [文案 + 引导] | data.length === 0 && !isLoading |
| Error | [信息 + 重试] | error !== null |

### 可访问性
- 键盘: [Tab / Enter / Escape 路径]
- ARIA: [清单]
- 焦点: [模态框循环 / 回退]
- 色盲: [颜色 + 图标双通道]

### 响应式
- 移动 (<640px): [变化]
- 平板 (768-1024px): [变化]
- 桌面 (>1280px): [变化]