# Layout and Composition

Nexamas UI layout should be expressed as intent, not manual pixel math. Use the Application window layout facades and semantic sizing values.

## Imports

```vbnet
Imports Nexamas.UI.Application
Imports Nexamas.UI.Layout
```

## Default page layout

Use `window.Controls.LayoutPage(...)` for most application pages:

```vbnet
window.Controls.LayoutPage(
    Sub(page)
        page.ApplicationPage(MASApplicationPageLayoutKind.Standard)
        page.Padding(MASLayoutSpacing.Spacious)
        page.Spacing(MASLayoutSpacing.Large)

        page.FullWidth(window.Controls.AddLabel("Orders"), MASSize.FillWidth)
        page.FullWidth(window.Controls.AddTextBox("Search"), MASSize.FillWidth)
        page.ActionGroup(
            Sub(actions)
                actions.AlignEnd()
                actions.Add(window.Controls.AddButton("Refresh"), MASSize.Default)
                actions.Add(window.Controls.AddButton("Create"), MASSize.Default)
            End Sub)
    End Sub)
```

## Application surface layout

Use `LayoutApplicationSurface(...)` when the screen has structural regions such as command bar, navigation, workspace, inspector, or footer:

```vbnet
window.Controls.LayoutApplicationSurface(
    Sub(surface)
        surface.Rhythm(MASApplicationSurfaceRhythm.Comfortable)

        surface.CommandBar(
            Sub(command)
                command.ActionGroup(
                    Sub(actions)
                        actions.Add(window.Controls.AddButton("New"))
                        actions.Add(window.Controls.AddButton("Save"))
                    End Sub)
            End Sub)

        surface.Navigation(MASApplicationSurfaceSideSize.Default,
            Sub(nav)
                nav.Add(window.Controls.AddListBox(New String() {"Dashboard", "Orders", "Settings"}))
            End Sub)

        surface.Workspace(
            Sub(workspace)
                workspace.ApplicationPage(MASApplicationPageLayoutKind.Surface)
                workspace.FullWidth(window.Controls.AddDataGrid(), MASSize.FillWidth)
            End Sub)
    End Sub)
```

## Semantic size and spacing

Prefer these vocabulary values over numeric layout constants:

| Concept | Public vocabulary |
|---|---|
| Size intent | `MASSize.Default`, `MASSize.Compact`, `MASSize.Large`, `MASSize.FillWidth`, `MASSize.HugContent` |
| Spacing intent | `MASLayoutSpacing.None`, `Tight`, `Small`, `Medium`, `Large`, `Spacious` |
| Size profile | `MASSizeProfileKind.Compact`, `Default`, `Comfortable`, `Large`, `TouchFriendly` |

Example:

```vbnet
window.Sizing.Use(MASSizeProfileKind.Comfortable)
window.Sizing.Refresh()
```

## Chrome reservation

When using standard chrome, let the shell reserve space:

```vbnet
window.Shell.AttachStandardTopBar("Nexamas App")
window.Controls.AddMenuBar(
    Sub(menu)
        menu.AddAction("File", "New", "file.new")
        menu.AddAction("File", "Exit", "file.exit")
    End Sub)
```

Do not manually position page content under the TopBar or MainMenuBar. Let retained layout and shell reservations move together.

## Avoid

Avoid direct dependencies on internal layout engines, layout nodes, responsive resolver internals, diagnostics report classes, or consumer-owned screen coordinate systems.

## Related pages

- [Application and window lifetime](application-and-window-lifetime.md)
- [Controls and component factories](controls-and-component-factories.md)
- [Layout and sizing guide](../developer/layout-and-sizing.md)
- [Layout/size reference](../reference/layout-size-surface.md)

## Evidence

- `MASSystem/Application/Facade/MASApplicationWindowControls.LayoutPage.vb`
- `MASSystem/Application/Facade/MASApplicationWindowControls.ApplicationSurface.vb`
- `MASSystem/Application/Facade/MASApplicationLayoutPageBuilder.vb`
- `MASSystem/Application/Facade/MASApplicationSurfaceLayoutBuilder.vb`
- `MASSystem/Layout/SizeLayoutSystem/`