Mobile UI skills for Ionic, Konsta UI, Tailwind, safe-area handling, and iPad/foldable resizability in Capacitor apps.

version
1.1.0
GitHub stars
79

Install

/plugin install capacitor-ui@capgo-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Cap-go/capgo-skills.

Contents

Discovered from source

Skills 5

Resizable Windows for Capacitor iOS Apps

A Capacitor app is a full-window WKWebView in CAPBridgeViewController. The web view follows its window. The work is to make the web layout respond to width changes, and to remove native code (app, custom code, plugins) that assumes one full-screen window.

When to Use

TRIGGER when:

  • Preparing an app for iPad multitasking, Stage Manager, windowed iPad apps, the foldable iPhone, or external displays
  • The layout breaks or does not update when the window is resized
  • A native overlay from a plugin (scanner, camera preview, custom sheet) is the wrong size or position in split view
  • Xcode or App Store Connect warns about UIRequiresFullScreen, missing iPad orientations, or launch screen requirements
  • The user asks to remove UIScreen.main, userInterfaceIdiom, interfaceOrientation or AppDelegate lifecycle use

Do not use:

  • CSS env(safe-area-inset-*) setup and notch padding only: safe-area-handling
  • Moving AppDelegate to SceneDelegate: capacitor-uiscene-migration (prerequisite for Xcode 27)
  • Keyboard overlap: capacitor-keyboard
  • Tailwind breakpoints only: tailwind-capacitor

Facts that drive the plan

  • iOS 27 ignores UIRequiresFullScreen and resizes the scene anyway (TN3192). Never delete the key silently: deleting it makes the app resizable at once on current iOS. Never add UIRequiresFullScreenIgnoredStartingWithVersion on your own: its value decides which releases keep the old behavior. Both are the user's call, after testing.
  • The iOS 27 SDK requires a launch screen declaration. Without one the upload is rejected with ITMS-90870. Capacitor templates set UILaunchStoryboardName; keep it.
  • Xcode 27 requires the scene lifecycle. Capacitor 8.5 templates ship SceneDelegate.swift. Without it, AppDelegate lifecycle methods are the only signal, which is wrong in multi-window. Run capacitor-uiscene-migration first if UIApplicationSceneManifest is missing.
  • Keep UIApplicationSupportsMultipleScenes = false. Each scene would create its own CAPBridgeViewController, with a second WebView and plugin set. Capacitor added scene-scoped notifications in 8.5 so plugins can prepare, but multi-window is not supported in the templates. Resizing works with a single scene.
  • CAPBridgeViewController builds supportedInterfaceOrientations from the iPhone key UISupportedInterfaceOrientations only, not from UISupportedInterfaceOrientations~ipad (Capacitor 8.5 source). An iPad that declares all four orientations can still be locked by the bridge mask. Report it; override supportedInterfaceOrientations in a bridge subclass only if the user wants different iPad behavior.
  • The web layer gets resize events for free. WKWebView resizes with the window and fires resize. Breakage comes from layout code that reads the device instead of the viewport.
  • Plugins are third-party code. Edits to node_modules are lost on install. Report plugin findings, upgrade the plugin, open an issue upstream, or use patch-package only as a stopgap, with user approval.

References

Only load a reference when its topic is in play.

FileLoad when
references/info-plist-and-scenes.mdChecking Info.plist keys, orientation masks, scene lifecycle and the AppDelegate methods that stop firing
references/web-layer.mdAuditing and fixing CSS/JS layout: viewport, units, device sniffing, safe areas that change at runtime
references/native-replacements.mdReplacing UIScreen.main, orientation, idiom, key window, lifecycle and hard-coded insets in Swift/ObjC
references/plugin-audit.mdScanning plugins in node_modules, triage, and what plugin authors should change
references/swiftui-in-plugins.mdA plugin or app presents native SwiftUI screens that must resize; iOS 27 SDK SwiftUI changes

Script: scripts/scan-legacy-apis.sh scans ios/App/App and every node_modules/**/ios folder and prints the resize-related Info.plist keys. Read-only.

Workflow

1. Prerequisites (read-only)

Read ios/App/App/Info.plist, AppDelegate.swift, SceneDelegate.swift, the @capacitor/ios version, and the TARGETED_DEVICE_FAMILY build setting (1,2 = iPhone and iPad). Report:

