Skip to content

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

compose-visuals-footguns

Verified

Compose look-and-feel traps: theme and colour tokens, artwork palettes, gradients and scrims, shimmer, glass and particle effects, animation, image loading, charts and stats displays (percent changes, shares, buckets). Use when a visual bands, pops, freezes or misleads.

FileKindSize
SKILL.mdskill md25.2 KB
references/ambient-tone-layer-behind-flat-pages.mdmarkdown8.2 KB
references/angled-gradient-modifier.mdmarkdown8.3 KB
references/animated-gradient-border-ring.mdmarkdown7.9 KB
references/artwork-palette-theming.mdmarkdown6.6 KB
references/artwork-seeded-dynamic-scheme.mdmarkdown6.2 KB
references/chrome-drawn-outside-the-theme-scope.mdmarkdown8.5 KB
references/compose-capture-to-share-image.mdmarkdown8.8 KB
references/crossfade-container-sizes-to-the-visible-child.mdmarkdown7.3 KB
references/delta-absent-not-infinite.mdmarkdown6.5 KB
references/deterministic-title-placeholder-painter.mdmarkdown7.7 KB
references/dont-pre-animate-a-self-animating-property.mdmarkdown5.7 KB
references/dont-slice-one-circle-between-unrelated-measures.mdmarkdown6.7 KB
references/draw-outside-bounds-particle-modifier.mdmarkdown8.6 KB
references/equal-buckets-or-no-buckets.mdmarkdown6.1 KB
references/fit-icon-glyphs-to-the-live-area.mdmarkdown6.4 KB
references/flat-twin-shares-geometry-not-material.mdmarkdown8.4 KB
references/force-dark-immersive-subtree.mdmarkdown8.0 KB
references/gate-optional-effect-at-the-shared-primitive.mdmarkdown8.9 KB
references/hoist-the-flag-not-the-animation.mdmarkdown4.6 KB
references/image-fallback-url-retry-in-composition.mdmarkdown7.6 KB
references/liquid-glass-backdrop.mdmarkdown9.7 KB
references/material-symbols-icon-system.mdmarkdown8.0 KB
references/mosaic-arrangements-must-be-hole-free.mdmarkdown8.0 KB
references/overflow-tilted-browse-card.mdmarkdown7.4 KB
references/palette-state-parks-on-loading.mdmarkdown6.5 KB
references/partial-chart-must-say-so.mdmarkdown6.7 KB
references/self-normalised-axes-need-a-second-shape.mdmarkdown8.7 KB
references/semantic-color-tokens-compositionlocal.mdmarkdown7.5 KB
references/shell-background-is-not-scheme-background.mdmarkdown8.9 KB
references/shimmer-skeleton-loaders.mdmarkdown6.9 KB
references/slide-transition-defaults-to-half-a-height.mdmarkdown7.5 KB
references/smooth-scrim-gradient.mdmarkdown6.9 KB
references/text-brush-shimmer-sweep.mdmarkdown8.3 KB
references/touch-indication-bounds-and-alpha.mdmarkdown8.3 KB
references/transparent-chip-selection-signals.mdmarkdown8.4 KB
references/word-timed-karaoke-lyrics.mdmarkdown9.4 KB

references/palette-state-parks-on-loading.md

View on GitHub
---
name: palette-state-parks-on-loading
description: A palette generator that flips its state to Loading before its own suspension point reports no colour for the entire duration of every generation, and a generation cancelled part-way leaves it Loading with nothing to restart it — so any surface reading the palette directly paints its null fallback. Covers why the effect must be keyed on the bitmap alone (or on nothing at all), why a "already done" flag assigned after a suspension is not a record of done, and why the last resolved colour has to be held separately. Use when a screen tinted from artwork is sometimes right and sometimes black, when the same item tints correctly on one visit and not the next, or when a derived colour scheme silently sits on its fallback.
---

# The palette holder has no "still valid" state

Extraction is asynchronous, and the state holder that wraps it has three states — Loading, Success,
Error — with `palette` readable **only** in Success. The order inside `generate()` is what makes this
sharp: it assigns Loading *before* it suspends. So for the whole duration of every generation the
palette reads null, and null resolves to whatever your fallback is — usually black.

That is fine when a generation always finishes. It stops being fine the moment one can be cancelled,
because a cancelled generation never assigns Success and nothing re-runs it. The holder sits on
Loading, `palette` stays null, and the surface stays on its fallback for as long as the screen lives.

## Traps

