frontend-designer

前端设计师

使用现代 React、TailwindCSS v4 和 shadcn/ui 构建可用于生产环境的前端界面。提供从项目脚手架到渲染后 UI 审核的 6 种模式。

输入： $ARGUMENTS — 模式关键词 + 目标、自然语言 UI 描述或文件路径。

---

规范术语

术语	含义	不应使用
服务器组件	在服务器上渲染的 React 组件；在 Next.js/Remix App Router 中为默认组件	“SSR 组件”
客户端组件	带有 "use client" 指令的 React 组件；在浏览器中运行	“CSR 组件”
设计令牌	保存设计决策（颜色、间距、字体）的 CSS 自定义属性	“CSS 变量”（过于笼统）
主题	在 @theme {} 中配置的一整套设计令牌	“皮肤”、“调色板”
组件	可复用的 UI 构建块（React 组件 + 样式）	“小部件”、“模块”
原语	提供行为但不含样式的 Radix UI 基础组件	“基础组件”
注册表	shadcn/ui 组件分发端点（本地或远程）	“包”、“库”
容器查询	用于组件级响应式设计的 CSS @container 规则	“媒体查询”（针对页面）
Action	React 19 Server Action：通过表单在服务器端执行的异步函数	“API 调用”、“处理程序”
脚手架	使用完整技术栈配置创建新项目	“引导”、“设置”
重构	按照当前最佳实践改造现有前端代码	“重写”
审核	只读分析前端代码库的质量和模式	“审查”、“扫描”
实用类	映射到单个 CSS 声明的 Tailwind CSS 类	“辅助类”
逻辑属性	在 RTL 中使用 start/end 而非 left/right 的 CSS 属性	“方向属性”
纹理修正	Monaspace 中用于调整等宽字体字形间距的技术	—

---

分派

将 $ARGUMENTS 路由到相应模式：

$ARGUMENTS 模式	模式	从以下位置开始
scaffold <name> / init <name>	脚手架	模式 A
component <name> / create <name>	组件	模式 B
page <name> / view <name> / screen <name>	页面/视图	模式 F
theme / theme <path> / tokens / tokens <path>	主题	模式 C
refactor <path> / style <path>	重构	模式 D
audit / audit <path>	审核	模式 E
自然语言 UI 描述（“构建侧边栏”、“设计卡片”）	自动：组件	模式 B
自然语言页面/视图描述（“构建着陆页”、“设计仪表板”）	自动：页面/视图	模式 F
指向现有 .tsx/.jsx/.css 文件或目录的路径	自动：重构	模式 D
错误消息 / “无法运行” / “已损坏”	自动：审核	模式 E
“后端”/“API”/“数据库”/“DevOps”/测试/状态/路由/构建工具	拒绝	转到相关技能
空	图库	展示模式及调用示例

分类关卡

对于含义模糊的输入，在路由前先消除歧义：

信号	路由到
错误、损坏、缺陷、崩溃、“无法运行”	审核
测试运行器、状态库、路由器、打包器、包管理器、CI	拒绝或转向相关技能
升级、现代化、迁移、更新、转换	重构
颜色、深色模式、令牌、调色板、品牌形象	主题
着陆页、仪表板、设置、结账、个人资料、应用外壳、路由、屏幕	页面/视图
构建、创建、设计、添加、新建 + 组件名词	组件
设置、初始化、启动、新建项目	脚手架
信号混杂	询问用户要使用哪种模式

实时文档（可选）

仅在以下情况查阅实时文档：用户报告了意外行为、参考资料注明了预发布 API，或用户询问了捆绑参考资料未涵盖的功能。

1. Context7 — 对 "tailwindcss"、"shadcn-ui" 或 "react" 使用 resolve-library-id，然后使用 query-docs。
2. WebSearch — 针对具体主题搜索 site:tailwindcss.com、site:ui.shadcn.com 或 site:react.dev。
3. 如果实时文档与捆绑参考资料冲突，以实时文档为准。

---

模式 A：脚手架搭建

目标： 使用完整的现代前端技术栈创建新项目。

加载： references/tailwind-v4.md、references/vite-config.md、references/shadcn-patterns.md、references/typography.md、references/aesthetic-guide.md

A.1 框架选择

询问用户或检测：

框架	适用场景
Vite + React	SPA，无需 SSR，搭建速度最快
Next.js App Router	SSR/SSG、Server Components、生产级 Web 应用
Remix	全栈、嵌套路由、渐进式增强

除非用户另有指定，否则默认使用 Vite + React。

A.2 Tailwind v4 设置

以 CSS 为主进行配置——无需 tailwind.config.js：

@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 260);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);
  --font-display: "Your Display Font", serif;
  --font-body: "Your Body Font", sans-serif;
  --font-mono: "Monaspace Neon", monospace;
}

A.3 shadcn/ui 初始化

npx shadcn@latest init

根据项目结构配置 components.json。安装核心组件：button、input、card、dialog、dropdown-menu、toast。

A.4 字体排版

• 代码/等宽字体： Monaspace Neon（或根据美学风格选择 Argon、Krypton、Radon、Xenon）
• 展示字体： 独特且富有个性——不要使用 Inter、Roboto、Arial、system-ui
• 正文： 简洁易读——搭配展示字体以形成对比
• 加载 references/typography.md，了解 @font-face 设置和流式字号比例。

A.5 美学方向

运行领域适配检查并完成设计思考练习（见下文“美学方向”部分）。编写 UI 代码前，先确定合适的设计方向。

A.6 文件结构

src/
  components/ui/     # shadcn/ui components (managed by CLI)
  components/        # Custom project components
  lib/               # Utilities, helpers
  hooks/             # Custom React hooks
  styles/            # Global CSS, @theme, @font-face
  app/ or pages/     # Routes (framework-dependent)

A.7 完成

在宣布脚手架搭建的 UI 已完成前，运行视觉验收检查。

---

模式 B：组件

目标： 以生产级质量设计并构建单个组件。

加载： references/react-19.md、references/shadcn-patterns.md、references/modern-css.md 条件加载： 对于视觉、落地页、主视觉或营销类组件，加载 references/aesthetic-guide.md。工具类组件、表单和数据表则跳过。

B.1 组件分类

场景	默认类型	是否需要 "use client"？
Next.js / Remix App Router	Server Component	仅在使用钩子、事件处理程序或浏览器 API 时需要
Vite + React	Client Component	不需要——"use client" 没有必要，所有组件都是客户端组件

对于复合组件（例如 <Tabs>、<Accordion>）：将服务端封装组件与客户端交互部分分开。

B.2 设计意图

构建前收集以下信息：

• 用途： 要解决什么问题？谁会使用？
• 交互： 点击、悬停、拖动、键盘、触控？
• 响应行为： 如何适配不同的容器尺寸？
• 无障碍： 需要哪些 ARIA 角色和键盘交互模式？

B.3 基元选择

检查 shadcn/ui 是否提供该组件或相近的基础组件。如果组件具有交互功能（对话框、下拉菜单、弹出框、工具提示、标签页、手风琴、切换按钮），请通过 shadcn/ui 使用 Radix UI 基元——绝不要从头构建。

加载 references/shadcn-patterns.md，了解 CLI 命令和自定义模式。

B.4 实现

• 使用 Tailwind v4 工具类和来自 @theme {} 的 CSS 自定义属性进行样式设置
• 响应式设计：使用 @container 查询进行组件级适配，而非媒体查询
• 现代 CSS：使用 :has() 实现基于父级的样式，使用视图过渡实现状态变化
• 保持组件文件专注——将钩子和工具函数提取到独立文件

B.5 无障碍

每个交互组件都必须满足以下要求：

• 支持键盘导航（根据需要使用 Tab、Enter、Escape、方向键）
• 提供 ARIA 属性（角色、标签、描述、实时区域）
• 管理焦点（在模态框中锁定焦点，关闭时恢复焦点）
• 颜色对比度：至少达到 WCAG AA 标准（文本为 4.5:1，大号文本/UI 为 3:1）

B.6 完成

对任何已渲染的组件或组件演示运行视觉验收关卡。

---

模式 C：主题

目标： 配置或重新配置项目的设计令牌系统。

