Ionic Framework Design#

When to Use#

TRIGGER when:

• Writing or reviewing Ion* / ion-* components in a Capacitor app
• Theming: --ion-color-*, dark mode, high contrast, per-platform styles
• iOS vs Material Design mode looks wrong, or mode overrides misbehave
• Upgrading Ionic 7/8 -> 9, or errors after npm i @ionic/*@latest
• Choosing Ionic vs another UI kit for a new Capacitor app

Do not use:

• Konsta UI components: konsta-ui
• Tailwind v4 install / config: tailwind-capacitor
• Notch / system bar padding outside Ionic: safe-area-handling
• Keyboard covering inputs: capacitor-keyboard (Ionic apps use resize: 'ionic')
• Leaving Appflow / Ionic Enterprise plugins: ionic-appflow-migration, ionic-enterprise-sdk-migration

Versions (October 2026)#

Check installed versions first: npm ls @ionic/core @ionic/react @ionic/vue @ionic/angular. Write code for the installed major; do not mix v8 and v9 APIs.

Workflow#

1. Inspect framework, Ionic major, router version, global CSS imports, setupIonicReact / IonicVue / provideIonicAngular config, capacitor.config Keyboard.resize.
2. Upgrading? Load references/ionic-9-migration.md; run npx @ionic/migrate in preview first, report findings, then apply.
3. Components: references/components.md for page shell, lists, forms, overlays, tabs.
4. Theming: references/theming.md for colors, dark/high-contrast palettes, mode-specific CSS, shadow parts.
5. Verify in both modes and on devices (below).

Only load a reference when its topic is in play.

Rules that prevent most Ionic bugs#

• Every routed page = IonPage > IonHeader + IonContent (+ optional IonFooter). Missing IonPage breaks transitions and lifecycle hooks.
• Scroll lives in ion-content. Do not make body or a wrapper div scroll; use IonContent scrollToTop()/getScrollElement().
• Use ion-router-outlet (IonRouterOutlet, IonTabs) for URL routing. In Ionic 9 ion-nav no longer integrates with ion-router; keep it for local URL-less stacks inside a page.
• Safe areas are handled through --ion-safe-area-top|right|bottom|left (default env()); do not add body padding on top. Requires viewport-fit=cover.
• Forms: put label + labelPlacement on the control itself (<IonInput label="Email" labelPlacement="floating" />). Legacy <IonItem><IonLabel/><IonInput/></IonItem> labeling was removed in Ionic 8.
• Overlays: prefer inline <IonModal isOpen> / trigger or hooks (useIonModal, modalController) consistently; always handle didDismiss to reset state.
• Platform: style via .ios / .md classes on html or mode CSS selectors; use isPlatform('ios') only for behavior, never navigator.userAgent.
• Icons: import only used icons (import { heart } from 'ionicons/icons') and pass icon={heart}; string names need addIcons registration in standalone/bundled builds.

Verification#

1. Build and sync: npm run build && npx cap sync.
2. Run both modes in the browser: append ?ionic:mode=ios and ?ionic:mode=md to the dev URL; check headers, toolbars, lists, buttons.
3. Toggle OS dark mode (or add ion-palette-dark to <html> if using the class palette); check contrast of custom colors.
4. Device check: iPhone with Dynamic Island + Android 15/16 gesture nav for header/tab bar insets; open keyboard on a form page.
5. After upgrade: grep -rn "ion-picker-legacy\|pickerController\|useIonPicker\|@ionic/angular/standalone\|autocorrect=\"off\"" src/ returns nothing; npx tsc --noEmit passes.

Error Handling#

Resources#

• Ionic docs: https://ionicframework.com/docs
• Ionic 9 breaking changes: https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md
• Theming: https://ionicframework.com/docs/theming/basics
• Dark mode: https://ionicframework.com/docs/theming/dark-mode