Paint

How a node looks: fills, gradients, corners, borders, clipping, masks, shadows and the four blurs. Layout and per-kind properties are on Nodes; easing any of these values is on Animation.

column {
    padding = 16,
    spacing = 8,
    background = "#1E1E2EF2",
    radius = 12,
    border_width = 1,
    border_color = "#FFFFFF1A",
    shadow_color = "#00000099",
    shadow_blur = 18,
    shadow_offset = { x = 0, y = 8 },
    children = {
        text { content = "Battery", font_size = 14, foreground = "#CDD6F4" },
        text { content = "82% · 3 h 10 min left", foreground = "#A6ADC8" },
    },
}

A card: a translucent rounded fill, a hairline border and a soft shadow below it.

Terms

Who takes what

A property on a kind that does not take it is refused, naming the closest property the kind takes or, with none close, listing them all.

Every property can be a signal. A signal nested inside a table (a gradient stop, one border edge) is refused, so derive the whole table with :map. A malformed value fails the pass instead of drawing a default: the previous scene stays and the error goes to mantle log (runtime).

Colours

Colours are strings "#RRGGBB" or "#RRGGBBAA", hex digits in either case. There are no named colours and no short #RGB form.

Box properties

A uniform border (same width and colour on all four edges) on a round corner follows radius. A per-edge border, or any border on a scoop, draws as four straight rectangles with square corners:

local function tile(label, props)
    props.width, props.height, props.radius = 88, 56, 14
    props.background = "#313244"
    props.children = { text { content = label, foreground = "#CDD6F4", align_h = "Center", align_v = "Center" } }
    return rect(props)
end

return row {
    spacing = 12,
    children = {
        tile("Round", { border_width = 2, border_color = "#89B4FA" }),
        tile("Scoop", { corner_shape = "Scoop", border_width = 2, border_color = "#89B4FA" }),
        tile("Per-edge", { border_width = { bottom = 3 }, border_color = "#89B4FA" }),
    },
}

Gradients

background and mask take a gradient table.

background = {
    gradient = "Linear",
    angle = 90,
    stops = { { 0, "#CBA6F7" }, { 0.5, "#F38BA8" }, { 1, "#89B4FA" } },
}

local stops = { { 0, "#CBA6F7" }, { 0.5, "#F38BA8" }, { 1, "#89B4FA" } }

local function swatch(label, fill)
    return column {
        spacing = 6,
        children = {
            rect { width = 96, height = 64, radius = 8, background = fill },
            text { content = label, foreground = "#A6ADC8" },
        },
    }
end

return row {
    spacing = 12,
    children = {
        swatch("Linear, 90", { gradient = "Linear", angle = 90, stops = stops }),
        swatch("Radial", { gradient = "Radial", stops = stops }),
        swatch("Conic", { gradient = "Conic", stops = stops }),
    },
}

Clip

clip decides what a box cuts its children to.

A rounded clip draws in the order fill, children, border, so the border stays on top of children that reach the arc.

Mask

mask multiplies the alpha of the node’s own fill and border and of its whole subtree.

Name exactly one of source or a gradient. A masked box draws its subtree offscreen every repaint and always cuts children to its box (to radius too under clip = "Rounded"), even with clip = "None".

local items = {}
for i = 1, 12 do
    items[i] = rect { width = "Fill", padding = 10, radius = 8, background = "#313244",
        children = { text { content = "Row " .. i, foreground = "#CDD6F4" } } }
end

return column {
    width = 200,
    height = 240,
    spacing = 6,
    scroll = scroll("feed"),
    mask = {
        gradient = "Linear",
        stops = { { 0, "#00000000" }, { 0.08, "#000000" }, { 0.92, "#000000" }, { 1, "#00000000" } },
    },
    children = items,
}

A scrolling list whose rows fade out at the top and bottom edges.

Shadows

A shadow draws when shadow_color has alpha above 0 and at least one of shadow_blur, shadow_offset or shadow_spread is set. The terms are CSS’s box-shadow.

Non-box nodes (text, icon, image, …) have no box to cast, so their shadow is always the content’s: text gets a glyph-shaped shadow. The same unfilled, bordered box in each mode:

local function card(mode)
    return column {
        padding = 14,
        radius = 12,
        border_width = 1,
        border_color = "#89B4FA",
        shadow_mode = mode,
        shadow_color = "#000000",
        shadow_blur = 4,
        shadow_offset = { x = 5, y = 6 },
        children = { text { content = mode, font_size = 20, foreground = "#CDD6F4" } },
    }
end

return row {
    padding = 24,
    spacing = 24,
    background = "#585B70",
    children = { card("Box"), card("Content") },
}

"Box" casts the rounded box and cuts the shadow out under it; "Content" casts the border ring and the glyphs.

Blurs

Four properties blur four different things. Sigmas are in logical px, [0, 8192], 0 is off. source_blur is a fast box approximation; the others are Gaussian.

blur = true. Mantle sends the compositor a region, through ext-background-effect-v1, made of every blur = true box on the surface: rounded to radius (or scooped), cut by ancestor clips, moved by transforms, and dropped while the node is invisible or at opacity 0. It ignores mask. The compositor decides strength, noise, xray and whether to blur at all; a compositor without the protocol or its blur capability gives nothing, and no error. It is never inferred from a translucent background; the background alpha only decides how much of the blurred desktop shows through.

source_blur. The blur is baked into the decoded pixels, which are stored cropped to the box under fit = "cover", so it is exact there. Under "contain" or "stretch" the stored pixels are rescaled and the blur with them. Animated GIFs ignore it. Changing it re-decodes; under async = true the image draws nothing until that lands, and retain does not cover it (the source did not change). See image.

panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true, left = true, right = true },
    height = 36,
    exclusive = true,
    background = "#1E1E2E99",
    blur = true,
    child = row { width = "Fill", padding = { left = 12, right = 12 }, children = { clock } },
}

A bar whose 60% fill tints the compositor-blurred desktop behind it.

rect {
    width = 320,
    height = 180,
    children = {
        image { source = "/usr/share/backgrounds/default.png", width = "Fill", height = "Fill", async = true },
        row {
            align_h = "Center",
            align_v = "Center",
            padding = { left = 14, right = 14, top = 6, bottom = 6 },
            radius = 999,
            background = "#FFFFFF1F",
            border_width = 1,
            border_color = "#FFFFFF33",
            backdrop_blur = 12,
            children = { text { content = "12:45", font_size = 18, foreground = "#FFFFFF" } },
        },
    },
}

A frosted pill: the image is painted first, so the pill’s backdrop_blur blurs the image under its rounded shape, and the fill tints it. The same pattern over a full-screen image frosts a lock screen’s wallpaper.

Combining effects

One node paints in this order, each step over the last:

1. Backdrop (backdrop_blur): replaces the pixels under the box with their blur.
2. Shadow, when it is a gradient quad or a silhouette.
3. Body: fill, children in z order, border. With a mask or a clip = "Rounded" the body goes through an offscreen pass.
4. Layer: for content_blur or a layered shadow, the body is drawn offscreen, its shadow cast from it, then the body blurred.
5. Transform (scale, rotate, translate) wraps all of the above.

How do I…

Frosted glass panel

panel {
    id = "sheet",
    layer = "Top",
    anchor = { top = true, right = true },
    margin = 8,
    child = column {
        width = 280,
        padding = 16,
        spacing = 8,
        radius = 16,
        background = "#1E1E2EB3",
        border_width = 1,
        border_color = "#FFFFFF2E",
        blur = true,
        children = { text { content = "Wi-Fi", font_size = 14, foreground = "#CDD6F4" } },
    },
}

The compositor blurs the desktop under the rounded sheet only; the rest of the surface stays clear. A faint light border separates glass from glass.

Card that lifts on hover

local lifted = hover("card_hover")
column {
    hover = lifted,
    padding = 16,
    radius = 12,
    background = "#313244",
    shadow_color = "#00000099",
    shadow_blur = lifted:map(function(on) return on and 36 or 12 end),
    shadow_offset = lifted:map(function(on) return { x = 0, y = on and 20 or 6 } end),
    animate = { shadow_blur = 200, shadow_offset = 200 },
    children = { text { content = "Hover me" } },
}

hover drives the shadow and animate eases it. Leave room around the card: the parent clips the shadow.

Pill button

local hovered = hover("save_hover")
button {
    hover = hovered,
    padding = { left = 16, right = 16, top = 6, bottom = 6 },
    radius = 999,
    background = hovered:map(function(on) return on and "#89B4FA59" or "#89B4FA33" end),
    border_width = 1,
    border_color = "#89B4FA66",
    animate = { background = 150 },
    on_click = function() print("saved") end,
    children = { text { content = "Save", foreground = "#CDD6F4" } },
}

A radius past half the height makes the ends round whatever the label’s width.

Gradient border

rect {
    padding = 2,
    radius = 14,
    background = { gradient = "Linear", angle = 135, stops = { { 0, "#CBA6F7" }, { 1, "#89B4FA" } } },
    children = {
        column {
            padding = 14,
            radius = 12,
            background = "#1E1E2E",
            children = { text { content = "Pro", foreground = "#CDD6F4" } },
        },
    },
}

border_color takes only flat colours, so paint the gradient as an outer fill and cover all but a 2px ring with an opaque inner box. Keep the inner radius the outer radius minus the ring width.

Circular avatar

rect {
    width = 64,
    height = 64,
    radius = 32,
    clip = "Rounded",
    border_width = 2,
    border_color = "#89B4FA",
    children = { image { source = "/var/lib/AccountsService/icons/user", width = "Fill", height = "Fill" } },
}

clip = "Rounded" cuts the image to the circle, and the border paints over the image’s edge.

Dim the background behind a modal

panel {
    id = "modal",
    layer = "Overlay",
    anchor = { top = true, bottom = true, left = true, right = true },
    width = "Fill",
    height = "Fill",
    exclusive = "Ignore",
    keyboard_interactivity = "OnDemand",
    child = rect {
        width = "Fill",
        height = "Fill",
        children = {
            rect { width = "Fill", height = "Fill", background = "#11111B99" },
            column {
                align_h = "Center",
                align_v = "Center",
                width = 360,
                padding = 24,
                spacing = 8,
                radius = 16,
                background = "#1E1E2EE0",
                blur = true,
                shadow_color = "#00000080",
                shadow_blur = 32,
                children = {
                    text { content = "Log out?", font_size = 18, foreground = "#CDD6F4" },
                    text { content = "Unsaved work in open apps will be lost.", foreground = "#A6ADC8" },
                },
            },
        },
    },
}

A full-screen panel whose first child is a translucent scrim and whose second is the dialog. Dim with a colour rather than blur = true on the scrim: the compositor’s blur does not fade with opacity, so a fading scrim would blur at full strength until it hits 0.

Gotchas

See also: nodes, surfaces, animation, input, glossary.

Source: allowlist, parsers, paint style, paint order, canvas, effects, shapes, blur region, compositor push.