CheckOK whenOtherwise
Launch screenUILaunchStoryboardName or UILaunchScreen presentReport ITMS-90870 risk
Scene lifecycleUIApplicationSceneManifest present, SceneDelegate.swift in the targetSend to capacitor-uiscene-migration first
iPad orientationsUISupportedInterfaceOrientations~ipad lists all four, or no iPad keyName the missing ones. Mention the bridge mask fact above
Full-screen opt-outUIRequiresFullScreen absentReport that iOS 27 ignores it. Ask the user before changing it

2. Scan

bash <skill>/scripts/scan-legacy-apis.sh .

Also scan the web code (references/web-layer.md):

grep -rnE 'screen\.(width|height|availWidth)|window\.orientation|orientationchange|\b100vh\b|navigator\.userAgent.*(iPad|iPhone)|isPlatform\(.(ipad|tablet|iphone)|innerWidth' src --include='*.{ts,tsx,js,jsx,vue,svelte,css,scss}'

Make a TODO list with one entry per file. Large projects: process files in batches of 3 to 5. Every file in the list gets a change or a written reason for no change.

3. Report, then ask

Group the findings into: app web code, app native code, plugins (by package), Info.plist. For each, state the fix. Ask the user before:

  • changing UIRequiresFullScreen, orientation keys or the orientation mask,
  • changing a public method signature in shared native code,
  • patching a plugin in node_modules.

4. Fix

  • Web layer first. It is usually the whole fix: references/web-layer.md.
  • App native code: references/native-replacements.md. Only edit lines that contain the target API. Keep every if/else branch and #available guard. Never replace a dynamic value with a literal, and never replace one global (UIScreen.main) with another (UIApplication.shared, UITraitCollection.current, UIDevice.current).
  • Empty template stubs (applicationDidBecomeActive and friends with only comments) are harmless. Move them only if they contain code.
  • Plugins: references/plugin-audit.md.

5. Verify

npx cap sync ios
xcrun simctl list devices available | grep -i ipad
npx cap run ios --target <iPad-simulator-UDID>
  • On the iPad simulator (iPadOS 26+), switch the app to a window and drag its corner. Check narrow, medium and wide sizes. Also try Split View with another app.
  • Rotate during each size. Open and close the keyboard in a narrow window.
  • Check native overlays from plugins (scanner, camera preview, pickers) at a narrow width.
  • Background and foreground the app. JS pause / resume must fire.
  • If Xcode offers a foldable iPhone simulator, test fold and unfold the same way.
  • Re-run the scan. Remaining hits must each have a written reason (non-layout use such as camera capture orientation or analytics).

Error Handling

SymptomCauseFix
Layout stuck at the old size after resizeJS cached window.innerWidth / screen.width at startup, or CSS uses 100vhRead sizes on resize or use CSS; replace 100vh with 100dvh
Content under the status bar or home indicator only in some window sizesSafe-area insets were read once, or a side inset was mirrored to both sidesUse env(safe-area-inset-*) per edge in CSS; never cache them in JS
Plugin overlay covers the wrong area in split viewPlugin sizes its view from UIScreen.main.boundsUpdate the plugin, or report upstream with the scan line
App launches but is not resizable on iOS 26UIRequiresFullScreen = trueExpected until the user removes it after testing
Upload rejected with ITMS-90870No launch screen keyRestore UILaunchStoryboardName with LaunchScreen.storyboard
pause / resume stop firing after adding SceneDelegateCustom code in AppDelegate lifecycle methodsMove it to scene methods or observe notifications (references/info-plist-and-scenes.md)

Related Skills

  • safe-area-handling: CSS env() variables and the status bar overlay
  • capacitor-uiscene-migration: SceneDelegate adoption, the prerequisite for scene-aware fixes
  • tailwind-capacitor: responsive breakpoints in Tailwind
  • capacitor-testing: simulator and device verification loop
  • capacitor-plugin-upgrade-v8-to-v9: when a plugin fix needs a new major version

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)

PackageCurrentNotes
@ionic/core, @ionic/react, @ionic/vue, @ionic/angular9.x (latest)8.x on v8-lts tag
ionicons8.x
Ionic 9 minimumsCapacitor 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+

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

