# 殷浚航 · 前端设计复用规范

版本：1.0 · 2026-10-26（Asia/Shanghai）

适用对象：接手新项目、迭代既有产品或集成动态组件的 Agent。样本为 MKYN Studio、同频、LumenLab、网络门户的当前本地实现。这里的“项目使用”表示发现业务调用，不等于逐一核验了各项目线上版本。

## 1. 执行优先级

1. 用户本轮要求。
2. 当前仓库 AGENTS.md、PRODUCT.md 与已确认的页面约束。
3. 真实代码、运行页面与已批准的品牌资源。
4. 本文可复用原则。
5. 新增建议。

不要把某个项目的色值、背景或动效直接变成所有项目的固定风格。本文区分用户要求、实现事实和建议；标注“建议”的数值需要结合宿主验证。

## 2. 用户明确要求：内容与结构

- 产品界面只保留实际内容、必要数据、日期、进度、短标签、操作按钮与必要状态。
- 删除宣传式空话、抒情段落、鼓励标语、重复解释和多余操作提示。详见独立文案规范。
- 用真实作品、真实项目与真实业务数据。预览使用合成数据时明确标注“演示”。
- 入口必须可用；没有接入的功能隐藏或禁用，并提供短事实状态。
- 品牌图形和字标使用批准资源，不擅自重画、换字体或近似替代。
- 产品内页优先完成任务；作品集可以使用表达性的背景和滚动展示。
- 桌面和手机都要实际检查；手机不能仅把桌面等比缩小。

## 3. 已实现的共同方法

### 3.1 先确定页面任务

| 场景 | 优先结构 | 可使用的表达 | 应避免 |
| --- | --- | --- | --- |
| 作品集 | 作品、预览、流程、联系 | 受控背景、连续卡片变形、摄影 | 大型 slogan、虚构项目成绩 |
| 学习 / 协作 | 当前任务、时间、记录、好友 | 完成反馈、日历、层级清楚的面板 | 装饰阻挡阅读、抒情空状态 |
| AI 工作区 | 内容、工具状态、可恢复操作 | 分步表单、清楚的运行状态 | 把产品内页做成营销页 |
| 管理 / 门户 | 一个主要任务、紧凑数据、确认操作 | 语义状态色、行内反馈 | 为装饰堆砌巨大指标和渐变 |

### 3.2 复用宿主，不拼接模板

组件安装后先统一字体、语义色、容器宽度、段落间距、圆角与按钮。模板里的演示客户、假评价、空链接和重复 CTA 必须清理。不要把整块 `min-h-screen` 演示容器原样嵌入产品。

推荐按职责拆分：页面组合 → 业务容器 → 受控展示组件 → 基础控件。业务 API、计时逻辑和权限判断不要塞进展示动画组件。

### 3.3 视觉基线

以下是从实际项目提取的值，保留各项目差异：

| 项目 / 用途 | 当前值 | 使用边界 |
| --- | --- | --- |
| MKYN Studio 纸面 | `#fbfcfe` | 来自 `.studio-shell` |
| MKYN Studio 主文字 | `#252d38` | 不用于图形品牌替色 |
| MKYN Studio 次级文字 | `#647183` | 必须随背景核验对比度 |
| MKYN Studio 链接强调 | `#315e9d` | 导航、焦点和操作强调 |
| 网络门户底色 / 内容 | `#fafafa` / `#171717` | 中性产品界面 |
| 网络门户强调 / 危险 | `#006bff` / `#d8001b` | 语义状态，不能只靠颜色区分 |
| 基础圆角 | `0.625rem` | 项目语义 token；具体卡片可有批准变体 |
| 正文字体 | Geist 与中文系统回退 | 标题、正文、控件共用可读体系 |
| 代码字体 | Geist Mono / 本地等宽字体 | 代码、数值、终端；不泛化成全站装饰 |

建议新界面先以 4px 间距单位建立少量层级；控件约 12–14px、正文约 14–16px，正文行高约 1.6–1.8。它们是起点，不是用户指定的全局值。

### 3.4 材质

个人网站已经确认玻璃卡片：低底色不透明度、约 14px 背景模糊、克制边缘高光与柔和阴影，内容保持清晰。不要恢复实心蓝 / 青卡片或单纯半透明白平面。

该材质只属于已经确认的场景。管理界面仍以中性底色、真实数据和任务层级为主。

## 4. 动效规范

### 4.1 连续性

