docs(test): 添加设计文档、测试规范与 E2E 测试套件

- 新增 ADR 架构决策记录 (Design DNA 集成与深化)
- 新增 CMS 系统设计文档
- 新增实施计划文档 (Phase1-3)
- 新增 Bain 品牌升级设计规格
- 新增 E2E 分层测试套件 (P1-P4)
- 新增视觉回归测试配置
- 新增光效分析、视觉验证等辅助脚本
- 更新验收测试报告
This commit is contained in:
张翔
2026-07-07 06:54:25 +08:00
parent 8def296301
commit 636bc4ecde
31 changed files with 9262 additions and 41 deletions
@@ -0,0 +1,599 @@
# 第一阶段:打好地基(Accenture 骨架)实现计划
> **面向 AI 代理的工作者:** 必需子技能:使用 superpowers:subagent-driven-development(推荐)或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框(`- [ ]`)语法来跟踪进度。
**目标:** 建立工业化、可扩展的设计系统基础,完成组件库清理和核心模块搭建
**架构:** 以 Accenture 工业化设计系统为骨架,完善三级设计令牌体系,统一组件库版本,搭建服务网格和数据条核心模块
**技术栈:** Next.js 14 + TypeScript + Tailwind CSS + CSS Variables + Framer Motion
---
## 文件结构总览
| 文件 | 操作 | 职责 |
|------|------|------|
| `src/app/globals.css` | 修改 | 设计令牌三级结构整理、金色残留清理、补充组件令牌 |
| `tailwind.config.js` | 修改 | 令牌映射优化、新组件令牌注册 |
| `src/components/sections/section-header.tsx` | 修改 | 金色→品牌红、样式优化、移除 font-serif |
| `src/components/sections/stats-bar.tsx` | 修改 | 样式升级、移除 font-serif、品牌色优化 |
| `src/components/sections/case-card.tsx` | 修改 | 金色残留清理 |
| `src/components/sections/insight-card.tsx` | 修改 | 金色残留清理 |
| `src/app/(marketing)/home-content.tsx` | 修改 | 金色残留清理 |
| `src/components/ui/scroll-reveal.tsx` | 修改 | 统一为唯一 ScrollReveal 组件 |
| `src/components/sections/scroll-reveal.tsx` | 删除 | 重复组件,迁移到 ui/ |
| `src/components/sections/service-grid.tsx` | 新建 | Accenture 式服务网格组件 |
| `src/components/sections/service-card.tsx` | 新建 | 服务卡片(编号 + 4px 色条) |
| `src/app/(marketing)/_archive/` | 移动 | 归档所有 v1 内容文件 |
| `src/components/content/sections.tsx` | 修改 | 已有内容组件,无需大改 |
---
### 任务 1:设计令牌体系完善与金色残留清理
**文件:**
- 修改:`src/app/globals.css`
- 修改:`tailwind.config.js`
#### 1.1 金色残留清理
- [ ] **步骤 1:定位所有金色配色引用**
运行搜索确认所有金色相关代码位置:
- `--color-gold-text`
- `--color-gold`
- `#C9A84C`
- `gold` 相关变量
涉及文件:section-header.tsx、case-card.tsx、insight-card.tsx、home-content.tsx
- [ ] **步骤 2:全局清理金色 CSS 变量**
在 globals.css 中删除所有 gold 相关变量,替换为品牌色或移除:
- `--color-gold-text` → 不再使用,统一用 `--color-brand``--color-text-muted`
- `--color-gold` → 直接删除
- [ ] **步骤 3:验证无金色残留**
运行搜索确认零结果:
```bash
grep -r "gold\|C9A84C" src/ --include="*.tsx" --include="*.css" --include="*.ts"
```
预期:0 个匹配
#### 1.2 三级令牌命名规范梳理
- [ ] **步骤 4:确认 base tokens(基础令牌)已完整**
检查 globals.css 中的基础令牌(颜色、字体、间距、圆角、阴影、动效),确保:
- 颜色:墨色、品牌色、辅助色、背景色、文字色、边框色、功能色 —— 全部存在
- 排版:字号、行高、字间距 —— 全部存在
- 间距:xs 到 6xl —— 全部存在
- 圆角:xs 到 full —— 全部存在
- 阴影:xs 到 xl + brand + glow —— 全部存在
- 动效:时长、缓动、stagger —— 全部存在
- [ ] **步骤 5:确认 semantic tokens(语义令牌)已完整**
检查语义化命名:
- `--color-bg-primary/secondary/tertiary`
- `--color-text-primary/secondary/tertiary/muted`
- `--color-border-primary/secondary`
- `--color-link/link-hover`
- `--color-success/warning/error/info`
- [ ] **步骤 6:补充 component tokens(组件令牌)**
在 globals.css 已有的组件令牌基础上,补充缺失项:
`/* === 组件令牌层(Component Tokens=== */` 区域补充:
```css
/* 导航 */
--nav-height: 4rem;
--nav-height-md: 4.5rem;
--nav-item-padding-x: 1rem;
--nav-item-padding-y: 0.75rem;
/* 标签/徽章 */
--badge-height: 1.5rem;
--badge-padding-x: 0.625rem;
--badge-font-size: 0.75rem;
--badge-border-radius: var(--radius-sm);
/* 输入框 */
--input-height: 2.75rem;
--input-padding-x: 1rem;
--input-border-radius: var(--radius-sm);
/* 下拉菜单 */
--dropdown-min-width: 12rem;
--dropdown-padding: 0.5rem;
--dropdown-border-radius: var(--radius-md);
--dropdown-shadow: var(--shadow-lg);
/* 模态框 */
--modal-max-width: 32rem;
--modal-padding: 2rem;
--modal-border-radius: var(--radius-xl);
--modal-shadow: var(--shadow-xl);
/* 表格 */
--table-row-height: 3rem;
--table-cell-padding-x: 1rem;
--table-cell-padding-y: 0.75rem;
/* 标签页 */
--tab-height: 2.75rem;
--tab-padding-x: 1.25rem;
--tab-border-radius: var(--radius-sm);
/* 提示框 */
--alert-padding-y: 1rem;
--alert-padding-x: 1.25rem;
--alert-border-radius: var(--radius-md);
```
- [ ] **步骤 7:同步更新 tailwind.config.js**
在 tailwind.config.js 的 theme.extend 中补充新组件令牌的映射(如果需要作为 Tailwind 工具类使用的话)。
- [ ] **步骤 8:运行 TypeScript 检查**
```bash
npx tsc --noEmit
```
预期:0 errors
---
### 任务 2:组件库系统化清理
**文件:**
- 删除:`src/components/sections/scroll-reveal.tsx`(重复,保留 ui/ 下的)
- 移动:所有 v1 内容文件到 `_archive/`
- 修改:所有引用了 sections/scroll-reveal 的文件
#### 2.1 重复组件清理
- [ ] **步骤 1:确认 ui/scroll-reveal.tsx 是主版本**
读取 `src/components/ui/scroll-reveal.tsx` 确认其功能完整。
- [ ] **步骤 2:更新所有引用路径**
将所有从 `@/components/sections/scroll-reveal` 的导入改为从 `@/components/ui/scroll-reveal` 导入。
搜索引用:
```bash
grep -r "from.*sections/scroll-reveal" src/ --include="*.tsx" --include="*.ts"
```
逐个修改导入路径。
- [ ] **步骤 3:删除 sections/scroll-reveal.tsx**
```bash
rm src/components/sections/scroll-reveal.tsx
```
#### 2.2 v1 内容文件归档
- [ ] **步骤 4:确认所有 v1 内容文件列表**
| 文件 | 当前位置 | 目标位置 |
|------|---------|---------|
| services-content-v1.tsx | `services/` | `_archive/` |
| service-detail-content-v1.tsx | `services/` | `_archive/` |
| team-content-v1.tsx | `team/` | `_archive/` |
| news-content-v1.tsx | `news/` | `_archive/` |
| news-detail-content-v1.tsx | `news/` | `_archive/` |
| about-content-v1.tsx | `about/` | `_archive/` |
| solutions-content-v1.tsx | `solutions/` | `_archive/` |
| solution-detail-content-v1.tsx | `solutions/` | `_archive/` |
| product-detail-content-v1.tsx | `products/` | `_archive/` |
| products-content-v1.tsx | `products/` | `_archive/` |
| erp-upgrade-content-v1.tsx | `products/erp-upgrade/` | `_archive/` |
| contact-content-v1.tsx | `contact/` | `_archive/` |
- [ ] **步骤 5:确认 v1 文件无引用**
搜索确认没有页面文件还在 import v1 内容:
```bash
grep -r "content-v1" src/app --include="*.tsx" --include="*.ts" | grep -v "_archive"
```
预期:0 个结果(除 _archive 外)
- [ ] **步骤 6:移动到 _archive 目录**
将所有 v1 文件移动到 `src/app/(marketing)/_archive/` 目录。
移动后验证:
```bash
ls src/app/\(marketing\)/_archive/ | grep v1
```
预期:12 个文件
#### 2.3 金色残留组件修复
- [ ] **步骤 7:修复 SectionHeader 组件**
修改 `src/components/sections/section-header.tsx`
1. 删除所有 `--color-gold-text``#C9A84C` 引用
2. Eyebrow label 颜色改为 `var(--color-brand)`(品牌红贯穿)
3. 移除 `font-serif` 类,改为系统 sans 字体
4. 优化样式,符合 Accenture 风格
- [ ] **步骤 8:修复 CaseCard 组件**
修改 `src/components/sections/case-card.tsx`
1. 删除金色相关变量引用
2. 替换为品牌色或中性色
- [ ] **步骤 9:修复 InsightCard 组件**
修改 `src/components/sections/insight-card.tsx`
1. 删除金色相关变量引用
2. 替换为品牌色或中性色
- [ ] **步骤 10:修复 home-content.tsx**
修改 `src/app/(marketing)/home-content.tsx`
1. 删除金色相关变量引用
2. 替换为品牌色或中性色
- [ ] **步骤 11:验证金色残留为零**
```bash
grep -r "gold\|C9A84C" src/ --include="*.tsx" --include="*.css" --include="*.ts" | grep -v "_archive" | grep -v node_modules
```
预期:0 个结果
- [ ] **步骤 12:运行 TypeScript 检查**
```bash
npx tsc --noEmit
```
预期:0 errors
---
### 任务 3:服务网格模块(Accenture 式)
**文件:**
- 新建:`src/components/sections/service-grid.tsx`
- 新建:`src/components/sections/service-card.tsx`
#### 3.1 ServiceCard 组件
- [ ] **步骤 1:创建 ServiceCard 组件**
`src/components/sections/service-card.tsx` 创建服务卡片组件:
```tsx
'use client';
import { motion } from 'framer-motion';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import Link from 'next/link';
export type ServiceColor = 'blue' | 'teal' | 'amber' | 'purple';
interface ServiceCardProps {
number: string;
title: string;
description: string;
color: ServiceColor;
href: string;
className?: string;
delay?: number;
}
const colorMap: Record<ServiceColor, string> = {
blue: 'var(--color-accent-blue)',
teal: 'var(--color-accent-teal)',
amber: 'var(--color-accent-amber)',
purple: 'var(--color-accent-purple)',
};
export function ServiceCard({
number,
title,
description,
color,
href,
className = '',
delay = 0,
}: ServiceCardProps) {
const shouldReduceMotion = useReducedMotion();
const accentColor = colorMap[color];
return (
<motion.div
className={`group relative bg-[var(--color-bg-primary)] rounded-[var(--radius-lg)] overflow-hidden transition-all duration-[var(--transition-normal)] ease-[var(--ease-ink)] hover:-translate-y-1 hover:shadow-[var(--shadow-lg)] ${className}`}
initial={shouldReduceMotion ? {} : { opacity: 0, y: 24 }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true, margin: '-40px' }}
transition={{ duration: 0.6, delay, ease: [0.22, 1, 0.36, 1] }}
>
{/* 左侧 4px 色条 */}
<div
className="absolute left-0 top-0 bottom-0 w-1 transition-all duration-[var(--transition-normal)] group-hover:w-1.5"
style={{ backgroundColor: accentColor }}
/>
<div className="p-6 md:p-8 pl-6 md:pl-8">
{/* 大号背景编号 */}
<div
className="absolute top-4 right-6 text-[5rem] font-black leading-none select-none pointer-events-none transition-opacity duration-[var(--transition-normal)] group-hover:opacity-10"
style={{ color: 'var(--color-border-light)', opacity: 0.06 }}
aria-hidden="true"
>
{number}
</div>
{/* 编号标签 */}
<div
className="text-xs font-bold tracking-[0.18em] uppercase mb-4"
style={{ color: accentColor }}
>
{number}
</div>
{/* 标题 */}
<h3 className="text-xl md:text-2xl font-bold mb-3 leading-tight" style={{ color: 'var(--color-text-primary)' }}>
{title}
</h3>
{/* 描述 */}
<p className="text-sm md:text-base leading-relaxed mb-6" style={{ color: 'var(--color-text-secondary)' }}>
{description}
</p>
{/* 链接 */}
<Link
href={href}
className="inline-flex items-center text-sm font-medium transition-colors duration-[var(--transition-fast)]"
style={{ color: 'var(--color-brand)' }}
>
<svg
className="ml-1.5 w-4 h-4 transform transition-transform duration-[var(--transition-fast)] group-hover:translate-x-1"
fill="none"
viewBox="0 0 24 24"
stroke="currentColor"
>
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
</svg>
</Link>
</div>
</motion.div>
);
}
```
- [ ] **步骤 2:验证组件无 TypeScript 错误**
```bash
npx tsc --noEmit src/components/sections/service-card.tsx
```
预期:0 errors
#### 3.2 ServiceGrid 组件
- [ ] **步骤 3:创建 ServiceGrid 组件**
`src/components/sections/service-grid.tsx` 创建服务网格组件:
```tsx
'use client';
import { ServiceCard, type ServiceColor } from './service-card';
import { SectionHeader } from './section-header';
interface ServiceItem {
number: string;
title: string;
description: string;
color: ServiceColor;
href: string;
}
interface ServiceGridProps {
label?: string;
title: string;
highlight?: string;
desc?: string;
items: ServiceItem[];
className?: string;
}
export function ServiceGrid({
label = '我们的服务',
title,
highlight,
desc,
items,
className = '',
}: ServiceGridProps) {
return (
<section className={`section-padding ${className}`}>
<div className="container-x">
<SectionHeader label={label} title={title} highlight={highlight} desc={desc} />
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 md:gap-8">
{items.map((item, index) => (
<ServiceCard
key={item.number}
number={item.number}
title={item.title}
description={item.description}
color={item.color}
href={item.href}
delay={index * 0.1}
/>
))}
</div>
</div>
</section>
);
}
```
- [ ] **步骤 4:验证组件无 TypeScript 错误**
```bash
npx tsc --noEmit src/components/sections/service-grid.tsx
```
预期:0 errors
- [ ] **步骤 5:在首页集成 ServiceGrid 做测试**
在 home-content.tsx 中临时添加一个使用示例,确保组件能正常渲染。测试后保留或根据实际内容结构调整。
---
### 任务 4:数据条组件升级(Stats Bar)
**文件:**
- 修改:`src/components/sections/stats-bar.tsx`
#### 4.1 StatsBar 样式升级
- [ ] **步骤 1:优化 StatsBar 组件**
修改 `src/components/sections/stats-bar.tsx`
1. 移除 `font-serif`,改为 sans 字体
2. 优化颜色使用,确保品牌红正确使用
3. 增强数字滚动动画(优化缓动曲线)
4. 增加 tabular-nums 数字等宽
5. 优化间距和响应式布局
6. 统一使用 CSS 变量而非内联样式中的硬编码值
关键改动:
```tsx
// 数字样式
className="font-sans tabular-nums text-[clamp(2.5rem,5vw,4rem)] font-extrabold leading-none mb-2 tracking-[-0.02em]"
// 品牌色单位
<span style={{ color: 'var(--color-brand)', fontSize: '0.4em', fontWeight: 700 }}>
{item.unit}
</span>
// 标签样式
className="text-xs sm:text-sm font-medium mb-2 tracking-[0.08em] uppercase"
```
- [ ] **步骤 2:验证组件无 TypeScript 错误**
```bash
npx tsc --noEmit src/components/sections/stats-bar.tsx
```
预期:0 errors
---
### 任务 5:页面布局规范统一
**文件:**
- 修改:`src/app/globals.css`(补充布局相关工具类)
- 检查:核心页面的 Section 间距一致性
#### 5.1 12 列网格确认
- [ ] **步骤 1:确认 Tailwind 默认 12 列网格可用**
检查 tailwind.config.js,确保:
- `grid-cols-1``grid-cols-12` 可用(Tailwind 默认支持)
- `gap` 间距与设计令牌对齐
- [ ] **步骤 2:补充布局工具类**
在 globals.css 的 `@layer utilities` 中确认以下类存在:
- `.container-x` ✅ 已存在
- `.section-padding` ✅ 已存在
确认响应式断点正确:
- sm: 640px
- md: 768px
- lg: 1024px
- xl: 1280px
- 2xl: 1536px
#### 5.2 Section 间距规范检查
- [ ] **步骤 3:抽查 3 个核心页面的 Section 间距**
检查页面:
1. 首页(home-content.tsx
2. 服务列表页(services-content-v2.tsx
3. 关于页(about-content-v2.tsx
确保所有 Section 统一使用 `section-padding` 类,间距一致。
如发现不一致,记录并修复。
---
### 任务 6:第一阶段验收
#### 6.1 代码质量检查
- [ ] **步骤 1TypeScript 类型检查**
```bash
npx tsc --noEmit
```
预期:0 errors
- [ ] **步骤 2:生产构建**
```bash
npm run build
```
预期:构建成功,无报错
- [ ] **步骤 3ESLint 检查**
```bash
npx eslint src/ --ext .ts,.tsx
```
预期:0 errorswarning 可接受)
#### 6.2 功能验证
- [ ] **步骤 4:启动开发服务器**
```bash
npm run dev
```
- [ ] **步骤 5:视觉验证清单**
在浏览器中验证:
1. ✅ 金色配色完全消失,品牌红正确贯穿
2. ✅ SectionHeader 样式正常(eyebrow 品牌红、字体 sans
3. ✅ StatsBar 数字滚动正常
4. ✅ ServiceGrid 服务卡片渲染正常(编号 + 色条)
5. ✅ 页面布局无错乱
6. ✅ 响应式布局正常(移动端/平板/桌面)
7. ✅ 暗色模式切换正常
8. ✅ 无控制台错误
---
## 验收标准
第一阶段完成标志:
1. ✅ 金色配色零残留
2. ✅ 三级设计令牌体系完善(base + semantic + component
3. ✅ 重复组件清理完成(scroll-reveal 统一)
4. ✅ v1 内容文件全部归档
5. ✅ ServiceGrid + ServiceCard 组件可用
6. ✅ StatsBar 样式升级完成
7. ✅ TypeScript 0 errors
8. ✅ 生产构建成功
9. ✅ 核心页面视觉正常
完成后,项目设计系统完成度从 40/100 → 65/100。