impeccable `adapt` 命令深度解析：面向 Web 的多端设计适配方法论与响应式实现要点

本文以 Impeccable 技能中的 adapt 参考文档（adapt.md）为主体，完整拆解这一"跨设备/跨场景适配"工作流的四个阶段——评估适配挑战、制定适配策略、落地实现技术、跨上下文验证——并结合技能源码与命令路由说明它在 Impeccable 中的实际执行方式。读完后，你将掌握把"缩放像素"升级为"为每个上下文重构体验"的完整决策框架，以及移动端优先断点、指针/悬停检测、安全区、响应式图片等可直接复制落地的 CSS/HTML 技术细节。

1. adapt 命令的定位：是重做体验，不是缩放像素

adapt 是 Impeccable 的 23 个命令之一，属于 Commands 表中 Fix 分类，描述为"为不同设备和屏幕尺寸做适配"。在 SKILL.md 的命令表中，它对应参考文档 adapt.md，原生平台则路由到 adapt.native.md。命令的参数格式在 command-metadata.json 中定义为：

argumentHint: "[target] [context (mobile, tablet, print...)]"
description: "Adapt designs to work across different screen sizes, devices, contexts, or platforms.
Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive
design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility."

文档开篇就点明了这条工作流的核心理念，原文是："The trap is treating adaptation as scaling. The job is rethinking the experience for the new context."（陷阱是把适配当成缩放；工作是面向新上下文重新思考体验）。

同时有两个使用前提：

1. 适用范围限定为 Web（含移动 Web）。文档明确要求：如果目标平台是 ios / android / adaptive（原生项目），应立即切换到 adapt.native.md，后者以 iOS/Android 的平台惯例（size classes、导航形态转换、跨平台 idiom 对照表）为骨架。
2. 需要补充上下文：文档开头标注了 Additional context needed: target platforms/devices and usage contexts，即执行前必须先弄清"适配到哪些设备/场景"。

从源码结构看，adapt 并不是孤立文档：它与 audit（技术质量检查）、polish（收尾）在同一技能内形成接力——adapt.md 结尾明确"当适配让每个上下文都感觉自然时，移交给 $impeccable polish 做最后一遍"，这条交接链在 SKILL.md 的 polish 命令描述（"Final quality pass before shipping"）中得到印证。

2. 阶段一：评估适配挑战（Assess Adaptation Challenge）

文档要求先回答"要适配什么、为什么"，分三步：

1）识别源上下文（Source context）

• 它最初是为什么设计的？（桌面 Web？移动应用？）
• 做了哪些假设？（大屏？鼠标输入？高速网络？）
• 当前上下文中哪些是真正做得好的？

2）理解目标上下文（Target context），逐项确认：

• 设备：手机、平板、桌面、TV、手表、打印？
• 输入方式：触摸、鼠标、键盘、语音、手柄？
• 屏幕约束：尺寸、分辨率、方向？
• 网络：高速 WiFi、慢速 3G、离线？
• 使用场景：路上随手看 vs 桌前专注；快速一瞥 vs 深度阅读？
• 用户预期：用户在这个平台上期待什么模式？

3）识别适配挑战，三类问题清单：

• 什么放不下？（内容、导航、功能）
• 什么会失效？（触摸端的 hover 状态、过小的触摸目标）
• 什么不合适？（在手机上用桌面模式，在桌面上用移动模式）

文档用 CRITICAL 强调收束这一步："适配是为新上下文重新思考体验，而不是缩放像素。"这一原则贯穿后文所有策略。

3. 阶段二：制定适配策略（Plan Adaptation Strategy）

文档按五类目标场景给出策略矩阵，这是全文信息密度最高的部分，下面完整继承。

3.1 移动端适配（Desktop → Mobile）

布局策略：

• 多列改单列
• 并排改纵向堆叠
• 固定宽度改全宽组件
• 顶部/侧边导航改底部导航

交互策略：

• 触摸目标最小 44×44px（且不依赖 hover）
• 在合适的地方使用滑动手势（列表、轮播）
• 用 bottom sheet 代替下拉菜单
• Thumbs-first 设计（控件放在拇指可及范围）
• 更大的点击区域、更多间距