- 图标、字标、图片、标题等需要形态过渡时分别设置共享布局标识。
- 共享标识必须有作用域，防止多个示例或多个列表串场。
- 图形与文字的移动、缩放、旋转连续进行，不用交叉渐变替代。
- 源节点和展开节点使用相同图片资源与原始比例，避免切图、重复解码与白边。
- 退出动画完成后再卸载 Portal；焦点返回触发控件。

### 4.2 真实参数

| 场景 | 参数 | 边界 |
| --- | --- | --- |
| 个人网站项目详情 | `0.85s`；`[0.42, 0, 0.22, 1]` | 图标、字标、分类、操作同步 |
| 首页滚动吸附 | 剩余距离 / `800px/s`；限制 `1.2–1.6s` | 无回弹；只在 Hero 范围 |
| 首页卡片几何 | `p*p*(3-2*p)` | 位置、大小、旋转、字标共用进度 |
| 导航底板 | spring `450 / 35` | 刚度 / 阻尼；减少动态直接定位 |
| 层叠面板 | `0.45s`；`[0.22,1,0.36,1]` | 间距 `32 → 48px` |
| 技术栈打字 | 输入 `60ms`，删除 `45ms`，停留 `1250ms` | 固定单行高度 |
| 轮换字容器 | `0.5s` tween | 防止前缀与新词相对抖动 |

这些参数属于对应实现；新场景先判断是否需要同类动效。

### 4.3 滚动行为

- 保留原生滚动，正反方向进度都可恢复。
- 真实滚轮 / 触摸可以即时中断程序化吸附。
- 键盘操作和减少动态不自动吸附。
- 模态开关前后，背景滚动位置和固定导航坐标不变。
- 不让 Hero 的吸附范围延伸到流程、页脚或其他路由。
- 手机内容高于视口时减少固定层；标题与简介可自然滚出。

## 5. 性能与降级

- 重型背景延迟加载；Next.js 中需要浏览器 API 的渲染器放在客户端包装器。
- WebGL 父容器显式设置宽高。
- 个人网站点阵：DPR `1`，最多 `30fps`；隐藏、离开视口、暂停或减少动态时停止持续绘制。
- 同频登录背景：桌面才挂载，DPR `1.25`；隐藏和减少动态时暂停，无 WebGL 保留静态底色。
- 清理 requestAnimationFrame、timer、observer、事件监听及图形资源。
- 业务正文不等待背景载入；无 JavaScript 时保留可读内容与真实链接。
- 摄影走稳定媒体代理，不将短期签名 URL 写进组件记录。

## 6. 可访问性和状态

- 有语义的按钮、链接、label；图标按钮有可读名称。
- 活动导航提供 `aria-current`，开关和筛选有明确选中状态。
- 文字与背景对比度目标：正文至少 4.5:1，大字至少 3:1。
- Tab 焦点可见；模态支持 Escape、焦点约束与关闭后的焦点恢复。
- 减少动态保留信息、静态图和手动切换；不能把“关闭动画”变成“关闭内容”。
- 核对默认、加载、成功、失败、禁用、空记录和长内容。
- 建议主操作触摸区域至少约 44px；高密度图表提供可聚焦替代操作。

## 7. 验收

1. 桌面、常见手机和 320px 窄屏无横向溢出、遮挡或无法关闭的层。
2. 实际完成入口 → 操作 → 结果 → 返回；不能只看静态截图。
3. 对照浏览器 console、失败网络请求和服务端日志。
4. 动效需检查完整下滑返回、开合返回、连续反向输入和减少动态。
5. 按仓库执行类型检查、lint、生产构建与必要测试。
6. 部署采用独立 release、健康检查和可执行回滚；不连带重启其他服务。
7. 公开档案仅展示本地调用、参数与演示；组件获取渠道和凭据不得出现在 HTML、JS、公开 Markdown、source map 或发布包。

## 8. Agent 复用指令

```text
先读当前仓库的 AGENTS、PRODUCT、设计文件和真实页面。
继承当前视觉体系；说明本次要完成的页面任务。
组件接入后统一字体、语义色、宽度、间距、圆角和按钮。
只保留内容、数据、日期、进度、短标签、操作和必要状态。
连续变形使用共享布局；滚动往返可恢复；减少动态仍能操作。
用真实数据，预览合成数据需标注。
实际检查桌面与手机的主流程、错误、网络和 console，然后交付。
```

## 9. 提取依据

本轮读取了 MKYN Studio 的 AGENTS / PRODUCT、布局、背景、打字、共享卡片、流程与部署记录；同频的 PRODUCT、登录背景、资料面板、移动导航和热力图；LumenLab 的设计文件、轮换字、反馈和分步创建；网络门户的产品记录、中性色 token、导航、指标与管理表格。归纳不要求各项目互相复制视觉。