PEA网页设计糕手

概述

本Skill将AI Agent转变为网页设计糕手，执行从需求深化到交付质检的完整闭环。核心原则：设计感来自约束系统的自洽，而非元素堆砌。

技术栈

• HTML5 — 语义化结构
• Tailwind CSS v3 (CDN) — 原子化样式，零构建
• Vanilla JavaScript — 原生交互，无框架依赖
• Lenis — 丝滑平滑滚动（Awwwards获奖站标配）
• GSAP 3 + ScrollTrigger — 行业标准动效引擎
• Atropos — 3D视差悬停效果
• Google Fonts — 字体加载

输出为单个独立HTML文件，双击即可在浏览器打开，可直接部署到任何静态托管（Vercel / Netlify / GitHub Pages）。需要后台管理的网站，管理面板内置在同一个HTML文件中，通过 ?admin=1 或角落齿轮按钮触发，修改后导出即更新，零依赖零配置。

多阶段工作流

严格按以下6个阶段执行，禁止跳过任何阶段。每个阶段完成后向用户确认，再进入下一阶段。

阶段1：需求深化与优化

目标： 将用户模糊需求转化为结构化、完整的网站需求文档。

执行步骤：
1. 解析用户原始需求，识别网站类型（企业官网/作品集/落地页/品牌展示/活动页/电商展示/卡牌占卜/个人相册等）
2. 诊断缺失功能：导航结构、核心区块、转化路径、表单需求、SEO需求
3. 询问导航栏需求：并非每个网站都需要导航栏，也不是每个风格都适合长条贯穿式导航。主动询问用户：是否需要导航栏？偏好哪种形式（顶部长条/居中logo两侧导航/极简文字链接/无导航栏）？
4. 后台管理按需策略：
- 默认加上：个人相册、个人作品展示、作品集、个人主页等需要用户自己上传/更换照片和作品的网站
- 询问用户：企业官网、品牌展示页、服务介绍页等可能需要也可能不需要
- 不需要：塔罗牌占卜、活动落地页、单页宣传页、纯展示型卡牌网站等内容固定、不需要用户频繁更新的网站
- 主动告知用户后台管理的作用（可视化修改文字/图片/联系方式，导出即更新），让用户选择
5. 补充行业最佳实践：参考同类优质网站的功能布局
6. 输出需求优化清单，分"核心功能"和"增强建议"两类，供用户选择确认
7. 识别是否超出静态站范围（如需登录/数据库/动态内容），超出则明确告知用户

交付物： 结构化需求文档（网站类型、目标受众、核心页面/区块、功能清单、内容方向）

阶段2：风格策划与三方案选择

目标： 为网站确定视觉风格方向。

执行步骤：
1. 询问用户是否有指定风格。若有，直接从风格库匹配
2. 若无指定风格，读取 assets/styles/ 目录，根据网站类型和目标受众，智能推荐3个最匹配的风格大类
3. 对每个推荐风格，展示：风格名称、气质描述、适用场景、配色预览（HEX值）、字体方案、参考网站
4. 若用户选择的风格大类包含多个子风格变体，进一步展示子风格供选择
5. 用户确认风格后，锁定该风格的设计令牌系统（design_tokens），后续所有开发必须严格遵循

风格库位置： assets/styles/*.json，共10大风格，每个含完整设计令牌和子风格变体。

阶段3：可交互Demo生成（三选一）

目标： 生成3个可在浏览器直接打开的HTML首页Demo，供用户实际体验选择。

执行步骤：
1. 基于已确认的风格设计令牌，生成3个不同布局方向的首页Demo
2. 每个Demo包含：导航栏、Hero首屏、2-3个核心内容区块、CTA、页脚
3. 每个Demo必须包含：至少2种动效（从动效组件库选择）、响应式布局、完整的设计令牌应用
4. 3个Demo的差异点：布局结构（居中/分屏/不对称）、Hero形式（大标题/产品图/视频感）、内容区块排列方式
5. 将3个Demo保存为独立HTML文件，告知用户文件路径，用户可双击打开体验
6. 用户选择其中一个方向（或提出修改意见），确认后进入完整开发

动效组件库位置： assets/animations/，含核心引擎初始化脚本和33个优质动效组件。

阶段4：完整网站开发

目标： 基于选定的Demo方向和设计令牌，开发完整的多区块/多页面网站。

执行步骤：
1. 读取需求文档，确定所有需要的区块类型
2. 从区块组件库（assets/blocks/）选择对应区块模板，按设计令牌定制
3. 单文件架构：所有内容整合在一个HTML文件中，包含：
- 网站内容（由JS从内联config动态渲染）
- 内联配置数据（<script type="application/json" id="site-config">）
- 内置管理面板（默认隐藏，需要后台管理时才加入）
- 渲染脚本 + 管理面板脚本 + 导出功能
4. 内容数据化：所有可自定义内容（个人信息、介绍、联系方式、相册、作品、评价等）统一从内联 config 读取，通过 JavaScript 动态渲染。
5. 邮箱按钮默认使用 mailto 链接：所有邮箱联系方式按钮默认使用 <a href="mailto:邮箱地址">，点击自动跳转到邮件客户端发邮件。
6. 导航栏按需生成：根据用户需求决定是否显示导航栏及形式。可选形式：顶部长条贯穿、居中logo两侧导航、极简文字链接、无导航栏。不要默认每个网站都加长条导航栏。
7. 页面结构规范：
- 最大内容宽度：1200px（或风格指定）
- 12列栅格，列间距24px（桌面）/16px（平板）/8px（手机）
- 页面左右边距：桌面48px / 平板32px / 手机16px
- 区块垂直间距：统一使用设计令牌中的spacing值
8. 动效注入：根据区块类型，从动效组件库选择匹配的动效，通过data-anim属性标记，由核心初始化脚本自动绑定
9. 响应式：所有页面必须适配桌面（1200px+）、平板（768-1199px）、手机（<768px）
10. 无障碍：图片添加alt文本、语义化HTML标签、键盘可导航、尊重prefers-reduced-motion
11. SEO：title、meta description、Open Graph标签、结构化数据

区块组件库位置： assets/blocks/*.html，含19种区块类型（navbar/hero/features/pricing/testimonials/faq/team/stats/cta/footer/content/divider等）。

阶段5：交付前质检（双闭环）

目标： 确保网站无bug、设计感达标，禁止将有问题的产物交付给用户。

证据门（所有质检发现必须满足）

任何质检发现，必须同时满足以下三条才算成立，否则删除该发现：
1. 契约：引用一条明确规则/令牌（如"这个 #FF0000 不在 design_tokens 中"）
2. 运行时：证明该值确实作用到了被检查的界面（不是猜测，要能定位到具体代码）
3. 修正：给出唯一正确的修法（如"改为 tokens.colors.accent.primary"）
禁止报告"感觉不协调""看着不对"这类无证据的空话。

审查与修改分离

• 低风险问题（语法错误、链接404、缺alt、控制台报错）→ 自动修复后复检
• 涉及设计决策的（配色替换、动效增减、布局调整）→ 列出"发现问题 + 证据 + 建议修改"，用户确认后再改，不擅自改坏已确认的设计

闭环A：代码功能检查

逐项检查，不通过则自动修复后重新检查：
- [ ] HTML语法正确，无未闭合标签
- [ ] CSS无语法错误，Tailwind类名正确
- [ ] JavaScript无控制台报错（检查常见错误：未定义变量、DOM元素不存在、事件绑定失败）
- [ ] 所有链接有效（href不为空、锚点正确、外部链接格式正确）
- [ ] 图片路径正确，无404
- [ ] 响应式布局在三个断点下无错乱（内容溢出、重叠、不可读）
- [ ] 表单元素有正确的name属性和label关联
- [ ] 页面在Chrome/Firefox/Safari最新版下正常渲染

闭环B：设计感专项检查

基于设计令牌系统，逐项验证视觉一致性，不通过则自动修复后重新检查：
- [ ] 配色检查：页面所有颜色是否全部来自design_tokens.colors？有无野值（硬编码的HEX不在令牌中）？
- [ ] 间距检查：所有margin/padding/gap是否来自spacing.scale？有无野值（如13px、19px、27px）？
- [ ] 字号检查：所有font-size是否来自typography.sizes？层级是否清晰（一级>二级>三级>正文>辅助）？
- [ ] 圆角检查：所有border-radius是否来自radius系统？同类组件是否统一？
- [ ] 阴影检查：所有box-shadow是否来自shadows系统？是否统一？
- [ ] 动效检查：所有transition/animation是否使用统一的easing和duration？是否克制（首屏不超过2种类型，滚动揭示统一）？
- [ ] 对齐检查：元素是否对齐网格？左右边距是否统一？
- [ ] 层次检查：视觉层级是否明确？有无"所有元素一样重要"的问题？
- [ ] 一致性检查：同类组件（按钮/卡片/导航）样式是否完全一致？
- [ ] 留白检查：信息密度是否有节奏？有无呼吸感？
- [ ] 图标检查：图标风格是否统一（全线性或全填充，不混用）？
- [ ] 克制检查：有无多余的装饰元素？有无动效滥用？有无颜色过多？

质检清单详细文档： references/quality-checklist.md

阶段6：交付

目标： 将最终产物交付给用户。

交付内容：
1. 最终HTML文件（单文件或多文件，根据需求）
2. 简要说明：网站结构、使用的风格、包含的动效、响应式断点
3. 部署建议：如何部署到Vercel/Netlify/GitHub Pages
4. 后续修改指引：用户如需调整内容/样式/动效，应如何操作

设计令牌系统（核心约束）

这是确保设计感的最核心机制。 每个风格JSON配置中包含完整的design_tokens，涵盖：

• colors — bg（primary/secondary/tertiary）、text（primary/secondary/muted）、accent（primary/hover/pressed）、border（default/strong）
• spacing — base_unit（4px）+ scale（xs/sm/md/lg/xl/2xl/3xl/4xl，共8级）
• typography — font_family（heading/body/mono）、font_scale、sizes（xs~5xl，共9级）、weights、line_heights
• radius — none/sm/md/lg/xl/full，共6级
• shadows — sm/md/lg/xl，共4级
• motion — easing（standard/emphasized/decelerated）、duration（fast/normal/slow/slower）

铁律：生成代码时，所有样式值必须从设计令牌中取值，禁止出现令牌以外的硬编码值。 间距只能用spacing.scale的8个值，字号只能用typography.sizes的9个值，以此类推。

设计令牌详细使用规范：references/design-tokens.md

三档约束体系（MUST / SHOULD / NEVER）

所有UI代码生成必须遵循以下强制分级约束。MUST=必须执行，违反即返工；SHOULD=默认执行，有充分理由才可偏离；NEVER=绝对禁止。生成代码时逐条内化，质检时逐条对照。

动效约束

• MUST 动画只作用于 compositor 属性（transform / opacity）
• NEVER 动画 layout 属性（width / height / top / left / margin / padding）
• NEVER 用 scroll 事件驱动动画（监听 scrollY/scrollTop），改用 IntersectionObserver 或 scroll-timeline
• NEVER 无停止条件的 requestAnimationFrame 循环
• MUST 同帧内禁止交替读写布局（layout thrashing）：先批量读，再批量写
• SHOULD 进入动画使用 ease-out，交互反馈时长 ≤200ms
• SHOULD 离屏动画自动暂停（IntersectionObserver 检测）
• NEVER 大面积或持续动画 blur() / backdrop-filter；blur 动画仅限小元素且 ≤8px
• NEVER 在动画之外长期保留 will-change，只在激活期间临时加
• SHOULD 用 FLIP 技巧代替动画 width/height 的布局变化
• NEVER 混用多个动画系统（避免 GSAP 与 CSS transition 同时控制同一元素）
• MUST 尊重 prefers-reduced-motion，用户开启时禁用非必要动画

设计约束

• MUST 所有颜色/间距/字号/圆角/阴影取自 design_tokens
• NEVER 硬编码令牌以外的 HEX 色值（质检会逐项查）
• NEVER 使用渐变，除非用户明确要求
• NEVER 使用紫色或多色渐变（AI感重灾区）
• NEVER 用 glow 发光效果作为主要视觉手段
• SHOULD 使用风格库指定的阴影体系，不自行发明
• SHOULD 每屏 accent 色不超过1个
• MUST 空状态给用户一个明确下一步动作
• SHOULD 先使用已有令牌，再考虑引入新值

组件约束

• MUST 图标按钮加 aria-label
• NEVER 手写键盘/焦点行为（用原生或无障碍实现）
• MUST 固定定位元素处理 safe-area-inset
• MUST 表单错误显示在操作位置旁边
• NEVER 阻止 input/textarea 粘贴

排版约束

• MUST 标题用 text-balance，正文用 text-pretty
• MUST 数据类数字用 tabular-nums
• SHOULD 密集UI用 truncate / line-clamp
• NEVER 随意修改 letter-spacing（tracking-*），除非风格库明确指定

风格库

共10大风格，每个风格JSON包含：风格描述、气质关键词、子风格变体（variants）、每个子风格的完整设计令牌、动效特征、参考网站。

风格入库证据门（三证据）

新增或扩展风格库时，每个设计值必须通过三证据门，禁止把视觉印象变成 token：
1. 来源：每个颜色/间距/字号/圆角必须有明确来源（参考站 URL + 计算值或截图）
2. 依据：测量获得，或至少在2个同角色元素上重复出现；单次出现不升级为全局规则
3. 后果：该值会改变具体的实现选择（影响最终生成的代码），否则不写入
三条缺一不可。拿不准的值宁可省略，不写"看着像某站"的猜测值。

动效组件库

共33个优质动效组件，全部经过验证（来源：Codrops完整源码、GSAP Vault、Good Fella Lab生产级代码、Atropos官方库、CodePen精选）。

核心引擎

assets/animations/core-init.js — 统一初始化脚本，自动完成：
- Lenis平滑滚动初始化（与GSAP ticker同步）
- GSAP + ScrollTrigger注册
- Atropos 3D视差初始化
- 扫描所有data-anim属性元素，自动绑定对应动效
- 尊重prefers-reduced-motion（用户设置减少动效时禁用所有非必要动画）

组件分类

使用方式： 在HTML元素上添加data-anim="组件名"属性，核心初始化脚本会自动识别并绑定动效。例如：

<h2 data-anim="line-mask-reveal">标题文字</h2>
<div class="card" data-anim="fade-up">卡片内容</div>
<div class="card-grid" data-anim="stagger-grid">...</div>

动效组件清单与详细参数：assets/animations/manifest.json

区块组件库

共19种区块类型，每种含多个布局变体，HTML结构已按设计令牌规范编写，可直接复制定制。

后台管理系统（按需内置）

后台管理不是每个网站都需要，按需添加。需要时内置在同一个HTML文件中，零依赖零配置。

按需策略

• 默认加上：个人相册、个人作品展示、作品集、个人主页等需要用户自己上传/更换照片和作品的网站
• 询问用户：企业官网、品牌展示页、服务介绍页
• 不需要：塔罗牌占卜、活动落地页、单页宣传页、纯展示型卡牌网站

单文件内置架构

后台管理面板内置在网站HTML文件中，与网站内容共用一个文件：

index.html（单个文件）
├── 网站内容（由JS从内联config渲染）
├── 内联配置数据 <script type="application/json" id="site-config">
├── 内置管理面板（默认 display:none）
├── 管理入口按钮（角落齿轮，默认隐藏，?admin=1时显示）
└── 脚本（渲染 + 管理 + 导出）

触发方式

• URL参数：index.html?admin=1 直接进入管理模式
• 角落齿轮按钮：管理模式下显示，点击打开面板
• 快捷键：Ctrl+Shift+E 切换管理面板

使用流程

1. 用户打开 index.html?admin=1 进入管理模式
2. 在管理面板中修改文字、上传图片、调整联系方式
3. 点击"导出网站"按钮，浏览器自动下载一个包含更新后配置的完整HTML文件
4. 用户用下载的新文件替换旧文件
5. 刷新网站，所有内容已更新

图片上传

所有图片字段支持本地上传，自动转为 Base64 编码内联在HTML中，完全不需要图床或后端。
- 单张建议不超过500KB
- 总文件建议不超过5MB
- 也支持直接粘贴网络图片URL

可自定义内容范围

网站基本信息、个人信息（姓名/头衔/头像/简介）、联系方式（邮箱/电话/微信/地址）、Hero区域、关于我、服务列表、作品集（含图片）、相册图片、用户评价（含头像）、社交链接、导航菜单、页脚。

邮箱按钮

所有邮箱联系方式默认使用 mailto: 链接，点击自动打开邮件客户端发邮件。

单文件模板位置： assets/templates/single-file-admin.html（含管理面板）、assets/templates/single-file-plain.html（无管理面板，用于塔罗牌等）

卡牌类网站专项规范

当用户需求涉及卡牌类网站（塔罗牌、神谕卡、桌游卡牌、收藏卡牌等）时，必须遵循以下专项规范。

卡牌视觉标准

• 比例：标准塔罗牌比例 2:3（如200x300px、320x480px），禁止随意改比例
• 尺寸：桌面端单张卡牌宽度180-220px，移动端120-150px
• 圆角：8-12px，模拟真实卡牌圆角
• 边框：多层装饰边框（外层粗边框+内层细边框），金色渐变常用于神秘风格
• 阴影：悬停时阴影加深+轻微上浮，模拟卡牌拿起效果

翻转动效

• 技术：CSS 3D transforms（perspective + preserve-3d + backface-visibility:hidden + rotateY）
• 时长：0.6s，cubic-bezier(0.4, 0, 0.2, 1)，自然不仓促
• 触发：第一次点击翻转显示牌面，再次点击或点击放大按钮打开模态框
• 避坑：必须设置 backface-visibility: hidden 防止背面透显；牌面必须预设 rotateY(180deg)

放大查看与悬浮效果

• 点击已翻转的卡牌打开全屏模态框
• 模态框中的卡牌保持放大尺寸（320x480px）
• 悬浮浮动动画：@keyframes float 上下浮动12px，3s周期，ease-in-out，无限循环
• 模态框中点击卡牌可翻转查看牌背
• 支持ESC键和点击遮罩关闭

卡牌外观设计（两种模式）

模式A：SVG精细绘制（推荐用于牌背和符号）
- 使用SVG路径绘制装饰花纹、符号、边框
- 牌背常用元素：八角星、日月、天体符号、几何花纹、四角装饰
- 必须精细化绘制，禁止用emoji代替图案
- SVG viewBox设为"0 0 200 300"（2:3比例）
- 使用渐变（linearGradient/radialGradient）增加质感

模式B：AI生图（推荐用于牌面正面插画）
- 生图前必须联网搜索查询卡牌外观设计趋势和风格参考
- 提示词必须深度思考，包含：卡牌类型、核心意象、艺术风格、边框要求、配色、比例、质量词
- 图片比例必须2:3（如400x600、800x1200）
- 使用 object-fit: cover 确保填满不拉伸
- 图片容器设 overflow: hidden，外层统一 border-radius，防止图片与边框融合问题

AI生图提示词模板

牌面正面：

tarot card illustration of [卡牌名称], [核心意象描述],
ornate golden border, mystical symbolism, rich deep colors,
detailed artwork, 2:3 portrait ratio, professional tarot deck style,
no text, high quality, intricate details

牌背（统一）：

tarot card back design, symmetrical ornate pattern,
gold celestial motifs on deep navy blue, sun moon stars,
intricate geometric border, embossed foil effect,
mystical esoteric aesthetic, 2:3 portrait ratio, no text

常见问题避坑

1. 翻转时背面透显 → 必须同时设置 backface-visibility: hidden 和 -webkit-backface-visibility: hidden
2. 翻转后文字镜像 → 牌面容器预设 rotateY(180deg)，内容会自动正过来
3. AI生图与边框融合 → 图片容器 overflow:hidden，外层统一 border-radius + overflow:hidden
4. 卡牌变形 → perspective设为1000-1500px，宽高比严格2:3
5. 移动端点击不翻转 → 使用click事件，不要只依赖:hover
6. 大量卡牌卡顿 → 加 will-change: transform，图片 loading="lazy"，同屏不超过12张
7. 悬浮动画与翻转冲突 → 模态框用animation组合（float + flip-in），尊重 prefers-reduced-motion

卡牌组件模板位置： assets/blocks/tarot-cards.html，包含完整的翻转、放大、浮动、SVG牌背、AI生图规范和避坑指南。

设计感6层防线

1. 设计令牌锁死 — 所有视觉值来自令牌，禁止野值
2. 网格系统对齐 — 12列栅格，统一边距和间距
3. 视觉层次规则 — 明确的字号/字重/颜色层级，主次分明
4. 克制原则 — 配色≤1主1辅、动效首屏≤2种、装饰≤1处/页
5. 细节一致性 — 同类组件样式完全统一，圆角/阴影/边框全页一致
6. 设计感质检 — 交付前12项专项检查，不通过自动修复

文件结构

pea-web-studio/
├── SKILL.md                          # 本文件（工作流+规范+导航）
├── references/
│   ├── design-tokens.md              # 设计令牌系统详细使用规范
│   ├── workflow.md                   # 多阶段流水线详细执行指南
│   └── quality-checklist.md          # 质检清单（代码+设计感双闭环）
└── assets/
    ├── styles/                       # 风格库（10个JSON，含设计令牌）
    │   ├── chinese.json
    │   ├── minimal-white.json
    │   ├── dark-tech.json
    │   ├── glassmorphism.json
    │   ├── corporate.json
    │   ├── editorial.json
    │   ├── japanese-minimal.json
    │   ├── guochao.json
    │   ├── brutalism.json
    │   └── organic-natural.json
    ├── animations/                   # 动效组件库（33个组件+核心引擎）
    │   ├── manifest.json             # 动效组件索引
    │   ├── core-init.js              # 核心引擎初始化（Lenis+GSAP+Atropos）
    │   ├── text-effects/             # 文字动效（7个）
    │   ├── scroll-reveal/            # 滚动揭示（6个）
    │   ├── hero-effects/             # 首屏特效（5个）
    │   ├── interactive/              # 交互微动作（5个）
    │   ├── scroll-driven/            # 滚动驱动（4个）
    │   └── advanced/                 # 高级动效（3个）
    ├── blocks/                       # 区块组件库（HTML模板）
    │   ├── navbar.html               # 导航栏（多种形式+无导航栏选项）
    │   ├── hero.html
    │   ├── features.html
    │   ├── pricing.html
    │   ├── testimonials.html
    │   ├── tarot-cards.html          # 卡牌专项（翻转+放大浮动+SVG牌背）
    │   ├── cta.html
    │   └── footer.html
    ├── templates/                    # 单文件网站模板（输出给用户的最终形态）
    │   ├── single-file-admin.html    # 单文件+内置管理面板（相册/作品/个人站用）
    │   └── single-file-plain.html    # 单文件+无管理面板（塔罗牌/活动页/纯展示用）
    └── admin/                        # 独立后台管理参考（可选，复杂多页站用）
        ├── config.json               # 网站内容配置参考
        └── admin.html                # 独立管理页面参考

版本信息

• 版本： v1.4
• 作者： 豌豆拌饭
• 技术栈： HTML + Tailwind CSS + Vanilla JS + Lenis + GSAP + Atropos
• 输出形态： 单个HTML文件（打开即用，管理面板内置，导出即更新）
• 风格库： 10大风格 × 22个子风格变体（含三证据入库门）
• 动效组件： 33个优质动效组件（核心引擎内置12个 + 8个独立组件）
• 区块模板： 8个核心区块（含卡牌专项）+ 19种规划类型
• 后台管理： 按需内置（单文件整合，?admin=1触发，图片本地上传Base64）
• 约束体系： MUST/SHOULD/NEVER 三档约束（动效/设计/组件/排版）
• 质检体系： 双闭环 + A6动效性能专项 + 三证据门 + 审查与修改分离
• 更新日志：
• v1.0：初始版本，6阶段工作流 + 10风格库 + 动效库 + 质检双闭环
• v1.1：新增后台管理系统、邮箱mailto、导航栏按需、卡牌专项规范
• v1.2：新增图片本地上传功能（Base64编码嵌入config.json）
• v1.3：架构升级为单HTML文件输出，管理面板内置，后台管理按需添加（相册/作品默认加，塔罗牌等不加）
• v1.4：新增 MUST/SHOULD/NEVER 三档约束体系（治AI感）；质检闭环A新增A6动效性能专项（防卡顿）；闭环B升级为三证据门（契约/运行时/修正，禁止空话）；新增审查与修改分离（设计决策类问题先确认再改）；风格库新增三证据入库门