Gradients (Paint)

A gradient turns a brush into a color-source picker driven by modulation: instead of one flat color, the brush samples a position along a list of named color stops and uses the result as the dab's spectral color.

What a gradient is

A gradient is an ordered list of spectral color stops along a 1-D parameter t ∈ [0, 1]. t = 0 returns the first stop's color, t = 1 the last, and any value in between is the gradient's interpolation mode applied to the two adjacent stops.

The gradient's interpolation mode is a paint blend mode — usually K-M for pigment-like mixes or LabLerp for smoothly perceptual ramps. The mode is independent of your brush's deposit blend mode: the gradient produces a color; the brush composites it.

When you select a gradient, the brush's flat-color swatch is greyed out and the GradientT row in the modulation grid becomes active. Wire GradientT to pressure (or any other input) and the brush sweeps along the gradient as you paint — at full pressure the dab samples the gradient at t = High, at zero pressure at t = Low.

Bundled starter gradients

The first time you launch the paint app, the library is seeded with six starter gradients:

Greyscale — black → white linear ramp.
Sunset — deep navy → orange → yellow → pale gold.
Steel — dark blue-grey → bright blue-grey, low chroma.
Foliage — shadowed green → leaf → highlight chartreuse.
Skin — shadow umber → warm mid → highlight pink.
Rainbow — six fully-saturated hues cycling back to red.

You can edit or delete any of these — the Restore bundled button in the library activity adds back any of the six that are missing from your file, without touching ones you've already customized.

The gradient library listing the six bundled starters with live preview strips, stop counts and interpolation modes.

Selecting a gradient

Open the Brush panel and look at the Color group in the Stroke tab. The full-width gradient strip at the bottom of the group shows the active gradient (a diagonal dash when none is selected).

Left-click the strip to open the library activity in pick mode. Double-click (or press Enter on) the gradient you want and the panel closes with that gradient applied to the brush.
Right-click the strip for a context menu with Edit gradient… (or New gradient… when none is selected) and Clear selection. Clearing resumes the brush's flat color.

The Stroke tab with a gradient selected: the GradientT row is wired to pressure, the preset well and stroke preview render the sweep, and the Color group shows the active gradient strip.

Wiring `GradientT` to a modulation input

In the modulation grid, find the GradientT row. The cell at the intersection with Pressure (for example) sets the gradient sample point that the brush moves between as pressure varies.

GradientT Lo = 0, GradientT Hi = 1 — full stroke from first stop to last as you press harder.
GradientT Lo = 0.3, GradientT Hi = 0.7 — restricted to the middle of the gradient. Useful when only a subset of the stops matter to the stroke you're painting.
No modulation wired — the dab samples at GradientT Hi for every dab. A static Hi = 0.5 is a quick "pick the middle of this gradient as my brush color" shortcut.

Authoring a gradient

The GradientEditorActivity lets you build or modify a gradient.

Open the library activity (click the gradient name in the Color section).
Click New to create a fresh black → white starter, or click Edit on an existing entry's row.

In the editor:

The gradient editor on a three-stop Sunset variant: name + interpolation header, the live track with the selected stop highlighted, and the per-stop spectral strip, color swatch and opacity cell.

The track at the top shows the gradient as a strip with every stop drawn as a circle at its t position. The strip is rendered using the current interpolation mode, so the preview is always live.
Click an empty spot on the track to add a new stop at that t. The new stop inherits the gradient's current sample at that position.
Drag a stop to move it along the track. The first and last stops are pinned to t = 0 and t = 1 — they can be recolored but not removed or repositioned.
Click a stop to select it (the dot turns yellow). The selected stop's spectrum appears below the track — drag the spectral strip to paint band values directly, or click the color swatch to open the spectral picker; whichever pigment you pick replaces that stop's color.
Remove stop removes the selected stop (greyed out for the endpoint stops).
The Interpolation button on the header opens the blend-mode picker. Modes that carry a mix-ratio (K-M, LabLerp, BandWise variants) use it as the mix between adjacent stops; modes without a mix-ratio (SrcOver, Plus, Multiply…) fall back to a linear-RGB lerp at sample time.
Save persists the gradient to your library and emits the change so the Brush panel re-syncs. Done pops without saving; if there are unsaved edits a confirm prompt asks before discarding.

Managing the library

The GradientLibraryActivity is the entry point for everything list-shaped:

Action	Effect
New	Open the editor on a brand-new black → white starter.
Duplicate	Clone the selected gradient under a unique name; the copy is a separate library entry with its own uuid.
Restore bundled	Re-add any of the six bundled starters whose uuid is missing from your library. User-edited entries with the same uuid are never overwritten.
Edit (per-row)	Open the editor for that gradient.
Delete (per-row)	Removes the gradient after a confirm prompt. A brush currently using it silently falls back to flat color.

The Name column is editable in place — double-click to rename.

The library is stored at $XDG_CONFIG_HOME/<org>/<app>/gradients.yaml. It's a small human-editable YAML file; you can hand-edit, version-control, or copy it between machines. See reference/paint/gradients-yaml.md for the schema.