| name | beautiful-component-design |
| description | 移动端 uni-app + wot-design-uni 组件美化规范 - 提供图标、文本对齐、响应式设计、表单分区标题、选择器美化、弹框交互的完整规范。
触发条件（满足任意一项即触发）：
- 需要添加 FormSectionTitle 组件（表单分区标题）
- 需要使用 Carbon Icons 图标
- 需要实现响应式设计（rpx 单位、图片网格）
- 需要美化选择器组件（wd-picker）
- 需要实现弹框交互（wd-message-box、wd-popup）
- 需要美化详情页卡片（通栏标题 + 色彩编码）
- 用户提及"美化"、"图标"、"对齐"、"响应式"、"FormSectionTitle"等关键词
- 修复组件嵌套顺序错误（wd-picker 和 wd-cell）
- 修复插槽使用错误（#value 插槽不存在）
必须协同的技能：
- use-wd-form（表单页面必须协同）
- api-migration（如果有接口调用）
- api-error-handling（如果有接口调用）
- z-paging-integration（列表页面美化）
禁止项：
- 禁止使用 <view class="section-title"> 代替 FormSectionTitle
- 禁止 wd-cell 包裹 wd-picker（正确：wd-picker 包裹 wd-cell）
- 禁止使用不存在的 #value 插槽（wd-cell 没有此插槽）
- 禁止使用 wd-popup 实现标准交互（应使用 wd-message-box）
- 禁止在详情页卡片容器保留 padding（应移除以实现通栏标题）
覆盖场景：表单页面、详情页面、列表页面、选择器页面、弹框交互、图标使用、响应式布局等所有需要美化的场景。
|
name: beautiful-component-design
color: pink
组件美化设计规范
用于指导编写视觉美观、文本与图标对齐良好、响应式友好的 Vue 组件的最佳实践。
⚠️ 多技能协同
表单页面通常需要同时使用：
use-wd-form - 表单结构、wd-picker、校验规则api-migration - 如果有接口调用api-error-handling - 如果有接口调用
列表页面通常需要：
z-paging-integration + api-migration - 分页列表
参阅 .claude/skills/check-trigger.md 了解完整的技能触发检查流程。
核心文档
使用本技能前必须阅读：
参考示例：
src/pages-sub/repair/staff-todo-detail.vue - 完整美化示例src/pages-sub/repair/select-resource.vue - 表单页面示例src/pages-sub/repair/add-order.vue - FormSectionTitle 使用示例
1. 专业能力
- 图标规范设计: 精通 Carbon Icons 图标集使用，熟悉图标与文本对齐的视觉设计原则
- 文本样式控制: 掌握 wot-design-uni 组件文本样式覆盖技巧，实现统一的字号和行高
- 响应式布局: 熟悉 uni-app rpx 单位系统和 UnoCSS 原子化 CSS，实现响应式友好设计
- 时间轴组件: 能设计美观的流程记录时间轴，支持状态颜色区分和动态数据展示
- 图片网格: 掌握响应式图片网格布局，支持多图展示和预览功能
2. 快速开始
2.1 图标使用模式
<template>
<wd-cell title="报修ID" :value="repairDetail.repairId">
<template #icon>
<wd-icon
name=""
custom-class="i-carbon-edit text-colorui-green mr-8rpx w-36rpx h-36rpx flex items-center justify-center"
/>
</template>
</wd-cell>
</template>
图标规范详见 references/icon-usage.md
2.2 文本样式统一
<template>
<view class="text-36rpx">主内容</view>
<view class="text-gray-600">次要内容</view>
</template>
文本规范详见 references/text-alignment.md
2.3 响应式图片网格
<template>
<view class="photo-grid">
<view v-for="(photo, index) in photos" :key="index" class="photo-grid__item">
<wd-img
:src="photo.url || photo.photo"
mode="aspectFill"
class="aspect-square w-full rounded"
:enable-preview="true"
/>
</view>
</view>
</template>
<style scoped>
.photo-grid {
display: flex;
flex-wrap: wrap;
margin: -8rpx;
}
.photo-grid__item {
box-sizing: border-box;
width: 33.3333%;
padding: 8rpx;
}
</style>
响应式规范详见 references/responsive-design.md
3. 设计原则
| 原则 | 说明 |
|---|
| 大小协调 | 文本 = 图标尺寸 - (4~8)rpx |
| 高度一致 | 行高 = 图标高度 |
| 对齐方式 | display: flex + align-items: center |
| 样式穿透 | :deep() + !important |
4. 本项目标准配置
.icon {
width: 36rpx;
height: 36rpx;
flex-shrink: 0;
}
.text {
font-size: 28rpx;
line-height: 36rpx;
}
.container {
display: flex;
align-items: center;
}
.container__text {
margin-left: 8rpx;
}
5. 目录
6. 选择器组件美观规范（⚠️ 重要）
在表单中使用 wd-picker 选择器组件时，需要特别注意组件嵌套顺序和标签宽度的一致性。
6.1. ⚠️ 严重错误：禁止的嵌套方式和插槽使用
❌ 绝对禁止使用不存在的 #value 插槽，会导致选择器无法显示和点击！
<!-- ❌ 严重错误！使用了不存在的 #value 插槽，导致选择器无法显示和点击 -->
<template>
<wd-cell-group border>
<wd-cell :title-width="LABEL_WIDTH" center>
<template #title>
<text>商品类型</text>
</template>
<template #value>
<!-- ❌ 错误1: wd-cell 组件没有 #value 插槽！#value 是 CellGroup 的插槽 -->
<!-- ❌ 错误2: wd-picker 被 wd-cell 包裹，点击事件被阻挡 -->
<wd-picker v-model="selectedIndex" :columns="options" label-key="name" value-key="id">
<text class="text-blue-500">
{{ options[selectedIndex]?.name || "请选择" }}
</text>
</wd-picker>
</template>
</wd-cell>
</wd-cell-group>
</template>
问题原因:
wd-cell 组件没有 #value 插槽！根据官方文档，wd-cell 组件支持的插槽只有：title、default（右侧内容）、icon、label。#value 插槽是 wd-cell-group 组件的插槽，不是 wd-cell 的插槽。- 即使改用正确的插槽，
wd-cell 包裹 wd-picker 也会导致点击事件被阻挡，选择器弹窗无法正常打开。
6.2. ✅ 正确做法 1: 标准模式（推荐）
使用场景: 绝大多数情况下使用此方式，简洁高效。
<template>
<wd-cell-group border>
<!-- ✅ 正确：直接使用 wd-picker，通过 label 属性设置标题 -->
<wd-picker
v-model="model.category"
label="分类"
:label-width="LABEL_WIDTH"
:columns="categoryOptions"
label-key="name"
value-key="id"
/>
</wd-cell-group>
</template>
6.3. ✅ 正确做法 2: 自定义插槽模式
使用场景: 仅在需要动态标题或复杂自定义显示时使用。
关键要点: wd-picker 包裹 wd-cell，而不是反过来！
<template>
<wd-cell-group border>
<!-- ✅ 正确：wd-picker 包裹 wd-cell，用于自定义显示 -->
<wd-picker
v-model="model.staffId"
:columns="staffOptions"
label-key="staffName"
value-key="staffId"
@confirm="handleStaffChange"
>
<wd-cell title="维修师傅" :title-width="LABEL_WIDTH" is-link center custom-value-class="cell-value-left">
<text :class="model.staffId ? 'text-gray-900' : 'text-gray-400'">
{{ selectedStaff?.staffName || "请选择员工" }}
</text>
</wd-cell>
</wd-picker>
</wd-cell-group>
</template>
<style lang="scss" scoped>
/** wd-cell 值靠左对齐 - 确保选择器选中值与其他表单项对齐 */
:deep(.cell-value-left) {
flex: 1;
text-align: left !important;
}
</style>
6.4. 关键属性说明（自定义插槽模式）
| 属性 | 作用 | 必要性 |
|---|
:title-width="80px" | 统一标签宽度，与其他项对齐 | 必须设置 |
center | 内容垂直居中对齐 | 必须设置 |
custom-value-class | 自定义选中值样式类，配合样式穿透使用 | 必须设置 |
is-link | 显示右侧箭头图标 | 推荐设置 |
6.5. 样式穿透要点
:deep(.cell-value-left) {
flex: 1;
text-align: left !important;
}
6.6. 📝 选择器使用检查清单
使用 wd-picker 组件时，请务必检查：
- ✅ 组件嵌套顺序:
wd-picker 在外层，wd-cell 在内层（仅自定义插槽模式）
- ✅ 优先使用标准模式: 直接使用
label 属性，除非确实需要自定义显示
- ✅ label-width/title-width: 与其他表单项保持一致的标签宽度
- ✅ 点击测试: 实现后务必测试选择器能否正常点击弹出
- ❌ 禁止使用
#value 插槽: wd-cell 组件没有 #value 插槽！不要将 wd-picker 或任何内容放在 wd-cell 的 #value 插槽内
- ❌ 禁止错误嵌套: 将
wd-picker 放在 wd-cell 内部会导致点击事件被阻挡
7. 弹框交互组件选型（⚠️ 重要）
在实现弹框交互时，必须优先使用 wd-message-box 而非 wd-popup，以确保视觉美观和用户体验。
7.1. ⚠️ 错误做法：使用 wd-popup 实现用户输入
<!-- ❌ 严重的视觉和代码问题 -->
<template>
<wd-popup v-model="showStopModal" position="center" closable>
<view class="p-6" style="width: 80vw;">
<view class="mb-4 text-center text-lg font-bold">暂停原因</view>
<!-- 问题1: 输入框没有边界，用户不知道哪里可以点击 -->
<!-- 问题2: 布局留白过大，视觉重心不稳 -->
<wd-textarea v-model="stopReason" placeholder="请填写暂停原因" :maxlength="200" show-word-limit :rows="4" />
<!-- 问题3: 按钮主次不分明，取消按钮颜色过于突出 -->
<view class="mt-4 flex">
<wd-button block @click="showStopModal = false">取消</wd-button>
<wd-button block type="primary" custom-class="ml-12rpx" @click="handleConfirm">确定</wd-button>
</view>
</view>
</wd-popup>
</template>
视觉问题总结（参考用户反馈截图）：
| 问题分类 | 具体表现 | 用户体验影响 |
|---|
| 输入区域 | 输入框无边框/背景色，占位符悬空，字数统计孤立 | 用户不知道哪里可以输入，认知负荷高 |
| 布局留白 | 垂直高度过高，中间空白区域占比过大 | 视觉流线断裂，廉价感、不专业 |
| 按钮样式 | 取消/确定按钮视觉权重接近，主次不分（颜色对比低） | 容易误操作，无障碍设计不达标 |
| 标题层级 | 标题与内容区分度不够，缺少分割线 | 内容层次感不清晰 |
7.2. ✅ 正确做法：使用 wd-message-box.prompt()
<!-- ✅ 系统原生风格，开箱即用，视觉美观 -->
<template>
<wd-button @click="handleStop(item)">暂停</wd-button>
</template>
<script setup lang="ts">
import { useGlobalMessage } from "@/hooks/useGlobalMessage";
const message = useGlobalMessage();
function handleStop(item: RepairOrder) {
message.prompt({
title: "暂停维修",
msg: "请填写暂停原因",
inputPlaceholder: "请输入暂停原因（必填）",
inputValue: "",
maxlength: 200,
inputValidate: (value: string) => {
if (!value || !value.trim()) {
return "暂停原因不能为空";
}
return true;
},
success: async (res) => {
if (res.action === "confirm" && res.value) {
// 直接使用输入值
await stopRepair({ repairId: item.repairId, remark: res.value.trim() });
}
},
});
}
</script>
7.3. 视觉效果对比
| 对比项 | wd-popup | wd-message-box |
|---|
| 输入框边界 | ❌ 无边框，占位符悬空，无法识别输入区域 | ✅ 清晰的边框和背景色，输入区域明确 |
| 布局留白 | ❌ 垂直留白过大，视觉重心不稳 | ✅ 紧凑合理，内容密度适中 |
| 按钮主次关系 | ❌ 取消/确定颜色对比低，易误操作 | ✅ 主次分明，确定按钮视觉权重更高 |
| 代码复杂度 | ❌ 需维护状态、模板、样式代码 | ✅ 零状态管理，一次性配置对象 |
| 无障碍设计 | ❌ 颜色对比度不足，可读性差 | ✅ 符合无障碍设计标准 |
7.4. 组件选型决策
需要弹框交互？
├─ 是标准场景（确认、提示、输入）？
│ └─ 是 → ✅ 使用 `wd-message-box`（confirm/alert/prompt）
└─ 需要复杂自定义内容（如多步骤表单、富文本编辑器）？
├─ 是 → 使用 `wd-popup`
└─ 否 → ⚠️ 优先使用 `wd-message-box`，避免自己实现视觉细节
7.5. 迁移检查清单
发现代码中使用 wd-popup 实现用户输入时，检查是否应该迁移：
如果以上任意一项为 是，强烈建议迁移到 wd-message-box。
📚 详细文档: 参阅 .claude/skills/component-migration/SKILL.md 第 8 节
📚 实际案例: src/pages-sub/repair/dispatch.vue:208-233
8. 详情页卡片设计规范（⚠️ 重要）
详情页通常包含多个信息卡片，需要统一的视觉风格和清晰的信息层次。本节介绍如何在详情页中使用 FormSectionTitle 组件和色彩编码系统。
8.1. 设计理念：通栏标题 + 色彩编码
核心策略
采用 "通栏标题 + 色彩编码" 的设计策略：
- 结构融合：
FormSectionTitle 不仅是分隔符，而是作为每个信息卡片的 "页眉 (Header)"。通过消除卡片容器的内边距，让淡灰色的标题栏撑满卡片顶部，形成 "灰色标题区 + 白色内容区" 的经典文档结构。
- 色彩编码系统：为不同类型的信息区域分配特定颜色，提升视觉识别度和导航效率。
- 圆角一致性：严格遵循小圆角 (
rounded-sm) 规范，使用 overflow-hidden 确保标题栏与卡片完美融合。
色彩编码体系
| 颜色类型 | HEX 色值 | 使用场景 | Carbon 图标示例 | 色彩心理学 |
|---|
| 🟦 蓝色 | #3b82f6 | 报修内容、核心信息 | document, file-doc | 理性、客观、文档数据 |
| 💠 青色 | #06b6d4 | 流转记录、时间轴 | time, history | 时间流逝、状态变更、流动感 |
| 🟧 橙色 | #ff9900 | 工单附件、图片墙 | image, folder-media | 视觉媒体、活力、吸引注意力 |
| 🟩 绿色 | #52c41a | 完成状态、成功提示 | checkmark, success | 成功、完成、正向反馈 |
| 🟥 红色 | #ef4444 | 警告信息、必填项 | warning, error | 警告、危险、需要关注 |
8.2. ✅ 正确做法：卡片结构调整
标准卡片模板
<template>
<!-- ✅ 正确：移除 padding，添加 overflow-hidden -->
<view class="mb-3 overflow-hidden rounded-sm bg-white shadow-sm">
<!-- 标题栏：FormSectionTitle 作为卡片头部 -->
<FormSectionTitle title="报修内容" icon="document" icon-class="i-carbon-document text-blue-500" :animated="false" />
<!-- 内容区：重新包裹并补回 padding -->
<view class="p-4">
<!-- 卡片内容 -->
<view class="text-sm text-gray-600 leading-relaxed">
{{ content }}
</view>
</view>
</view>
</template>
结构调整技巧
| 步骤 | 操作 | 目的 |
|---|
| 步骤 1 | 移除卡片容器的 p-4 | 让 FormSectionTitle 撑满卡片宽度 |
| 步骤 2 | 添加 overflow-hidden | 配合小圆角，让直角的标题栏被自动裁剪 |
| 步骤 3 | FormSectionTitle 直接放在卡片顶部 | 形成通栏标题效果 |
| 步骤 4 | 内容区域用 <view class="p-4"> 重新包裹 | 补回内边距，确保内容不贴边 |
⚠️ 常见错误
<!-- ❌ 错误1：卡片容器保留了 padding -->
<view class="mb-3 rounded-sm bg-white p-4 shadow-sm">
<FormSectionTitle title="报修内容" />
<!-- 问题：FormSectionTitle 两侧有留白，无法形成通栏效果 -->
</view>
<!-- ❌ 错误2：缺少 overflow-hidden -->
<view class="mb-3 rounded-sm bg-white shadow-sm">
<FormSectionTitle title="报修内容" />
<!-- 问题：FormSectionTitle 默认直角，与卡片圆角不匹配 -->
</view>
<!-- ❌ 错误3：内容区域没有 padding -->
<view class="mb-3 overflow-hidden rounded-sm bg-white shadow-sm">
<FormSectionTitle title="报修内容" />
<view class="text-sm">内容贴边显示</view>
<!-- 问题：内容直接贴边，缺少呼吸感 -->
</view>
8.3. 色彩编码应用矩阵
维修工单详情页示例
| 卡片区域 | 标题文本 | 图标 (icon) | 图标样式 (icon-class) | 动效 (animated) | 理由 |
|---|
| 报修内容 | 报修内容 | document | i-carbon-document text-blue-500 | false | 静态核心信息，蓝色代表理性/文档 |
| 工单附件 | 工单附件 | image | i-carbon-image text-orange-500 | false | 图片区域，橙色代表视觉媒体 |
| 流转记录 | 流转记录 | time / history | i-carbon-time text-cyan-500 | true | 动态区域，青色呼应状态流转，启用动效 |
动效使用原则
- ✅ 启用动效：流转记录、处理中状态、动态更新区域
- ❌ 禁用动效：静态内容、已完成状态、图片附件
8.4. 实际案例代码
完整示例：维修工单详情页
<script setup lang="ts">
import FormSectionTitle from "@/components/common/form-section-title/index.vue";
import RepairStatusTag from "@/components/common/repair-status-tag/index.vue";
</script>
<template>
<view class="repair-detail-page">
<!-- 1. 头部状态卡片（不使用 FormSectionTitle，保持独立设计） -->
<view class="relative mb-3 overflow-hidden rounded-sm bg-white p-4 shadow-sm">
<view class="flex items-start justify-between">
<view>
<text class="mb-1 block text-xs text-gray-500">工单编号</text>
<view class="mb-2 text-xl text-gray-900 font-bold leading-none">
{{ repairDetail.repairId }}
</view>
</view>
<RepairStatusTag :status-cd="repairDetail.statusCd" :status-name="repairDetail.statusName" :animated="true" />
</view>
</view>
<!-- 2. 报修内容卡片（蓝色系，静态） -->
<view class="mb-3 overflow-hidden rounded-sm bg-white shadow-sm">
<FormSectionTitle
title="报修内容"
icon="document"
icon-class="i-carbon-document text-blue-500"
:animated="false"
/>
<view class="p-4">
<view class="mb-4 text-sm text-gray-600 leading-relaxed">
{{ repairDetail.context }}
</view>
<!-- 基础信息列表 -->
<view class="border-t border-gray-100 pt-4">
<view class="flex items-center justify-between">
<text class="text-sm text-gray-500">报修人</text>
<text class="text-sm text-gray-800 font-medium">{{ repairDetail.repairName }}</text>
</view>
<view class="mt-12rpx flex items-center justify-between">
<text class="text-sm text-gray-500">联系电话</text>
<text class="text-sm text-gray-800 font-medium">{{ repairDetail.tel }}</text>
</view>
</view>
</view>
</view>
<!-- 3. 工单附件卡片（橙色系，静态） -->
<view v-if="hasImages" class="mb-3 overflow-hidden rounded-sm bg-white shadow-sm">
<FormSectionTitle title="工单附件" icon="image" icon-class="i-carbon-image text-orange-500" :animated="false" />
<view class="p-4">
<view class="photo-grid">
<view v-for="(photo, index) in photos" :key="index" class="photo-grid__item">
<wd-img
:src="photo.url"
mode="aspectFill"
class="aspect-square w-full rounded-sm bg-gray-100"
:enable-preview="true"
/>
</view>
</view>
</view>
</view>
<!-- 4. 流转记录卡片（青色系，启用动效） -->
<view v-if="staffRecords.length > 0" class="mb-3 overflow-hidden rounded-sm bg-white shadow-sm">
<FormSectionTitle title="流转记录" icon="time" icon-class="i-carbon-time text-cyan-500" :animated="true" />
<view class="p-4">
<!-- 时间轴内容 -->
<view class="relative pl-2">
<view v-for="(record, index) in staffRecords" :key="index">
<!-- 时间轴节点和内容 -->
</view>
</view>
</view>
</view>
</view>
</template>
<style lang="scss" scoped>
.repair-detail-page {
min-height: 100vh;
background-color: #f5f5f7;
}
.pb-safe {
padding-bottom: calc(24rpx + var(--window-bottom, 0px));
}
.photo-grid {
display: flex;
flex-wrap: wrap;
margin: -8rpx;
}
.photo-grid__item {
box-sizing: border-box;
width: 33.3333%;
padding: 8rpx;
}
</style>
8.5. 设计检查清单
详情页卡片专项检查
色彩一致性检查
8.6. 视觉效果预期
实施该方案后，用户将看到：
- 极具秩序感：每个板块由淡灰色标题条开启，清晰界定信息区域
- 色彩导航：潜意识建立色彩关联 — 蓝色看内容，橙色看图片，青色看进度
- 精致细节：
- 卡片圆角处理得当，标题栏与卡片完美融合
- 呼吸动效在流转记录处轻微律动，暗示工单正在处理中
- 2px 微妙分割线（FormSectionTitle 的
margin-bottom: 2px）
8.7. FormSectionTitle 在表单页 vs 详情页
| 对比项 | 表单页 (use-wd-form) | 详情页（本节内容） |
|---|
| 使用频率 | 每个表单分区都使用 | 仅在重要信息区域使用（3-4 个） |
| 背景处理 | 直接放在页面中，背景自然融入表单 | 作为卡片头部，通过 overflow-hidden 融合 |
| 动效使用 | 通常启用（强调表单区域划分） | 仅在动态区域启用（如流转记录） |
| 色彩编码 | 通常使用单一颜色（如蓝色） | 多色彩编码（蓝/青/橙），提升信息识别度 |
| 卡片结构 | 无需调整，直接使用即可 | 需要移除卡片 padding，添加 overflow-hidden |
| 配合组件 | wd-form, wd-picker, 表单校验规则 | RepairStatusTag, 时间轴, 图片网格 |
8.8. 参考案例
详情页最佳实践：
- ✅
src/pages-sub/repair/order-detail.vue - 维修工单详情页（完整色彩编码示例）
- ✅
src/pages-sub/repair/staff-todo-detail.vue - 待办详情页
- ✅
src/pages-sub/property/apply-room-detail.vue - 房屋申请详情页
表单页最佳实践：
- ✅
src/pages-sub/repair/add-order.vue - FormSectionTitle 在表单中的使用
- ✅
src/pages-sub/repair/select-resource.vue - 表单分区标题示例
9. 典型应用场景
- 维修工单详情页的信息展示
- 报修记录的列表项设计
- 状态展示的标签和图标组合
- 图片墙和画廊展示
- 时间轴和流程记录
- 表单中选择器组件的统一对齐
- 标准弹框交互（确认、提示、输入）
- 详情页卡片的通栏标题和色彩编码
9. 设计检查清单
9.1. 通用美化检查
9.2. 选择器组件专项检查（⚠️ 必须检查）
9.3. 弹框交互组件专项检查（⚠️ 必须检查）