Use the selected project and its installed dependencies. Package installation and migration tools execute code; limit them to the requested setup or upgrade, preserve the lockfile and existing changes, and review generated edits before running changed build scripts.

  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

Error / symptomCauseFix
Package path ./dist/... is not exported from package (webpack) / ERR_PACKAGE_PATH_NOT_EXPORTED (Node) for @ionic/coreIonic 9 exports map; deep importImport from @ionic/core, @ionic/core/components, @ionic/core/components/ion-*.js, @ionic/core/loader, @ionic/core/css/*.css
Import errors or migrate warnings for @ionic/angular/standalone (Ionic 9)Standalone imports movedImport from @ionic/angular; lazy APIs from @ionic/angular/lazy
React: Property 'component' does not exist on Route / IonRouteIonic 9 requires React Router 6element={<Page />}, Navigate instead of Redirect, useNavigate instead of useHistory
Autocorrect turned ON after upgradeautocorrect="off" string is truthy in Ionic 9Remove the attribute or bind false
ionChange no longer fires on re-selecting same optionIonic 9 fires only on value changeUse ionDismiss for dismissal
Sheet modal handle now focusable / cycles breakpointsIonic 9 handleBehavior default cyclehandle-behavior="none" to restore
Styles missing, components unstyledCore CSS not importedImport @ionic/<fw>/css/core.css (+ structure/typography) once at entry
Dark mode never activatesNo palette importedImport css/palettes/dark.system.css (or .class.css + ion-palette-dark class)
Angular 21 view not updating after async workZoneless default in Ionic 9 + Angular 21Use signals / markForCheck(), or add provideZoneChangeDetection()

Resources

Konsta UI for Capacitor

When to Use

TRIGGER when:

  • Adding Konsta UI to a Capacitor app or choosing it over Ionic
  • Upgrading Konsta v3/v4 (Tailwind v3 konstaConfig) to v5 (Tailwind v4)
  • Components unstyled, colors ignored, ios:/material: classes do nothing
  • Navbar / Tabbar under the status bar or gesture bar
  • Theme should follow platform (ios on iPhone, material on Android)

Do not use:

  • Ionic Framework components or theming: ionic-design
  • Tailwind install/config without Konsta: tailwind-capacitor
  • Android SystemBars / edge-to-edge native config: safe-area-handling
  • Keyboard overlap in forms: capacitor-keyboard

Versions (October 2026)

KonstaTailwindFrameworksConfig style
5.x (latest, 5.5.0)v4React 19 (ref as prop), Vue 3, Svelte 5 (runes, snippets)CSS: @import 'konsta/<fw>/theme.css' + @theme
4.xv3adds Svelte 5 typesJS: konstaConfig() in tailwind.config.js
3.x and belowv3JS konstaConfig()

Check first: npm ls konsta tailwindcss react vue svelte. Never mix v5 CSS setup with a tailwind.config.js konstaConfig wrapper.

Workflow

  1. Inspect versions, main CSS file, tailwind.config.*, postcss.config.*, vite.config.*, index.html viewport meta, whether Ionic is also present.
  2. Install / upgrade (below). For an existing Tailwind v3 project, migrate Tailwind first (tailwind-capacitor).
  3. Wrap the app in App (or KonstaProvider with Ionic/Framework7).
  4. Build screens with components: references/components.md.
  5. Verify (below).

Only load a reference when its topic is in play.

Setup (v5, React shown; Vue/Svelte use konsta/vue/theme.css / konsta/svelte/theme.css)

npm i konsta tailwindcss @tailwindcss/vite
// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [react(), tailwindcss()] });
/* src/index.css */
@import 'tailwindcss';
@import 'konsta/react/theme.css';

@theme {
  --color-brand-primary: #007aff; /* only --color-brand-* drive component colors */
  --color-brand-red: #ff3b30;     /* use with class k-color-brand-red */
}
import { Capacitor } from '@capacitor/core';
import { App } from 'konsta/react';

const theme = Capacitor.getPlatform() === 'android' ? 'material' : 'ios';

export default function Root() {
  return (
    <App theme={theme} safeAreas>
      {/* pages */}
    </App>
  );
}
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

App props: theme ('ios' | 'material' | 'parent', default material), safeAreas (default true), dark, iosHoverHighlight, materialTouchRipple (global switches added in v5). Only one App per app.