加载： references/tailwind-v4.md、references/modern-css.md、references/typography.md

C.1 子流程分发

如果 $ARGUMENTS 包含 tokens：运行令牌提取工作流：

1. 在 .tsx、.jsx、.css 文件中搜索硬编码的颜色值（hex、rgb、hsl）
2. 搜索未使用 Tailwind 工具类的硬编码间距/字体值
3. 整理为三层：基础（原始值）→ 语义（以用途命名）→ 组件（限定范围的覆盖值）
4. 生成整理好的自定义属性 @theme {} 块

C.2 颜色系统

使用 oklch 进行感知均匀的颜色调整：

@theme {
  --color-primary: oklch(0.6 0.2 260);
  --color-primary-light: color-mix(in oklch, var(--color-primary) 70%, white);
  --color-primary-dark: color-mix(in oklch, var(--color-primary) 70%, black);
}

contrast-color() 仍处于实验阶段——仅 Firefox 146+ 和 Safari TP 支持。请使用手动回退方案：

/* Fallback for contrast-color() */
--color-on-primary: oklch(1 0 0); /* manually chosen for contrast */

C.3 深色模式

使用 Tailwind v4 的 CSS 自定义属性策略：

@custom-variant dark (&:where(.dark, .dark *));

在 .dark 选择器上覆盖令牌：

.dark {
  --color-surface: oklch(0.15 0 0);
  --color-text: oklch(0.95 0 0);
}

C.4 字体排印比例

使用 clamp() 实现流式字体排印比例：

@theme {
  --text-base: clamp(1rem, 0.5vw + 0.875rem, 1.125rem);
  --text-lg: clamp(1.125rem, 0.75vw + 1rem, 1.25rem);
  --text-xl: clamp(1.25rem, 1vw + 1.125rem, 1.5rem);
}

C.5 RTL 准备

审查方向性属性，并转换为逻辑属性：

物理属性	逻辑属性
margin-left	margin-inline-start
padding-right	padding-inline-end
text-align: left	text-align: start
float: right	float: inline-end

---

模式 D：重构

目标： 将现有前端代码现代化，采用当前最佳实践。

加载： references/tailwind-v4.md、references/react-19.md、references/modern-css.md、references/anti-patterns.md

D.1 预扫描检查清单

进行任何更改前，扫描项目：

• 查找 tailwind.config.js 或 tailwind.config.ts——是否使用 v3 旧版配置？
• 统计 .tsx/.jsx 文件中 "use client" 的数量
• 搜索 @media 与 @container，比较数量——使用了哪种组件响应式模式？
• 搜索 CSS 自定义属性之外硬编码的 hex/rgb/hsl 颜色值
• 搜索 font-family 声明——是否使用了有特色的字体，还是默认字体？
• 检查 package.json 中的 React 版本、Tailwind 版本和 Vite 版本

D.2 迁移模式

从	到	参考
tailwind.config.js	CSS 优先的 @import "tailwindcss" + @theme {}	references/tailwind-v4.md
用于组件尺寸的 @media	@container 查询	references/modern-css.md
手动实现的下拉菜单/模态框	通过 shadcn/ui 使用 Radix 原语	references/shadcn-patterns.md
硬编码颜色	@theme {} 中的设计令牌	模式 C
类组件	函数组件 + Hooks	references/react-19.md
过多使用 "use client"	尽可能使用服务端组件（仅限 Next.js/Remix）	references/react-19.md

D.3 工作流

1. 提交逐文件迁移计划 → 用户批准关卡
2. 执行更改，每次处理一个文件
3. 每处理一个文件后进行验证：项目检查通过，且视觉验收关卡未发现回归
4. 重新运行预扫描检查清单，确认改进效果

---

模式 E：审计

目标： 只读分析前端代码库质量。绝不修改代码。

加载： references/anti-patterns.md

E.1 预扫描

运行与模式 D（§D.1）相同的检查清单。

E.2 评分维度

