Angled Gradient Modifier Agent Skill

Angled gradient background

Brush.linearGradient takes two points, not an angle. So "a gradient at 30°" is really the question

*where do the two endpoints go so the ramp completes exactly across the box at 30°*, and the answer

depends on the box's aspect ratio — which is why the same brush cannot be built once at composition

time. The whole thing lives inside a draw modifier, where the size is known.

// adapted (guard clauses trimmed; see Traps for the ones that were removed)
fun Modifier.angledGradientBackground(colors: List<Color>, degrees: Float) =
    this.then(
        if (colors.size < 2) Modifier else Modifier.drawBehind {
            val (x, y) = size
            val gamma = atan2(y, x)                 // angle of the box's own corner
            if (gamma == 0f || gamma == (PI / 2).toFloat()) return@drawBehind

            val degreesNormalised = (degrees % 360).let { if (it < 0) it + 360 else it }
            val alpha = (degreesNormalised * PI / 180).toFloat()

            val gradientLength = when (alpha) {
                in 0f..gamma, in (2 * PI - gamma)..2 * PI -> x / cos(alpha)   // exits a vertical edge
                in gamma..(PI - gamma).toFloat()          -> y / sin(alpha)   // exits a horizontal edge
                in (PI - gamma)..(PI + gamma)             -> x / -cos(alpha)
                in (PI + gamma)..(2 * PI - gamma)         -> y / -sin(alpha)
                else                                      -> hypot(x, y)      // unreachable; keep it
            }

            val offsetX = cos(alpha) * gradientLength / 2
            val offsetY = sin(alpha) * gradientLength / 2
            drawRect(
                brush = Brush.linearGradient(
                    colors = colors,
                    start = Offset(center.x - offsetX, center.y - offsetY),
                    end = Offset(center.x + offsetX, center.y + offsetY),
                ),
                size = size,
            )
        },
    )

The formula is one line of trigonometry worth understanding rather than copying. γ = atan2(h, w)

is the angle at which the ray from the centre passes through the box's corner, so it is exactly the

boundary between "this ray leaves through a vertical edge" and "…through a horizontal edge". In the

vertical-edge case the length is w / |cos α|, so the horizontal half-offset is w/2 — the endpoint

sits *on* the edge by construction — and the other coordinate is (w/2)·tan α, which the range test

guarantees is at most h/2.

Traps

Rotating the diagonal overshoots, and truncating to the edge distorts the angle. The tempting

shortcut is to take a vector of length hypot(w, h)/2 and rotate it. That length is only correct at

the four corners: elsewhere the distance from the centre to the boundary is

min(w / 2|cos α|, h / 2|sin α|), which is strictly smaller, so the endpoint lands outside the box

and only the middle of the ramp is visible — a gradient that never reaches either end colour.

Clipping the overshooting point back to the nearest edge fixes the overshoot but moves the point

sideways, so the line between the endpoints is no longer at the angle you asked for.

Normalise the angle before you compare it. Kotlin's % keeps the sign of the dividend, so

-30f % 360 is -30f and falls through every range test into the fallback branch. Add 360 when the

remainder is negative.

A degenerate box gives a zero-length gradient, not a division by zero. γ collapses to 0 (zero

height) or π/2 (zero width), and the branch the angle then selects is the one whose *numerator* is

the collapsed dimension — so the length comes out 0 and both endpoints land on the centre. A true

0/0 needs the divisor to be exactly zero as well, which the Float π these angles are built from

does not deliver. Bail out on γ anyway: nothing can be drawn, and boxes really do get measured at

zero before they have a size.

Keep the unreachable else. The four ranges cover [0, 2π] mathematically, but they are

compared in floating point with inclusive bounds, and γ is a Float while the π-derived bounds

are Double. Drop the else and this does not compile — a when used as an expression must be

exhaustive — and the diagonal is a harmless answer for whatever the ranges somehow miss.

Angles are clockwise on screen, because y grows downward. 0° runs left→right, 45° runs

top-left→bottom-right, 90° runs top→bottom. Porting angles from a design tool that measures

counter-clockwise means negating them — which the normalisation trap above is what makes safe.

Guard colors.size < 2 rather than finding out what your renderer does with one stop. A single

colour is a caller bug — a "gradient" with one end — and the cost of the guard is one comparison.

The axis-aligned directions need none of this. Brush.linearGradient substitutes the box's size

for infinite endpoint coordinates: on ui-graphics-android 1.12.0-alpha03 its createShader tests

all four coordinates against Float.POSITIVE_INFINITY and swaps in size.width / size.height.

Brush.linearGradient(colors, start = Offset.Zero, end = Offset(Float.POSITIVE_INFINITY, 0f))  // left → right
Brush.linearGradient(colors, start = Offset.Zero, end = Offset(0f, Float.POSITIVE_INFINITY))  // top → bottom
Brush.linearGradient(colors, start = Offset.Zero, end = Offset.Infinite)  // the box DIAGONAL, not 45°

The third line is the trap inside the shortcut. Offset.Infinite is infinite in *both* coordinates,

so both get substituted, the endpoint lands on the far corner, and the ramp runs at atan2(h, w) —

the box diagonal, whose angle follows the aspect ratio and is 45° only on a square. That is what

Verify #4 exposes; a real 45° elsewhere needs the arithmetic above. Check it against the artifact:

AAR=$(find ~/.gradle/caches/modules-2 -path '*ui-graphics-android*' -name '*.aar' | sort -V | tail -1) \
  && echo "$AAR" && D=$(mktemp -d) && unzip -oq "$AAR" classes.jar -d "$D" \
  && unzip -oq "$D/classes.jar" -d "$D/cls" \
  && javap -c -p -classpath "$D/cls" androidx.compose.ui.graphics.LinearGradient \
     | sed -n '/createShader/,/^  public/p' | grep -c "float Infinityf"

Expect 4, one comparison per endpoint coordinate — the count on 1.12.0-alpha03. sort -V picks the

newest *cached* version, not necessarily the one your build resolves, so read the echoed path. Reach

for the angle math when the design needs an angle that is not axis-aligned, or when it is animated.

Do not also set a background(...) colour underneath. drawBehind paints on every draw pass, so

a second opaque layer behind it is invisible work. On a browse tile this modifier *is* the

background — see overflow-tilted-browse-card.

Verifying it

• Find every call site and check the angle constants against the clockwise convention above:

   grep -rn --include='*.kt' "angledGradientBackground(" . | grep -v '/build/'

• Find hand-rolled endpoint arithmetic that should be using the modifier instead — any

Brush.linearGradient whose start/end are computed rather than Offset.Zero/Offset.Infinite:

   grep -rn -A6 --include='*.kt' "Brush.linearGradient(" . | grep -v '/build/' | grep -E "start =|end ="

• Prove the endpoints land on the edge rather than trusting the eye: give the gradient two

maximally different colours (pure red to pure blue, no alpha) and check that both pure colours

are visible in the corners of the box. A ramp whose endpoints overshoot shows only muddy purple.

• Resize the box from square to very wide and back while the gradient is on screen. The visible

angle must not change — that is the entire point of the per-quadrant branch, and it is the one

thing a fixed-endpoint gradient gets wrong.