从能跑到成品:motion-web的生产级打磨清单,OG图、favicon、404、暗色模式一次补齐
从能跑到成品:motion-web的生产级打磨清单,OG图、favicon、404、暗色模式一次补齐
一个动效网页跑起来之后,离「成品」还差一堆只在正常路径之外才暴露的小事:标签页没有 favicon、分享到 IM 的 OG 图是空的、404 还是框架默认页、暗色模式手机上一打开就闪白。motion-web 把这一层生产级打磨写成了可逐项核对的清单 references/production-polish.md——OG 图、favicon、404、暗色模式一次补齐,让页面从 demo 变成能交付的成品。
「能跑」与「成品」之间的差距,是实测出来的
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>的页面,会在搜索、读屏和翻译上白白吃亏。
一步写对 <head>:OG 图、favicon、theme-color 全在这
production-polish.md §1 给出的 head 结构,每一项都是「存在即合格」:
<title>40–60 字符:品牌名 + 一句主张。只写品牌名(28 字符中位数)等于浪费了搜索结果里唯一一行。meta description120–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 的卡片,不是截图
- 静态导出:hero 的静帧,或一张带字标和标题的卡片,单页站足够。
- 按路由生成:
@vercel/og/satori一类方案。有 40 个 URL 还在共享一张图,就是浪费信号。
设计原则:它在信息流里只有 ~500px 宽,字号要巨大、安全区要宽。做完后把 URL 粘进 Slack 看真实 unfurl 再喊完成——大多数 OG bug 是缓存或绝对 URL 问题,markup 里看不到。
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」。
暗色模式:要么真做,要么干脆别做
样本里只有 1/18 的创意站、4/14 的产品站真的写了 prefers-color-scheme 分支。motion-web 的态度很直接:只做一个底色是合法选择,但要做到底——设上 color-scheme,让表单控件、滚动条、光标颜色都跟着走,否则深色页面会渲染出一堆浅色原生控件。
如果决定明暗都发,规则只有三条:
- 只做二级 token 重映射(references/project-setup.md §2)。任何一个组件需要单独改代码,说明 token 层没定义好。
- 用
light-dark()一份定义(Baseline 2024),而不是媒体查询和属性选择器各写一遍;手动开关只需切换color-scheme。 - 不许闪:有手动开关时,在
<head>里放一小段阻塞式内联脚本,首帧前就把data-theme打到<html>上——useEffect一类的后置切换每次加载都会闪一下。
另外记住:素材不跟着重映射。照片、视频、shader 输出保持原样,让页面框架去适配两种底色,或者干脆换一套资产。文字压在动效上时,在最忙的帧上分别测明暗两遍对比度。
发布前 10 项手动检查:别估算,去跑
自动化先行(构建零错误零警告 + Lighthouse 桌面/移动端 + 全站逐路由跑):
npm run build && npm run typecheck
npx lighthouse <url> --form-factor=mobile --throttling-method=simulate --view
然后按顺序手工过一遍(§9 原顺序):
- 禁用 JS 加载——内容还在吗?(纯 canvas 页面:还剩什么?)
prefers-reduced-motion: reduce——应该是设计过的页面,不是坏掉的页面- Tab 走完全页——焦点环处处可见、顺序符合阅读顺序、无焦点陷阱
- 320 / 375 / 414 / 768 / 1440 五个宽度——无横向滚动、无两行按钮、展示字不裁切
- 缩放到 200 %——纯
vw的clamp()就是在这里死掉的 - 真机测:中端 Android,不只是模拟器
- 把 URL 粘进 Slack,看 unfurl 是否如预期
- 提交表单,包括故意失败的那次,读一读你真写出来的错误文案
- 访问一个不存在的 URL——看你的 404
- 刷新五次:无闪烁、无布局偏移、无 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 的自动化判据台架,「能跑」到「成品」就是照着清单逐项打勾的事。




