05-styling/03-layout-patterns.md

Layout patterns

Layout patterns

Vroq apps should use consistent layout patterns so screens feel related and are easy to extend.

Prefer composing layouts with Vroq layout components before inventing custom wrapper structures.

Preferred layout tools

Prefer these tools first:

• VStack
• HStack
• Spacer
• Grow
• ScrollView
• existing surface and container components

These give a consistent visual and structural language across apps.

Layout rules

• use stack-based layout first
• keep top-level screens visually simple
• use spacing tokens and standard gaps
• prefer one clear primary content flow per screen
• avoid deeply nested layout wrappers unless they add clear structure

Screen structure

A typical screen should have:

• outer page container
• one main content stack
• clearly grouped sections
• consistent spacing rhythm

When to introduce custom layout wrappers

Introduce a custom layout wrapper only when:

• the layout is reused
• the structure is complex enough to deserve a name
• repeated inline layout code would make screens harder to read

Final rule

Prefer simple, named, stack-based layout patterns that make screens easy to read and easy to modify.