Pokédex - Kotlin Multiplatform Showcase

A modern, cross-platform Pokédex application demonstrating dual-UI design systems (Material Design 3 Expressive + Compose Unstyled) with shared business logic across Android, iOS, Desktop, and Server.

✨ Key Features

Dual-UI Design Systems: Runtime theme switching between Material Design 3 and Compose Unstyled
Adaptive Layouts: Responsive grid columns (2/3/4) and navigation (bottom bar → rail → drawer) based on window size
Cross-Platform: Single Kotlin codebase for Android, iOS, Desktop (JVM), and Server
Shared Business Logic: ViewModels, repositories, and domain models 100% shared across platforms
Material 3 Adaptive: Uses official Material3 Adaptive library for responsive layouts
Type-Safe Navigation: Navigation Compose 3 with Koin DI integration
PokéAPI Integration: Real-time data from official PokéAPI v2

🏗️ Architecture

This project demonstrates production-ready Kotlin Multiplatform architecture with:

/composeApp - Compose Multiplatform UI (Android, Desktop, iOS Compose)
- commonMain - Shared UI code and app entry point
- Platform-specific folders for Android/iOS/Desktop customizations
- Dual-theme support with runtime switching
/features - Vertical slice feature modules
- :features:<feature>:api - Public contracts (interfaces, domain models, navigation)
- :features:<feature>:data - Repositories, DTOs, API services
- :features:<feature>:presentation - ViewModels and UI state (shared with iOS)
- :features:<feature>:ui-material - Material Design 3 UI implementation
- :features:<feature>:ui-unstyled - Compose Unstyled UI implementation
- :features:<feature>:wiring - Business logic DI (Koin modules)
- :features:<feature>:wiring-ui-material - Material navigation registration
- :features:<feature>:wiring-ui-unstyled - Unstyled navigation registration
/core - Shared infrastructure modules
- :core:designsystem-core - Shared theme utilities
- :core:designsystem-material - Material 3 Expressive theme
- :core:designsystem-unstyled - Compose Unstyled theme
- :core:navigation - Navigation 3 modular architecture
- :core:di - Koin DI configuration
- :core:httpclient - Ktor HTTP client setup
/iosApp - Production iOS app using native SwiftUI
- Consumes KMP ViewModels via :shared framework
- Native iOS UI with SwiftUI
- Direct Integration pattern for ViewModel usage
/iosAppCompose - Experimental iOS app using Compose Multiplatform
- Shares same Compose UI code with Android/Desktop
- See the README for details
/server - Ktor Backend-for-Frontend (BFF)
/shared - iOS umbrella framework
- Exports feature APIs and ViewModels to iOS
- commonMain - Shared Kotlin code

🚀 Quick Start

Primary Validation (Always Run First)

Before making changes, always run:

./gradlew :composeApp:assembleDebug test --continue

This builds the Android app and runs all 114 tests across all modules (~45 seconds on modern hardware).

Build and Run Android Application

To run the development version of the Android app:

on macOS/Linux

./gradlew :composeApp:assembleDebug test --continue

on Windows

.\gradlew.bat :composeApp:assembleDebug test --continue

Features in Android App:

Dual-theme switcher via navigation items (Material/Unstyled tabs in bottom bar or rail)
Adaptive grid layout (2/3/4 columns based on window size)
Adaptive navigation (bottom bar → rail → drawer)
Pokemon list with infinite scroll
Pokemon detail with stats, types, abilities

Build and Run Desktop (JVM) Application

To run the development version of the desktop app:

on macOS/Linux
```
./gradlew :composeApp:run
```
on Windows
```
.\gradlew.bat :composeApp:run
```

Features in Desktop App:

Same dual-theme switcher as Android
Window resizing triggers adaptive layouts (grid columns + navigation style)
Full keyboard and mouse support
Native window decorations

Build and Run Server

To build and run the development version of the server, use the run configuration from the run widget in your IDE’s toolbar or run it directly from the terminal:

on macOS/Linux
```
./gradlew :server:run
```
on Windows
```
.\gradlew.bat :server:run
```

Build and Run iOS Application

Native SwiftUI App (Production):

To build and run the development version of the iOS app with native SwiftUI, use the run configuration from the run widget in your IDE's toolbar or open the /iosApp directory in Xcode and run it from there.

Compose Multiplatform iOS App (Experimental):

To build and run the experimental iOS app using Compose Multiplatform:

Build the framework:

./gradlew :composeApp:embedAndSignAppleFrameworkForXcode

Open in Xcode:

open iosAppCompose/iosAppCompose.xcodeproj

Run in simulator (Cmd+R)

See iosAppCompose/README.md for detailed information about the Compose iOS implementation.

📚 Documentation

Note: Technical documentation has been consolidated into Agent Skills (.agents/ directory). Skills are the canonical reference. See AGENTS.md for the complete skill catalog and decision trees.

