281 lines
14 KiB
Markdown
281 lines
14 KiB
Markdown
# Precision Atelier 设计系统改造记录
|
||
|
||
## 改动日期
|
||
- 2026-04-02：视觉层改造（配色、字体、组件样式）
|
||
- 2026-04-03：全局布局改造（AppShell 三栏布局 + 去重）
|
||
|
||
## 背景
|
||
基于 `方案设定/stitch/` 中的 17 份前端设计稿（solidjoin_3d_1~15 + solidjoin_precision + solidjoin_3d_inventory_2），将前端视觉风格从 "Apple HIG" 切换为设计稿指定的 "Precision Atelier" 风格。
|
||
|
||
## 核心变更
|
||
|
||
### 1. 配色体系（colors.ts）
|
||
|
||
| 维度 | 旧值 | 新值 | 用途 |
|
||
|------|------|------|------|
|
||
| 品牌色 | `#008D74`（Teal） | `#546067`（Graphite） | 导航高亮、标题、CTA |
|
||
| 次要色 | `#47C4AF` | `#4b626e`（Fog Blue） | 链接、辅助操作 |
|
||
| 成功色 | `#34C759` | `#286c34`（Sage Green） | 成功状态、验证 |
|
||
| 错误色 | `#FF3B30` | `#9f403d` | 错误提示 |
|
||
| 主背景 | `#FFFFFF` | `#f9f9fb`（surface） | 页面底色 |
|
||
| 侧边栏 | `#F5F5F7` | `#f2f4f6`（surface-container-low） | 侧边栏 |
|
||
| 卡片/浮动面板 | `#FFFFFF` | `#ffffff`（surface-container-lowest） | 卡片 |
|
||
| 二级工作区 | — | `#ebeef2`（surface-container） | 数据区域 |
|
||
| 深色背景 | `#000000` / `#1C1C1E` | `#0c0e10` / `#1a1c1e` | 深色主题 |
|
||
|
||
新增令牌：
|
||
- `glassmorphismTokens` — 玻璃面板颜色（70% 白 + blur 20px）
|
||
- `ambientShadowTokens` — 环境阴影（带 on-surface 色调 `rgba(45, 51, 56, 0.06)`）
|
||
- `toastColors` — Toast 专用颜色
|
||
|
||
### 2. 字体系统（typography.ts）
|
||
|
||
双字体策略：
|
||
- **展示字体**：Manrope — 用于品牌标题、大标题
|
||
- **功能字体**：Inter — 用于数据、标签、表单、技术规格
|
||
|
||
命名体系对照：
|
||
| 旧名 | 新名 | 用途 |
|
||
|------|------|------|
|
||
| largeTitle | displayLg (3.5rem) | 品牌大标题 |
|
||
| title1 | displayMd (2.5rem) | 展示标题 |
|
||
| title2 | headlineLg (1.75rem) | 页面标题 |
|
||
| title3 | headlineMd (1.5rem) | 区块标题 |
|
||
| headline | headlineSm (1.25rem) | 小标题 |
|
||
| body | bodyMd (0.875rem) | 正文 |
|
||
| callout | bodyLg (1rem) | 大正文 |
|
||
| subhead | bodySm (0.75rem) | 小正文 |
|
||
| footnote | bodySm (0.75rem) | 注释 |
|
||
| caption1 | bodySm (0.75rem) | 小标签 |
|
||
| caption2 | labelSm (0.6875rem) | 微标签 |
|
||
|
||
兼容处理：`legacyTextStyleMap` 映射旧名到新名，`CompatibleTextStyle` 类型同时接受新旧名。
|
||
|
||
### 3. 全局样式（globals.css）
|
||
|
||
- **@theme 块**：颜色变量全部替换为 Precision Atelier 配色
|
||
- **字间距**：展示标题统一 `letter-spacing: -0.02em`，技术标签 `0.05em`
|
||
- **圆角**：改为紧凑风格（0.375rem ~ 1rem）
|
||
- **过渡**：200ms ease-out（"Snappy but Silky"）
|
||
- **阴影**：环境阴影 `0px 4px 32px rgba(45, 51, 56, 0.06)`
|
||
- **Ghost Border**：`rgba(172, 179, 184, 0.3)` 用于数据网格分隔
|
||
- **深色主题**：完整的深色变量覆盖
|
||
- **Glassmorphism**：70% 白/深 + 20px blur
|
||
- **滑块**：品牌色从 `#008D74` 改为 `#546067`，深色模式对应
|
||
|
||
### 4. UI 组件改动
|
||
|
||
**Button.tsx**
|
||
- filled 变体：纯色背景改为 145° 渐变 `linear-gradient(145deg, var(--color-blue), var(--color-teal))`
|
||
|
||
**Typography.tsx**
|
||
- `variant` prop 类型改为 `CompatibleTextStyle`，兼容旧名（caption1/body/headline 等）
|
||
- `fontType` 新增 `display` 选项，支持 Manrope 展示字体
|
||
|
||
### 5. 硬编码颜色替换
|
||
|
||
~20 个业务文件中的 82 处 `#008D74` 硬编码替换为 CSS 变量引用。
|
||
|
||
### 6. 兼容性处理
|
||
|
||
- `appleColorTokens`、`appleSemanticColors`、`appleToastColors`：旧名兼容导出
|
||
- `appleTypographyTokens`：旧名兼容导出
|
||
- `appleAnimationTokens`：保持原名不变
|
||
- `precisionAtelierSpacingTokens`：新名，旧函数签名不变
|
||
|
||
## 设计原则
|
||
|
||
1. **No-Line Rule**：不用 1px 边框，通过 surface 层级的 hex 差异产生视觉分离
|
||
2. **Glassmorphism**：浮动面板用 70% 白 + 20px blur
|
||
3. **环境阴影**：仅用于浮动元素，颜色带 on-surface 色调
|
||
4. **Snappy but Silky**：200ms ease-out 过渡
|
||
5. **Ghost Border**：数据网格用 0.5px `outline-variant` @ 30% 透明度
|
||
6. **CTA 渐变**：primary → primary-dim，145° 角，"machined metal" 质感
|
||
|
||
## 改动文件清单
|
||
|
||
| 文件 | 改动类型 |
|
||
|------|----------|
|
||
| `src/lib/design-tokens/colors.ts` | 全部重写 |
|
||
| `src/lib/design-tokens/typography.ts` | 全部重写 |
|
||
| `src/lib/design-tokens/spacing.ts` | 重命名+圆角调整 |
|
||
| `src/lib/design-tokens/index.ts` | 注释更新 |
|
||
| `src/app/globals.css` | 颜色/字体/阴影全部替换 |
|
||
| `src/components/ui/Button.tsx` | CTA 渐变效果 |
|
||
| `src/components/ui/Typography.tsx` | 兼容旧名 variant |
|
||
| ~20 个业务文件 | 硬编码颜色替换 |
|
||
|
||
---
|
||
|
||
## 第二阶段：全局布局改造（2026-04-03）
|
||
|
||
### 7. AppShell 三栏布局
|
||
|
||
新增全局布局框架，所有常规页面统一使用三栏结构：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ AppTopNav（h-14，Glassmorphism 毛玻璃顶栏） │
|
||
│ Logo + 搜索 + 通知 + 主题切换 + 用户菜单 │
|
||
├──────────┬──────────────────────────────────────┤
|
||
│ AppSideNav│ 主内容区（ml-56 mt-14） │
|
||
│ w-56 │ │
|
||
│ │ PlatformSplitLayout 等页面组件 │
|
||
│ 导航链接 │ │
|
||
│ 新建配置 │ │
|
||
│ 技术支持 │ │
|
||
│ 归档 │ │
|
||
└──────────┴──────────────────────────────────────┘
|
||
```
|
||
|
||
**新增文件：**
|
||
- `src/components/layout/AppTopNav.tsx` — 固定顶栏（Logo + 搜索 + 工具按钮）
|
||
- `src/components/layout/AppSideNav.tsx` — 固定左侧导航（5 个导航项 + 底部操作区）
|
||
- `src/components/layout/AppShell.tsx` — 全局布局容器，组合 TopNav + SideNav + main
|
||
|
||
**排除页面：** `/login`、`/first-login`、`/debug-theme`、`/ui-preview` 不使用 AppShell。
|
||
|
||
**AppSideNav 导航项：**
|
||
| 路由 | 标签 | 图标 |
|
||
|------|------|------|
|
||
| `/` | 首页概览 | Home |
|
||
| `/asset-center` | 资产中心 | Boxes |
|
||
| `/assisted-assembly` | 辅助装配 | Layers |
|
||
| `/draft-groups` | 草稿组 | PackageOpen |
|
||
| `/warehouse` | 仓库管理 | Warehouse |
|
||
|
||
### 8. 功能去重
|
||
|
||
引入 AppShell 后，各页面中与全局导航重复的元素已清理：
|
||
|
||
**去重 1：顶栏导航 tab 移除**
|
||
- AppTopNav 原本有 5 个导航 tab（首页/资产中心/辅助装配/草稿组/仓库），与 AppSideNav 完全重复
|
||
- 已移除顶栏中的导航 tab，顶栏只保留：Logo、搜索框、通知铃铛、主题切换、用户菜单
|
||
- 导航职责统一由左侧边栏承担
|
||
|
||
**去重 2：页面内 headerTools（ThemeToggle + UserMenu）移除**
|
||
以下 7 个文件移除了 `headerTools={<PlatformHeaderTools user={user} />}` 传参：
|
||
- `src/app/asset-center/AssetCenterClient.tsx`
|
||
- `src/app/assisted-assembly/page.tsx`（服务端）+ `AssistedAssemblyClient.tsx`（客户端）
|
||
- `src/app/draft-groups/DraftGroupsClient.tsx`
|
||
- `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx`
|
||
- `src/app/intake/IntakeClient.tsx`
|
||
- `src/app/warehouse/WarehouseClient.tsx`
|
||
- `src/app/HomeClient.workspace.tsx`
|
||
|
||
**去重 3：eyebrow 副标题移除**
|
||
各页面中 `eyebrow` prop（如"主链起点"、"系列模板驱动"、"中台承接页"等）已全部移除。
|
||
侧边栏已有清晰的页面标识，无需重复。
|
||
|
||
### 9. Platform 组件适配
|
||
|
||
**PlatformPageFrame.tsx**
|
||
- 移除：radial-gradient 背景、rounded-[28px] 卡片包装、liquid-glass-enhanced 头部
|
||
- 现在：简洁的内联布局，Manrope 标题 + 内联 eyebrow badge + PlatformFlowNav
|
||
|
||
**PlatformSplitLayout.tsx**
|
||
- 移除：独立的 sticky 头部（含 Card、返回按钮、eyebrow）
|
||
- 适配：`h-[calc(100vh-56px)]` 填满 AppShell 主内容区
|
||
- 右侧面板：w-80（320px），surface-container-lowest 背景
|
||
- `eyebrow` 和 `headerTools` 保留为 `@deprecated` props（解构后静默忽略），确保旧代码不报错
|
||
|
||
## 最终布局职责划分
|
||
|
||
| 区域 | 组件 | 职责 |
|
||
|------|------|------|
|
||
| 顶栏 | AppTopNav | Logo、搜索、通知、主题切换、用户菜单 |
|
||
| 侧边栏 | AppSideNav | 5 个导航链接、新建配置按钮、技术支持、归档 |
|
||
| 主内容区 | 各页面组件 | 只负责业务内容，不再自带导航/头部工具 |
|
||
|
||
## 改动文件清单（完整）
|
||
|
||
| 文件 | 改动类型 |
|
||
|------|----------|
|
||
| `src/lib/design-tokens/colors.ts` | 全部重写 |
|
||
| `src/lib/design-tokens/typography.ts` | 全部重写 |
|
||
| `src/lib/design-tokens/spacing.ts` | 重命名+圆角调整 |
|
||
| `src/app/globals.css` | 颜色/字体/阴影全部替换 |
|
||
| `src/components/ui/Button.tsx` | CTA 渐变效果 |
|
||
| `src/components/ui/Typography.tsx` | 兼容旧名 variant |
|
||
| `src/components/layout/AppTopNav.tsx` | **新增**：全局顶栏 |
|
||
| `src/components/layout/AppSideNav.tsx` | **新增**：全局侧边导航 |
|
||
| `src/components/layout/AppShell.tsx` | **新增**：全局布局容器 |
|
||
| `src/app/layout.tsx` | 引入 AppShell 包裹 |
|
||
| `src/components/platform/PlatformPageFrame.tsx` | 简化为内联布局 |
|
||
| `src/components/platform/PlatformSplitLayout.tsx` | 适配 AppShell + deprecated props |
|
||
| `src/app/asset-center/AssetCenterClient.tsx` | 移除 headerTools/eyebrow |
|
||
| `src/app/assisted-assembly/page.tsx` | 移除 headerTools 传参 |
|
||
| `src/app/assisted-assembly/AssistedAssemblyClient.tsx` | headerTools 改为可选 |
|
||
| `src/app/draft-groups/DraftGroupsClient.tsx` | 移除 headerTools/eyebrow |
|
||
| `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx` | 移除 headerTools/eyebrow（2 处） |
|
||
| `src/app/intake/IntakeClient.tsx` | 移除 headerTools/eyebrow（2 处） |
|
||
| `src/app/warehouse/WarehouseClient.tsx` | 移除 headerTools/eyebrow |
|
||
| `src/app/HomeClient.workspace.tsx` | 移除 topTools 传参 |
|
||
| ~20 个业务文件 | 硬编码颜色替换 |
|
||
|
||
---
|
||
|
||
## 第三阶段：管理基础设施视觉升级 (2026-04-16)
|
||
|
||
### 10. 管理端专属视觉模式 (Management UI Patterns)
|
||
|
||
在重构 `/admin` 和 `/users` 页面时，引入了针对“高密度控制类页面”的增强视觉模式，以平衡“工业精密感”与“视觉通透度”。
|
||
|
||
**1. 沉浸式页头 (Immersive Page Header)**
|
||
- **视觉特征**：
|
||
- 采用 `bg-white/60` + `backdrop-blur-2xl`。
|
||
- 强化左侧 Icon 视觉，使用 `rounded-[2rem] bg-black` 黑色底座，并叠加状态徽章（如 `ShieldCheck`）。
|
||
- **排版建议**：Manrope 3XL 标题 + 紧跟其后的 `text-apple-blue` 高亮关键词。
|
||
- **副标题**：使用 `text-[10px] tracking-[0.4em] uppercase` 的精密说明文字。
|
||
|
||
**2. 精密控制条 (Precision Control Bar)**
|
||
- **定义**：将原本分散的“搜索框”与“筛选器”整合进一个逻辑整体。
|
||
- **视觉实现**：
|
||
- 容器：`rounded-[2rem]` 极圆圆角，`border-white/80` 微光边框，`bg-white/40` 背景。
|
||
- 搜索框：沉浸式设计，背景为 `bg-white/80`，聚焦时通过 `ring-apple-blue/5` 产生柔和晕染。
|
||
- 筛选器：图标 (Lucide Icon) + Select 组件的紧凑组合，图标作为装饰前缀。
|
||
|
||
**3. 玻璃态卡片增强 (Enhanced Glass Cards)**
|
||
- **改动**：在 `rounded-[2rem]` 的基础上，引入了“装饰线”动效。
|
||
- **动效逻辑**：`group-hover:w-full` 的底部 1.5px 强调线，颜色与模块 Icon 色调一致。
|
||
- **背景文字装饰**：绝对定位的 `text-[80px]` 背景大字（如模块 path），设置 `opacity-[0.03]` 极低透明度，增加“空间感”。
|
||
|
||
**4. 状态指标看板 (System Health Dashboard)**
|
||
- 应用场景：`/admin` 首页。
|
||
- 组成：Icon 容器 + 上下两行文本（上行为微缩标签，下行为状态值）。
|
||
- 配色：动态使用 `emerald-500` (正常), `blue-500` (活动), `amber-500` (注意)。
|
||
|
||
**5. 三栏工作区 (Three-Column Workspace)**
|
||
- 应用场景：`/asset-center/material-library`。
|
||
- 定义：左侧极简分类 (Navigation) + 中间响应式网格 (Grid) + 右侧实时定义面板 (Inspector)。
|
||
- 优势：极大降低页面跳转成本，实现“即时反馈”。
|
||
|
||
**6. 精密滑块交互 (Precision Sliders)**
|
||
- 视觉表现：细条轨道 + 圆形 Thumb + 右侧数值百分比徽章。
|
||
- 应用场景：物理参数调节 (Metallic/Roughness/Opacity)。
|
||
- 规范：取代原有的输入框，滑动步长固定为 0.01 (1%)。
|
||
|
||
**7. 悬浮坞系统 (Floating Dock System)**
|
||
- 应用场景：`/assisted-assembly`。
|
||
- 定义：左侧布局的交互式入口，采用 `bg-black/60` + `backdrop-blur-3xl`。
|
||
- 动效：点击后向右水平展开列表。
|
||
- 逻辑：通过视觉发光 (Glow) 和计数徽标反馈当前分类的选择状态。
|
||
|
||
**8. 环境 HUD (Ambient HUD)**
|
||
- 定义：底部的非侵入式信息条。
|
||
- 样式：极圆胶囊型，`backdrop-blur-xl`。
|
||
- 作用：提供当前操作环境的实时状态（如“捕捉已就绪”）。
|
||
|
||
### 11. 改动文件清单
|
||
|
||
| 文件 | 改动类型 | 备注 |
|
||
|------|----------|------|
|
||
| `src/app/admin/page.tsx` | 重构 | 系统总控制台首页视觉重载 |
|
||
| `src/app/users/page.tsx` | 重构 | 身份控制中心 (用户管理) 三栏重写 |
|
||
| `src/app/asset-center/material-library/MaterialLibraryClient.tsx` | 重构 | 材质库首页视觉重写 (草稿图 12.png) |
|
||
| `src/app/assisted-assembly/AssistedAssemblyClient.tsx` | 重构 | 拼装工作台沉浸式重写 & 引入 Floating Dock |
|
||
| `src/components/platform/PlatformSplitLayout.tsx` | 基础重构 | 统一加装 backHref 导航标准 |
|
||
|
||
|
||
|