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/compose-capture-to-share-image.md

View on GitHub
---
name: compose-capture-to-share-image
description: Render a composable off-screen into an ImageBitmap so a button can save or share it as a picture — a capture primitive ported into common code rather than pulled in as a platform-only dependency, a max-width ceiling standing in for a fixed output size, artwork that has to already be resolved before the button is even reachable, and an Android MediaStore save gated behind a permission that the same feature's Desktop save never needs. Use when a "share as image" feature exports a blank or half-drawn picture, when the exported picture comes out a different size on every device, or when saving works on some Android versions and fails silently on others.
---

# Capturing a composable to a shareable image

Three pieces, each an expect/actual pair except the capture itself:

1. A `capturable()` modifier plus `CaptureController` — common code, no platform split — that
   records a composable's own draw pass into a `GraphicsLayer` and hands it back as an `ImageBitmap`
   on demand.
2. `ImageBitmap.toPngByteArray()` — PNG, not whatever format the app's existing bitmap-to-bytes
   function already produces.
3. `saveImageToDevice()` / `shareImage()` — MediaStore plus a share sheet on Android, a downloads
   write plus "reveal in the file manager" on Desktop.

```kotlin
fun Modifier.capturable(controller: CaptureController): Modifier = this then CapturableModifierNodeElement(controller)

// inside the modifier node
override fun ContentDrawScope.draw() {
    currentGraphicsLayer.record { this@draw.drawContent() }
    drawLayer(currentGraphicsLayer)
}
```

The content draws exactly as before — the layer is recorded, then drawn straight onto the visible
canvas — so attaching this to a node changes nothing about how it looks until something actually
calls `captureAsync()`.

## Traps

**A capture library with no Kotlin Multiplatform metadata may still be portable — check what it
imports before ruling it out.** A well-known capture library for this exact job ships a single
Android `.aar` with no KMP metadata, so a KMP build's non-Android target cannot resolve it as a
dependency — yet its code is one dead Android import on a KDoc reference and nothing else; every call
that runs is `androidx.compose.ui.graphics.layer`, already common-code-safe. Reading the small number
of files it takes to port a rejected dependency beats assuming "Android-only artifact" means
"Android-only code" and writing the mechanism from scratch.

**The capture request travels through a `Channel`, not a hot `Flow`.** A request fired the instant a
controller is created can arrive before the drawing node attaches and starts collecting; a hot
`SharedFlow` drops that emission and the caller's `Deferred` never completes — it hangs, silently,
with no exception to grep for. An unbounded `Channel` buffers it instead, so whichever comes first —
the attach or the request — the other still gets served:

```kotlin
private val requests = Channel<CaptureRequest>(capacity = Channel.UNLIMITED)
```

**Assuming the capture needs a fixed pixel size is backwards — a max-width ceiling is what makes the
image legible on every device.** A literal fixed width clips on a phone smaller than it and wastes
space on one larger. Give the captured composable a ceiling (`Modifier.widthIn(max = ...)`) instead
and let the capture take whatever width composition produced. The ceiling's job is capping wide
windows, not scaling every device differently: this codebase's own `ShareLyricsCardMaxWidth = 340.dp`
KDoc notes 340dp does not fit a 360dp phone's 20dp gutters, so a phone and a tablet alike land on the
identical 340dp card once the window clears ceiling-plus-gutters — dp size stops moving there, and
only density varies further. Only a window narrower than that actually shrinks the card.

**The image handed to the captured subtree must already be resolved before the share button is even
reachable.** A capture fires synchronously off a click; a `Painter` or async image loader that is
still fetching over the network at that instant gets captured as whatever it draws while empty — a
blank square, not a retry. The fix is not "await the load inside the capture flow": it is structural.
Pass the composable an `ImageBitmap` that some other part of the same screen already resolved for a
different purpose (a blurred backdrop, a dominant-color scan) — the capture entry point does not
exist on a screen where nothing has decoded the artwork yet, so there is nothing left to wait for.

