Spacing

Padding, Margin, and Gap control whitespace inside and between AutoLayout elements. They use the same Spacing struct under the hood and accept pixel or percentage values.

The three knobs

Property	Where it sits	Best for
Padding	Inside the element, between its bounds and its content area	Inset card content, give text breathing room
Margin	Outside the element, between it and its siblings	Push siblings apart without changing the parent’s gap
Gap	Between adjacent children of a Row/Column container	Even spacing in a flex layout

Picture: ASCII view of the box model

┌─── Margin ────────────────────────┐
│                                   │
│  ┌─── Element bounds ──────────┐  │
│  │                             │  │
│  │  ┌─── Padding ──────────┐   │  │
│  │  │                      │   │  │
│  │  │   content area       │   │  │
│  │  │                      │   │  │
│  │  └──────────────────────┘   │  │
│  │                             │  │
│  └─────────────────────────────┘  │
│                                   │
└───────────────────────────────────┘

Padding

Inset between the element’s bounds and its children’s content area. Reduces the “free” space children can occupy.

AutoUI.Create()
    .Column().WidthFill().HeightHug()
    .Padding(16)                              // 16 on all sides
    .Background(Color.gray)
    .Children(
        AutoUI.Create().Text("Hello")
    )
    .Build();

Four overloads, in order of common-ness:

.Padding(16)                                  // all four sides
.Padding(16, 12)                              // horizontal (L+R), vertical (T+B)
.Padding(16, 16, 8, 12)                       // left, right, top, bottom
.Padding(new Spacing(left, right, top, bottom)) // explicit Spacing struct

For percentage-based padding:

.PaddingPercent(5)                            // 5% of parent dimensions on each side

Percentage padding is useful for responsive layouts that scale with screen size — 5% on a 1920-wide canvas is 96px; on 1280, it’s 64px.

Margin

Outset between the element and its siblings. Same overloads as Padding:

.Margin(8)
.Margin(8, 4)
.Margin(8, 8, 0, 0)

When to use Margin vs Padding vs Gap:

Padding when you want space inside this element (between its bounds and its children).
Margin when you want space outside this element that depends on this element specifically (e.g. only the second child needs extra space above).
Gap when you want even spacing between all children of a Row/Column. Don’t use Margin for that — Gap is what you want.

Gap

The space between adjacent children in a Row or Column. Has no effect on Grid (use ColumnGap/RowGap instead — see Grid).

AutoUI.Create()
    .Row().WidthFill().HeightHug()
    .Gap(8)
    .Children(
        AutoUI.Create().Width(100).Height(40),
        AutoUI.Create().Width(100).Height(40),    // 8px to the left of this
        AutoUI.Create().Width(100).Height(40)     // 8px to the left of this
    )
    .Build();

Percentage variant:

.GapPercent(2)                                // 2% of parent's main-axis size

Gap with wrap

When .Wrap() is enabled, Gap controls the main-axis spacing (between siblings on the same line) and WrapGap controls the cross-axis spacing (between wrap lines).

AutoUI.Create().Row().WidthFill().HeightHug()
    .Wrap().Gap(8).WrapGap(12)               // 8px between cards on a line, 12px between lines
    .Children(...)
    .Build();

WrapGap(-1) (the default) means “use the same value as Gap.”

Spacing in Grid

Grid containers have their own gap properties:

AutoUI.Create().Grid().GridColumns(3)
    .ColumnGap(12)                            // horizontal spacing
    .RowGap(8)                                // vertical spacing
    .Build();

// or set both at once:
AutoUI.Create().Grid().GridColumns(3)
    .Gap(12)                                  // sets ColumnGap AND RowGap
    .Build();

Padding on a Grid container works the same as on Row/Column — it’s the inset between the grid bounds and the cell area.

Common patterns

Card with padded content

AutoUI.Create().Column().WidthFill().HeightHug()
    .Background(Color.gray)
    .Padding(16)                              // inset content from card edge
    .Gap(8)                                   // space between title and body
    .Children(
        AutoUI.Create().Text("Title", 18f),
        AutoUI.Create().Text("Body text")
    )
    .Build();

AutoUI.Create().Row().WidthFill().Height(48)
    .Padding(12, 0)                           // 12 horizontal, no vertical
    .Gap(8)                                   // space between buttons
    .Children(
        AutoUI.Create().Button("File", OnFile),
        AutoUI.Create().Button("Edit", OnEdit),
        AutoUI.Create().WidthFill(),          // spacer
        AutoUI.Create().Button("Help", OnHelp)
    )
    .Build();

Form field group with label margin

AutoUI.Create().Column().WidthFill().HeightHug()
    .Children(
        AutoUI.Create().TextSize().Text("Username")
            .Margin(0, 0, 0, 4),              // 4px below the label
        AutoUI.Create().WidthFill().Height(28).Background(Color.white)
    )
    .Build();

Overview — full property index
RowColumn — Wrap and main/cross axis behavior
Grid — ColumnGap / RowGap reference
AutoUI — builder reference