
ionic-design
Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).
- Installs
- 1.6K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cap-go/capgo-skills --skill ionic-design- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads ionic-design automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
modeoverrides 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 useresize: 'ionic') - Leaving Appflow / Ionic Enterprise plugins:
ionic-appflow-migration,ionic-enterprise-sdk-migration
Versions (October 2026)
| Package | Current | Notes |
|---|---|---|
@ionic/core, @ionic/react, @ionic/vue, @ionic/angular | 9.x (latest) | 8.x on v8-lts tag |
ionicons | 8.x | |
| Ionic 9 minimums | 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+ |
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
- Inspect framework, Ionic major, router version, global CSS imports,
setupIonicReact/IonicVue/provideIonicAngularconfig,capacitor.configKeyboard.resize. - Upgrading? Load references/ionic-9-migration.md; run
npx @ionic/migratein preview first, report findings, then apply. - Components: references/components.md for page shell, lists, forms, overlays, tabs.
- Theming: references/theming.md for colors, dark/high-contrast palettes, mode-specific CSS, shadow parts.
- 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(+ optionalIonFooter). MissingIonPagebreaks transitions and lifecycle hooks. - Scroll lives in
ion-content. Do not makebodyor a wrapperdivscroll; useIonContentscrollToTop()/getScrollElement(). - Use
ion-router-outlet(IonRouterOutlet,IonTabs) for URL routing. In Ionic 9ion-navno longer integrates withion-router; keep it for local URL-less stacks inside a page. - Safe areas are handled through
--ion-safe-area-top|right|bottom|left(defaultenv()); do not add body padding on top. Requiresviewport-fit=cover. - Forms: put
label+labelPlacementon the control itself (<IonInput label="Email" labelPlacement="floating" />). Legacy<IonItem><IonLabel/><IonInput/></IonItem>labeling was removed in Ionic 8. - Overlays: prefer inline
<IonModal isOpen>/triggeror hooks (useIonModal,modalController) consistently; always handledidDismissto reset state. - Platform: style via
.ios/.mdclasses onhtmlormodeCSS selectors; useisPlatform('ios')only for behavior, nevernavigator.userAgent. - Icons: import only used icons (
import { heart } from 'ionicons/icons') and passicon={heart}; string names needaddIconsregistration in standalone/bundled builds.
Verification
- Build and sync:
npm run build && npx cap sync. - Run both modes in the browser: append
?ionic:mode=iosand?ionic:mode=mdto the dev URL; check headers, toolbars, lists, buttons. - Toggle OS dark mode (or add
ion-palette-darkto<html>if using the class palette); check contrast of custom colors. - Device check: iPhone with Dynamic Island + Android 15/16 gesture nav for header/tab bar insets; open keyboard on a form page.
- After upgrade:
grep -rn "ion-picker-legacy\|pickerController\|useIonPicker\|@ionic/angular/standalone\|autocorrect=\"off\"" src/returns nothing;npx tsc --noEmitpasses.
Error Handling
| Error / symptom | Cause | Fix |
|---|---|---|
Package path ./dist/... is not exported from package (webpack) / ERR_PACKAGE_PATH_NOT_EXPORTED (Node) for @ionic/core | Ionic 9 exports map; deep import | Import 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 moved | Import from @ionic/angular; lazy APIs from @ionic/angular/lazy |
React: Property 'component' does not exist on Route / IonRoute | Ionic 9 requires React Router 6 | element={<Page />}, Navigate instead of Redirect, useNavigate instead of useHistory |
| Autocorrect turned ON after upgrade | autocorrect="off" string is truthy in Ionic 9 | Remove the attribute or bind false |
ionChange no longer fires on re-selecting same option | Ionic 9 fires only on value change | Use ionDismiss for dismissal |
| Sheet modal handle now focusable / cycles breakpoints | Ionic 9 handleBehavior default cycle | handle-behavior="none" to restore |
| Styles missing, components unstyled | Core CSS not imported | Import @ionic/<fw>/css/core.css (+ structure/typography) once at entry |
| Dark mode never activates | No palette imported | Import css/palettes/dark.system.css (or .class.css + ion-palette-dark class) |
| Angular 21 view not updating after async work | Zoneless default in Ionic 9 + Angular 21 | Use signals / markForCheck(), or add provideZoneChangeDetection() |
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
FAQ
What does the ionic-design skill do?
Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).
How do I install ionic-design?
Run npx skills add https://github.com/cap-go/capgo-skills --skill ionic-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ionic-design/ (personal) or .claude/skills/ionic-design/ (project).
Which AI agents can use ionic-design?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is ionic-design safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains ionic-design?
It is published by cap-go in cap-go/capgo-skills. It has 1,590 recorded installs.
More from cap-go/capgo-skills
capacitor-best-practices
cap-go/capgo-skills
Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).
capacitor-plugins
cap-go/capgo-skills
Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).
debugging-capacitor
cap-go/capgo-skills
Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).
capacitor-testing
cap-go/capgo-skills
Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor
safe-area-handling
cap-go/capgo-skills
Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).
capacitor-deep-linking
cap-go/capgo-skills
Implements and debugs deep links in Capacitor apps - custom URL schemes, iOS Universal Links (apple-app-site-association, Associated Domains entitlement), Android App Links (assetlinks.json, autoVerify), and routing via @capacitor/app appUrlOpen + App.getLaunchUrl(). Covers the Capacitor 8.5+ UIScene change where AppDelegate application(:open:options:) and continue userActivity stop being called and custom handling must move to SceneDelegate, plus cold vs warm launch testing. Use when links open Safari/Chrome instead of the app, appUrlOpen never fires, the launch URL is lost on cold start, or OAuth redirects do not return to the app. Do not use for the full UIScene migration (capacitor-uiscene-migration), push notification taps (capacitor-push-notifications), or social login plugin setup (capacitor-plugins).
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.