Skip to content

maxrave-dev/kotlin-footguns / skills/compose-screens-footguns

compose-screens-footguns

Verified

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.

FileKindSize
SKILL.mdskill md21.6 KB
references/collapsing-parallax-toolbar.mdmarkdown8.4 KB
references/commit-a-text-field-on-an-explicit-action.mdmarkdown8.1 KB
references/control-range-must-cover-stored-values.mdmarkdown6.2 KB
references/custom-modal-sheet-family.mdmarkdown7.1 KB
references/custom-thin-media-slider.mdmarkdown8.3 KB
references/desktop-mini-player-window.mdmarkdown7.8 KB
references/edit-a-shape-as-a-shape.mdmarkdown7.1 KB
references/empty-state-must-keep-its-navigation.mdmarkdown7.0 KB
references/event-not-state-edge-for-one-shot-effects.mdmarkdown7.5 KB
references/expandable-and-linkified-text.mdmarkdown6.9 KB
references/floating-overlay-reserves-its-own-strip.mdmarkdown9.1 KB
references/fullscreen-video-gesture-overlay.mdmarkdown7.6 KB
references/hidden-setting-does-not-clear-the-stored-value.mdmarkdown6.3 KB
references/layered-video-backdrop-pager.mdmarkdown8.6 KB
references/lazy-item-grouping-beats-arrangement-gap.mdmarkdown8.2 KB
references/lazy-list-drag-reorder.mdmarkdown8.0 KB
references/lazy-scroll-helper-kit.mdmarkdown6.9 KB
references/nav-tab-registration-drift.mdmarkdown8.6 KB
references/nowplaying-pager-no-feedback-loop.mdmarkdown7.5 KB
references/progress-indicator-as-scrubber.mdmarkdown6.0 KB
references/responsive-gate-size-not-platform.mdmarkdown9.0 KB
references/scoped-composable-shadows-the-top-level-one.mdmarkdown5.3 KB
references/screen-shell-content-split.mdmarkdown7.2 KB
references/selection-mode-state-holder.mdmarkdown8.0 KB
references/self-hiding-child-cannot-hide-its-slot.mdmarkdown5.2 KB
references/settings-value-round-tripped-through-its-label.mdmarkdown6.2 KB
references/stacked-bars-double-consume-window-insets.mdmarkdown8.7 KB
references/story-reel-auto-pager.mdmarkdown8.5 KB
references/swipe-action-list-row.mdmarkdown7.7 KB
references/type-safe-nav-graph-organization.mdmarkdown7.6 KB
references/variant-layout-math-stays-in-the-variant.mdmarkdown5.8 KB
references/weight-fill-false-to-center-a-cluster.mdmarkdown8.6 KB

references/settings-value-round-tripped-through-its-label.md

View on GitHub
---
name: settings-value-round-tripped-through-its-label
description: A selection dialog that maps the chosen localized label back to a stored value breaks the day two labels translate identically — the write is skipped or lands on the wrong option, with no error; covers carrying the id instead of the text, making the miss loud, and the sibling hazard of a default declared both in the store and as the collector's initial value. Use when a settings choice does not stick in one language only, when a picker writes a neighbouring option, or when a screen renders the wrong variant for a moment on entry.
---

# Do not round-trip a setting through its own label

The shape is everywhere: pair each stored value with its translated caption, show the captions, get
back the chosen caption, look the value up again by string equality.

```kotlin
// adapted — the reverse lookup that is the bug; list and setter renamed, body inlined
styleLabels.firstOrNull { it.second == selected }?.first?.let { setStyle(it) }
```

Forward is fine — value to caption, for the subtitle under the row. It is the return trip that
depends on every caption being unique in every language, which is not a property anyone maintains.

## Traps

**Two identical translations silently disable the write.** Many languages have no distinct wording
for two neighbouring options, and translators are not shown the constraint. When it happens the
lookup either fails — the `?.let` swallows it, the dialog closes, the setting is unchanged, nothing
is logged — or, worse, matches the *first* pair with that caption and writes the wrong value. The
same failure arrives from a stray trailing space, a differing apostrophe, or a caption that renders
one way in the list and another in the dialog.

**Carry the id, not the text.** The selection API should hand back an index or the value itself. If
the dialog is yours, that is a small change and it removes the whole class. If it is not, map by
position against the *same list instance* you built the captions from.

**Positional mapping only works if the list is built once.** Option lists are frequently conditional
— an entry added only on a platform that supports it — so a list rebuilt in the dialog callback can
have different indices from the one that was displayed. One `val` built once, read by both the
display and the callback.

**Make the miss loud.** `?.let { }` is the wrong terminator for a lookup that must succeed. Log a
warning, or throw in debug builds. A settings write that quietly does nothing is reported months
later as "it doesn't save", by one user, in one language.

**A default declared in the store and again at the collector is two places to drift.** The store
falls back to a default when the key is absent; the screen collecting that flow supplies an initial
value for the frames before the first emission. When they disagree, the screen renders the *other*
option for a beat on every entry — and a "reset to defaults" path can write the value the store
believes while the UI showed the collector's. Reference one named constant from both, and prefer a
store API that never needs a second default (a flow with a start value, or a state flow).

**The boolean version of that drift is the same bug, just cheaper to spot.** A screen full of `false`
collector defaults is a list of duplicated defaults; each is a wrong first frame if the store's
fallback is `true`. Audit them the same way — but note that a store keeping its flags as named string
constants writes its false as a dotted name, not as a literal, so the two halves of one screen are
spelled differently and a filter that knows only `false` silently keeps every one of the others.

**The forward direction has its own quiet failure.** The row's subtitle looks the caption up from the
stored value and falls back to an empty string when nothing matches — so a value written by an older
build, or by the wrong-option bug above, renders as a settings row with a blank subtitle rather than
as an error. Fall back to the default option's caption instead, and log the miss.

**Watch what else that click lambda does.** Dialog titles and buttons in this pattern are frequently
fetched with a blocking resource read. Inside an event handler that is tolerable; the same call from
composition is not — see `compose-multiplatform-viewmodel-base`.

## Verifying it

1. Every reverse lookup by caption. Each hit is either a bug or needs a comment explaining why the
   captions are guaranteed unique:

   ```bash
   grep -rn --include='*.kt' --exclude-dir=build "it.second == \|\.second == selected" .
   ```

2. Every lookup that ends in a silent `?.let`, which is how the miss stays invisible:

   ```bash
   grep -rn --include='*.kt' --exclude-dir=build "firstOrNull {.*}?\..*?\.let {" .
   ```

3. Collector defaults that are not plain booleans — these are the ones whose drift is visible as a
   wrong first frame. Each hit must name the same constant the store falls back to in step 4:

   ```bash
   grep -rnE --include='*.kt' --exclude-dir=build \
     "collectAsState[A-Za-z]*\((initialValue *= *)?[A-Za-z_][A-Za-z0-9_.]*\)" . \
     | grep -vE "\((initialValue *= *)?(true|false|null|[A-Za-z0-9_.]*\.(TRUE|FALSE))\)"
   ```

   Both halves of that pattern are load-bearing. The argument position has to be optional, because
   the default is as legally passed positionally as by name — and a codebase mixes the two, so an
   audit anchored on `initialValue = ` reports a clean screen while the twin declaration of the very
   setting you are auditing sits in another file, in the other spelling. The exclusion has to cover
   both spellings of a boolean for the reason in the trap above, or widening the match simply refills
   the listing with the flags it was meant to drop. `null` is excluded on different grounds: it is a
   not-yet-loaded sentinel rather than a default anyone declared twice.

4. The store's own fallbacks, to compare against step 3:

   ```bash
   grep -rn --include='*.kt' --exclude-dir=build "preferences\[.*\] ?: " .
   ```

5. By hand, and this is the test that finds it: switch the app to a language where two options of one
   setting read the same, choose the second of them, reopen the dialog. If the first is ticked — or
   the old value is — the round trip is going through the caption.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance 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.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall