Impeccable 原生设计适配指南：adapt.native 如何将 iOS/Android 设计跨设备、跨方向与跨平台重构

Impeccable 原生设计适配指南：adapt.native 如何将 iOS/Android 设计跨设备、跨方向与跨平台重构

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

本文围绕 Impeccable 技能库中的原生适配参考 adapt.native.md 展开，讲清楚在ios/android/adaptive平台上把一个既有的原生设计搬到新上下文（另一类设备、另一种屏幕方向、另一个操作系统，甚至从 Web 移植而来）时的完整方法论：从“源/目标上下文 + 破坏点”三步评估，到手机→平板、方向与折叠屏、iOS↔Android 双平台互转、Web→Native 四类适配策略，再到基于 size class 的实现要求与“模拟器覆盖广度、真机验证真相”的验收流程。读完你应能独立判断一次原生适配属于哪一类挑战，选对重构策略，并给出可落地的验证方案。

一、adapt 命令的双路由：Web 版与原生版分道扬镳

在 Impeccable 的命令体系中，adapt [target]属于 Fix 类命令，命令表见 SKILL.src.md：

adapt [target]| Fix | Adapt for different devices and screen sizes | reference/adapt.md · native: reference/adapt.native.md

命令元数据中对其定位是：“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.”（见 command-metadata.json）

关键的路由规则写得很明确：adapt.md 开篇就声明其只覆盖Web（含移动 Web），而“Native platforms (ios/android/adaptive) route to adapt.native.md instead; if the project is native, switch to it now.” 也就是说，一旦context.mjs在 Setup 阶段记录的项目平台是ios、android或adaptive，适配工作流就会切换到本文的主角——adapt.native.md。

这份参考开篇给出两个前提：

1. 额外上下文需求（Additional context needed）：目标平台/设备与使用场景。没有“目标端是什么、用户怎么拿设备”这两条信息，适配无从谈起；
2. 核心警示：把适配当成缩放（scaling）是陷阱。“The job is rethinking the experience for the new context”——任务是为新上下文重新思考体验，而不是把像素放大缩小。

它还要求：在规划之前，如果 Setup 阶段还没读过目标平台的参考文档，必须先读 ios.md 或 android.md，因为一切适配都发生在目标平台的平台约定之内。

二、评估适配挑战：源上下文、目标上下文、破坏点

文档将评估阶段压缩为三个问题，构成适配前的强制检查清单：

1. Source context（源上下文）：这个设计原本是为什么设计的，做了哪些假设？只针对手机？只针对竖屏？只用了某一个平台的惯用法（idioms）？还是一个网站？
2. Target context（目标上下文）：目标设备类别（phone、tablet、foldable）、屏幕方向、平台，以及使用姿态（usage posture）——单手在途操作，还是双手静置操作。
3. What breaks（什么会坏）：哪些导航不适合目标端？哪些布局只是被拉伸而非重构？哪些手势或控件在目标端根本不存在？

第三步尤其值得展开。它把常见的适配失败模式直接点名了：

• 导航形态不匹配——例如把手机底部 Tab 原样留在平板上（这正是 android.md 明令禁止的 “Never ship a phone bottom-bar untouched on a tablet”）；
• 布局“stretch instead of restructure”——被拉伸的布局而非被重构的布局，是手机 UI 上平板的第一失败模式；
• 手势/控件不存在——例如依赖 iOS 边缘滑动返回，但目标平台只有 Predictive Back；或 Web 时代的 hover 交互在触控端没有对应物。

三、四类适配策略

3.1 手机 → 平板（iPad / 大屏）

文档给出的四条策略，核心词是Restructure, don't stretch（重构，而非拉伸）：

• 用 size class 切换结构：iOS 使用 size classes，Android 使用 window size classes 来驱动结构变化，而不是判断设备型号。
• 导航改变形态：iPad 上 Tab bar 可以保留，也可以变成侧边栏（sidebar）；Android 的 navigation bar 在扩展宽度（expanded width）下变为 rail（导航栏）或 drawer（抽屉）。这一要求与 android.md 中 “Navigation bar (bottom, 3–5 destinations) on compact width; navigation rail or drawer on expanded width” 的规则互相印证。
• 利用宽度：split view / master-detail（列表+详情并排）、多列网格；手机上用 sheet（半屏弹层）的场景，在平板上改用 popover。
• 多任务是尺寸问题，不是边界情况：iPad Split View 和 Android multi-window 随时可能把一个手机宽度的窗口交到你手上——只要布局由 size class 驱动，这两种情况“for free”地被同时处理。

