Impeccable 原生适配指南用 size class 重构而非缩放把 iOS / Android 设计带到新上下文【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable原生界面适配native adaptation是 Impeccable 设计技能skill中adapt命令的一个专门分支把一个已经成形的原生native设计——ios/android/adaptive平台——带到另一种设备类别、方向、平台或来源中去。它在 .opencode/skills/impeccable/reference/adapt.native.md 中定义适用于 SwiftUI / UIKit、Jetpack Compose / Android Views、React Native、Expo、Flutter 等所有真实原生工程。本文将从评估适配挑战出发展开手机→平板、方向与折叠屏、iOS↔Android 跨平台、Web→原生四条策略主线并结合仓库中的平台基准、Slop 测试与验证流程说明为什么适配的本质是为新上下文重新思考体验而不是缩放像素并给出可以直接落地的实施与验收方法。何时会用到这份原生适配参考在 Impeccable 的目录结构里adapt命令有两条参考路线Web 项目含移动端网页走 .opencode/skills/impeccable/reference/adapt.md而原生平台一律路由到adapt.native.md。在 .opencode/skills/impeccable/reference/adapt.md 开头就有明确分流说明Native platformsios/android/adaptiveroute to adapt.native.md instead; if the project is native, switch to it now.平台身份ios/android/adaptive在会话 Setup 阶段由context.mjs判定并写入setup.platform。.opencode/skills/impeccable/reference/routing.md 同时提醒live与detect.mjs这类浏览器态工具只属于 Web当setup.platform是ios/android/adaptive时不应使用——因为浏览器叠加层与 HTML 规则引擎对原生代码不生效。这正说明原生适配必须回到平台自身的参考体系HIG / Material 3来评估而不是套用网页响应式的做法。典型触发场景包括产品从 iPhone 拓展到 iPad、新增折叠屏支持、把 iOS 设计移植到 Android或反过来、把一个能跑的网页重做成原生应用。执行前通常还需要一次性的额外上下文澄清目标平台/设备与具体使用场景即文档顶部的Additional context needed因为它直接决定后续所有策略选择。评估适配挑战先问三个问题动手改代码之前先把为什么要适配讲清楚。参考文档给出了一个三段式评估框架源上下文Source context它当初是为谁设计的隐含了哪些假设仅手机仅竖屏只遵循某一平台的惯用法还是一个网站目标上下文Target context目标设备类别手机 / 平板 / 折叠屏、方向、平台以及使用姿态——单手行走途中使用还是双手安坐时使用哪些会坏What breaks放不进目标的导航被拉伸而不是被重构的布局在该平台上根本不存在的手势或控件评估时最需要警惕的思维陷阱是全文档反复强调的一句判断The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.陷阱是把适配当成缩放工作是为新上下文重新思考体验。无论是网页参考还是原生参考都沿用了这一原则这也解释了为什么整套策略都以重构结构、替换隐喻为基调。策略一手机 → 平板iPad / 大屏平板上最典型的失败形态是放大的手机 UI。原生参考给出的对策是重构而不是拉伸Restructure, dont stretch。iOS 用size classesAndroid 用window size classes来切换结构而不是按设备型号硬编码分支。导航改变形态iPhone 的 tab bar 到 iPad 可以升级为 sidebar侧边栏Android 的底部导航栏在展开宽度下应变成 rail 或 drawer。这与 android.md 中Navigation bar (bottom, 3–5 destinations) on compact width; navigation rail or drawer on expanded width. Never ship a phone bottom-bar untouched on a tablet的规则一一对应。用足宽度split view / master-detail列表详情并排、多列网格、用 popover 替代手机上的 sheet。把多任务当成一种尺寸而不是边界情况iPad Split View 与 Android 多窗口完全可能在平板上给你一个手机宽度的窗口。只要布局由 size class 驱动这两种窗口尺寸就会被免费正确处理无需专门的特判代码。策略二方向与折叠屏横屏要做结构重构并排窗格、重新布局控件永远不要裁剪或信箱化letterbox画面。只有任务确实需要时才锁定方向——用锁定方向来掩盖布局缺陷属于文档明令禁止的行为见后文 NEVER 清单。折叠屏Android要感知姿态posture与铰链hinge通过 window size classes 响应状态变化并分别测试折叠folded、展开unfolded与桌面模式tabletop三种状态。策略三iOS ↔ Android 平台间移植跨平台时的方法是翻译惯用法translate idioms而不是移植控件transplant。参考文档给出了一张实用的对照表iOSAndroidTab barNavigation bar / rail / drawerEdge-swipe back、back chevronPredictive Back 手势 / 返回按钮Switch、segmented control、系统 pickerMaterial switch、chips、Material pickerAction sheetBottom sheet / Material dialogSF Symbols、SF Pro、Dynamic TypeMaterial Symbols、Roboto、sp 缩放语义化系统颜色、材质materialsMaterial color roles、tonal elevation系统 push/sheet 转场Container transform、shared-axis、fade-through执行要点是用目标平台的词汇重建导航与控件同时把品牌表达层brands expressive layer——调色板意图、字体点缀、动效个性——通过目标平台的主题系统继承过去。也就是说被翻译掉的是平台外壳被保留的是品牌内核。两份平台基准文件为这张表提供了更细的支撑ios.md 要求遵循 HIG语义化系统颜色label、secondaryLabel、systemBackground、separator、tint在深色模式与高对比度下自动适配raw hex breaks thereSF Symbols 要基线对齐、感知 Dynamic Typeedge-swipe back 是肌肉记忆绝不关闭或覆盖系统转场push 滑动、sheet 升起不得被自造转场对抗。android.md 要求 Material Design 3 作为规则手册Material color roles 的角色 token 自动解析明暗与对比度变体Dynamic ColorMaterial You在 Android 12 上可从壁纸推导配色、并保留静态回退方案sp 单位、非 px让字号跟随系统字体设置同一文件还特别提醒——An iOS app wearing Androids skin套着 Android 皮肤的 iOS 应用是 Android Slop 最常见的症状。双端约束的交叉项也值得注意即使是Material everywhere的跨平台应用只要同时发往 iPhone就仍须在 Apple 硬件上兑现 iOS 的系统保障——安全区 insets、Reduce Motion、edge-swipe back。策略四Web → 原生把网站移植成应用原生参考对移植网站给出的要求是重新符合规范reconform而不是重新排版reflow用平台自身的导航模型替换网页导航用平台控件替换 HTML 形态的控件把悬停hover暗示改成touch-first的交互把px 字号换成 Dynamic Type / sp。完成后要整套走一遍平台参考全文——其中slop test低质量原生判断测试详见下节就是验收及格线。换句话说网页移植过来不算完成直到它在每个平台上读起来像原生。原生 Slop test判断是否像原生ios.md 与 android.md 各定义了自己的 Slop test它们正是 Web→原生移植乃至一切原生适配的验收标准iOS 版Would a fluent iPhone user trust this app, or pause at off-spec controls? 最典型的破绽是从网站移植来的痕迹——自造导航栏、自定义返回手势、网页形状的按钮、依赖 hover 的暗示。Android 版Would a fluent Android user trust this app, or trip on off-spec components? 最常见的是套着 Android 皮肤的 iOS 应用——照搬 iPhone 的纯底部导航、无视系统 Back 手势的返回箭头、Cupertino 造型的开关与对话框。Impeccable 甚至把越界的系统漂移纳入了原生技术审计维度audit.native.md 的 Platform Conformance 维度会专门核查 broken system gestures、inset violations、off-platform navigation、web-shaped controls、icon drift、system drift——因此一次/impeccable adapt之后用/impeccable auditnative 变体复检就能用结构化评分确认适配是否真正落地。实施与验证从 size class 到真机证据用 size class 驱动结构永远不做设备型号检查原生参考明确规定结构必须由 size classesiOS/ window size classesAndroid驱动绝不依赖 device-model 检查例如按具体机型字符串判断。理由很直接适配要在任意未来窗口尺寸下都成立设备清单永远是不完整、不可移植的特判。每个新形态都要处理安全区与窗口 insetsnotch、Dynamic Island、铰链hinge、状态栏、键盘IME——任何新增的配置形态都必须遵守安全区safe area与窗口 insets。ios.md 与 android.md 都把它列为布局第一原则iOS 上no controls under the notch, Dynamic Island, home indicator, or rounded cornersAndroid 上要 edge-to-edge 应用 status bar、navigation bar、display cutout 与 IME insets使内容永远不被系统栏或键盘遮挡。先模拟器取广度再真机取真相验证路径分两层每个发布平台至少测一台手机 一台平板两种方向都要覆盖支持分屏的平台上要测分屏在支持的平台上测新配置的全部安全区/insets 场景。具体取证方式应遵循各平台基准的 Verifying the build 章节iOS截图只能来自 Simulator不能用浏览器。用xcrun simctl io booted screenshot path抓取多台运行时用 UDID 替换booted用xcrun simctl ui booted appearance dark切换深色外观并在大号 Dynamic Type 下复查截断。Android截图来自 emulator 或真机用adb exec-out screencap -p path多设备用adb -s serialadb shell cmd uimode night yes切换深色主题adb shell settings put system font_scale 1.3用后还原1.0检验大字体的裁切问题。两份基准给出了同一句忠告Simulators give breadth; posture, gestures, and performance need hardware.模拟器负责覆盖面而姿态、手势与性能必须上真机并且要在交付证据时说明这份证据来自模拟器还是硬件。收尾交接当每个上下文下的适配都感觉是原生之后把结果交给/impeccable polish做最后一轮打磨。这里的语义是adapt负责把结构、导航与控件改造成原生形态polish再在不偷换设计、只收尾质量的约束下做最终一致性处理详见 .opencode/skills/impeccable/reference/polish.md。NEVER原生适配的绝对禁区参考文档以一组禁令收尾这同时也是适配完成度的自检清单绝不在平板上交付一个被拉伸的手机布局Ship a stretched phone layout on a tablet绝不把一个平台的控件或导航移植到另一个平台Port one platforms controls or navigation onto the other绝不在小设备上隐藏核心功能——如果它重要就让它可用Hide core functionality on smaller devices绝不为了回避布局缺陷而锁定方向Lock orientation to dodge a layout bug绝不只信模拟器——姿态、手势与性能必须经真机验证Trust simulators alone。小结把原生感当作适配成功的判据回顾整套方法可以归纳为一条可执行的主线评估时问清源上下文假设了什么、目标上下文需要什么、什么会坏掉实施时用 size class 重构结构、用目标平台词汇重建导航与控件、把品牌层通过主题系统带过去验证时先模拟器铺广度、再真机取真相并以平台 Slop test 作为验收及格线。如果你手头正是一个ios/android/adaptive工程需要跨设备、跨方向或跨平台改造直接以 adapt.native.md 为行动底稿配合 ios.md 与 android.md 两份平台基准共同执行即可改造完成后用/impeccable polish收尾用原生变体的/impeccable audit见 audit.native.md复查 Platform Conformance 与 Adaptivity 评分就能形成适配—审计—打磨的完整闭环。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考