第11节：前端 UI 设计与前端基础组件

前面几节里，我们已经把 Hify 的后端基础设施、前端工程骨架和一键启动链路都搭起来了。到这一步，项目已经从"空目录"变成了"能运行的工程"。

但如果你打开现在的前端页面，大概率还是会有一种很强烈的感觉：

它能用，但还不像一个真正的产品。

对很多后端工程师来说，前端最难的地方往往不是语法，而是另外两件事：

• 怎么把页面从"能用"做成"好看"

• 怎么把那些每个页面都会重复写的东西抽成公共组件

也正因为这个原因，很多人一提到前端就会本能地往后躲。不是因为完全做不出来，而是因为细节太多、迭代太慢、自己又很难判断什么叫"设计感"和"组件化做对了"。

这一节，我想解决的就是这个问题。

而且这次我们不只是让 Claude Code 帮忙"写页面"，而是让它在三个角色里一起工作：

• 当设计师，先帮你定风格、出初稿

• 当前端工程师，把公共组件一次性封装好

• 当实现搭档，配合你一轮一轮打磨细节

如果前面几节你已经接受了"让 AI 参与架构和基础设施设计"，那么这一节其实是在继续往前走一步：

让 AI 参与界面设计与产品打磨。

第一部分：先让 AI 当设计师，而不是直接让它"随便做个页面"

很多人第一次让 AI 做前端，最常见的问题就是提示词太空。

比如只说一句：

帮我设计一个好看的后台页面。

这种说法看起来像是在给自由度，实际效果往往是让它瞎猜。最后出来的页面通常不会丑，但也很容易变成一种"标准 AI 风格"：工整、干净、没明显错误，但也没什么记忆点。

如果你想让 Claude Code 真正参与设计，提示词不能只停留在"好看"这一级，而要把设计约束讲清楚。

第一步：先定视觉方向

我当时先没有让 Claude Code 直接改代码，而是先用咨询模式让它帮我做一套设计系统的初稿。

提示词是这样的：

Hify是一个AI Agent开发平台，面向技术团队内部使用，主要用户是开发者和技术管理者。界面以 管理后台 为主------大量的表格、表单、配置页面，加上一个对话交互页面。我想要的视觉风格：浅底 + 科技感点缀。整体用浅色背景保持信息可读性（管理后台表格多，深色底长时间看眼睛累）。但不要太素------侧边栏用深色底，按钮和关键交互元素用亮色，制造科技感和品牌感。色调方向：主色用蓝紫系（科技感强），辅色用青色或薄荷绿（数据/状态指示）。参考Linear、Supabase的视觉风格------干净但不无聊，有设计感但不花哨。帮我设计一套完整的设计系统：主色/辅色/背景 色阶 /文字色阶/圆角/阴影/过渡动效，用 CSS 变量输出。

Figure 1: Claude Code 生成前端设计系统初稿

这条提示词之所以有效，不是因为它字多，而是因为它信息层级清楚：

• 先说产品是什么

• 再说主要用户是谁

• 再说界面场景是什么

• 再给出你想要的视觉方向

• 再补色调偏好

• 最后给参考锚点

这个结构很重要。因为 Claude Code 做设计时，跟写代码一样，也需要约束和上下文。你说得越具体，它猜得越少，第一稿就越接近你想要的东西。

第二步：先改最显眼的部分，优先做侧边栏

如果要从一个页面里挑出"改完最立竿见影"的区域，我几乎总会先选侧边栏。

原因很简单：它是用户打开页面后第一眼就看到的地方，而且它决定了整个后台的第一层气质。

所以我给 Claude Code 的下一条指令是：

改造Hify的侧边栏。要求：

1. 背景用深色（接近纯黑但不是纯黑，用 --color-bg-dark），和浅色内容区形成对比

2. 顶部Logo区域：显示"Hify"品牌名，用主色渐变文字，下面一行小字 "AI Agent Platform"

3. 菜单项：默认白色文字 + 透明背景，hover时背景微亮（rgba白色10%透明度），选中态左边一条3px的主色竖线 + 背景微亮

4. 菜单图标：每个菜单项前加Element Plus图标（模型管理用Setting，Agent管理用User，对话用ChatDotRound）

5. 底部：折叠/展开按钮，版本号

6. 整体要炫酷，有科技感，但不能花哨到影响使用

Figure 2: 侧边栏视觉升级后的效果

这一步很值得注意的一点是：提示词里不是只说"做得高级一点"，而是把几个最关键的视觉元素拆开说清楚了，比如背景、Logo、选中态、图标、底部区域。

这样做的好处是，你不是在评价一个模糊的整体，而是在控制几个具体可改的设计点。

第三步：把页面整体布局拉到统一节奏

侧边栏改完之后，下一步就该处理页面整体布局。因为真正的"设计感"很多时候不是来自某个单独控件，而是来自：

• 背景和卡片之间有没有层次

• 标题区和内容区节奏是否统一

• 间距是不是稳定

• 按钮主次是否清楚

我给 Claude Code 的提示词是：

优化Hify的页面整体布局：

1. 顶栏：左侧面包屑导航（显示当前页面路径），右侧用户信息区域（头像 + 用户名placeholder）

