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/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).
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