维度	检查内容
技术栈时效性	是否采用 Tailwind v4 的 CSS 优先模式？React 19？最新版 shadcn/ui？
组件模式	服务端与客户端如何划分？是否使用 Radix 基础组件？复合组件？
设计令牌	是否使用 @theme？是否存在硬编码值？令牌层级如何？
CSS 现代性	是否使用容器查询？:has()？逻辑属性？@supports 保护？
排版	字体是否有辨识度？代码是否使用 Monaspace？字号比例是否流畅？
无障碍	是否有 ARIA 属性？键盘导航？焦点管理？对比度是否达标？
视觉验证	是否检查了截图或浏览器？是否覆盖移动端和桌面端状态？是否检查溢出、重叠、焦点和减少动态效果？

E.3 报告格式

## Frontend Audit Report

### Critical (must fix)
- [finding with evidence]

### Warning (should fix)
- [finding with evidence]

### Suggestion (nice to have)
- [finding with evidence]

### Strengths
- [well-implemented patterns]

### Recommended Actions
- [action] → use `/frontend-designer refactor <path>`
- [action] → use `/frontend-designer theme`

---

模式 F：页面/视图

目标： 设计并构建完整页面、路由、屏幕、仪表板、着陆页或应用外壳。

加载： references/react-19.md、references/shadcn-patterns.md、references/modern-css.md、references/typography.md 按需加载： 对于营销、主视觉、编辑、作品集、游戏或品牌特色鲜明的页面，加载 references/aesthetic-guide.md。

F.1 判定页面上下文

构建前收集以下信息：

• 领域： SaaS/管理后台/运维/文档/金融，或营销/作品集/编辑/游戏/产品展示
• 用户任务： 主要操作、重复工作流、扫描/比较需求、决策点
• 构成： 布局外壳、路由插槽、导航、响应式断点、加载/空/错误状态
• 集成： 框架路由约定、服务端/客户端边界、数据占位符、组件复用

F.2 设计与实现

1. 执行审美方向的领域适配检查。
2. 优先使用 shadcn/ui 基础组件和现有项目组件进行组合，再考虑自定义 UI。
3. 页面级布局使用媒体查询实现响应式，组件内部使用容器查询实现响应式。
4. 如果页面展示数据，需包含有意义的加载、空和错误状态。
5. 在宣布完成前，执行视觉验收检查。

---

视觉验收检查

对于脚手架、组件、页面/视图和重构输出，只要存在渲染界面，就执行此检查。

1. 可行时启动或使用项目开发服务器；否则说明无法实时渲染的原因。
2. 分别在一个移动端宽度和一个桌面端宽度下检查。
3. 为已更改界面截取或描述视觉证据。
4. 确认没有不协调的重叠、文本裁切、水平溢出、布局跳动或难以阅读的状态。
5. 检查键盘焦点顺序、可见焦点指示器、相关场景下的 Escape/方向键行为，以及动画的减少动态效果行为。
6. 检查是否符合 WCAG AA 对比度要求：普通文本为 4.5:1，大号文本和 UI 指示器为 3:1。
7. 如有可用命令，运行项目相关的冒烟测试/构建命令。

---

美学方向

在构建视觉组件或页面之前，先选择适合领域和受众的方向：

领域	默认方向
SaaS、CRM、管理后台、金融、运营、文档	克制、密集、便于浏览、可预测
营销、作品集、编辑内容、品牌、产品展示	富有表现力、以素材为主、令人难忘
游戏、玩具、实验、艺术工具	轻松有趣、沉浸式、高度交互

设计思考：

1. 目的 — 这个界面要解决什么问题？谁会使用它？
2. 基调 — 选择适合该领域的基调；只有产品情境支持时，才采用极端美学风格
3. 约束 — 框架、性能预算、无障碍要求
4. 差异化 — 有什么能让人印象深刻？人们会记住的那一点是什么？

避免平庸的规则：

• 绝不要默认使用 Inter、Roboto、Arial 或系统字体
• 绝不要在白色背景上使用紫色渐变
• 绝不要制作看起来像是任何 AI 都能生成的千篇一律的布局
• 绝不要让不同生成结果都趋于相同的美学风格——主题、字体和调色板要有所变化
• 让实现复杂度与设计构想相匹配：极繁主义需要精细的代码，极简主义需要精准把控

完整的美学目录、色彩理论、动态设计和空间构图，请加载 references/aesthetic-guide.md。

