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/liquid-glass-backdrop.md
View on GitHub---
name: liquid-glass-backdrop
description: Build refracting "liquid glass" surfaces in Compose with a backdrop library, and avoid the three failures that waste the most time — a rim highlight that is directional by default and so goes nearly invisible on small round buttons, a backdrop source nested inside the glass it feeds, which is a render-feedback loop that stops the shader, and a source with nothing in it, which renders the control as a grey coin over a flat page. Covers the source/surface split, giving a flat page a ground worth refracting rather than dropping the effect, the white default tint that only suits forced-dark screens, the effect stack, keeping the press gesture observe-only, and the swap experiment that tells a geometry problem from a placement problem. Use when a glass surface renders as a flat rounded box or a grey coin, when the rim shows on a wide pill but not on a circular button, when its glyph disappears at light theme, or when the draw pass crashes inside the shader.
---
# Liquid glass: source, surface, rim
A backdrop library splits the effect in two. A **source** modifier records a composable's rendering
into a graphics layer; a **draw** modifier on the **surface** samples that recording, pushes it
through an effect stack, and paints the result behind itself:
```kotlin
// adapted
Modifier.drawBackdrop(
backdrop = backdrop,
shape = { shape }, highlight = { highlight },
effects = {
vibrancy()
colorControls(brightness = 0.05f, contrast = 1f, saturation = 1.5f)
blur(radius)
// refraction height below the inradius (minDimension / 2), so top and bottom refractions
// never meet at the medial axis — that meeting is the dark seam on a wide pill
lens(size.minDimension / 4f, size.minDimension / 2f, false)
},
// darken as the background brightens, or bright artwork washes the glass out to white
onDrawSurface = { drawRect(scrimColor.copy(alpha = darken)) },
)
```
Three moving parts, in order of trouble caused: the **rim highlight**, the **source/surface
relationship**, and the effect stack — the stack being a list of filters you tune by eye.
## Traps
**The rim highlight's default style is directional, not an outline.** This is why a wide pill looks
like glass and a 48 dp circular button beside it looks like nothing — same modifier, same parameters.
Read the default style's shader rather than guessing:
```glsl
// annotated — the library's own shader body, re-indented and `=`-aligned; the comments are added
float2 grad = gradSdRoundedRect(centeredCoord, halfSize, gradRadius); // outward edge normal
float2 normal = float2(cos(angle), sin(angle)); // one light direction
float d = dot(grad, normal);
float intensity = pow(abs(d), falloff);
return color * intensity;
```
Brightness at a point on the outline is the alignment between that point's **edge normal** and one
fixed direction. On a stadium an entire straight edge shares one axis-aligned normal, so both long
edges light to a constant at once — most of the outline, uniformly, which reads as a rim. On a circle
the normal sweeps every direction, so intensity runs `|cos(θ − angle)|`: full at two opposing points,
**zero at the two 90° away**, under 70% over half the circumference — nothing left on a 48 dp button.
Two independent levers fix it. **Swap the style** for the library's uniform one (a colour and a blend
mode; no angle, no falloff, therefore no direction). Or **widen the rim, keeping the directional
style**: `width` feeds `strokeWidth = ceil(width.toPx()) * 2`, so the 0.5 dp default is the thinnest
stroke the library draws and `Highlight(width = 1.dp)` puts back enough pixels for the surviving arc.
The audited tree ships the *second* at every site that reaches for a lever, keeping them matched to
the pills beside them as a style swap would not. In the 2.0.x line resolved here the default is white
at 0.5 alpha, additive, 45°, falloff 1; the uniform style white at 0.38 alpha, additive.
**The backdrop source must be a sibling of the glass, never its parent.** The source records what it
draws and the surface reads that recording while drawing itself, so a surface *inside* the source
makes the recording depend on its own output — the loop stops the shader in the draw pass:
```kotlin
// adapted — the source is the content column; the glass buttons are siblings placed with align()
Box(Modifier.fillMaxWidth()) {
Column(Modifier.fillMaxWidth().layerBackdrop(headerBackdrop)) {
Spacer(Modifier.height(48.dp)) // reserves the strip the buttons sit over
…artwork and text…
}
GlassIconButton(headerBackdrop, …, modifier = Modifier.align(Alignment.TopStart))
}
```
**A source that draws nothing gives the glass nothing to bend — and the cure is a ground, not a
retreat.** Over an empty region the output is the surface scrim and nothing else: on a flat page the
control renders as a grey coin, worse than no chrome at all. That is a full arc here — glass
introduced, then *removed* for a plain icon button with exactly that reasoning written into the
commit, then restored once the page had a ground worth refracting. The ground is a `matchParentSize()`
box carrying the page colour plus the page's ambient tone, and the source is **that box** — never the
content column, which is mostly transparent and rendered the control as a solid dark coin over a
tinted page. Where the content genuinely draws (a list whose first item is a full-width image header)
it is the right source, its strip reserved by a `Spacer`. The glass must also *float* over the
ground rather than ride the scrolling column, which scrolls it away on a flat page.
**The default tint assumes a forced-dark screen.** These controls are usually built first for screens
inside a forced-dark subtree, where a white glyph always sits over dark artwork and `Color.White` is
sound. On a theme-following page it is white-on-white at light theme — and the flat fallback an
off-setting swaps in is light too, so the glyph vanishes in both materials. Pass the scheme's
on-surface token instead; `force-dark-immersive-subtree` is why the donor screens never hit this.
**Run the discriminating experiment before changing the code.** When one glass widget works and
another does not, swap their positions: if the effect follows the *widget* the cause is its own
geometry (the rim trap above), if it follows the *position* it is what the source records there. Four
rebuilds went on plausible fixes first — widening the button to 96 dp (a longer edge catches more of
the sweep, so the rim *does* appear: a symptom, not a fix), shrinking the lens radii, moving the
source between a full-size box and the content column, and painting artwork in at low alpha.
**Keep the press gesture observe-only.** The glass scales up and draws a pointer-following glow on
press, and it wraps buttons that need their own clicks. The recogniser must never `consume()`, must
accept already-consumed downs (`awaitFirstDown(requireUnconsumed = false)`), and must bail when a
change *has* been consumed — or the surface animates while the button inside it stops responding.
**Check whether the library ships a variant for your other targets before writing a no-op actual.**
Assuming a shader-heavy effect is one-platform and stubbing the desktop `actual` leaves it dead code
there that nobody notices — it compiles and renders a plain rounded box. If the artifact is
multiplatform the abstraction has nothing to abstract: delete the `expect class`, keep a `typealias`
so call sites do not churn, and move the effect into common code — which the class blocked anyway.
## Verifying it
1. **Confirm the default rim is directional and the uniform one is not**, out of the dependency
cache, no build. The range starts at the uniform block, not at `half4 main`:
```bash
JAR=$(find ~/.gradle/caches -name '*backdrop*.jar' | head -1)
DEF=$(unzip -l "$JAR" | awk '/HighlightStyle\$Default\.class/{print $4}')
PLAIN=$(unzip -l "$JAR" | awk '/HighlightStyle\$Plain\.class/{print $4}')
unzip -p "$JAR" "$DEF" | strings -n 6 | sed -n '/uniform float2 size/,/return color/p'
unzip -p "$JAR" "$PLAIN" | strings -n 6 | grep -c 'angle\|falloff'
```
→ observed: `uniform float angle` and `uniform float falloff` declared, then the
`dot(grad, normal)` main quoted above; then `0` — the uniform style ships no shader source at all.
2. **List every backdrop source; read each one's enclosing block, and what it draws.**
`grep -rn 'layerBackdrop(' --include='*.kt' . | grep -v 'fun Modifier'`
→ observed: every hit is a `Box`/`Column` *sibling* of the glass it feeds — including the analytics
screen, whose source is the `LazyColumn` itself (first item an image header, so it draws), buttons
placed after it by `align()`. A source whose subtree holds a `drawBackdrop` for the same backdrop
is the crash; a bare transparent source is the grey coin.
3. **See which rim lever each call site reaches for.**
`grep -rn 'highlight = ' --include='*.kt' . | grep -v 'fun \|highlight: '`
→ observed: six sites pass `Highlight(width = 1.dp)` (the wider-rim lever, style left directional),
one bar passes `Highlight.Default.copy(alpha = …)`, nothing passes the uniform style. Two 48 dp
back buttons on the theme-following pair are on the bare default — the first ones to look at.
4. Resize one glass button between circle and wide pill, everything else unchanged: a rim appearing
only in the pill state is the highlight trap. If both levers rescue it, geometry is confirmed.
Related: `compose-desktop-runtime-hardening` (shader-adjacent crashes from the rendering backend
rather than your draw code) and `shell-background-is-not-scheme-background` (what a ground is made of).
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 |