3.2 屏幕方向与折叠屏

• 横屏要重构而非裁剪：并排面板（side-by-side panes）、控件重新定位；“never clip or letterbox”——绝不允许裁剪内容或留黑边。
• 锁定方向是高门槛操作：只有任务真正需要时才锁定方向（后文红线清单中再次出现：不得用锁方向来逃避布局 bug）。
• 折叠屏（Android）：通过 window size classes 对 posture（形态）与 hinge（铰链状态）做出反应；测试时必须覆盖folded（折叠态）、unfolded（展开态）、tabletop（桌面半开态）三种姿态。

3.3 平台 → 平台（iOS ↔ Android）：翻译惯用法，绝不移植

原文给出了一句总纲：“Translate idioms; never transplant them”（翻译惯用法，绝不整株移植）。对照表完整如下：

这张表里的每一项都能在两份平台参考文档中找到对应条款，例如：

• “SF Symbols, SF Pro, Dynamic Type” ↔ ios.md 的“SF Symbols 图标、San Francisco 承载 UI、Dynamic Type 系统文本样式，禁止硬编码字号（11 pt 下限、Body 17 pt）”；
• “Material Symbols, Roboto, sp scaling” ↔ android.md 的“Roboto 为系统字体、sp 单位而非固定 px”；
• “Semantic system colors, materials” ↔ ios.md 的“语义系统色自动适配 Dark Mode 与高对比度，raw hex 在那里会失效”；“Material color roles, tonal elevation” ↔ android.md 的“角色 token 自动解析亮/暗主题，禁用任意 drop shadow”。
• 动效一行也直接对应 android.md 的 “Material motion patterns: Container transform, shared-axis, fade-through, with standard easing and durations”。

跨平台时品牌如何处理？文档的答案是：在目标平台自己的词汇表里重建导航与控件，品牌只迁移表达层（expressive layer）——配色的意图（palette intent）、字体的强调（type accent）、动效的性格（motion personality），并且必须通过目标平台的主题系统（target's theming system）去落地。这与 android.md 的 “brand expresses through Material's theming (color roles, type scale, shape, motion)” 以及 ios.md 的 “brand expresses through the layer the platform leaves open (tint, type, motion, content)” 完全一致：品牌走主题通道，结构与交互让位给平台规则。

3.4 Web → Native（移植网站或 Web 应用）

策略词是Reconform, don't reflow（重新塑形，而非重排）。四步替换：

1. Web 导航 → 平台的导航模型；
2. HTML 形态的控件 → 平台原生控件；
3. hover 交互 → 触控优先的交互；
4. px 字号 → Dynamic Type（iOS）/ sp（Android）。

之后的验收标准被直接锚定到平台参考文档：把移植结果当作全新的原生项目，完整套用对应平台参考（ios.md 或 android.md），并且——“the slop test there is the acceptance bar”——该平台的 slop test（“像不像套皮移植”的检测）就是验收线。ios.md 的 slop test 是“熟练 iPhone 用户是否会信任这个 App，还是会在不符合规范的控件前停顿”，其典型破绽正是 “reinvented navigation bars, custom back gestures, web-shaped buttons, hover-dependent affordances”——这恰好就是 Web 移植最容易踩中的全部四类坑。

四、实现与验证：size class 驱动、安全区、双端真机

4.1 三条实现铁律

文档的 Implement & Verify 一节给出三条硬性要求：

1. 结构由 size classes / window size classes 驱动，永远不要做设备型号判断（never from device-model checks）。这是整篇文档最重要的工程决策：只有 size class 才能同时覆盖旋转、Split View、多窗口、折叠屏展开/折叠等一切“同一设备的不同窗口形态”。
2. 每一种新配置下都尊重 safe areas 与 window insets：刘海（notch）、铰链（hinge）、状态栏、键盘。对应 ios.md 的 “Lay out inside the safe-area insets. No controls under the notch, Dynamic Island, home indicator, or rounded corners” 与 android.md 的 “Edge-to-edge with window insets... content never hides behind system bars or the keyboard”。
3. 测试策略是“模拟器管广度，真机管真相”（simulators for breadth, real hardware for truth）：每个已发布的平台至少一台手机 + 一台平板，两个方向，支持分屏就测分屏。