2. 内容区：背景用 --color-bg-secondary（浅灰），内容卡片用白色背景 + 轻阴影 + 圆角，和背景有层次感

3. 页面标题区域：每个页面顶部有标题 + 描述文字 + 操作按钮区（右侧）

4. 间距统一：页面边距24px，卡片内边距20px，元素间距16px

5. 按钮样式：主要操作用主色渐变按钮（蓝紫渐变），次要操作用白色边框按钮，危险操作用红色

Figure 3: 页面整体布局和内容卡片层次优化

Figure 4: 顶栏、标题区与按钮层级的统一效果

到这里，前端页面通常就已经会从"原型味很重"变成"有产品感"的状态了。

第二部分：前端基础组件，不要一个页面一个页面重复造

光把视觉风格调漂亮还不够。

如果你后面每做一个页面，都要重新写：

• 表格加载状态

• 分页逻辑

• 弹窗显隐控制

• 删除确认

• 通知提示

• 请求三态管理

那速度还是会很慢。

对后端工程师来说，前端最耗时间的常常不是业务逻辑本身，而是这些碎而重复的交互样板代码。

所以这里的思路和后端很像：先把基础组件抽出来，后面做业务页面时只填配置。

一条完整指令，直接生成一批公共组件

这一步我没有一个组件一个组件去搭，而是直接给 Claude Code 一条完整指令，让它一次性生成前端公共组件。

提示词是：

在hify-web中创建以下前端公共组件，放在src/components/目录下。所有组件使用Vue 3 Composition API + TypeScript + Element Plus：

1. HifyTable.vue：通用列表页表格组件。Props接收columns配置（label/prop/width/slot）、api方法（返回PageResult格式）、是否显示分页。内部自动管理loading状态、分页参数、数据请求。暴露refresh()方法供外部调用刷新。空状态显Element Plus的el-empty。

2. HifyFormDialog.vue：通用表单弹窗组件。Props接收 title、width、表单rules。v-model控制显示隐藏。内部管理提交loading、关闭时自动重置表单。暴露open(data?)方法，传data为编辑模式，不传为新增模式。提交时触发submi事件，由父组件处理API调用。

3. src/composables/useConfirm.ts：删除确认composable。接收确认文案和API方法，弹出ElMessageBox确认框，确认后调用API，成功后显示ElMessage成功提示，返回Promise。一行代码完成 "确认删除→调接口→提示成功" 全流程。

4. src/composables/useRequest.ts：请求状态管理composable。接收API方法，返回 { data, loading, error, execute }。自动管理三态，避免每个页面写try-catch-finally样板代码。

5. src/utils/notify.ts：统一通知封装。导出notifySuccess/notifyError/notifyWarning三个方法，底层调用ElMessage，统一配置duration和样式。 每个组件要有TypeScript类型定义，用泛型支持不同数据类型。组件风格和第一步定的设计系统一致。

Figure 5: 一条指令生成前端公共组件集合

这一步我特别想强调一个观念：

后端工程师做前端，不需要把大量时间耗在组件实现细节上。

你真正要做的，是把组件接口和行为讲清楚：

• 它接收什么输入

• 它自动处理哪些状态

• 它向外暴露什么能力

• 它和项目已有约定如何对接

只要这几个点说清楚，Claude Code 通常就能把第一版搭出来。

然后你快速过一遍：

• TypeScript 类型对不对

• 组件接口设计顺不顺手

• 和 Element Plus 的结合有没有明显问题

前端组件本身不需要每一行都深度 review，能用、顺手、可继续扩展，通常就够了。

第三部分：真正花时间、也最有价值的，其实是细节打磨

UI 和基础组件都有了，但实际打开页面时，你一定还是会觉得有很多地方不够顺眼。

这是完全正常的。

因为前端设计几乎从来不是"一条指令出完美结果"，而是：

1. 先出一个可用初稿

2. 再通过多轮非常具体的反馈不断打磨

这个来回调整的过程，恰恰最能体现人机协作的价值。

用 ProviderList 页面演示真实的打磨过程

我先让 Claude Code 基于刚才封装好的组件，生成一个完整的 Provider 列表页面。

提示词是：

用HifyTable和HifyFormDialog实现Provider列表页面（src/views/provider/ProviderList.vue）。用mock数据，不调真实API。 列表展示：名称、类型（OpenAI/Claude/Gemini/Ollama）、Base URL、状态（启用/禁用，用el-tag显示）、创建时间、操作（编辑/删除）。 页面顶部有标题 "模型提供商管理"、描述文字、右侧 "新增提供商" 按钮。 点新增弹出HifyFormDialog，表单字段：名称、类型（下拉）、API Key、Base URL。 删除用useConfirm。 mock数据写5条，类型分布开。

这一步做完之后，我不会立刻去看源码，而是先启动页面看效果。

因为在 UI 这件事上，真正的判断来自"看起来对不对"，而不是"代码像不像对的"。

第一轮：调布局

第一版页面最常见的问题通常是间距和节奏不对。

比如我当时给 Claude Code 的反馈是：