---

范围边界

取代： frontend-design 技能。所有美学指导现在都在这里。

不适用于：

• 后端 API、数据库设计、DevOps 配置
• 测试框架（Jest、Vitest）——使用标准测试模式
• 状态管理库（Zustand、Redux、Jotai）——根据项目需求选择
• 路由（React Router、TanStack Router）——参阅框架专属文档
• 完整的 SSR 框架配置（Next.js、Remix 中超出 React 19 模式的配置）
• 构建工具、软件包管理——遵循 javascript-conventions

---

参考文件索引

在相关模式下按需加载。不要一次性全部加载。

文件	内容	在以下阶段加载
references/tailwind-v4.md	CSS 优先配置、@theme、@import、Oxide 引擎、深色模式、容器查询、v3→v4 迁移	Scaffold、Theme、Refactor
references/shadcn-patterns.md	CLI 命令、components.json、RTL、注册表、Radix 原语、复合组件、表单	Scaffold、Component
references/react-19.md	服务端与客户端决策树（取决于框架）、Actions、useActionState、use()、Suspense	Component、Refactor
references/modern-css.md	容器查询、:has()、@scope、视图过渡、滚动驱动动画、锚点定位、color-mix()、@layer	Component、Theme、Refactor
references/typography.md	Monaspace 超级字体家族、可变字体、@font-face、字体搭配、使用 clamp() 的流式字号比例	Scaffold、Theme、Component（视觉）
references/aesthetic-guide.md	设计思考、美学目录、色彩理论、动态设计、空间构图、避免平庸的规则	Component（视觉/着陆页/主视觉）、Scaffold
references/vite-config.md	当前 Vite 配置、插件、CSS 处理、资源优化、环境变量安全	Scaffold
references/anti-patterns.md	常见前端反模式的检测标准与修复方法	Audit、Refactor

---

验证约定

在宣布更改完成前，请从此技能目录运行：

python scripts/check.py
pytest -q tests/test_frontend_designer_scan.py

完成标准：

1. scripts/check.py 以状态码 0 退出。
2. 针对性测试全部通过，错误数为 0。
3. 此技能目录下不再存在任何可移植 CLI 违规。

更改技能定义、公开描述、参考文件或评估行为后，如果 docs-steward 可用，请调用它。

---

关键规则

1. Tailwind v4 中绝不使用 tailwind.config.js — 仅使用 CSS 优先方式，搭配 @import "tailwindcss" 和 @theme {}
2. 采用感知框架的组件模型 — 在 Next.js/Remix 中：尽量减少 "use client"，默认使用服务器组件。在 Vite+React 中：无需使用 "use client"，所有组件都是客户端组件
3. 交互组件使用 shadcn/ui 提供的 Radix 基元 — 绝不从头构建自定义对话框、弹出框、下拉菜单或工具提示
4. 通过 @theme {} 在 CSS 自定义属性中定义设计令牌 — 绝不硬编码颜色、间距或字体值
5. 使用容器查询实现组件响应式 — 使用媒体查询处理页面布局和用户偏好（prefers-color-scheme、prefers-reduced-motion、hover、pointer）
6. 使用 @supports 保护渐进增强功能 — contrast-color()、锚点定位、滚动驱动动画和 @scope 必须使用
7. 使用逻辑属性以支持 RTL — 使用 margin-inline-start 而非 margin-left，使用 padding-block 而非 padding-top
8. 绝不默认使用 Inter/Roboto/Arial/system-ui — 选择具有鲜明特色的字体；代码场景使用 Monaspace
9. 无条件保证无障碍性 — 键盘导航、ARIA、焦点管理、WCAG AA 对比度（文本为 4.5:1，大号文本为 3:1）
10. 仅在需要时查阅实时文档 — 参考资料稳定；仅在遇到意外行为或未涵盖的功能时，才获取 Context7/WebSearch
11. 正文保持在 500 行以内 — 深入的技术细节放入参考文件
12. 审计模式为只读 — 审计模式下绝不修改代码
13. 必须验证渲染后的 UI — 未通过视觉验收关卡或明确说明阻碍因素，不得宣布前端工作已完成