maxrave-dev/kotlin-footguns / skills/compose-visuals-footguns
compose-visuals-footguns
VerifiedCompose 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.
references/shimmer-skeleton-loaders.md
View on GitHub---
name: shimmer-skeleton-loaders
description: A self-measuring shimmer modifier plus skeleton composables that stand in for a list while it loads — how the modifier learns its own size, why the base colour under the sweep is load-bearing, why the modifier order between clip and background changes what gets rounded, and why the skeleton's lazy lists must have scrolling switched off. Use when building loading placeholders, or when a shimmer renders as a flat block, has square corners under a rounded design, or pauses visibly between passes.
---
# Shimmer placeholders
The shimmer is one modifier. It measures itself, so a caller never passes a size — a placeholder is
just a `Box` with a width, a height, a shape and this on the end:
```kotlin
// adapted
fun Modifier.shimmer(): Modifier = composed {
val colors = LocalAppColors.current
var size by remember { mutableStateOf(IntSize.Zero) }
val transition = rememberInfiniteTransition(label = "Shimmer")
val startOffsetX by transition.animateFloat(
initialValue = -2 * size.width.toFloat(),
targetValue = 2 * size.width.toFloat(),
animationSpec = infiniteRepeatable(animation = tween(1000)),
label = "Shimmer",
)
background(
brush = Brush.linearGradient(
colors = listOf(colors.shimmerBackground, colors.shimmerLine, colors.shimmerBackground),
start = Offset(startOffsetX, 0f),
end = Offset(startOffsetX + size.width.toFloat(), size.height.toFloat()),
),
).onGloballyPositioned { size = it.size }
}
```
Skeletons built on it are ordinary layout — no framework, no library. Each is a hand-laid stack of
boxes at the sizes the real row will occupy, wrapped in the same list shape the real content uses.
## Traps
**Put `clip` before `background`, not after.** `clip` is a graphics layer that clips what is drawn
*after* it; a `background` to its left has already been painted, square. So
`.background(base).clip(shape).shimmer()` gives you a square base colour under a rounded sweep —
and looks fine on the day you write it, because the sweep is the visible half. The other order,
`.clip(shape).background(base).shimmer()`, rounds both. It is easy to end up with both orders in
one file; the verify grep below is exactly for that.
**Keep a solid base colour under the sweep — the first frame has no size.** `size` starts at
`IntSize.Zero`, so on the composition before the first layout pass `start` and `end` are the same
point and the gradient is degenerate: what it resolves to is an engine detail, not something to
reason about or rely on. The solid `.background(colors.shimmerBackground)` every call site paints
first is what *guarantees* a painted first frame, whatever the degenerate gradient does over it.
**Each call site animates independently.** `composed { }` materialises per use, so every placeholder
box holds its own `rememberInfiniteTransition` and measures its own width. Twenty boxes are twenty
unsynchronised animations — the sweeps will not line up across a row, and a wide box and a narrow
one beside it travel at different speeds because the travel range is a multiple of each box's own
width. If a screen needs one coherent wave across several boxes, hoist a single transition and pass
the phase down instead.
**The sweep is off the box for roughly half of each cycle.** Travel runs from `-2 × width` to
`+2 × width` while the band itself is one width across, so the band overlaps the box for about half
the cycle; a linear gradient clamps outside its stops, and both outer stops are the base colour, so
the rest of the cycle is a flat pause. That pause is the design here, not a bug — but if you want a
continuous ripple, narrow the travel range rather than speeding up the tween, which only makes the
same pause arrive sooner.
**The sweep is diagonal, and its angle follows the box's aspect ratio.** The gradient ends at
`(startOffsetX + width, height)`, so it runs corner-to-corner: near-horizontal across a short wide
title bar, steep down a tall square thumbnail. Inside one skeleton those angles differ visibly. If
the design calls for one angle everywhere, fix the `end` offset's `y` to a constant instead of the
measured height.
**Switch scrolling off on every lazy list inside a skeleton.** A skeleton holds an arbitrary,
invented number of fake rows standing in for a count nobody knows yet; there is nothing further down
to reach, and any scroll offset the user establishes is discarded the moment the real list — a
different list, with different keys — replaces it. Nested lazy lists also compete for the drag with
whatever scrolls outside them. `LazyColumn(userScrollEnabled = false)` on all of them.
**Derive placeholder sizes from the real row, not by eye.** The point of a skeleton is that nothing
moves when the data lands. Read the real row's thumbnail size, text line heights and paddings and
reuse those numbers; a placeholder that is 4 dp short produces a visible settle on every load, which
reads as jank rather than as a wrong constant.
**Shimmer colours do not belong in the material colour scheme.** The base and the highlight line are
two tokens with no scheme slot to sit in. Carry them in your own immutable colour holder exposed
through a composition local, with a light and a dark instance, so the placeholder tracks the theme
without a `if (isDark)` at every call site.
## Verifying it
Run these from the repository root against your skeleton file and the file holding the modifier.
1. **Find mismatched clip/background order.** List both and compare line numbers per box:
`grep -n 'clip(\|background(' <skeletonFile>`
→ observed: **two** placeholders had `background(` before `clip(` — at 33/35 and again at 136/138
— so their base colours are square, while every other pair in the file (56/58, 67/69, 78/80, …)
puts `clip(` first. One file, both orders, and the second offender is far enough down that reading
only the first few hits would have missed it: read the whole listing.
2. **Every lazy list in the skeleton has scrolling disabled.** Compare the two counts:
```bash
grep -c 'LazyColumn(\|LazyRow(' <skeletonFile>
grep -c 'userScrollEnabled = false' <skeletonFile>
```
→ observed: `3` and `3`. Any gap is a skeleton the user can scroll.
3. **The modifier measures itself rather than taking a size parameter.**
`grep -n 'fun Modifier.shimmer\|composed {\|onGloballyPositioned\|size.width' <modifierFile>`
→ observed: the `composed {` factory, the `onGloballyPositioned` write, and the reads of
`size.width` in both the animation bounds and the gradient end point. A shared extensions file
will surface unrelated hits from its other modifiers as well; match on the line numbers between
`fun Modifier.shimmer` and the next declaration.
4. Screenshot the skeleton and the loaded screen at the same scroll position and flip between them.
Anything that shifts is a placeholder measured by eye.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |