# Layout System

## What is a Layout?

At its core, a **Layout** is a negotiation of space. It is the process where the system decides where to place a widget and how big that widget should be.

In Digia, you don't use absolute pixels (e.g., "Place this button at x=50, y=100"). Instead, you describe the **relationship** between widgets (e.g., "Place this button in the center of the screen").

## Why Understanding Layout Matters

Digia uses a **Server-Driven UI** model. You define the layout JSON once, and it renders using the native rendering engines of the target platform (Flutter, Android/Jetpack Compose, or iOS/SwiftUI).

While Digia handles the translation for you, understanding how these engines "think" helps you build interfaces that:

1. **Adapt Responsively**: Work on both an iPhone SE and an iPad Pro.
2. **Avoid Errors**: Prevent "Pixel Overflow" or "Clipped Content" issues.
3. **Perform**: Render efficiently without unnecessary calculations.

## Core Layout Principles

Modern UI frameworks all follow a similar pattern known as **Declarative Layout**.

### 1. Flutter

The motto of Flutter's layout engine is:

> **"Constraints go down. Sizes go up. Parent sets position."**

1. **Constraints Down**: A parent (like a Column) tells its child: *"You can be as wide as the screen, but only 50px high."*
2. **Sizes Up**: The child (like a Button) calculates its content and replies: *"Okay, I will be 100px wide and 50px high."*
3. **Parent Sets Position**: The parent then decides coordinates: *"I will place you at x=0, y=0."*

### 2. Android (Jetpack Compose)

Compose uses a similar logic called **Single Pass Layout**.

> **"Constraints flow down, measurements flow up."**

Parents pass `Constraints` to children, and children return `Placeables` (with a width and height). Parents are strictly forbidden from measuring a child twice, ensuring high performance.

### 3. iOS (SwiftUI)

SwiftUI follows a three-step process:

> **"Parent proposes a size. Child chooses its own size. Parent places the child."**

1. **Proposal**: The parent offers the child a size (e.g., the whole screen).
2. **Choice**: The child decides how much of that it needs (e.g., "I only need 200x50").
3. **Placement**: The parent respects that choice and positions the child (e.g., centered).

## The WYSIWYG Reality

Digia Studio acts as a **unified layout engine** in your browser. It mimics these native behaviors so that what you see is *mostly* what you get.

However, each platform has subtle text rendering engines, spacing defaults, and safe area calculations.

> \[!WARNING] **Always Test on Device** While the Digia Studio preview is 99% accurate, the final 1% (text kerning, shadow rendering, precise safe areas) depends on the physical device. Use **Digia Preview** on a real phone to verify your layouts before publishing.