# compose-screens-footguns

Adopt this skill: https://proskills.md/skills/other/maxrave-dev-kotlin-footguns-skills-compose-screens-footguns

Page: https://proskills.md/skills/other/maxrave-dev-kotlin-footguns-skills-compose-screens-footguns
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/compose-screens-footguns/SKILL.md
size: 8050
upstream: https://github.com/maxrave-dev/kotlin-footguns/blob/main/skills/compose-screens-footguns/SKILL.md

```text
---
name: compose-screens-footguns
description: "Compose screen and interaction traps: navigation, adaptive layout, window insets, pagers, toolbars, sheets, list drag and selection, sliders, text fields, settings UI, one-shot effects. Use when layout, gestures or navigation misbehave."
---

# Compose screens footguns: layout, navigation and interaction

32 traps mined from a production Kotlin and Compose Multiplatform app, one short file each
under `references/`. Every file gives the working pattern, the **Traps** (the specific ways it
fails in practice, and why), and a **Verifying it** section with commands to run against the
user's own tree.

**How to use this index.** Match the code about to be written, or the symptom being chased,
against the entries below: each names its topic and the symptom that should send you to it. Read
every file that plausibly applies with the Read tool before proposing code or a fix; each is under
150 lines. Where a Verifying command names the source project's paths, substitute the equivalent
paths in the user's tree.

**Cross-references.** A backticked trap name inside a file that is not listed here lives in a
sibling area skill: glob `../*/references/<name>.md` to open it.

## Screens, navigation and adaptive layout

- [`responsive-gate-size-not-platform`](references/responsive-gate-size-not-platform.md) — Gate an adaptive layout on the window's own width-versus-height, never on the platform, and flip every geometry value the gate owns in the same breath — frame sizing, content scale and scrim height. Use when a layout is right on a phone and wrong in a narrow or resized desktop window, when forcing an adaptive flag to one value breaks a different platform's screen, or when artwork swallows the whole page on a wide window.
- [`nav-tab-registration-drift`](references/nav-tab-registration-drift.md) — A top-level tab has to be registered in every navigation surface that holds its own copy of the tab list — bottom bar, rail, and a stylized bar that keeps two lists — plus the graph and the flag that gates it, or the tab exists in code and never renders. The same drift catches a status entry point carried by more than one top app bar, where the missing badge reads as "nothing is running" rather than as a bug. Covers why a tab's ordinal is an identity rather than a position, what a conditional tab needs when it disappears under the user, and why a badge dot needs a ring of the page colour. Use when a newly added tab or badge shows on one surface but not another, when selection highlights the wrong tab after reordering, or when a tab bar overflows once one more tab appears.
- [`type-safe-nav-graph-organization`](references/type-safe-nav-graph-organization.md) — Lay out a type-safe Navigation-Compose graph so it stays readable as the destination list grows — one serializable route object per file grouped by area, area graphs as extension functions on the graph builder, a single transition set on the host, and per-route theming applied by wrapping the screen inside its own entry. Use when a navigation file has grown to hundreds of lines, when route arguments start needing custom types, or when transitions or theming differ between destinations for no stated reason.
- [`collapsing-parallax-toolbar`](references/collapsing-parallax-toolbar.md) — Build a collapsing header from five siblings in one box — four sharing a single scroll state, one driven by a boolean instead — with artwork moved by a graphics layer at half the scroll rate, a title interpolated along a two-segment curve into the pinned bar, and a derived flip point that swaps the floating back button for a real top bar. Use when a parallax header jitters or re-measures while scrolling, when the collapsing title drifts off its intended path, or when the pinned bar appears at the wrong scroll offset after a window resize.
- [`fullscreen-video-gesture-overlay`](references/fullscreen-video-gesture-overlay.md) — The gesture and chrome layers of a fullscreen video screen — tap anywhere to toggle the controls, double-tap either half to seek, an auto-hide timer that every interaction postpones, and a picture-in-picture (PiP) guard that removes both layers. Use when single taps work on only half the screen, when the controls vanish while the user is dragging the seek bar, when the seek thumb snaps back under the finger, when a double-tap produces no ripple or a ripple that never fades, or when app chrome is still drawn over the video inside a small floating window.
- [`nowplaying-pager-no-feedback-loop`](references/nowplaying-pager-no-feedback-loop.md) — A now-playing artwork pager that both follows the player and drives it, without the two writing to each other in a loop — the in-progress-scroll flag covers programmatic animation as well as drags, the seek is dispatched from the settled page only, and the page-difference decision is a pure function outside the UI runtime. Use when a swipe bounces back to the page it came from, when one swipe skips two tracks, when the pager stops following the player after a fast swipe, when swiping backwards restarts the current track instead of going back one, or when a far swipe under shuffle lands on the wrong song.
- [`layered-video-backdrop-pager`](references/layered-video-backdrop-pager.md) — Building a swipeable now-playing page whose layers — a colour backdrop, a full-bleed looping video or image, and a centred square cover — all belong to one pager, with per-page colours taken from the bitmap that page actually painted and a scrim spanning the whole page. Use when a swipe makes the background and the cover slide out of step, when video from one track bleeds into the neighbouring page mid-swipe, when the backdrop colour belongs to the wrong track or flashes black between pages, when the bottom of the video shows through the controls, or when a tap overlay stops the pager from being dragged at all.
- [`desktop-mini-player-window`](references/desktop-mini-player-window.md) — A second always-on-top, frameless desktop window for playback controls — its existence held as one boolean outside the composition, the same state object as the main window, a hand-rolled drag that anchors to absolute pointer coordinates, a native minimum size in device pixels, and geometry persisted without flooding the store. Use when the small window drifts or jitters while being dragged, when it cannot be resized past a corner, when it collapses below its content, when it disappears the moment the main window is closed, when it opens invisible, or when its state disagrees with the main window's.
- [`screen-shell-content-split`](references/screen-shell-content-split.md) — Split one screen into a shell that owns every cross-look concern and a content layer that only renders, connected by two holders — a state snapshot and an actions bag — so adding a second look costs one branch instead of a parameter-list edit; covers why the holders are stable-but-not-immutable, what must stay in the shell, and what must not. Use when a screen has grown a second visual style, when a style switch resets the scroll position or the artwork page, when adding a look means editing a fifty-argument signature, or when a "shared" helper starts needing a per-style `if`.
- [`variant-layout-math-stays-in-the-variant`](references/variant-layout-math-stays-in-the-variant.md) — When two looks of one screen each need a fit-exactly-one-screen measurement — measure the fixed blocks, split the remainder into equal gaps, floor it at a minimum — keep a copy per look instead of hoisting one; covers the effect keys the block needs, the invisible spacer that must mirror the ratio actually drawn, and which spacer may animate. Use when the gap above or below a hero element keeps last track's size, when content that should end at the fold overflows or leaves a band of dead space, or before extracting "the same" layout maths from two screens into one helper.
- [`empty-state-must-keep-its-navigation`](refere
```

## File: README.md
upstream: https://github.com/maxrave-dev/kotlin-footguns/blob/main/README.md

````text
# kotlin-footguns

**By [maxrave-dev](https://github.com/maxrave-dev)** — creator and maintainer of
[SimpMusic](https://github.com/maxrave-dev/SimpMusic), the 10.8k-star cross-platform music app
every lesson in this repository was mined from.

[![skills.sh](https://skills.sh/b/maxrave-dev/kotlin-footguns)](https://skills.sh/maxrave-dev/kotlin-footguns)
[![SimpMusic stars](https://img.shields.io/github/stars/maxrave-dev/SimpMusic?style=flat&logo=github&label=SimpMusic)](https://github.com/maxrave-dev/SimpMusic)
[![GitHub followers](https://img.shields.io/github/followers/maxrave-dev?style=flat&logo=github&label=Followers)](https://github.com/maxrave-dev)
[![Sponsor](https://img.shields.io/badge/GitHub_Sponsors-%E2%9D%A4-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/maxrave-dev)
[![Buy Me a Coffee](https://img.shields.io/badge/Buy_Me_a_Coffee-%E2%98%95-FFDD00?logo=buymeacoffee&logoColor=black)](https://www.buymeacoffee.com/maxrave)
[![Blog](https://img.shields.io/badge/Blog-simpmusic.org-4B8BBE?logo=rss&logoColor=white)](https://www.simpmusic.org/blogs)
[![License](https://img.shields.io/badge/License-GPL--3.0-blue)](LICENSE)

228 battle-tested traps mapping the footguns of Kotlin, Compose Multiplatform and desktop JVM
development, packaged as ten agent skills plus a scanner that checks a change against them. Mined
from a production codebase, not written from documentation.

The traps are grouped into ten area skills in the open agent-skills format, readable by Claude
Code and any coding agent that understands the format — and just as readable by a human. Each
area skill is an index of its traps; each trap is a standalone markdown file the agent opens
when the work in front of it matches. The corpus is 28,000+ lines across 228 files, and in most
of them the largest section is **Traps**: the
specific ways a technique fails in practice, each paired with a way to verify the failure and
the fix on your own tree.

## Why this repository exists

Most agent-skill collections for Kotlin and Android are written from official documentation.
They tell an agent what the API is supposed to do. This repository records what happened when
its author shipped against those APIs for years: the API that reports success while discarding
your data, the build flag that means something different on one platform, the verification
step that passes on broken code, the migration that deleted the wrong thing first.

None of it is theory. Every lesson here is older than the document that describes it — each
one had already been paid for in crash reports, failed releases, review rounds and user-filed
issues before it was written down.

## Where the lessons come from

![The SimpMusic repository on GitHub](assets/simpmusic-github-header.png)

The source is [SimpMusic](https://github.com/maxrave-dev/SimpMusic), a cross-platform music
client built with Kotlin and Compose Multiplatform, in continuous production since April 2023.
As of this writing it has earned more than 10,800 GitHub stars and 550 forks, and ships to
real users on Android, Windows, macOS and Linux through GitHub releases, F-Droid, IzzyOnDroid
and OpenAPK.

That codebase spans territory most sample projects never touch: a native media engine bound
over JNA, dual-player crossfade and DSP chains, a Room database at real-user scale, desktop
packaging and code-signing for three operating systems, CI that builds all of it, and a UI
written entirely in Compose. The traps are the distillation of that surface area.

The corpus itself is deliberately service-neutral. The traps teach architecture and failure
modes, never the mechanics of any third-party service; no service names or vendor field names
appear in any trap file. What was learned integrating specific services survives here as the
generic core that applies to whichever API you are consuming.

## What is inside

| Area skill | Traps | Focus |
|---|---|---|
| [`desktop-and-build-footguns`](skills/desktop-and-build-footguns/SKILL.md) | 24 | Native code on the desktop JVM; desktop packaging, code signing, CI and build |
| [`kmp-architecture-footguns`](skills/kmp-architecture-footguns/SKILL.md) | 25 | Multiplatform module structure, dependency injection, architecture; Kotlin language traps |
| [`media-playback-footguns`](skills/media-playback-footguns/SKILL.md) | 33 | Players and crossfade, audio processing and DSP, queues, shared listening sessions |
| [`data-layer-footguns`](skills/data-layer-footguns/SKILL.md) | 26 | Room and SQL at scale, migrations, repositories, caching and paging |
| [`compose-visuals-footguns`](skills/compose-visuals-footguns/SKILL.md) | 36 | Theming and colour, gradients and scrims, effects and animation, charts |
| [`compose-screens-footguns`](skills/compose-screens-footguns/SKILL.md) | 32 | Screens, navigation, adaptive layout, components and interaction |
| [`state-and-background-footguns`](skills/state-and-background-footguns/SKILL.md) | 23 | Flow, StateFlow and ViewModel lifecycles; background work, services, platform runtime |
| [`webview-footguns`](skills/webview-footguns/SKILL.md) | 3 | WebView on low-RAM phones and provider-less devices: startup, renderer death, AndroidView lifecycle, cookies |
| [`remote-api-footguns`](skills/remote-api-footguns/SKILL.md) | 17 | Clients and parsing, auth and retries, realtime sessions and wire protocols |
| [`engineering-method-footguns`](skills/engineering-method-footguns/SKILL.md) | 9 | Experiments, build logs, commit history, changelogs, removing a feature |

Each area skill lists its traps under headings, each with the description that tells an agent
when to open it. The whole index on one page is [CATALOG.md](CATALOG.md). An eleventh skill,
[`footgun-scan`](skills/footgun-scan/SKILL.md), checks code against the traps (below).

## Why ten skills and not 228

Until version 2.0 every trap was its own skill, and the set crowded out everything else in the
agent's skill listing. Claude Code lists every installed skill's name and description on every
turn, inside a budget of 1% of the context window (8,000 characters for a 200K-token window),
and lists whatever does not fit by name alone, least-used first. The 224 descriptions came to
about 124,000 characters and the names alone to 7,500, so at that budget every trap reached the
agent as a bare name, and so did every other skill the user had installed, their own included.

As ten area skills plus the scanner the listing is about 2,900 characters. The agent loads an area's index when
the work touches that area, sees every trap in it at once with the symptom that should send it to
each one, and opens only the files that apply.

## Scanning a change

`footgun-scan` turns the traps into a check. It matches 32 patterns against the lines a change
adds; each pattern is tied to one trap, and the agent opens that trap to confirm or dismiss every
hit. Ask for it in plain words ("check my uncommitted Kotlin changes for footguns"), or run the
script yourself, for example as a CI step:

```bash
python3 .claude/skills/footgun-scan/scripts/scan.py --base origin/main --fail
```

A hit is `likely` when the shape is wrong unless the exception its trap names holds, and `look`
when it marks a place the trap says to inspect. Over the whole of SimpMusic and its core module the
scanner raised 26 `likely` hits, and all 26 matched their trap on inspection: 22 vertical slides
left at their half-height default, two fades from `Color.Transparent` into a colour, and two values
spliced into migration SQL. The `look` hits are places to read, not verdicts.

## Does it help?

[`evals/`](evals/README.md) holds thirteen `claude plugin eval` cases, each run with the plugin and
without it. With it, all twelve trap questions passed in every run and the agent opened the right
trap file every time. Without it they averaged 0.56. On five of them the model already knew the
lesson. On four it was confidently wrong: it described a Room connection-routing rule and a
resourc
````
