compose-expert
A guide for building shared Compose Multiplatform UI components, managing state, and optimizing performance across Android and Desktop platforms.
Install
mkdir -p .claude/skills/compose-expert && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/1754" && unzip -o skill.zip -d .claude/skills/compose-expert && rm skill.zipInstalls to .claude/skills/compose-expert
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Advanced Compose Multiplatform UI patterns for shared composables. Use when working with visual UI components, state management patterns (remember, derivedStateOf, produceState), recomposition optimization (@Stable/@Immutable visual usage), Material3 theming, custom ImageVector icons, or determining whether to share UI in commonMain vs keep platform-specific. Delegates navigation to android-expert/desktop-expert. Complements kotlin-expert (handles Kotlin language aspects of state/annotations).Key capabilities
- →Organizes shared UI code in commonMain
- →Optimizes recomposition via stable/immutable annotations
- →Implements cross-platform Material3 theming
- →Generates ImageVector icons for shared use
- →Structures state management for multiplatform apps
How it works
Applies a set of architectural rules for grouping UI logic and state handling into shared library modules.
Inputs & outputs
When to use compose-expert
- →Refactoring shared UI components into commonMain
- →Optimizing recomposition with @Stable and @Immutable
- →Building custom ImageVector icons
- →Implementing Material3 theming for cross-platform apps
About this skill
compose-expert
Where shared Compose UI lives in Amethyst and the house rules for it. What goes in
commons vs commonsUI vs a platform shim is in AGENTS.md ("Sharing Philosophy",
"Feature Workflow") and commonsUI/ARCHITECTURE.md; this skill does not repeat it.
Delegate: Activity / manifest / flavors -> android-expert; Window, tray, menu bar ->
desktop-expert; source-set placement, expect/actual, extracting an Android composable ->
kotlin-multiplatform; feeds and Account state -> account-state; Flow and coroutine
scopes -> kotlin-coroutines.
Where things live
All paths below are under
commonsUI/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/.
| What | Where |
|---|---|
| Screens | ui/screen/loggedIn/<feature>/ (and ui/screen/ for shared feed views) |
| Reusable components | ui/components/ (catalog: references/shared-composables-catalog.md) |
| Feed scaffolding | ui/feeds/ (RenderFeedContentState, RefresheableBox, FeedEmpty, LoadingFeed) |
| Note rendering | ui/note/ (NoteCompose), rich text in ui/richtext/ + ui/components/RichTextViewer.kt |
| Theme | ui/theme/ (AmethystColorScheme.kt palettes + ColorScheme.* tokens, ColorScheme.isLight, Shape.kt, Type.kt) |
| Window tiers | ui/layouts/ScreenLayout.kt (ScreenLayoutSpec, LocalScreenLayout, FeedContentMaxWidth) |
| Shell + nav | ui/app/AmethystApp.kt, ui/app/AppRoot.kt, ui/navigation/ (see below) |
| Platform ports for UI | ui/platform/AppPlatform.kt (LocalAppPlatform), ui/components/PlatformPermission.kt |
| Icons | icons/ (Amethyst glyph font) and icons/symbols/ (MaterialSymbols, AmethystIcons) |
| Robohash avatars | robohash/ (CachedRobohash, RobohashAssembler, parts/) |
| Strings | commonsUI/src/commonMain/composeResources/values/strings.xml -> Res.string.* (rules: AGENTS.md "Strings") |
The Android app's AmethystTheme wrapper is still in
amethyst/src/main/java/com/vitorpamplona/amethyst/ui/theme/Theme.kt; the palettes it
applies are shared.
The shell and window tiers
One shell for every window, chosen by size, not by platform (AGENTS.md "Navigation Shell"):
AmethystApp(ui/app/AmethystApp.kt) is the root both front ends call. Android'sMainActivitypassesAndroidAppRoot; the desktop window (AmethystDesktop.kt) passes aDesktopAppRoot.AppRoot(ui/app/AppRoot.kt) is the port each platform implements:createAccountViewModel,rememberScreenLayoutSpec,registerDestinations,ShellOverlay,NavigationEffects, ...ScreenLayoutSpec.navigationStyleisBOTTOM_BAR,NAV_RAILorPERMANENT_DRAWER;hasRoomForNotificationPaneldocks the notification panel.isLargeScreenis "not the bottom bar". Read it withLocalScreenLayout.current, never with a platform check.AppShellLayout(ui/navigation/shell/) lays out the bar / rail / drawer;ui/navigation/bottombars/holdsAppBottomBarandAppNavigationRail;ui/navigation/deck/DeckArea.ktadds the opt-in deck columns on windows of 1,200 dp+.
Navigation 3
The app owns its back stack as snapshot state; NavDisplay only renders it. No
NavController, no graph. Full rules in references/navigation.md.
- Routes:
@Serializable sealed class Routeincommons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/model/navigation/Routes.kt. The back stack is saved through kotlinx-serialization, so every route argument must be serializable. NavBackStacks(same package) holds the window'sNavModel:StackModel(stack, never empty, starts atRoute.Home;savedTabs, the root of each bottom-bar tab you left),TabsModelorWindowsModel. Every navigation is aNavRequestthe model reads its own way. ANavStackEntry'scontentKeyis"nav-$id": saved state and ViewModels key on it, so the same route opened twice is two screens.Nav(ui/navigation/navs/Nav.kt) implementsINav:nav,navDrawer,newStack,navBottomBar,popBack,popUpTo, each after the keyboard settles (ImeSettler).- Register a screen once with a builder from
ui/navigation/host/NavDestinations.kt. Shared screens go inNavDestinations.sharedDestinations(ui/navigation/host/SharedDestinations.kt); Android-only ones inandroidDestinationsinamethyst/src/main/java/com/vitorpamplona/amethyst/ui/navigation/AppNavigation.kt. The builder picks the motion and the reading-column cap:
// from SharedDestinations.kt
composableCapped<Route.Home> { HomeScreen(accountViewModel, nav) }
composable<Route.Message> { MessagesScreen(accountViewModel, nav) }
composableFromEnd<Route.Polls> { PollsScreen(accountViewModel, nav) }
composableFromEnd<Route.Browser>(capWidth = false) { BrowserScreen(accountViewModel, nav) }
composableFromBottomArgs<Route.AwardBadge> { AwardBadgeScreen(it.kind, it.pubKeyHex, it.dTag, accountViewModel, nav) }
A route nobody registered fails the first time it is opened (the desktop installs an
unavailable screen instead). Gate a menu item on canOpen(route) when a front end may lack it.
Composable conventions that differ from the default
- Strings come from
Res, read withstringRes(Res.string.x); no literal user-visible text in a shared composable, no AndroidR.string. Default label parameters areStringResource(seeAddButtoninui/components/ActionButtons.kt). - UI-state collections are
kotlinx.collections.immutable(ImmutableList,ImmutableMap,persistentListOf), anapidependency ofcommonsUI. The parser output (RichTextViewerState,ParagraphState) and the platform ports already use them; pass those, notList, into composables. @Immutable/@Stablemark the state classes and port interfaces handed to composables (ScreenLayoutSpec,AppPlatform,PlatformPermission). Only mark a class you can keep truly immutable.- Theme-dependent values come from the color scheme:
MaterialTheme.colorScheme.isLight(memoized inAmethystColorScheme.kt), not a hand-rolled luminance check. - Icons follow
AGENTS.md"Icons":icons/*.ktcompile intoamethyst_icons.ttfand draw throughAmethystIconGlyph; Material icons areMaterialSymbolsfrom a subset font, so a new codepoint needstools/material-symbols-subset/subset.sh. Robohash is the one ImageVector-built asset:references/icon-assets.md. - Parse rich text through
CachedRichTextParser, never per recomposition:references/rich-text-parsing.md. - Permissions in shared UI go through an
expect fun rememberXPermission(): PlatformPermission(seeui/components/LocationPermission.kt; the Android actual wraps Accompanist).
Reviewing a component's public API
For slot parameters, modifier placement, and the other API-shape checks, use
references/api-style.md.
Performance: measure first
Feed jank in this app has been measured as GC-bound and RenderThread-bound, with composition a
small share of frame time. Stability annotations, derivedStateOf and deferred reads only help
when a trace shows composition is the cost. Profile a release-like build (the benchmark
build type in amethyst/build.gradle.kts is minified and profileable) before you apply them, and
measure again afterwards.
Compose compiler reports are configured only for :amethyst (composeCompiler { reportsDestination ... } near line 551 of amethyst/build.gradle.kts, written to amethyst/build/compose_compiler/).
They cover only composables compiled in that module. Shared composables are compiled in
:commonsUI, which has no such block. To inspect their skippability, add the block to
commonsUI/build.gradle.kts temporarily, and don't commit it.
See it running
A screen change is not done until you've looked at it: tools/desktop-run/run-headless.sh start
runs the desktop app, which is this same UI, on a virtual display and screenshots it.
AMETHYST_SCREEN=480x900x24 shows the phone tier. See tools/desktop-run/README.md and
desktop-expert.
References
references/navigation.md: back-stack operations, rendering, transitions, intents, testsreferences/shared-composables-catalog.md: the reusable components and their signaturesreferences/rich-text-parsing.md:RichTextParser, segments,CachedRichTextParser, NIP-92 imetareferences/icon-assets.md: robohash avatarsreferences/api-style.md: component API review checklist (slots, modifiers)
When not to use it
- →Applications targeting a single platform exclusively
- →UI logic tied heavily to platform-specific system APIs
Prerequisites
Limitations
- →Requires familiarity with KMP architectural constraints
- →Material3 primitives must be strictly followed for sharing
- →Debugging cross-platform state is complex
How it compares
It provides a clear framework for deciding when to share code, avoiding the common 'share-everything' approach that causes platform crashes.
Compared to similar skills
compose-expert side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| compose-expert (this skill) | 6 | 7mo | Review | Advanced |
| android-kotlin | 7 | 7mo | No flags | Intermediate |
| kotlin-expert | 5 | 5mo | No flags | Advanced |
| android-jetpack-compose-expert | 4 | 7mo | No flags | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by vitorpamplona
View all by vitorpamplona →You might also like
android-kotlin
alinaqi
Android Kotlin development with Coroutines, Jetpack Compose, Hilt, and MockK testing
kotlin-expert
vitorpamplona
Advanced Kotlin patterns for AmethystMultiplatform. Flow state management (StateFlow/SharedFlow), sealed hierarchies (classes vs interfaces), immutability (@Immutable, data classes), DSL builders (type-safe fluent APIs), inline functions (reified generics, performance). Use when working with: (1) State management patterns (StateFlow/SharedFlow/MutableStateFlow), (2) Sealed classes or sealed interfaces, (3) @Immutable annotations for Compose, (4) DSL builders with lambda receivers, (5) inline/reified functions, (6) Kotlin performance optimization. Complements kotlin-coroutines agent (async patterns) - this skill focuses on Amethyst-specific Kotlin idioms.
android-jetpack-compose-expert
sickn33
Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Design 3.
reviewing-changes
bitwarden
Guides Android code reviews with type-specific checklists and MVVM/Compose pattern validation. Use when reviewing Android PRs, pull requests, diffs, or local changes involving Kotlin, ViewModel, Composable, Repository, or Gradle files. Triggered by "review PR", "review changes", "check this code", "Android review", or code review requests mentioning bitwarden/android. Loads specialized checklists for feature additions, bug fixes, UI refinements, refactoring, dependency updates, and infrastructure changes.
kmp-cmp-app-builder
firdaus1453
>
Android Navigation
li-lance
Standards for Jetpack Navigation Compose (Type-safe)