Material Roboto font: add it yourself (Google Fonts link or self-hosted for offline). iOS uses the system font.

Migrating v4 -> v5

v4v5
tailwind.config.js: module.exports = konstaConfig({...})Delete wrapper; @import 'konsta/react/theme.css' in CSS
konstaConfig.colors.primary@theme { --color-brand-primary: ... }
Per-component ripple configPrefer the global App materialTouchRipple; check component types in your installed version
SegmentedButton strong roundedRemoved; use Segmented theme-specific style props
Link navbar/toolbar/tabbar propsRemoved; context-driven
React forwardRef usage / innerRef patternsref prop (React 19)
Svelte slots{#snippet ...}

Then run the Tailwind v4 upgrade (npx @tailwindcss/upgrade) if Tailwind itself is still v3; see tailwind-capacitor.

Traps

  • With Ionic in the same app, use KonstaProvider (not App) and pick one owner for safe areas (Ionic's --ion-safe-area-* or Konsta's safe-areas), not both.
  • Dark mode in Konsta v5 is class-based (@custom-variant dark (&:where(.dark, .dark *)) in its CSS): toggle dark on <html>, set App dark, and match native bars with SystemBars.setStyle.
  • Konsta's own docs show user-scalable=no, maximum-scale=1; prefer allowing zoom for accessibility and fix iOS input zoom with 16px inputs instead.
  • Modals/side panels that are not full-screen need no-safe-areas (or no-safe-areas-top etc.) to avoid extra padding.
  • Konsta is UI only: no router, no page transitions. Pair with React Router / Vue Router / SvelteKit and handle Android back button with @capacitor/app backButton.

Verification

  1. npm run build && npx cap sync, run on iOS and Android.
  2. Inspect <html>/root: .k-ios or .k-material class present; ios:/material: utilities apply.
  3. Navbar clears the Dynamic Island; Tabbar clears the home indicator and Android gesture bar (Android 15+ edge-to-edge).
  4. Toggle dark mode; components and status bar icons switch together.
  5. Leftover check: grep -rn "konstaConfig\|konsta/config" . returns nothing on v5.

Error Handling

Error / symptomCauseFix
Cannot find module 'konsta/config'v5 removed JS configUse CSS @import 'konsta/react/theme.css'
Components render unstyledTheme CSS not imported, or Tailwind not scanning (no @tailwindcss/vite / @tailwindcss/postcss)Import theme after @import 'tailwindcss'; add the Tailwind plugin
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS pluginTailwind v4 PostCSS plugin movedUse @tailwindcss/postcss or @tailwindcss/vite
Brand color ignoredVariable not named --color-brand-*, or defined outside @themeRename inside @theme
ios: classes have no effectApp/KonstaProvider missing, so no .k-ios ancestorWrap app
React warning about ref / forwardRef after upgradeReact 18 with Konsta 5Upgrade to React 19 or stay on Konsta 4
Double top paddingKonsta safeAreas + Ionic or custom env() paddingKeep one owner

Resources

Safe Area Handling in Capacitor

When to Use

TRIGGER when:

  • Content renders under the status bar, notch, Dynamic Island, cutout, home indicator, or Android navigation/gesture bar
  • env(safe-area-inset-*) is 0px on Android, or correct only after rotation
  • Layout broke after Capacitor 8 upgrade or raising targetSdkVersion to 35/36
  • StatusBar.setOverlaysWebView / setBackgroundColor stopped working on Android
  • Landscape / split-screen / iPad windowed layouts have wrong side padding

Do not use:

  • Keyboard covering inputs: capacitor-keyboard
  • Ionic ion-header/ion-toolbar theming: ionic-design; Konsta safeAreas: konsta-ui
  • Tailwind plugin/utility setup: tailwind-capacitor
  • iOS scene sizing, UIScreen.main, multi-window: capacitor-ios-resizability
  • Splash screen colors: capacitor-splash-screen

Facts that drive every decision

Platform / versionBehavior
iOS (all)WebView is full-screen. env(safe-area-inset-*) works only with viewport-fit=cover. ios.contentInset defaults to never.
Android, Capacitor <= 7android.adjustMarginsForEdgeToEdge config could add native margins.
Android, Capacitor 8+adjustMarginsForEdgeToEdge removed. SystemBars core plugin (in @capacitor/core) handles insets.
Android 15 (targetSdk 35)Edge-to-edge enforced; opt-out via windowOptOutEdgeToEdgeEnforcement still possible.
Android 16 (targetSdk 36, Capacitor 8 default; 37 on Capacitor 9)Opt-out ignored. @capacitor/status-bar overlaysWebView and backgroundColor have no effect.
Android WebView < 140env(safe-area-inset-*) wrong/0 (Chromium bug). SystemBars injects --safe-area-inset-* variables (default insetsHandling: 'css').

How SystemBars behaves on Android (from core source): if the page has viewport-fit=cover and WebView >= 140, insets pass through to env() and the WebView is edge-to-edge. Otherwise Capacitor pads the WebView natively so content sits between the bars and env() reports 0. --safe-area-inset-* variables carry correct values in both cases when insetsHandling is css.

Workflow

  1. Inspect: index.html viewport meta, capacitor.config.* (ios.contentInset, android.adjustMarginsForEdgeToEdge, plugins.SystemBars, plugins.StatusBar), @capacitor/core + @capacitor/status-bar versions, android/variables.gradle targetSdkVersion, global CSS that sets padding-top, UI framework (Ionic / Konsta handle insets themselves).
  2. Decide the design: full-bleed (draw under bars, pad content) vs. contained (content between bars). Ask the user if mockups are unclear.
  3. Full-bleed (recommended): viewport-fit=cover + the CSS fallback chain below, applied once at the layout shell, not per component.
  4. Remove legacy config: delete android.adjustMarginsForEdgeToEdge; drop Android uses of StatusBar.setOverlaysWebView / setBackgroundColor (keep for iOS if wanted); prefer SystemBars.setStyle for icon color.
  5. Framework check: Ionic already applies --ion-safe-area-*; Konsta uses safeAreas. Do not double-pad.
  6. Verify on devices (below).

Only load a reference when its topic is in play:

Baseline

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
:root {
  --sat: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
  --sar: var(--safe-area-inset-right, env(safe-area-inset-right, 0px));
  --sab: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
  --sal: var(--safe-area-inset-left, env(safe-area-inset-left, 0px));
}
.app-header { padding-top: var(--sat); padding-inline: var(--sal) var(--sar); }
.app-tabbar { padding-bottom: var(--sab); padding-inline: var(--sal) var(--sar); }

The --safe-area-inset-* names are injected by Capacitor's SystemBars on Android; on iOS and web they are undefined, so the env() fallback applies.

import { SystemBars, SystemBarsStyle } from '@capacitor/core';
await SystemBars.setStyle({ style: SystemBarsStyle.Dark }); // light icons on dark background

SystemBarsStyle.Dark = light content for dark backgrounds; Light = dark content. iOS needs UIViewControllerBasedStatusBarAppearance = YES (template default).

Traps

  • Missing viewport-fit=cover is the #1 cause of env() = 0 on iOS and of Capacitor padding the WebView on Android.
  • Do not combine ios.contentInset: 'always' with CSS safe-area padding: insets apply twice.
  • Do not hardcode 20/44/47/59 px status bar heights; heights differ per device, orientation, and window size.
  • Insets change at runtime (rotation, iPad windowed mode, foldables, Android split screen, keyboard). Use CSS, or re-read on resize; never cache once at startup.
  • On iOS the bottom inset stays while the keyboard is visible; use max() with keyboard height (see capacitor-keyboard).
  • 100vh includes the area under system bars; use 100dvh or flex layout with a fixed shell.
  • Ionic: ion-content with fullscreen + ion-header already pads; adding body padding shifts everything twice.

Verification

  1. npx cap sync, run on: iPhone with Dynamic Island, iPhone SE-class (home button, small top inset), iPad (rotate + Stage Manager/windowed), Android 15/16 device or emulator in gesture and 3-button navigation, landscape.
  2. Check Android WebView version: adb shell dumpsys package com.google.android.webview | grep versionName (< 140 relies on injected variables).
  3. In Safari Web Inspector / chrome://inspect, run:
getComputedStyle(document.documentElement).getPropertyValue('--sat');
document.querySelector('meta[name=viewport]').content.includes('viewport-fit=cover');
  1. Confirm no element overlaps bars; tab bar taps work above the gesture bar; no double padding.
  2. Grep for leftovers:
grep -rn "adjustMarginsForEdgeToEdge\|setOverlaysWebView\|setBackgroundColor\|windowOptOutEdgeToEdgeEnforcement" capacitor.config.* src android/app/src/main/res 2>/dev/null

Error Handling

Symptom / messageCauseFix
Header under status bar on iOS, env() = 0No viewport-fit=coverAdd to viewport meta
Android: content correct but no edge-to-edge, env() = 0No viewport-fit=cover or WebView < 140, so Capacitor pads nativelyAdd viewport-fit=cover; use --safe-area-inset-* fallback
Android: double gap at topNative padding + your CSS padding with insetsHandling: 'disable' or custom MainActivity insets codeRemove custom setDecorFitsSystemWindows / inset listeners; keep SystemBars default
StatusBar.setBackgroundColor / setOverlaysWebView no effect on AndroidtargetSdk 35+/36 edge-to-edgeDraw a background under the bar in CSS; use SystemBars.setStyle for icon color
android.adjustMarginsForEdgeToEdge still in config after Capacitor 8 upgrade, margins goneOption removed and ignoredDelete it; rely on SystemBars + CSS
Logcat Unknown insetsHandling value '...'. Falling back to 'css'.Invalid SystemBars.insetsHandlingUse a value listed in the current docs (css, disable; newer cores also accept native)
Status bar text invisible (white on white)Style mismatchSystemBars.setStyle({ style: SystemBarsStyle.Light })
Layout jumps on first paint (Android)SystemBars detects viewport-fit after page commitSet plugins.SystemBars.initialViewportFitValueHint: 'cover' (in core config declarations; verify in your version)

Resources

Tailwind CSS in Capacitor Apps

When to Use

TRIGGER when:

  • Adding Tailwind to a Capacitor app (Vite, Angular, Next static export, etc.)
  • Upgrading Tailwind v3 -> v4, or a v4 install produces no styles
  • tailwind.config.js edits have no effect (v4 is CSS-first)
  • Colors / gradients broken or transparent on older iOS devices
  • Safe-area, dark mode, platform-specific, or touch-target utilities

Do not use:

  • Konsta UI setup/components: konsta-ui
  • Ionic components and --ion-* variables: ionic-design
  • SystemBars / Android edge-to-edge / status bar plugin: safe-area-handling
  • Inputs hidden by keyboard: capacitor-keyboard
  • Adding Capacitor to a framework: framework-to-capacitor

Version facts (October 2026)

  • tailwindcss 4.x is latest (4.3.x); 3.4.x on v3-lts.
  • v4 is configured in CSS. tailwind.config.js is not read unless you add @config "./tailwind.config.js";.
  • v4 targets Safari 16.4+, Chrome 111+, Firefox 128+ (uses @property, color-mix(), cascade layers, oklch).
  • Capacitor 8 supports iOS 15+, Capacitor 9 iOS 16+. WKWebView = the device's Safari version. Devices on iOS 15.x - 16.3 render v4 styles incorrectly. Android System WebView auto-updates, so Chrome 111+ is usually met (Capacitor 9 minSdk 26).

Decision: if the iOS deployment target (or real user base) includes iOS < 16.4, ask the user: stay on Tailwind 3.4, or raise the minimum OS. Do not silently ship v4.

Workflow

Use the selected project and its installed dependencies. Package installation and migration tools execute code; limit them to the requested setup or upgrade, preserve the lockfile and existing changes, and review generated edits before running changed build scripts.

  1. Inspect: npm ls tailwindcss, tailwind.config.*, postcss.config.*, bundler config, main CSS file, ios/App/App.xcodeproj IPHONEOS_DEPLOYMENT_TARGET, presence of Ionic or Konsta.
  2. New install (below) or upgrade: references/v3-to-v4.md.
  3. Mobile utilities (safe areas, platform variants, touch, dark mode): references/mobile-patterns.md.
  4. Verify (below).

Only load a reference when its topic is in play.

Install (Vite: React, Vue, Svelte, Solid)

npm i tailwindcss @tailwindcss/vite
// vite.config.ts
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [tailwindcss() /* + framework plugin */] });
/* src/styles.css */
@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));
@custom-variant ios (&:where(.plt-ios, .plt-ios *));
@custom-variant android (&:where(.plt-android, .plt-android *));

@theme {
  --color-brand: oklch(0.55 0.2 265);
  --font-sans: system-ui, -apple-system, "Roboto", sans-serif;
}

@utility pt-safe { padding-top: env(safe-area-inset-top); }
@utility pb-safe { padding-bottom: env(safe-area-inset-bottom); }
@utility px-safe { padding-left: env(safe-area-inset-left); padding-right: env(safe-area-inset-right); }

Other toolchains: PostCSS (Angular, webpack, Next) -> npm i tailwindcss @tailwindcss/postcss and postcss.config.mjs { plugins: { "@tailwindcss/postcss": {} } }; standalone -> @tailwindcss/cli. Angular CLI 17+ reads .postcssrc.json.

// main.ts: platform class for ios:/android: variants
import { Capacitor } from '@capacitor/core';
document.documentElement.classList.add(`plt-${Capacitor.getPlatform()}`); // plt-ios | plt-android | plt-web

Add viewport-fit=cover to the viewport meta or the safe-area utilities resolve to 0.

Traps

  • Content detection is automatic in v4 (respects .gitignore). Classes in node_modules or outside the project root need @source "../path";. Dynamic class names (`bg-${color}-500`) are never generated; map to full class strings.
  • v4 hover: only applies on devices with (hover: hover), so sticky hover on touch is solved by default. Use active: for press feedback.
  • v4 defaults changed: border color is currentColor, ring is 1px, shadow-sm/shadow and rounded-sm/rounded scales shifted, outline-none -> outline-hidden. The upgrade tool renames most; review visually.
  • Ionic + Tailwind: Preflight resets Ionic typography. Import Tailwind without Preflight (@layer theme, base, components, utilities; @import "tailwindcss/theme.css" layer(theme); @import "tailwindcss/utilities.css" layer(utilities);) or load Ionic CSS after Tailwind.
  • Konsta UI v5 already imports Tailwind theme pieces via konsta/<fw>/theme.css; follow konsta-ui instead of duplicating setup.
  • Do not use 100vh for full-screen layouts; use h-dvh (v4 has dvh/svh/lvh utilities) or a flex shell.
  • Android WebView < 140 reports safe-area env() as 0; Capacitor 8 SystemBars injects --safe-area-inset-*. For Android robustness, use @utility pt-safe { padding-top: var(--safe-area-inset-top, env(safe-area-inset-top)); } (see safe-area-handling).

