makepad-2-0-layout – Coding skill for AI agents

Limitations

• Verify against current Makepad 2.0 docs; upstream APIs change frequently.
• Do not run bundled scripts without explicit user approval.

When to Use

• Build or diagnose Makepad layouts using the project's installed Splash/script DSL.
• Investigate sizing, flow, clipping, scrolling or overlay-placement problems.

First identify the exact Makepad revision and DSL in the project. These sketches assume the imported 2.0-style syntax and are not compiled test fixtures; do not migrate a working application wholesale to match them. See the [official Makepad repository](https://github.com/makepad/makepad) for matching widget/source examples.

Makepad 2.0 Layout System

Makepad uses a layout turtle system -- not CSS flexbox, not CSS grid. The turtle walks

through children one by one, placing each widget according to two core concepts:

• Walk -- how a widget sizes itself (width, height, margin)
• Layout -- how a container arranges its children (flow, spacing, padding, align)

Every container widget (View, SolidView, RoundedView, ScrollYView, etc.) has both Walk

properties (its own size) and Layout properties (how it lays out children).

---

Walk System (Widget Sizing)

Walk controls how an individual widget claims space inside its parent.

width / height

| Syntax | Meaning |

|--------|---------|

| width: Fill | Fill all remaining horizontal space (default) |

| width: Fit | Shrink to fit content |

| width: 200 | Fixed 200 pixels |

| width: Fill{min: 100 max: 500} | Fill with constraints |

| width: Fit{max: Abs(300)} | Fit content, capped at 300px |

| height: Fill | Fill all remaining vertical space (default) |

| height: Fit | Shrink to fit content |

| height: 100 | Fixed 100 pixels |

use mod.prelude.widgets.*

// Fill: takes all available width
View{
    width: Fill height: Fit
    flow: Down
    Label{text: "I stretch to fill the width"}
}

// Fit: shrinks to content
View{
    width: Fit height: Fit
    padding: 10
    Label{text: "I am only as wide as this text"}
}

// Fixed: exact pixel size
View{
    width: 300 height: 200
    Label{text: "I am exactly 300x200 pixels"}
}

// Constrained Fill: fills but within bounds
View{
    width: Fill{min: 200 max: 600} height: Fit
    flow: Down padding: 16
    Label{text: "I fill available space but stay between 200-600px"}
}

CRITICAL: height: Fit on Containers

This is the number one layout bug in Makepad.

The default height is Fill. When your output renders inside a Fit container,

Fill inside Fit creates a circular dependency and resolves to 0 pixels.

A symptom can be zero or unexpected height; inspect the actual parent/child constraints rather than assuming every invisible widget has this cause.

**Rule: ALWAYS set height: Fit on every View, SolidView, RoundedView, and similar

container unless the parent has a fixed or Fill height.**

// CORRECT -- height: Fit makes the container visible
View{
    width: Fill height: Fit
    flow: Down padding: 10
    Label{text: "I am visible"}
}

// WRONG -- defaults to height: Fill, resolves to 0px, invisible
View{
    width: Fill
    flow: Down padding: 10
    Label{text: "I am invisible (0px tall)"}
}

Exceptions where height: Fill is acceptable:

1. Inside a fixed-height parent:

View{
    height: 400
    View{
        height: Fill
        Label{text: "I fill the 400px parent"}
    }
}

2. Inside a height: Fill chain that ultimately reaches a known size (e.g., Window body).

3. A ScrollYView needs a bounded viewport. height: Fill inside a known-height parent is one option; an explicit fixed/constrained height is also valid.

margin

Margin adds space around the outside of a widget.

// Uniform margin on all sides
Label{text: "Hello" margin: 10}

// Selective margin with Inset
Label{
    text: "Indented"
    margin: Inset{top: 5 bottom: 5 left: 20 right: 20}
}

// Zero margin (note the trailing dot for float literal)
Label{text: "Flush" margin: 0.}

---

Layout System (Child Arrangement)

Layout controls how a container positions its children.

flow (Direction)

| Syntax | Meaning | CSS Equivalent |

|--------|---------|----------------|

| flow: Right | Left-to-right, single line (default) | flex-direction: row |

| flow: Down | Top-to-bottom, single column | flex-direction: column |

| flow: Overlay | Stack children on top of each other | position: absolute stacking |

| flow: Flow.Right{wrap: true} | Left-to-right with wrapping | flex-wrap: wrap |

| flow: Flow.Down{wrap: true} | Top-to-bottom with wrapping | column wrap |

use mod.prelude.widgets.*

// Vertical stack (most common)
View{
    width: Fill height: Fit
    flow: Down spacing: 10
    Label{text: "First"}
    Label{text: "Second"}
    Label{text: "Third"}
}

// Horizontal row
View{
    width: Fill height: Fit
    flow: Right spacing: 10
    Label{text: "Left"}
    Label{text: "Center"}
    Label{text: "Right"}
}

// Overlay -- children stacked on top of each other
View{
    width: Fill height: 200
    flow: Overlay
    Image{width: Fill height: Fill fit: ImageFit.Biggest}
    View{
        width: Fill height: Fit
        align: Align{x: 0.5 y: 1.0}
        padding: 10
        Label{text: "Caption overlay" draw_text.color: #fff}
    }
}

// Wrapping flow -- like a tag cloud or grid of cards
View{
    width: Fill height: Fit
    flow: Flow.Right{wrap: true}
    spacing: 8
    padding: 10
    Label{text: "Tag 1" margin: 4}
    Label{text: "Tag 2" margin: 4}
    Label{text: "Tag 3" margin: 4}
    Label{text: "Tag 4" margin: 4}
}

spacing

Gap between children. A single number applies uniformly.

View{
    flow: Down spacing: 12
    Label{text: "12px gap below me"}
    Label{text: "12px gap above and below me"}
    Label{text: "12px gap above me"}
}

padding

Inner space between the container edge and its children.

// Uniform padding
View{
    width: Fill height: Fit
    padding: 20
    Label{text: "20px padding on all sides"}
}

// Selective padding with Inset
View{
    width: Fill height: Fit
    padding: Inset{top: 10 bottom: 10 left: 24 right: 24}
    Label{text: "Different padding per side"}
}

align (Child Alignment)

Alignment positions children within the remaining space of the container.

Values range from 0.0 (start) to 1.0 (end) on each axis.

Alignment Reference Table

| Shorthand | Equivalent | Description |

|-----------|-----------|-------------|

| Center | Align{x: 0.5 y: 0.5} | Center on both axes |

| HCenter | Align{x: 0.5 y: 0.0} | Horizontal center, top-aligned |

| VCenter | Align{x: 0.0 y: 0.5} | Left-aligned, vertical center |

| TopLeft | Align{x: 0.0 y: 0.0} | Top-left corner (default) |

| Align{x: 1.0 y: 0.0} | -- | Top-right corner |

| Align{x: 0.0 y: 1.0} | -- | Bottom-left corner |

| Align{x: 1.0 y: 1.0} | -- | Bottom-right corner |

| Align{x: 0.5 y: 1.0} | -- | Bottom center |

use mod.prelude.widgets.*

// Center everything
View{
    width: Fill height: 300
    align: Center
    Label{text: "I am centered"}
}

// Horizontal center only (children flow from top)
View{
    width: Fill height: Fit
    flow: Down
    align: HCenter
    Label{text: "I am horizontally centered"}
}

// Vertically center children in a horizontal row
View{
    width: Fill height: 60
    flow: Right spacing: 10
    align: Align{y: 0.5}
    Label{text: "Vertically centered" draw_text.text_style.font_size: 14}
    Label{text: "Small text" draw_text.text_style.font_size: 9}
}

clip_x / clip_y

Controls whether overflowing content is clipped.

// Clip overflow (default behavior)
View{
    width: 200 height: 100
    clip_x: true
    clip_y: true
    Label{text: "Very long text that will be clipped at the container boundary"}
}

// Allow overflow to be visible
View{
    width: 200 height: 100
    clip_x: false
    clip_y: false
    Label{text: "This text can overflow beyond the container"}
}

Important boundary: clip_x: false / clip_y: false only allow a local child to

paint outside its parent. They do NOT turn that child into a true window-level overlay.

If the UI element is a popup/menu/tooltip that should float independently of the local

layout tree, use a top-level Modal/overlay owner instead of relying on local overflow.

Overlay Popups: walk.abs_pos vs margin

For popup-style positioning inside an overlay (Modal, tooltip layer, popup owner),

prefer walk.abs_pos over runtime margin tweaks.

• margin is layout spacing. It is best for nudging normal flow children.
• walk.abs_pos is an explicit turtle anchor for overlay-style placement.
• button.area().clipped_rect(cx) gives you the trigger's actual screen-space rect,

including view_shift and clipping.

• For overlay content, compute the popup's absolute screen-space target, then write

that into popup.walk.abs_pos = Some(dvec2(x, y)).

// Sketch: define popup_height from measured content; clamp

… (full content is in the download package)