ProviderList页面的表格和顶部标题区之间间距太大了，从24px改成16px。表格的行高偏高，把el-table的row-style行高从默认改成52px。操作列的两个按钮间距太小，加8px的margin-left。

这类问题非常适合交给 Claude Code。

你不需要自己去翻样式文件，也不用手动试来试去，只要能准确指出哪里不对、想改成什么，它通常就能非常快地改到位。

第二轮：调状态色

颜色的判断也很典型。

比如 Provider 页面里，"禁用"状态如果被 Claude Code 第一版做成红色，其实并不是严格意义上的错误，但从产品感觉上说，它不够合适。

所以我的反馈是：

状态列的el-tag颜色不对。启用状态用绿色（type="success"），禁用状态用灰色（type="info"），不要用红色------禁用不是错误，不应该用danger色。

这就是一个非常典型的"AI 先出初稿，人做审美判断"的场景。

Claude Code 的第一版通常会基于一种通用直觉来处理状态；而你更了解这个页面在真实产品语境里的含义，所以你来做最后判断。

第三轮：调弹窗和表单细节

表单弹窗也很容易在第一版里显得不够顺手。

比如我给过 Claude Code 这样一轮调整：

新增提供商的弹窗宽度太宽了，600px改成520px。API Key输入框改成password类型，加一个 "显示/隐藏" 切换按钮。Base URL输入框加placeholder示例：" https://api.openai.com/v1"。表单label宽度统一100px，从左对齐改成右对齐。

这种调整很能说明一件事：

你未必会写 Vue 组件细节，但你完全可以通过"视觉和使用体验判断"来指导 Claude Code 把它改好。

第四轮：补响应式细节

如果页面只在宽屏下好看，很多时候还是不够的。

我当时还会继续往前推一层：

当浏览器宽度小于1200px时，侧边栏自动折叠成只显示图标的窄模式。表格在窄屏下隐藏Base URL和创建时间两列，只保留关键信息。

这一步特别重要，因为它会强迫你从"单一静态效果"转向"真实使用场景"去看页面。

第五轮：做整体微调

最后再来一轮整体细节调整，比如：

整体看一下ProviderList页面，做以下微调：

1. 表格头部背景色太深了，换成 --color-bg-secondary（浅灰）

2. 分页器居右对齐，上方加一条细分割线

3. "新增提供商" 按钮加一个Plus图标

4. 鼠标悬停表格行时背景微微变色（hover效果）

5. 操作列的 "编辑" 按钮用text类型蓝色，"删除" 用text类型红色，不要默认的primary按钮样式

这时候你会发现，真正的 UI 打磨过程，几乎从来不是"出一个大方案"，而是这种一轮一轮、非常具体的小调整。

而这恰好也是 Claude Code 最适合协作的方式之一。

因为它不怕琐碎，也不嫌你改得细。你只要说得足够具体，它就能快速把你的判断翻译成代码。

真正重要的认知：你不一定要会写 CSS，但你要能看出哪里不对

这一节最核心的收获，我觉得不是你学会了几个 Vue 组件，也不是你背下了什么 UI 设计原则。

真正重要的是下面这件事：

你不一定需要亲自写前端细节，但你必须能说清楚"哪里不对"和"应该怎样"。

比如：

• 间距太大，改成 16px

• 禁用状态不该用红色，应该用灰色

• 弹窗太宽，收窄到 520px

• hover 效果不够明显，需要更轻一点的背景变化

这些判断不依赖你是不是专业前端工程师，它更像是一种产品和设计判断能力。

而 Claude Code 的价值就在于：它可以把这种判断快速翻译成可执行的实现。

也就是说，你不需要亲自去精通每一行 CSS，但你要学会用自己的眼睛和产品直觉来做反馈。

一旦这套协作方式跑顺了，后面做 Agent 页面、对话页面、工作流页面，其实都只是同一种方法的重复。

总结

这一节，我们其实做了三件非常关键的事：

• 先让 Claude Code 参与前端视觉设计，而不是只把它当页面生成器

• 用一条完整指令把前端公共组件一次性封装起来

• 通过 Provider 页面的一轮轮微调，建立真实的 UI 打磨协作流程

如果要把这一节的方法论压缩成三句话，我会这样说：

第一，让 AI 当设计师时，输入一定要具体。

不要只说"做得好看一点"，而要告诉它产品是什么、用户是谁、你想要什么风格、有什么参考锚点。

第二，前端基础组件要提前封装，不要每个页面重复造轮子。

列表页表格、表单弹窗、删除确认、请求状态、统一通知，这些东西一旦抽出来，后面做业务页面会快很多。

第三，真正有价值的不是第一版，而是你和 Claude Code 之间的多轮细节打磨。

第一版几乎永远不会完美，真正的水平来自你能否看着页面，清楚说出哪里不对、为什么不对、该怎么改。

到这里，Hify 的前端已经不再只是"有几个页面能打开"，而是开始具备一套真正像产品的视觉语言和组件体系了。

而这也意味着，接下来进入正式业务页面开发时，你不再是在一块空白画布上硬做，而是在一个已经有设计系统、有公共组件、有打磨方法的前端基础上继续往前推进。