Verification

  1. npm run build succeeds; built CSS contains your utilities: grep -c "pt-safe" dist/assets/*.css.
  2. npx cap sync and run on: oldest supported iOS version (check colors, gradients, shadows render), current iPhone, Android 15/16.
  3. Toggle dark mode class and OS appearance; check ios:/android: variants by inspecting <html class>.
  4. Leftovers after upgrade: grep -rn "@tailwind base\|@tailwind components\|@tailwind utilities\|require('tailwindcss')" src postcss.config.* 2>/dev/null returns nothing.

Error Handling

Error / symptomCauseFix
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin. The PostCSS plugin has moved to a separate packagev3-style PostCSS config with v4Use @tailwindcss/postcss (or @tailwindcss/vite)
No styles at allMissing @import "tailwindcss" or bundler pluginAdd both
Cannot apply unknown utility class in @applyCustom class not defined via @utility, or CSS module / Vue <style> without theme referenceDefine with @utility; add @reference "../styles.css"; in the scoped style
tailwind.config.js theme changes ignoredv4 does not auto-load JS configMove to @theme, or add @config
Transparent/missing colors on some iPhonesiOS < 16.4 lacks features v4 usesRaise min iOS or stay on 3.4
dark: follows OS, ignores toggleDefault dark variant is media-basedAdd @custom-variant dark (&:where(.dark, .dark *));
Upgrade tool fails: requires Node@tailwindcss/upgrade needs Node 20+Upgrade Node (Capacitor 9 needs 24+ anyway)

Resources

Sponsors

Details

Marketplace
Cap-go/capgo-skills
Source
plugins/capacitor-ui
Author
Capgo
Category
Development
License
MIT
Keywords
capacitor, ionic, konsta, tailwind, safe-area, ipad, resizability

More from Cap-go/capgo-skills

All 11