**A capture is the card, never the chrome around it.** The composable wrapped in `capturable()` must
be exactly the surface you intend to hand someone — a progress bar or a save/share row rendered above
or below it is not part of the picture the user meant to send. Apply the modifier to the innermost
content node, not to a container that also lays out controls.

**Convert to PNG through a new function, not by changing what the existing one returns.** Flat colour
behind crisp text is exactly what JPEG's block-based encoding ring-artifacts hardest, and JPEG has no
transparency — a rounded corner comes out filled black instead of clipped. If an existing
`toByteArray()` already returns JPEG bytes and something else in the app still calls it, redefining
its format silently changes every existing caller's output. Add `toPngByteArray()` alongside it.

**Saving to shared storage and sharing through the app's own cache are different trust boundaries, and
only one of them can be refused.** Android's share path writes to the app's cache directory and hands
a `FileProvider` URI to the system chooser — no permission involved, because nothing left app-private
storage. Saving inserts a row into `MediaStore.Images`, which needs a runtime-granted
`WRITE_EXTERNAL_STORAGE` only below API 29; scoped storage from API 29 on lets an app insert its own
new image with no permission at all. Cap the manifest declaration to match
(`android:maxSdkVersion="28"`) — an uncapped permission next to code that only ever requests it below
29 is a declaration nothing in the app can still trigger, and one a permission review answers for on
every OS version regardless. `app-backup-to-zip-mediastore` writes the same zero-permission MediaStore
path on API 29+; this feature is the one that also has to carry the pre-29 half.

**Desktop has no share sheet and no reliable "reveal and select this exact file."** The honest
substitute is: write the file to the downloads folder, then open its containing folder. `Desktop.open`
is tried first but is not guaranteed to work even when correctly probed at start-up — see
`compose-desktop-runtime-hardening` for why that probe has to run before any native library load — so
a per-OS command fallback belongs behind it: `open -R <file>` on macOS, `explorer /select,<file>` on
Windows, and on Linux just the containing folder via `xdg-open`/`gio open`, because no Linux file
manager agrees on a flag for "open this folder with that one file selected."

## Verifying it

Run these from the app repository root — paths below are this codebase's; adapt them to your layout.

1. **The shared capture code has no platform import** — the "ported, not Android-only" claim:

   ```bash
   grep -n "^import android\.\|^import java\.awt" composeApp/src/commonMain/kotlin/com/maxrave/simpmusic/ui/component/capture/Capturable.kt
   ```

   Pass condition: no output. The escaped dot matters — `android` without it also matches every
   `androidx.*` import, which is common-code-safe and not what this check is for.

2. **The composable inside the capture region never loads its own image:**

   ```bash
   grep -n "AsyncImage\|rememberAsyncImagePainter\|SubcomposeAsyncImage" composeApp/src/commonMain/kotlin/com/maxrave/simpmusic/ui/component/lyrics/ShareLyricsCard.kt
   ```

   Pass condition: no output — artwork must arrive as an already-decoded bitmap parameter.

3. **The manifest permission and the runtime gate agree** (cwd `androidApp/src/main` for this one):

   ```bash
   grep -A1 "WRITE_EXTERNAL_STORAGE" AndroidManifest.xml
   ```

   Pass condition: `android:maxSdkVersion` appears in that tag, at the same API level your runtime
   check branches on — a bare declaration with no ceiling is the two drifting apart.

4. **PNG and the app's existing byte-array function are two functions, not one that changed shape:**

   ```bash
   grep -rn "toByteArray()\|toPngByteArray()" --include="*.kt" . | grep -v '/build/'
   ```

   Pass condition: call sites for both names exist somewhere in the tree — a caller still on the old
   name depends on the old format, which is why it has to keep working.

5. Capture the same screen at a window narrower than the ceiling plus its own gutters (a 360dp phone)
   and one wider (a tablet). The narrow capture's dp width must come in under the ceiling; the wide
   one must land exactly on it — two wide captures differing only by density is correct, not a bug.
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