**A restarting effect is a cancelling effect, and the key decides what counts as a reason.** Keyed on
the bitmap, a generation is only ever interrupted by a newer bitmap — which is exactly when
interrupting is correct. Keyed on anything coarser, unrelated changes cancel it:

- a **state container** whose other fields (an extra media payload, lyrics, metadata) land after the
  artwork does — deterministic, because the later field always arrives later;
- a **URL** that goes null and comes back to the *same* value across a reload — the key changed
  twice, so the effect restarts twice, even though nothing about the image moved.

Both look like harmless extra keys. Neither adds correctness, and both add a cancellation window.

**The most robust form is an effect that never restarts.** Key on nothing, and let a snapshot flow
decide what a new bitmap is:

```kotlin
// adapted — generation lives in its own effect that cannot be restarted from outside
LaunchedEffect(Unit) {
    snapshotFlow { state.bitmap }
        .filterNotNull()
        .distinctUntilChanged()
        .collectLatest { paletteState.generate(it) }
}
```

`distinctUntilChanged` drops the same-bitmap re-emissions that a recomposition produces, and
`collectLatest` cancels only for a genuinely different bitmap. Nothing else in the composition can
reach it.

**A guard assigned after a suspension is not a record of "done".** The common shape is
`generate(bm); generatedFor = url` inside an `if (generatedFor != url)`. On the cancelled path the
assignment never runs, so the flag and the holder now disagree about what happened — and which way
that fails depends on polarity and timing, which is the worst property a guard can have. If a flag is
genuinely needed, set it before the suspension and clear it on failure, or drop it and let
`distinctUntilChanged` do the deduplication structurally.

**Hold the last colour that actually resolved.** This is the fix that makes the rest of it stop
mattering, and it is one extra piece of state:

```kotlin
// adapted — reading paletteState.palette straight paints black for the whole of every generate()
var pageBackground by remember { mutableStateOf(Color.Black) }
LaunchedEffect(paletteState.palette) {
    paletteState.palette?.let { pageBackground = it.toBackground() }
}
```

Every surface reads `pageBackground`, never the holder. A generation in flight then changes nothing
on screen, and a cancelled one costs the *update*, not the colour.

**Cancellation is not the only way the palette never arrives.** If the bitmap itself never
materialises — a remote image whose load fails, so the success callback never fires — the generator
is never called at all and the same fallback is shown, with a completely different cause and the same
symptom. Check which one you have before fixing the effect; see
`image-fallback-url-retry-in-composition`.

**"Sometimes black" is the signature, and it is why this survives.** A deterministic failure gets
fixed. This one depends on which async result wins a race, so it reproduces on some items, on some
navigations, on a cold start but not a warm one. Treat *any* intermittent artwork-derived colour as
this until proven otherwise, rather than as a rendering glitch.

**Everything downstream of the palette inherits the fallback.** A single accent is obviously wrong
when it is wrong. A whole tonal scheme derived from the seed degrades to a plausible-looking scheme
in the app's default colour, which reads as a design decision — see `artwork-seeded-dynamic-scheme`,
and `artwork-palette-theming` for what to do when extraction genuinely returns nothing. A screen
painting itself from artwork is also a screen that must be forced dark regardless of the app theme
(`force-dark-immersive-subtree`); the two omissions land on the same screens and look nothing alike.

## Verifying it

1. **List every generation and the key of the effect around it.** Read the key on each line, not the
   call:

   ```bash
   grep -rn --include='*.kt' -B 6 "State.generate(" . | grep -v '/build/' \
     | grep -E "LaunchedEffect|State.generate\("
   ```

   Thirteen generations here. Eight are keyed on `bitmap` alone and one on `Unit` with a snapshot
   flow inside; every other key is a cancellation source that needs a reason.

2. **Find surfaces reading the holder directly instead of a held colour:**

   ```bash
   grep -rn --include='*.kt' -E "paletteState\.palette|\.palette\?\." . | grep -v '/build/'
   ```

   Hits inside a `LaunchedEffect` that assigns a remembered colour are the correct shape. A hit
   inside a modifier, a `background(...)` or a theme call paints the fallback during every
   generation.

3. **Reproduce it deliberately rather than waiting for it.** Add a temporary `delay(2000)` before
   `generate(...)`, then navigate onto the screen and immediately trigger whatever else updates that
   effect's key — a reload, a range change, a second data field arriving. With a coarse key the
   surface stays on its fallback; with the bitmap-only key it resolves. Remove the delay afterwards.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall