你现在缺的不是更多原则，是三样东西：组件的状态怎么定、中间态怎么画、动效和 3D 到底从哪来。
这一页把 5 个问题一次答完：设计系统该怎么组织、组件和中间态怎么写、动效库和灵感从哪找、3D landing 用什么做、我们自己还缺什么。每个判断都能落到一个文件、一个 token 或一个组件上。
不绕弯子：我们的设计系统现在是一份很好的“视觉 token 表”，但还不是一套“能交接的系统”。
tokens.md 的两层结构（结构/主题）做得比多数团队好；但 501 条元素没有收敛成组件清单，组件没有 anatomy、variants、states、API、a11y 字段。
我们画了默认态、hover 态，但拍卖/交易/验证真正难的是 pending、confirmed、failed、stale、refunded——这些状态没有统一的词、颜色和下一步动作。
现有动效全部是本地 keyframes + transition，没有引 GSAP/Lottie/Three。不是坏事，但缺“动效 token → 语义 → 编排 → 降级”的规范。
大量 landing page 用的是预渲染视频、滚动帧序列、CSS 3D 或 WebGL 背景；真 3D hero 的成本在素材、性能和移动端降级，不在代码。
这次把 Material / Carbon / Polaris / Primer / Spectrum 的导航、组件页、状态表逐页核过；OpenDesign 的“九段”有两个互相矛盾的说法，必须分清。
它不是组件库，而是“给 AI 读的品牌生成规格”：一个系统一个目录，manifest.json + DESIGN.md + tokens.css，可选 USAGE.md、components.html、design-tokens.json。DESIGN.md 是从品牌官网逆向提取的视觉语言（Linear 22KB、Stripe 20KB），解决“生成一个看起来像 Linear 的落地页”，不解决“按钮 disabled 用哪个 token”。
| # | 仓库实际九段（A，可作准） | 它规定什么 | 我们 tokens.md 有没有 |
|---|---|---|---|
| 1 | Visual Theme & Atmosphere | 品牌气质、关键特征清单 | 没有 |
| 2 | Color Palette & Roles | 按角色分组的色值与用途 | 有（结构/主题两层） |
| 3 | Typography Rules | 字体、字重、字距、OpenType 特性 | 有字号阶梯 |
| 4 | Component Stylings | 按钮/卡片/输入/导航的样式配方 | 有 13 组静态规格 |
| 5 | Layout Principles | 栅格、容器、间距节奏 | 没有（只在 CSS 里） |
| 6 | Depth & Elevation | 阴影栈、边框、层级 | 有零散阴影，无层级规范 |
| 7 | Do's and Don'ts | 正反例 | 没有 |
| 8 | Responsive Behavior | 断点降级规则 | 没有 |
| 9 | Agent Prompt Guide | 喂给模型的色值/Prompt/迭代守则 | 没有 |
对照结果：9 段里我们有 4 段（Color / Typography / Components 的部分 / Depth 的零散值），缺 5 段。粉丝站那套 B（Color/Type/Spacing/Layout/Components/Motion/Voice/Brand/Anti-patterns）不是仓库 schema，但其中 Voice 与 Anti-patterns 值得单独补——只是别写成“OpenDesign 官方九段”。
_schema/AGENTS.md 把 token 分四层：A1-identity（品牌决定，缺失 guard 失败：--bg/--fg/--accent）、A1-structure（字号阶梯/容器宽/节奏）、A2、B-slot；每个 token 回答“谁决定值、缺省怎么办”。再加 manifest 契约 + CI guard，才让“一系统一目录”可校验。这套比九段散文更适合我们。| 系统 | 实际一级导航 | 组件页字段 | 状态 / 动效 | 最值得抄的一件事 |
|---|---|---|---|---|
| Material 3 | Components（146）/ Foundations（68）/ Styles（38）/ Develop / Blog | Overview · Guidelines · Specs · Accessibility（每组件固定 4 页） | 状态在 Foundations → Interaction → States；动效在 Styles → Motion；state layer 0.08 / 0.10 / 0.10 / 0.16 | 状态做成全站一套 token，而不是每组件各画一套 |
| IBM Carbon | Getting started / Building blocks（Foundations 11 / Components 42 / Patterns 18 / Data viz）/ Building experiences（按用户旅程） | Guidelines · Specifications · Code · Accessibility；Specs 用「State × Element × Property × Token」四列表 | Motion 分 productive / expressive 两种语气；组件 checklist 是 DoD | 状态表四列 + 组件完成清单（token 强制、单测 80%、Percy VRT、WCAG AA） |
| Shopify Polaris | 已迁到 shopify.dev：设计规范在 /docs/apps/design，组件 API 在 /docs/api/*/web-components（7 个功能组）；旧四栏已 301 下线 | Use cases · Preview · Properties（每个枚举值有解释） | 状态散在 Properties；无独立动效栏目；页面顶部有 v2.0 RC / v1.1 latest / v1.0 版本通道 | 版本通道：预发布/最新稳定/旧版做进 URL 与 UI |
| GitHub Primer | Getting Started / Foundations / React / Primitives / UI Patterns / Scenario Patterns / Components / Internal / Hooks / CSS Utilities / Contribute + Accessibility / Brand / Octicons | Overview · Guidelines · Accessibility；头部有 React ready / Rails ready / Figma 就绪徽章；Props 表 | Guidelines 内 + inactive state 专页；只在 CSS Utilities → Animations | 组件成熟度三档 Experimental / Ready / Deprecated（废弃时控制台警告） |
| Adobe Spectrum | Foundations（9 组，含 Behavior）/ Components（按平台）/ Pattern library / Content / Getting started | 固定 8 段：Anatomy · Options · States · Behaviors · Usage · Content · i18n · Accessibility | States 是“支持/不支持”表；Behaviors 给可测规则（最小宽=高 2.25×、pending 延迟 1s）；Motion 在 Behavior | 8 段模板 + 明确写“不支持” + 可测行为 |
| OpenDesign | 无传统导航：design-systems/<slug> 目录 + manifest/DESIGN.md/tokens.css | Component Stylings 配方，不是 props/states/a11y 规范 | 无状态矩阵、无 a11y；靠 Do's & Don'ts | token 四层契约 + manifest + CI guard |
| 我们 | 单页 #/design：Foundations 13 节 + Components 13 节 | 规格 + 静态样例 + “为什么” | 徽章状态矩阵最完整；其他组件 2–5 态；动效实现至少有 5 条缓动 / 7 个时长（含 pools-spec） | 已经“活的”，缺 IA/状态/治理 |
状态不是形容词，是「哪个元素的哪个 CSS 属性换成哪个 token」：Hover / Container / background-color / $button-primary-hover。直接解决我们“状态只有截图”的问题。
Anatomy / Options / States / Behaviors / Usage / Content / i18n / A11y 强制齐全；States 明确写 Supported / Not supported；pending 延迟 1s 这种规则可测试。
Requirement / Details / Why 三列，含 token 强制、单测 80%、Percy VRT、IBM Equal Access、WCAG AA、破坏性变更 codemod。把它当我们的 DoD。
Experimental / Ready / Deprecated；Deprecated 使用时控制台警告，把文档约束变成运行时约束。
v2.0 RC / v1.1 latest / v1.0 做进 URL 与页面顶部，旧版可查、可迁移。
A1-identity / A1-structure / A2 / B-slot，每个 token 回答“谁决定、缺省怎么办”；配 manifest + CI guard，防组件裸 hex。
一个组件能不能交接，不看它好不好看，看它有没有把这 20 个字段写全。
| 字段 | 写什么 | 我们的常见错误 |
|---|---|---|
| 名称 / 版本 | Button / v1.2；废弃名与别名 | 同一个东西三个叫法 |
| 用途 | 一句话：什么时候用它，什么时候不用 | 只写“按钮” |
| Anatomy | 容器 / 图标 / 标签 / 辅助文字 / 状态点，各自可不可选 | 只有一张截图 |
| Variants | primary / secondary / ghost / danger；不是颜色，是语义 | 用颜色命名变体 |
| Sizes | sm / md / lg 的高度、内边距、字号、图标尺寸 | 每个页面自己调 |
| Props / API | variant、size、loading、disabled、icon、fullWidth、onClick | 只有 CSS 类，没有行为契约 |
| States | 12 态全集（见下方矩阵；每组件至少 9 个必做） | 只做 default + hover |
| Tokens | 背景、文字、描边、圆角、阴影分别引用哪个 token | 组件里写死 hex |
| Interaction | 点击后发生什么；防重复提交；乐观更新还是等待 | 点了没反馈 |
| Motion | 进入/退出/状态切换的时长、缓动、位移 | 每个组件自己拍一个时长 |
| Content | 标签字数上限、大小写、数字格式、错误文案模板 | 文案散落在页面里 |
| A11y | 角色、aria、焦点顺序、对比度、是否只靠颜色 | 没测键盘 |
| Responsive | 断点、最小宽度、移动端是否换行/收起 | 只在 1440 看过 |
| Keyboard | Tab / Enter / Space / Esc 的行为 | 只能鼠标点 |
| Do / Don't | 各 2 条，配反例 | 只有正例 |
| Related | 和哪些组件容易混、怎么选 | Button 和 Link 混用 |
| State attr | data-state="default|hover|focus|pressed|selected|disabled|readonly|loading|error|success|empty|skeleton"；交易区 data-tx、拍卖区 data-phase | 状态靠 class 拼，前端各写一套 |
| Error / Empty | 错误原因、空态文案、重试/下一步 | 只换红边，不解释 |
| Test / Screenshot | 每态一张截图 + Playwright 用例 + axe 结果 | 只截默认态 |
| Owner / Status | owner、stable / experimental / deprecated、最后更新 | 没人认领，改坏了不知道 |
| 状态 | 视觉上怎么变 | 还能交互吗 | 键盘 / 读屏 | 动效 |
|---|---|---|---|---|
| default | 基准样式 | 是 | 可聚焦 | 无 |
| hover | 背景/描边亮一档；位移 ≤1px | 是 | 不影响 | 150ms |
| focus-visible | 2px 外描边 + 2px offset | 是 | 必须可见 | 无（瞬时） |
| active / pressed | 下沉 1px 或亮度降低 | 是 | Enter/Space 触发 | 80–120ms |
| selected | 底色 + 勾选/描边，不只换颜色 | 是（可取消） | aria-selected | 150ms |
| disabled | opacity 38%，去掉阴影 | 否 | aria-disabled；仍可被读屏发现 | 无 |
| read-only | 像文本，不像禁用 | 不可编辑，可复制/聚焦 | aria-readonly | 无 |
| loading | spinner 或骨架；按钮宽度不变 | 否，防重复 | aria-busy | 800ms 循环 |
| error | 描边 + 图标 + 文案，三者同时 | 是（可改） | aria-invalid + aria-describedby | 150ms |
| success | 描边 + 勾选，不自动消失太快 | 是 | aria-live polite | 200ms |
| empty | 说明 + 一个下一步动作 | 是 | 可读标题与说明 | 无 |
| skeleton | 结构占位，不闪白 | 否 | aria-hidden | 1.4s 循环 |
20 字段是“最小集”。完整模板另含 6 个扩展字段：不适用场景、状态转移、数据契约、reduced-motion、变更记录、反例。小团队先把 20 个填完，再按需加。
/* 1. 状态用属性表达，视觉只认 data-state */
.btn[data-state="hover"] { background: var(--btn-bg-hover); }
.btn[data-state="loading"] { cursor: progress; }
.btn[data-state="loading"] .label { opacity: 0; }
.btn[data-state="loading"] .spinner { display: block; }
.btn[data-state="disabled"] { opacity: .38; pointer-events: none; }
.btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
/* 优先级：disabled > loading > error > success > selected > focus > hover > default */
/* focus 永远额外可见，不被其他状态覆盖 */// 2. 交易状态机：UI 只从状态派生，不各自 if
type TxState =
| { s: 'idle' }
| { s: 'signing' }
| { s: 'pending'; hash: string }
| { s: 'confirmed'; hash: string; block: number }
| { s: 'failed'; reason: string; canRetry: boolean }
| { s: 'reorg'; hash: string };
// 规则：拿到 receipt.status=1 之前不显示成功；
// reorg 回到“核对中”，禁止自动重发（nonce 冲突会变成重复出价）。disabled > loading > error > success > selected > focus > hover > default，只显示最高一级视觉，但 focus 永远额外可见。② 状态用属性表达，不用 class 堆叠：根节点 data-state、交易区 data-tx、拍卖区 data-phase、表单 data-validate；CSS 只认这些值，前端不再各写一套。| 类别 | 状态 | 用户看到什么 | 下一步 / 可撤销 |
|---|---|---|---|
| 加载 | 首屏加载 | 骨架屏（结构一致，不闪白） | — |
| 局部刷新 | 旧数据 + 顶部细进度条 / 小 spinner | 可继续操作 | |
| 长任务 | 步骤进度 + 预计时间 + 可离开 | 后台继续 | |
| 乐观更新 | 先显示成功态，失败再回滚并提示 | 可重试 | |
| 数据 | stale | 最后更新时间 + “刷新”按钮 | 可刷新 |
| partial | 哪些数据有、哪些缺，逐项标 | 可补 | |
| empty | 为什么空 + 一个下一步 | 可行动 | |
| error | 发生了什么 + 为什么 + 重试 | 可重试 | |
| 交易 | 钱包未连接 | 连接按钮 + 为什么需要 | 可取消 |
| 待签名 | 钱包弹窗 + 页面说明“在钱包里确认” | 可拒绝 | |
| 已签名 / 上链中 | tx hash + 确认数 + 预计时间 | 不可撤销 | |
| 成功 | 结果 + 下一步（领币/持仓） | — | |
| 失败 / revert | 原因 + 重试 + 资金未动 | 可重试 | |
| 重组回滚 | “状态回滚，正在重新确认” | 等待 | |
| 拍卖 | 未开始 | 开始时间 + 提醒我 | 可订阅 |
| 进行中 / 最后一小时 | 倒计时 + 当前清算价 + 毕业进度 | 可出价/改价 | |
| 待清算 / 未达标退款 | 清算中；未达标则退款路径与时间 | 退款可查 | |
| 表单 | 校验中 | 字段旁 spinner，不阻塞其他字段 | 可继续填 |
| 草稿已保存 | “已保存 · 14:02”，不弹窗 | 可恢复 | |
| 保存失败 | 顶部状态条 + 重试 + 本地副本 | 可重试 |
状态机不是文档装饰：它是前端 if/else、颜色、文案、按钮 disabled 的唯一来源。
动效只回答三个问题：发生了什么、东西从哪来到哪去、这件事有多重要。回答不了，就不该动。
--dur-1 100ms：按下、颜色、图标切换--dur-2 150ms：hover、focus、描边--dur-3 200ms：按钮、chip、tooltip--dur-4 300ms：面板、tab、modal--dur-5 500ms：页面转场、大区块--ease-out cubic-bezier(.2,.8,.2,1)：进入--ease-in cubic-bezier(.4,0,1,1)：退出--ease-spring cubic-bezier(.34,1.56,.64,1)：toast、徽章40–60ms：列表、徽章组4 / 8 / 12px：小/中/大与 tokens.md 的 150/200/300 对齐：100ms 只给“按下”，500ms 只给页面转场；toast 的 350ms 弹簧是登记例外，不算 bouncy 反模式。
| 动效 | 触发 | 时长 / 缓动 | 只动什么 | 降级 |
|---|---|---|---|---|
| hover 反馈 | 指针进入 | 150ms / ease-out | 背景、描边、translateY(-1px) | reduced-motion 只保留颜色 |
| 按下 | mousedown / Enter | 100ms / ease-out | scale .98 或 translateY(1px) | 无 |
| Toast | 操作结果 | 350ms / spring | opacity + translateY + scale | 直接显示，2.6s 后消失 |
| Modal | 需要确认 | 280ms / ease-out | opacity + translateY + scale | 无动画，直接显示 |
| 数字 ticker | 金额变化 | 900ms / ease-out | 只改 textContent，不动布局 | 直接显示最终值 |
| 骨架 → 内容 | 数据到达 | 200ms / ease-out | opacity 交叉淡入 | 直接替换 |
搜 .json / .lottie / .riv / .mp4 / .glb。有 Lottie JSON 就是 Lottie；有 glb/gltf 就是 Three/R3F/Spline 一类；有 mp4 很可能是预渲染。
搜 gsap、ScrollTrigger、three、framer-motion、lottie。压缩过的看 chunk 名和全局变量。
Record 几秒：只动 transform/opacity 通常 60fps；大面积 layout/paint 往往是低质量实现；canvas 持续重绘可能是 Three/WebGL。
元素上有 animation-name 就是 CSS keyframes；有 transform: matrix3d 可能是 GSAP 或 3D；有 will-change 说明做了合成层优化。
滚动驱动、时间轴驱动、手势驱动是三种不同实现。滚动驱动的多半是 ScrollTrigger / IntersectionObserver / scroll-driven animations。
能识别一部分库和框架，但识别不了手写 CSS。最终还是要回到 Network + Sources。
badgeBreath / badgeRing / badgePopIn / badgeFlash / hbEnter / hbRingBurst / toastPop / fadeIn / dsSkel / dsPulse，外加 transition。早期参考过 pools.trade 的参数（pools-toast-pop、pools-pulse 的 2.8s 节拍），后来徽章 v2 重做，撤掉了 conic 旋转，改成描边闭合。也就是说：我们没有引入 GSAP / Lottie / Three，所有效果都是可控的 CSS——这既是优点（轻、可控），也是缺点（做不了复杂时间轴/3D）。transform 和 opacity；不要动 width/height/top/left；常驻动画不超过 2 个；不在 24px 徽章上跑彩色 conic；prefers-reduced-motion 下全部关闭；自动播放视频必须给暂停。答案分三层：设计工具（Rive/Spline/Lottie）、代码库（GSAP/Motion/Anime）、平台 API（View Transitions / scroll-driven）。先判断属于哪层，再决定学哪个。
Lottie（AE → JSON）、Rive（状态机 → .riv）、Spline（3D 场景 → runtime）。设计师能改，开发只嵌 runtime。
GSAP（时间轴/滚动）、Motion（React 手势/布局）、Anime.js（轻量时间轴）、Theatre.js（3D 编排）。开发主导。
View Transitions API、CSS scroll-driven animations、prefers-reduced-motion。零依赖，优先用。
| 库 | 最强场景 | License | 成本 / 性能 | 适合我们 | 不适合 |
|---|---|---|---|---|---|
| GSAP + ScrollTrigger | 复杂时间轴、滚动叙事、SVG 动画 | Standard License 免费；禁止做与 Webflow 竞争的搭建器 | core 27.4KB + ScrollTrigger 18KB ≈45KB gzip | 落地页滚动叙事、数据图入场 | 简单 hover；React 内状态动画 |
| Motion（原 Framer Motion） | React 手势、布局动画、AnimatePresence | MIT | 按需引入，中等 | 未来 React 版前端 | 纯静态页 |
| Lottie / dotLottie | AE 导出的矢量动画、空态插画 | MIT（lottie-web） | JSON 可大；需懒加载 | 空态、成功/失败插画 | 需要交互状态机的场景 |
| Rive | 可交互状态机、角色/图标动画 | runtime 免费，编辑器订阅 | 很小，GPU 友好 | 徽章/验证状态动效、品牌角色 | 团队没人会 Rive 编辑器 |
| Theatre.js | 3D / 时间轴可视化编排 | Apache-2.0 | 中等，偏重 | 未来 3D hero 编排 | 普通 UI 动效 |
| Anime.js | 轻量时间轴、SVG、DOM | MIT | ~17KB | 小体量营销页 | 复杂滚动/React 布局 |
| View Transitions API | 同文档/跨文档页面转场 | 原生 | 零依赖 | 页面/路由转场首选 | 需要兼容旧浏览器时 |
| Lenis | 平滑滚动 / 惯性 | MIT | 很小 | 落地页滚动叙事 | 数据密集型产品页（会晕） |
| AutoAnimate | 列表增删/排序过渡 | MIT | ~3KB | 成交表、持仓列表 | 复杂编排 |
| Swiper | 轮播、卡片滑动 | MIT | 中等 | 首页 banner/趋势横滑 | 简单 3 张图（CSS scroll-snap 更轻） |
| Barba.js | 多页站点转场 | MIT | 小 | 传统多页营销站 | Next.js SPA（用 View Transitions） |
| Popmotion | 弹簧/物理动画 | MIT | 小 | 手势反馈 | 已被 Motion 覆盖，新项目别选 |
| 站点 | 擅长什么 | 怎么用 | 注意 |
|---|---|---|---|
| Codrops | 前沿 CSS/WebGL/滚动实验，带源码 | 找“效果怎么实现”的第一站 | 偏实验，不一定适合产品 |
| Motion Showcase | Motion 官方示例 | 看 React 手势/布局动画 | 只覆盖 Motion |
| Godly | 精选高质感网站 | 看整体气质与 hero | 多为品牌站，不是产品 |
| Awwwards | 获奖站点、3D/实验 | 找“天花板”和 3D 参考 | 性能/可访问性常被牺牲 |
| SiteInspire / Land-book / Lapa Ninja | 按行业/风格筛落地页 | 找结构、排版、首屏 | 静态截图，看不到交互 |
| Httpster | 独立/工作室风格 | 找不那么“模板”的视觉 | 更新慢 |
| Savee / Muzli | 视觉灵感流 | 配色、版式、动效片段 | 容易只看热闹 |
| LottieFiles | 可直接用的 Lottie 动画 | 空态/加载/成功动画 | 注意 license 与品牌一致性 |
| Rive Marketplace | 可交互动画文件 | 徽章/角色/状态机参考 | 需要 Rive 编辑器 |
| Spline Community | 3D 场景与素材 | 3D hero 参考与 remix | 注意性能与移动端 |
| 案例 | 类型 / 技术 | 看什么 | 我们怎么用 | 降级 |
|---|---|---|---|---|
| Apple MacBook Pro 产品页 | 预渲染视频 + 滚动 scrub，不是 WebGL | 3 个 beat 的镜头推进；滚动位置驱动播放/暂停，不是自动播放 | W6 的 Proof Shell 就照这个节奏：一个符号、三次拆解 | 静态 poster；reduced-motion 不自动播 |
| Bruno Simon 作品集 | Three.js 真 3D 小游戏 | “玩法即品牌”的隐喻；加载与低端机代价 | 只看叙事，不抄预算；我们没有这个人月 | 无；不建议作为基线 |
| Spline Community | Spline runtime 真 3D | 一个主体 + 一个交互点；材质和灯光怎么省 | B 方案：只做一个可 hover/拖拽的 hero 物件 | 静态图/视频 |
| Motion Examples | React Motion | mount/unmount、layout、gesture 的写法 | toast / modal / tab / ticker 的中间态 | CSS transition |
| Codrops | CSS / WebGL / SVG 实验，带源码 | 从 Scroll / WebGL 分类挑 1 个，拆它的层级与时长 | 只借“一个动效”，不搬整套 | CSS / 静态 |
| Rive Marketplace | Rive 状态机动画 | 可交互状态怎么组织；徽章/验证状态参考 | 只给徽章/成功失败，不给全站 | SVG + CSS |
CSS transition + keyframes 足够；加 View Transitions 做页面转场，AutoAnimate 做列表。不要引 GSAP/Three。
用 GSAP + ScrollTrigger 做滚动叙事，或纯 CSS scroll-driven；hero 动效控制在 1–2 个，别做满屏。
徽章/验证状态可以考虑 Rive；空态插画用 Lottie。先有设计再选库，不要为了库而做动画。
你看到的“酷炫 3D”，至少有一半不是真 3D。先分清四类，再决定要不要做。
| 类型 | 你看到的效果 | 实现 | 成本 | 适合 |
|---|---|---|---|---|
| 真 WebGL 3D | 可旋转/随滚动变化/可交互的立体场景 | Three.js / R3F / Babylon / PlayCanvas / Spline runtime | 高：建模、材质、灯光、性能、移动降级 | 品牌 hero、产品可视化、互动演示 |
| 预渲染视频 / 帧序列 | 非常顺滑的“3D 大片”，但不能自由旋转 | Blender/C4D 渲染 → MP4 / WebP 帧序列 → scroll scrub | 中：美术成本高，前端很低 | 产品发布、landing hero |
| CSS 3D / 视差 | 层叠、卡片翻转、伪 3D 场景 | transform: perspective/rotate3d + 视差 | 低 | 卡片、图标、轻量 hero |
| 2.5D / 伪 3D 图 | 等距插画、深度模糊、光效 | 静态图 + 位移/模糊 | 最低 | 空态、功能说明、营销图 |
| 栈 | 上手 | 性能 / 包体 | 移动端 | License | 典型用法 |
|---|---|---|---|---|---|
| Spline | 低（设计工具） | runtime ~273KB gzip + 场景；免费版导出带水印 | 有降级，需测试 | 免费/付费档 | 设计直接导出 Web 场景；hero、产品展示 |
| React Three Fiber + Drei | 中高（React） | Three 体积大，按需拆 | 需自己处理 | MIT | React 站点里的 3D 组件 |
| Three.js | 中高 | ~185KB gzip（整包，可 tree-shake） | 需自己处理 | MIT | 完全自定义 WebGL |
| Babylon.js | 中 | 较大，功能全 | 较好 | Apache-2.0 | 复杂 3D/游戏化场景 |
| PlayCanvas | 中（编辑器） | 优化好 | 好 | MIT/商业档 | 3D 产品配置器、游戏 |
| model-viewer | 低 | 很轻 | 好 | Apache-2.0 | 只展示 glb 模型（360° 查看） |
| OGL / Curtains.js | 中 | 轻 | 中 | OGL: Unlicense / Curtains: MIT | WebGL 图片/文字转场 |
| Zdog | 低 | 很小 | 好 | MIT | 扁平伪 3D 插画/图标 |
| Theatre.js | 中 | 中等，偏重 | 需自己处理 | Apache-2.0 | 3D/时间轴可视化编排，与 Three/R3F 配合 |
| 预渲染视频 / 帧序列 | 低（前端） | 2–3MB 视频；零 3D runtime | 换 poster 即可 | 素材授权另计 | 滚动 scrub 的“伪 3D 大片”，性价比最高 |
表中 OGL / Curtains 合并为一行，预渲染视频是管线不是库；完整 10 项对照与包体数据见 `notes/04-3d-landing.md`。
| 来源 | 有什么 | License | 注意 |
|---|---|---|---|
| Spline Community | 场景、材质、可 remix 的 3D | 逐个看（3D Library 素材可商用） | 免费版导出带水印，去水印需 Hobby $12/席/月；改到像自己的 |
| Sketchfab | 海量模型 | CC / 付费混合 | 逐条看许可；注意面数 |
| Poly Haven | HDRI、材质、模型 | CC0 | 适合真实感场景 |
| Quaternius / Kenney | 低多边形模型/游戏资产 | Quaternius: QAL v1.0 / Kenney: CC0 | 风格化，不适合写实金融 |
| pmndrs GitHub 仓库 | R3F 生态模型/材质/示例 | 逐个看（多为 CC0） | 官网 market.pmnd.rs 实测 404，从 GitHub 取 |
| Mixamo | 角色动画 | 免费（账号） | 中国大陆账号不可用；角色类，不是金融产品 3D |
prefers-reduced-motion 时停止自动旋转| 案例 | 它到底是什么 | 值得学 | 不要学 |
|---|---|---|---|
| Apple MacBook Pro | 预渲染视频，滚动驱动播放；不是实时 3D | 节奏、镜头、信息随滚动出现；兼容性与成本最稳 | 不要为了“3D”上 WebGL；视频也能做出同样的体感 |
| Bruno Simon | Three.js 真 3D + 游戏逻辑 | 把品牌做成可玩的隐喻；交互的记忆点 | 加载、移动端、低端机成本；我们没有人月 |
| Spline Community | Spline runtime 真 3D | 一个主体 + 一个交互点；设计师可独立维护 | 物理、复杂材质、全站 3D |
| 页面 | 要不要 3D | 理由 | 建议形态 |
|---|---|---|---|
| 产品页（首页/项目页/持仓/验证） | 不要 | 用户来读数据、做交易决策；3D 增加加载与干扰 | CSS 动效 + 图表动画即可 |
| 落地页 W6 hero | 可以，但要克制 | 需要记忆点与“真实项目”感 | A：预渲染视频/帧序列（最低风险） B：Spline 轻场景（中） C：R3F 自建（暂不做） |
| 空态/错误页 | 可以 | 用 Lottie/2.5D 插画降低挫败感 | Lottie 或静态 2.5D |
CSS 3D 的例子见 §03 动效里的方块：六个面 = 六个 div + transform: rotate3d。产品页里的“3D 感”大多到这个程度就够；真 WebGL 留给 landing。
对着 tokens.md、501 条元素台账、演示站 #/design 和三个知识库页面逐条核过：15 个缺口，6 个强项。
tokens.md / styles.css / 规范页截图至少 10 处值不一致（底色、surface、positive、导航高度、圆角、字号、字体）。
交易、拍卖、验证三条路径只有静态 toast / 两态，没有 pending、reverted、退款、过期。
text-3 38% 对比度 3.31:1；violet 3.96:1；无 focus-visible；卡片是 div+onclick。
501 条元素没有 component 列，无法回答“多少已被组件覆盖”；六边形徽章 P22 仍是孤儿。
| # | 领域 | 现状（证据） | 成熟标准 / 差距 | 严重度 | 修法 | 量 |
|---|---|---|---|---|---|---|
| 1 | token 分层 | 只有结构/主题两层；缺 primitive/semantic/component；同概念两套命名（--fg vs --text-1、--radius vs --r）；四套主题未落地 | W3C 三层 + 单一 JSON 源；组件直接引用 primitive 时换肤失效 | 高 | tokens.json 三层；生成 CSS/TS；弃用映射；CI 禁裸 hex | M |
| 2 | 组件清单 | 规范页 13 组组件；501 条无组件 ID；向导 6 步 vs 台账 7 步；首页筛选与 1012 不一致 | Atomic Design + inventory；组件 ID ↔ 元素 ID 双向追溯；40–60 个组件 | 高 | C-xx 命名；501 加 component 列；20 个核心覆盖 80% | L |
| 3 | 状态矩阵 | 按钮 3 态、输入 5 态、卡片/行只有 default+hover；is-disabled 不是真 disabled | 每组件 12 态全集（其中 9 个必做），同时定义视觉/行为/ARIA | 高 | 组件 × 状态矩阵；Storybook 每态一 story | M |
| 4 | 中间态 | 交易只有静态 toast；拍卖 3 状态；验证 pass/fail；无 pending/confirmed/reverted/退款/过期 | 三条异步状态机 + 超时/重试/回滚 | 高 | TxStatus / AuctionStatus / VerificationStatus 三组件 | L |
| 5 | 动效 token | 文档说“一套时长一条缓动”，实现至少有 5 条缓动 + 7 个时长（含 pools-spec）；reduced-motion 只关徽章 | duration/easing/loop tokens + 全局降级 | 中 | 补齐 --dur/--ease/--loop；全局 reduced-motion；lint 查裸 cubic-bezier | S |
| 6 | 无障碍 | text-3 3.31:1、紫 3.96:1；无 focus-visible；卡片/筛选 div+onclick；toast 无 aria-live；modal 无 focus trap | WCAG 2.2 AA：4.5:1、焦点可见、键盘、44px | 高 | 提对比度；focus ring token；语义控件；axe 进 CI | M |
| 7 | 响应式 | 只有 900/1100 两档；卡片 1100 以下 2 列无 1 列；无移动导航；验收全是 1440 | 1280/1024/768/480 四档；移动抽屉；表格转卡片；粘性 CTA | 高 | 四档断点；移动导航；375/390/768 进验收 | M |
| 8 | 数据可视化 | 只有 sparkline 和面积图；无轴/刻度/单位/图例/tooltip/零线/负值/空值；null 不许显示 0 只写在文档 | 轴/单位/时间粒度/零线/null 断点/空态/色盲安全 | 高 | 图表规范 + Chart API；P402–P405 当验收样例 | M |
| 9 | 内容规范 | 有命名规则，但无术语表/数字格式/日期格式/语气/中英词表；金额有 $1.2M 与 $1,200,000；0 显示 +0.0% | 术语 + 数字/日期/百分比 + microcopy + 双语词表 | 中 | 内容规范 v1；format.ts 单测；0 的符号规则 | M |
| 10 | 组件 API | 只有 class/CSS，没有 props/variants/slots/events；6 变体 × 3 尺寸靠任意拼 class | 每组件 API 表 + TS 类型 + 合法组合矩阵 | 高 | 20 个核心组件 API 表；Storybook controls | M |
| 11 | 文档站结构 | 单页 #/design 只有 Foundations / Components 26 节；无 Patterns / Content / Governance；无搜索/owner/更新时间 | 五段式 IA + 搜索 + 状态徽章 + owner | 中 | 8 栏 IA；front-matter；Patterns 从 501 生成 | M |
| 12 | 版本与变更 | tokens.md 只有日期；规范页 v0.3、徽章 v2 在其后、截图 v0.1；无 CHANGELOG | SemVer + CHANGELOG + 组件状态（实验/稳定/废弃） | 高 | v1.0 基线；CHANGELOG；meta 自动读 manifest | S |
| 13 | 贡献/评审 | 有代码规范与 DoD，但无设计系统贡献流程、owner、废弃策略 | RFC + owner + 评审清单 + 变更分级 | 中 | CONTRIBUTING；1 owner + 2 reviewer；PR 模板 | S |
| 14 | 设计-代码一致 | tokens.md vs styles.css 至少 10 处值冲突；无 tokens.json/Figma/Storybook；规范页自称 SSOT 但值在 app.js 字符串里 | token 单一源 → 生成 CSS/TS/文档；视觉回归 | 高 | tokens.json 为源；CI 生成；Playwright 截图对比 | L |
| 15 | 资产规范 | 图标较强（Lucide 22 个）；无插图/空态插画/3D/OG/favicon 规范；资产来源与许可不可追溯 | 图标网格/笔画/命名；插图风格；3D 边界；OG/favicon；动效导出 | 中 | 资产清单 + 图标规范 + 3 个插图示例 + OG | S/M |
四条动效只服务“已验证”，未验证零动效；v2 用 SVG 描边闭合替代 conic 旋转；有 locked/obtained/rare/legendary/just-earned 状态。这已经是品牌资产，把 P22 从台账孤儿接回产品即可。
先拆结构/主题、再谈四套主题，还规划了 CSS/JSON/主题三文件。方向对，问题在执行——补第三层和生成管线，不要推翻。
#/design 支持深链、有竞品对比、每个组件写“为什么”、按钮/输入/弹层可点。比 Figma 截图更适合一人推动、多人使用的阶段。
强制 tabular-nums、数字用等宽、null 不许显示 0、把“收入已验证”与“X 已认证”从命名上分开。这些是交易产品的命门。
纸色/宋体/880px/17px-1.9/侧栏/搜索/四类 callout/响应式/打印。产品 UI 用暗色数据语言，规范站用纸色编辑语言，共享 token 逻辑但不共享皮肤。
501 条元素按页分布（项目页 155 / 向导 99 / 首页 73 / 全局 72 / 持仓 44 / 落地 31 / 验证 27），只差组件 ID 这一列。
为谁服务、五条原则、非目标、路线图、如何提需求。
颜色三层、字体、间距、圆角、阴影、栅格断点、动效 token、图标网格。
对比度、焦点、键盘、减弱动效、44px、颜色非唯一、验收清单。
解剖、变体、状态矩阵、API、A11y、do/don't、代码链接。
交易、拍卖、验证、空/错/载、图表、发币向导。
术语、数字单位、日期、百分比负值、错误/空态文案、中英词表、免责声明。
Lucide、品牌 marks、头像、插图/空态、OG/favicon、3D 边界、动效导出。
版本/CHANGELOG、贡献、评审、废弃、owner、tokens.json 下载、迁移。
不要同时开三条线。先让规范“能用”，再让它“好看”。
逐条裁决 tokens.md 与 styles.css 的 10 处冲突，冻结唯一源；修对比度、focus ring、键盘、全局 reduced-motion。
501 条合并成 40–60 个组件，20 个核心；12 态全集（9 个必做）；组件页模板 20 字段。
交易/拍卖/验证三张状态机；动效 token 与 6 个标准 recipe；内容、数字格式、图表规范。
8 栏 IA、CHANGELOG、CONTRIBUTING、评审清单；Playwright 截图回归，冻结 v1.0。
这一页是“规范的索引 + 缺口诊断”，不是规范本身；真正要落地的规范应回到演示站 #/design 并按 8 栏 IA 重写。
2026-10-18。5 路并行调研（设计系统标准与 OpenDesign / 组件状态与中间态 / 动效库与灵感 / 3D landing / 我们自己的缺口），再由 1 路审核 agent 逐份复核链接、事实和覆盖度。链接已逐条检查：无 404；Codrops / LottieFiles / Land-book / Lapa 等对爬虫返回 403 或 429，浏览器通常可打开。license 与商用条款以官网为准，标「待核实」的条目需在采购/上线前再确认。我们的现状证据来自 产品/tokens.md、501 条元素台账、演示站 #/design、AboutFace4整理 三页实现与验收截图。
这是不可撤销操作。成交后清算价可能低于你的最高单价；未达毕业线将全额退款。