内容策略：

• 渐进式披露（不要一次展示全部）
• 优先主内容（次要内容放进 tabs/手风琴）
• 更短的文案
• 更大字号（正文最小 16px）

导航策略：

• 汉堡菜单或底部导航
• 降低导航复杂度
• Sticky 头部保持上下文
• 导航流中提供返回按钮

3.2 平板适配（Hybrid Approach）

布局：两列布局（既不是单列也不是三列）；侧边面板承载次要内容；master-detail（列表 + 详情）视图；根据横竖屏方向自适应。

交互：同时支持触摸与指针；触摸目标 44×44px 但布局密度可以比手机高；侧滑导航抽屉；合适时允许多列表单。

3.3 桌面端适配（Mobile → Desktop）

布局：多列布局（利用横向空间）；侧边导航常显；同时展示多个信息面板；固定宽度 + max-width 约束（不要拉伸到 4K 全屏）。

交互：hover 状态承载附加信息；键盘快捷键；右键上下文菜单；有帮助时引入拖放；Shift/Cmd 多选。

内容：前置更多信息（减少渐进式披露）；多列数据表格；更丰富的可视化；更详细的描述。

3.4 打印适配（Screen → Print）

布局：在逻辑节点分页；移除导航、页脚和一切交互元素；黑白或有限色彩；为装订留合适页边距。

内容：展开被截断的内容（完整 URL、隐藏章节）；加页码、页眉页脚；包含元数据（打印日期、页面标题）；图表转为打印友好版本。

3.5 邮件适配（Web → Email）

布局：窄宽（最大 600px）；仅单列；CSS 全部内联（不能用外部样式表）；表格布局以兼容邮件客户端。

交互：大而醒目的 CTA（用按钮而不是文字链接）；不用 hover 状态（在邮件客户端中不可靠）；复杂交互用深链接跳回 Web 应用。

4. 阶段三：实现适配（Implement Adaptations）

策略确定后，文档给出系统化的落地技术清单。

4.1 响应式断点（Responsive Breakpoints）

推荐区间：

• 移动：320px–767px
• 平板：768px–1023px
• 桌面：1024px 以上
• 或者内容驱动断点——在设计真正"碎掉"的位置才加断点（这一理念在后文 Reference Material 中再次强调）。

4.2 布局适配技术

• CSS Grid / Flexbox：让布局自动回流
• Container Queries：按容器而非视口适配
• clamp()：在 min/max 之间的流式尺寸
• Media queries：不同上下文用不同样式
• display 属性：按上下文显隐元素

4.3 触摸适配（Touch Adaptation）

• 触摸目标最小 44×44px
• 交互元素之间加间距
• 移除依赖 hover 的交互
• 添加触摸反馈（ripple、高亮）
• 考虑拇指热区（底部比顶部更易触达）

4.4 内容适配（Content Adaptation）

• 谨慎使用 display: none（资源仍会被下载）
• 渐进增强：核心内容先加载，增强留给大屏
• 屏外内容懒加载
• 响应式图片（srcset、picture 元素）

4.5 导航适配（Navigation Adaptation）

• 移动上把复杂导航折叠成汉堡/抽屉
• 移动应用用底部导航栏
• 桌面保持常驻侧边导航
• 小屏用面包屑维持上下文

文档给出两条强约束：

• IMPORTANT：要在真机上测试。DevTools 的设备模拟有帮助但不完美。
• NEVER 清单（原文逐条继承）：
  1. 不在移动端隐藏核心功能（重要就让它能用）
  2. 不假设"桌面 = 高性能设备"（要考虑无障碍、旧机器）
  3. 不在不同上下文间使用不同的信息架构（会造成困惑）
  4. 不破坏平台预期（移动用户期待移动模式）
  5. 不忘记移动/平板的横屏
  6. 不盲目套通用断点（应用内容驱动断点）
  7. 不忽略桌面上的触摸（很多桌面设备带触摸屏）

5. 阶段四：验证适配（Verify Adaptations）