4.2 验证的具体手段（来自平台参考的补充）

adapt.native.md 本身只规定“测什么”，而“怎么采证”由两份平台参考给出可直接执行的命令，适配完成后应按目标平台执行：

• iOS（ios.md “Verifying the build”）：截图必须来自 Simulator 而非浏览器，xcrun simctl io booted screenshot <path>（多台模拟器运行中时用xcrun simctl list devices booted拿 UDID 替换booted）；Dark Mode 与 Dynamic Type 必须纳入本轮验证——xcrun simctl ui booted appearance dark切换外观，再用大号 Dynamic Type 检查固定布局藏住的截断。
• Android（android.md “Verifying the build”）：截图来自模拟器或连接设备，adb exec-out screencap -p > <path>（多设备时加adb -s <serial>）；暗色主题与字体缩放必须验证——adb shell cmd uimode night yes切主题，adb shell settings put system font_scale 1.3（验证后恢复1.0）抓出固定布局藏住的标签截断。

两份文档还有一条共同的“硬件诚实性”条款：模拟器/仿真器提供广度，但姿态（posture）、手势、刷新率与性能必须靠真机确认——“Say which one produced the evidence”（说明证据由谁产生）。这也正是 adapt.native.md 红线“Trust simulators alone”的具体含义：折叠屏姿态、边缘滑动/预测返回手势、性能表现，模拟器都替代不了。

4.3 收尾：交接给 polish

当适配在每个上下文中都“feels native”时，文档指定了下一步：交接给polish命令做最终一轮。polish.md 明确其职责边界：“Polish is refinement, never concealed redesign”，并要求在原生平台上“the shipped device classes on the simulator, emulator, or hardware, captured per the platform reference's Verifying the build section”——即适配阶段建立的“多设备类 × 双方向 × 分屏”证据基线，正是 polish 收集证据时的既定要求。

五、红线清单：五条 NEVER

原文档以加粗 NEVER 收尾，这五条是整篇方法论的负面边界，建议在团队评审时逐条对照：

1. 不得把拉伸的手机布局直接上平板；
2. 不得把一个平台的控件或导航移植到另一个平台；
3. 不得在小设备上隐藏核心功能（“if it matters, make it work”）；
4. 不得用锁定屏幕方向来逃避布局 bug；
5. 不得只信任模拟器（姿态、手势与性能需要真机）。

前三条对应三类最常见的交付事故（假适配、套皮移植、功能阉割），后两条对应两类过程事故（用锁屏掩盖横屏问题、用模拟器截图冒充完整验证）。

六、适用范围与限制

• 本文适用前提是项目已被 Impeccable 识别为原生平台（ios/android/adaptive），Setup 阶段由context.mjs载入平台参考；Web 项目的适配应走 adapt.md（其中含 Web 侧完整的断点、clamp()、pointer/hover 查询、safe-areaenv()等实操参考）。
• adapt.native.md 本身是方法论与验收标准文档，不含可执行脚本；其命令入口是adapt [target]（参数提示[target] [context (mobile, tablet, print...)]，见 command-metadata.json），截图与主题切换的具体命令则沉淀在 ios.md 与 android.md 的 “Verifying the build” 小节。
• 参考文档中的 ios.md / android.md 内部链接在仓库中的真实位置分别是 skill/reference/ios.md 与 skill/reference/android.md；本技能在仓库中同时存在于源目录 skill/reference/ 与插件打包目录 plugin/skills/impeccable/reference/，两者内容一致。

核心结论：Impeccable 的原生适配流程把“适配”从像素问题重新定义为结构问题——先用“源/目标/破坏点”三问定位挑战，再按四类迁移路径（设备类、方向/折叠、跨平台、跨形态）选择重构策略，最终以 size class 驱动结构、safe area 兜底布局、双端真机采证，并以平台 slop test 作为验收线。这套流程的最大价值在于给出了一条可审计的决策链：每一步“为什么这样改”都能回溯到平台参考文档中的具体条款。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable