从能跑到成品:motion-web的生产级打磨清单,OG图、favicon、404、暗色模式一次补齐

原创2026-10-26 10:01:561,373 阅读

从能跑到成品:motion-web的生产级打磨清单,OG图、favicon、404、暗色模式一次补齐

一个动效网页跑起来之后,离「成品」还差一堆只在正常路径之外才暴露的小事:标签页没有 favicon、分享到 IM 的 OG 图是空的、404 还是框架默认页、暗色模式手机上一打开就闪白。motion-web 把这一层生产级打磨写成了可逐项核对的清单 references/production-polish.md——OG 图、favicon、404、暗色模式一次补齐,让页面从 demo 变成能交付的成品。

motion-web 生产级动效案例演示动画

「能跑」与「成品」之间的差距,是实测出来的

motion-web 对 32 个真实站点做了静态结构测量(工具见 scripts/measure_structure.py),差距几乎全部集中在打磨层:

检查项 创意站 (n=18) 产品站 (n=14)
og:image / og:title / og:description 16 / 15 / 14 14 / 14 / 14
rel=canonical 8/18 13/14
lang 写在 <html> 上 14/18 14/14
页面只有一个 <h1> 10/18(5 个为零) 11/14
skip link(跳转到主内容) 0/18 4/14
prefers-color-scheme 暗色规则 1/18 4/14
<title> 长度中位数 28.5 字符 42.5 字符

📌 结论:这一层没有审美判断,只有「存在或缺陷」。缺了 lang、canonical 和 <h1> 的页面,会在搜索、读屏和翻译上白白吃亏。

motion-web 粘性叠层唱片封面案例暗色与亮色版面对比

一步写对 <head>:OG 图、favicon、theme-color 全在这

production-polish.md §1 给出的 head 结构,每一项都是「存在即合格」:

  • <title> 40–60 字符:品牌名 + 一句主张。只写品牌名(28 字符中位数)等于浪费了搜索结果里唯一一行。
  • meta description 120–155 字符:写给人看的完整一句话。
  • link rel=canonical:给爬虫一个唯一身份,避免重复索引。
  • Open Graph 全家桶:og:title、og:description、og:image——Slack、iMessage、微信、飞书的链接预览都读它。
  • favicon 三件套:32px .ico(兼容旧浏览器)+ 可缩放的 .svg(支持主题感知)+ 180×180 无透明 PNG 作 apple-touch-icon。
  • theme-color 分明暗两行:让手机浏览器 chrome 区域跟着主题走,页面立刻不像「套壳 WebView」。

⚠️ 最常见的坑只有一个:og:image 必须是绝对 URL。相对路径会静默产出空白预览——「为什么链接在 Slack 里是坏的」的头号原因,而且从代码里完全看不出来。

OG 图怎么做:1200×630 的卡片,不是截图

  1. 静态导出:hero 的静帧,或一张带字标和标题的卡片,单页站足够。
  2. 按路由生成:@vercel/og / satori 一类方案。有 40 个 URL 还在共享一张图,就是浪费信号。

设计原则:它在信息流里只有 ~500px 宽,字号要巨大、安全区要宽。做完后把 URL 粘进 Slack 看真实 unfurl 再喊完成——大多数 OG bug 是缓存或绝对 URL 问题,markup 里看不到。

motion-web 墨线群集案例展示链接预览卡片风格

404 与错误页:把「没人设计的路由」补齐

这一节(§3–§4)管的是所有正常路径之外的状态:

状态 「完成」长什么样
Loading 设计好的占位画面——不是白底转圈,布局预留空间不跳动
Pending(表单提交中) 按钮原地换文案、禁用,防双击提交
Success 结果留在页面上;会消失的 toast 不是回执
Error 挨着出错原因,说清怎么修,挂 aria-describedby
Empty(空列表/空搜索) 说出当前筛选条件,并给一条出路
Offline / 慢网 有兜底内容,而不是无限骨架屏

还有两件容易被忘掉的小事:

  • 设计过的 404 页:用站点自己的字体和视觉语言,只给一条回家的路。框架默认 404 是「没人做完」最响亮的信号。
  • robots.txt + sitemap.xml:各一行配置,却是「被正确索引」和「被奇怪索引」的分界线。

微文案(microcopy)是页面人格的所在地——404 那句话、空状态那句、提交按钮下的提示,读者卡住时读得比任何标题都仔细。用和正文一致的语气,永远别写「Request failed with status 422」。

motion-web 字符帘幕案例展示页面完整视觉状态

暗色模式:要么真做,要么干脆别做

样本里只有 1/18 的创意站、4/14 的产品站真的写了 prefers-color-scheme 分支。motion-web 的态度很直接:只做一个底色是合法选择,但要做到底——设上 color-scheme,让表单控件、滚动条、光标颜色都跟着走,否则深色页面会渲染出一堆浅色原生控件。

如果决定明暗都发,规则只有三条:

  1. 只做二级 token 重映射(references/project-setup.md §2)。任何一个组件需要单独改代码,说明 token 层没定义好。
  2. 用 light-dark() 一份定义(Baseline 2024),而不是媒体查询和属性选择器各写一遍;手动开关只需切换 color-scheme。
  3. 不许闪:有手动开关时,在 <head> 里放一小段阻塞式内联脚本,首帧前就把 data-theme 打到 <html> 上——useEffect 一类的后置切换每次加载都会闪一下。

另外记住:素材不跟着重映射。照片、视频、shader 输出保持原样,让页面框架去适配两种底色,或者干脆换一套资产。文字压在动效上时,在最忙的帧上分别测明暗两遍对比度。

motion-web 滚轮轨道视差案例页面成品效果

发布前 10 项手动检查:别估算,去跑

自动化先行(构建零错误零警告 + Lighthouse 桌面/移动端 + 全站逐路由跑):

npm run build && npm run typecheck
npx lighthouse <url> --form-factor=mobile --throttling-method=simulate --view

然后按顺序手工过一遍(§9 原顺序):

  1. 禁用 JS 加载——内容还在吗?(纯 canvas 页面:还剩什么?)
  2. prefers-reduced-motion: reduce——应该是设计过的页面,不是坏掉的页面
  3. Tab 走完全页——焦点环处处可见、顺序符合阅读顺序、无焦点陷阱
  4. 320 / 375 / 414 / 768 / 1440 五个宽度——无横向滚动、无两行按钮、展示字不裁切
  5. 缩放到 200 %——纯 vw 的 clamp() 就是在这里死掉的
  6. 真机测:中端 Android,不只是模拟器
  7. 把 URL 粘进 Slack,看 unfurl 是否如预期
  8. 提交表单,包括故意失败的那次,读一读你真写出来的错误文案
  9. 访问一个不存在的 URL——看你的 404
  10. 刷新五次:无闪烁、无布局偏移、无 console 报错

交付前 5 分钟自查清单

production-polish.md §10 的完整 checklist 浓缩成六个 yes/no:

  • [ ] lang、40–60 字符 <title>、description、canonical 都在 ✅
  • [ ] og 三件套齐全、og:image 是 1200×630 的绝对 URL,真实 unfurl 验过 ✅
  • [ ] favicon .ico + .svg + apple-touch-icon,theme-color 分模式 ✅
  • [ ] 设计过的 404、robots.txt + sitemap.xml、尾斜杠/大小写策略已定并统一重定向 ✅
  • [ ] loading / pending / success / error / empty 五种状态都建过且真见过 ✅
  • [ ] 暗色模式:要么 color-scheme 配齐 + token 重映射 + 无闪烁,要么明确不发 ✅

动效让页面「活」,打磨层让它「真」。想看打磨完成度参照系,可以打开案例画廊 cases/index.html(如 cases/press-stack/ 每屏都带完整的状态与 token),配合 SKILL.md 里的 polish 意图识别和 references/verification-harness.md 的自动化判据台架,「能跑」到「成品」就是照着清单逐项打勾的事。

登录后查看全文
motion-web