用途：在 Capacitor 应用中编写或审查 Ion*/ion-* 组件，处理主题（--ion-color-*、深色模式、高对比度、按平台样式）、平台模式显示异常、Ionic 7/8 升级到 9 后的报错，以及为新 Capacitor 应用选择 UI 套件。不适用于 Konsta UI、Tailwind v4 配置、非 Ionic 的安全区处理、键盘遮挡（Ionic 用 resize: 'ionic'）及 Appflow/企业插件迁移。
版本：@ionic/core、@ionic/react、@ionic/vue、@ionic/angular 当前 9.x，8.x 在 v8-lts 标签；ionicons 8.x。Ionic 9 最低要求 Capacitor 7+、iOS 16+、Android Chromium 89+、Angular 18-22、React 18/19 与 React Router 6.4+、Vue 3.5 与 vue-router 5、TypeScript 5.4+。先用 npm ls @ionic/core @ionic/react @ionic/vue @ionic/angular 查看已装版本，按已装主版本写代码，勿混用 v8 与 v9 API。
关键规则：每个路由页面为 IonPage > IonHeader + IonContent（可选 IonFooter），缺失 IonPage 会破坏转场与生命周期；滚动在 ion-content，勿让 body 或包装 div 滚动，用 scrollToTop()/getScrollElement()；URL 路由用 ion-router-outlet（IonRouterOutlet、IonTabs），Ionic 9 中 ion-nav 不再与 ion-router 集成，仅用于页内无 URL 栈；安全区通过 --ion-safe-area-* 处理，勿给 body 加 padding，需 viewport-fit=cover；表单把 label 与 labelPlacement 放在控件上，旧式 IonItem+IonLabel 标注在 Ionic 8 已移除；弹层统一用内联 IonModal isOpen/trigger 或 useIonModal、modalController，并处理 didDismiss；平台样式用 .ios/.md 类或 mode 选择器，行为判断用 isPlatform('ios')；图标按需导入并注册。
验证：npm run build && npx cap sync；浏览器分别加 ?ionic:mode=ios 与 ?ionic:mode=md 检查；切换系统深色模式或加 ion-palette-dark 检查对比度；在带灵动岛 iPhone 与 Android 手势导航设备检查内边距并打开表单键盘；升级后用 grep 检查遗留 API，npx tsc --noEmit 通过。
常见错误含 @ionic/core 深层导入、@ionic/angular/standalone 导入、React Router 6 的 element/Navigate/useNavigate、autocorrect="off"、ionChange 仅值变化触发、Sheet modal handleBehavior 默认 cycle、未导入核心 CSS 或深色调色板、Angular 21 无 Zone 更新等，资料给出对应修法。