文档要求跨上下文充分测试，矩阵覆盖七个维度：

维度	覆盖内容
真机	实际手机、平板、桌面
方向	竖屏与横屏
浏览器	Safari、Chrome、Firefox、Edge
操作系统	iOS、Android、Windows、macOS
输入方式	触摸、鼠标、键盘
极端尺寸	320px 极小屏、4K 超大屏
慢网络	限速网络环境

验证通过的标准不是"没报错"，而是"当适配让每个上下文都感觉像本地产品（feels native to each context）"，随后移交给 $impeccable polish 收尾。

从源码结构看，这套验证标准并非孤立的纸面要求：技能内 audit.md 定义了对应的量化评分——Responsive 维度按 0–4 打分（"0=Desktop-only (breaks on mobile) … 4=Excellent (fluid, all viewports, proper touch targets)"），且技术检查项明确包含"Interactive elements < 44×44px"的触摸目标判定；critique.md 的 UX 评审中也包含"Are touch targets at least 44×44pt?"一条。可以说 adapt 负责"改"，audit/critique 负责"量"，两者共享同一套阈值。

6. 内置参考：响应式设计的深层要点（Reference Material）

文档后半部分注明：以下章节原为独立的 responsive-design.md，现已内联到 adapt 流程中，"让适配流在一个地方拿到全部响应式深度参考"。这部分是可直接落地的技术要点。

6.1 Mobile-First：从基础样式写起

先用移动端的 base styles，再用 min-width 查询逐层叠加复杂度。Desktop-first（max-width）的代价是移动端要先把不必要的样式加载完。

6.2 断点：由内容驱动

不要追着设备尺寸跑，让内容告诉你哪里该断：从最窄开始，加宽到设计碎掉为止，在那里加断点。通常三个断点足够（640 / 768 / 1024px）；能用 clamp() 做流式值就不需要断点。

6.3 检测输入方式，而不只是屏幕尺寸

原文强调："Screen size doesn't tell you input method."（屏幕尺寸不能告诉你输入方式）——触屏笔记本、带键盘的平板都是反例。应使用 pointer 与 hover 特性查询：

/* Fine pointer (mouse, trackpad) */
@media (pointer: fine) {
  .button { padding: 8px 16px; }
}

/* Coarse pointer (touch, stylus) */
@media (pointer: coarse) {
  .button { padding: 12px 20px; }  /* Larger touch target */
}

/* Device supports hover */
@media (hover: hover) {
  .card:hover { transform: translateY(-2px); }
}

/* Device doesn't support hover (touch) */
@media (hover: none) {
  .card { /* No hover state - use active instead */ }
}

Critical：不要把功能挂在 hover 上——触摸用户根本无法 hover。这一条与第 4.3 节"移除 hover 依赖交互"以及 pointer: coarse 下加大 padding 的做法互为表里：功能可用性归 hover: none 管，尺寸舒适度归 pointer 管。

6.4 安全区：处理刘海与圆角

现代手机有刘海、圆角和 Home 指示条，用 env(safe-area-inset-*) 处理：

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

/* With fallback */
.footer {
  padding-bottom: max(1rem, env(safe-area-inset-bottom));
}

max(1rem, env(...)) 是文档给出的回退写法：不支持 env() 的环境至少保有 1rem 的底部留白。并且必须在 viewport meta 中启用 viewport-fit=cover，否则 safe-area-inset-* 全部为 0：

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

6.5 响应式图片：srcset 与 picture

宽度描述符 srcset：

<img
  src="hero-800.jpg"
  srcset="
    hero-400.jpg 400w,
    hero-800.jpg 800w,
    hero-1200.jpg 1200w
  "
  sizes="(max-width: 768px) 100vw, 50vw"
  alt="Hero image"
>

工作机制（原文逐条）：

• srcset 列出可用图片及其实际宽度（w 描述符）
• sizes 告诉浏览器图片将以多宽显示
• 浏览器根据视口宽度和设备像素比挑最合适的文件

艺术方向用 picture——需要不同裁切/构图（而不只是不同分辨率）时：

<picture>
  <source media="(min-width: 768px)" srcset="wide.jpg">
  <source media="(max-width: 767px)" srcset="tall.jpg">
  <img src="fallback.jpg" alt="...">
</picture>

6.6 布局适配模式

三个高频场景的既定模式：

• 导航：三段式——移动端汉堡 + 抽屉，平板横向紧凑，桌面完整带标签
• 表格：移动端用 display: block + data-label 属性转成卡片
• 渐进披露：可折叠内容用 <details>/<summary>

6.7 测试：别只信 DevTools

DevTools 设备模拟对布局有用，但会漏掉：

• 真实触摸交互
• 真实 CPU/内存约束
• 真实网络延迟形态
• 字体渲染差异
• 浏览器 chrome / 软键盘的出现

至少要测：一台真 iPhone、一台真 Android、相关的话加一块平板。文档原话："Cheap Android phones reveal performance issues you'll never see on simulators."（廉价安卓机能暴露模拟器上永远看不到的性能问题。）

文末的 Avoid 清单收束全篇：不做 desktop-first 设计；不做设备检测代替特性检测；不为移动/桌面维护独立代码库；不忽略平板和横屏；不假设所有移动设备都高性能。

7. 从源码结构看：adapt 在技能中的执行链路

参考文档本身是给 Agent 阅读的"剧本"，它的运行方式可以从仓库源码中确认：

1. 路由与加载：SKILL.md 规定 Setup 阶段先运行 node <skill-base-dir>/scripts/context.mjs 加载 PRODUCT.md / DESIGN.md 与对应 surface brief，再按请求加载命令参考。用户输入 adapt 时加载本文档；若 setup.platform 为 ios/android/adaptive 则改走 adapt.native.md。无参数调用时则先读 routing.md 生成上下文感知菜单，"Never auto-run a command"。
2. 上下文来源：context.mjs 的文件头注释说明其按"活动项目根 → .agents/context/ → docs/ → 仓库根 → $IMPECCABLE_CONTEXT_DIR"的优先级解析 PRODUCT.md / DESIGN.md，并识别 monorepo（pnpm-workspace.yaml、turbo.json 等标记文件）。这解释了 adapt 第一步"识别源上下文"为何强调先弄清既有设计假设——假设信息来自项目已持久化的产品/设计上下文，而非临场猜测。
3. 量化校验：如第 5 节所述，audit.md 的 Responsive 0–4 分制与"触摸目标 < 44×44px"检查项，为 adapt 的产出提供了独立于改代码过程的技术验收；critique.md 则在 UX 评审侧复核 44×44pt 触摸目标。
4. 收尾交接：adapt 与 polish 的交接在 polish.md 对应的命令描述（"Final quality pass before shipping"）中闭合，形成"改 → 量 → 收"的完整回路。

8. 小结：可执行的适配检查单

把全文压缩成一张可以贴在工位上的检查单：

1. 先答三问：源上下文是什么、目标上下文的六个维度（设备/输入/屏幕/网络/场景/预期）是什么、什么放不下/失效/不合适。
2. 对号入座选策略：Mobile / Tablet / Desktop / Print / Email 五套策略矩阵中挑对应的一套，别混用。
3. 实现四件套：内容驱动断点（640/768/1024 或碎掉处）、pointer/hover 特性查询、env(safe-area-inset-*) + viewport-fit=cover、srcset/picture 响应式图片。
4. 守住 NEVER 清单：不隐藏核心功能、不跨上下文拆信息架构、不盲目套通用断点、不忽略桌面触摸与横屏。
5. 真机验证：至少一台真 iPhone + 一台真 Android，覆盖双方向、慢网络、320px 与 4K 两端。
6. 移交 polish：当每个上下文都"feels native"时收尾。

这套工作流的价值在于把"响应式设计"从一组 CSS 技巧升级成了有评估、有策略选择、有实现约束、有验收标准的完整工程流程——这正是 Impeccable 把 adapt.md 作为独立命令参考、并与 adapt.native.md、audit.md、polish.md 分工协作的原因。