Essential Guides

@kmp-commands - Commands, patterns, validation
@kmp-critical-patterns - 6 core patterns (ViewModel, Either, Impl+Factory, Navigation, Testing, Convention Plugins)
@kmp-architecture - Architecture master reference (START HERE for architecture questions)
@kmp-testing-strategy - Kotest, MockK, Turbine, property tests (114 tests passing)

Project Documentation

prd.md - Product requirements (CANONICAL)
user_flow.md - User journeys and flows
ui_ux.md - UI/UX guidelines
onboarding.md - First-run experience and onboarding flows

Agent Skills (26 Total)

Located in .agents/ — AI agents can load via @skill-name syntax.

For skill selection guidance: See AGENTS.md decision trees and skill categories.

Core Skills: @kmp-critical-patterns, @kmp-architecture, @kmp-presentation, @kmp-data-layer, @kmp-testing-strategy, @kmp-di, @kmp-domain

Platform Skills: @kmp-ios, @kmp-desktop, @compose-screen, @swiftui-screen, @kmp-navigation

API & Build: @ktor-backend, @kmp-api-services, @kmp-gradle, @kmp-commands

Development & Testing: @kmp-developer, @kmp-mobile-expert, @kmp-testing-patterns, @kmp-compose-unstyled

Design & Planning: @product-designer, @ui-ux-designer, @onboarding, @user-flows

Quality: @docs-maintainer

Full skill list and detailed descriptions: See AGENTS.md for all 26 skills organized by category.

🧪 Testing

Test Suite: 114 tests passing (androidUnitTest + commonTest)

Coverage:

Repository tests: Success + all error paths (Network, Http, Unknown)
ViewModel tests: State transitions with Turbine + TestScope
Mapper tests: Property-based tests with Kotest
UI tests: @Preview for all @Composable functions

Property-Based Testing:

34 property tests (~34,000 scenarios per run)
40% property tests, 60% concrete tests
Mappers: 100% property test coverage

Quick Start Testing:

# Run all tests
./gradlew test --continue

# Run specific module tests
./gradlew :features:pokemonlist:presentation:testDebugUnitTest

See @kmp-testing-strategy skill for comprehensive guide.

🎨 Design Systems

Material Design 3 Expressive

Custom Pokémon color scheme (coral primary, yellow secondary, grass green tertiary)
Google Sans Flex variable font (Android/Desktop), SF Pro (iOS)
Emphasized easing curves for motion
18 Pokémon type colors (WCAG AA compliant)

Compose Unstyled

Platform-native theming with automatic light/dark support
Headless components with full styling control
Same feature set as Material, different visual approach
Educational showcase for design system comparison

Theme Switching:

Navigation items in bottom bar (compact) or rail (medium/expanded)
Two tabs: "Material" and "Unstyled" for instant comparison
Entire app switches atomically (scaffold + content)
State persisted across sessions
First-run modal explains the feature

Build Logic & Convention Plugins

For how modules are configured (KMP targets, Android config, Compose, and shared deps), see:
- @kmp-gradle skill
- Plugins you will see across the repo:
  - convention.kmp.library, convention.core.library
  - convention.feature.base, convention.feature.api, convention.feature.data, convention.feature.presentation, convention.feature.ui, convention.feature.wiring
  - convention.compose.multiplatform, convention.kmp.android.app

Development Workflow

Commit Message Convention

This project uses Conventional Commits format.

Format:

<type>(<scope>): <description>

Quick Reference:

Type	Use Case	Example
`feat`	New features	`feat(pokemonlist): add infinite scroll pagination`
`fix`	Bug fixes	`fix(pokemondetail): resolve crash on missing sprite data`
`docs`	Documentation	`docs(conventions): add commit message guidelines`
`test`	Tests	`test(pokemonlist): add property-based tests for repository`
`build`	Build/dependencies	`build(gradle): update Kotlin to 2.1.0`
`refactor`	Code refactoring	`refactor(designsystem): extract theme tokens to constants`
`chore`	Maintenance	`chore: update .gitignore for build artifacts`

Scopes: Use general feature or area names: pokemonlist, pokemondetail, designsystem, navigation, testing, ios, di, conventions

CHANGELOG Generation

This project uses git-cliff to generate changelogs from conventional commits.

Installation (macOS):

brew install git-cliff

Generate/Update CHANGELOG:

git cliff -o CHANGELOG.md

For Releases:

git cliff -o CHANGELOG.md --tag v1.0.0

Configuration: See cliff.toml for git-cliff configuration including commit grouping, scope-based sub-grouping, and GitHub link templates.

Learn more about Kotlin Multiplatform…

Name	docs-maintainer
Description	This skill should be used when updating documentation, checking links, and consolidating information. Use for doc maintenance and consistency.

docs-maintainer

SKILL.md