05-styling/06-consistent-app-visual-structure.md

Consistent app visual structure

Vroq apps should follow a predictable visual structure so new screens and features feel like part of the same system.

Consistency in layout and spacing makes apps easier to extend and easier for LLMs to modify safely.

Typical screen structure

A typical screen layout should look like this:

page container
main vertical stack
clearly separated sections
consistent spacing between sections

Example pattern:

VStack(
  { gap: "xl", style: { padding: "32px", maxWidth: "900px", margin: "0 auto" } },

  HeaderSection(...),
  ContentSection(...),
  FooterSection(...)
)

This pattern keeps screens readable and avoids deeply nested layout wrappers.

Spacing rhythm

Spacing should follow a consistent rhythm using tokens such as:

xs
sm
md
lg
xl

Avoid arbitrary spacing values unless there is a clear visual need.

Section boundaries

Sections should be visually grouped using:

stack spacing
surface containers
card-style grouping

This makes it easier to scan the screen and easier to extract sections into separate files.

Avoid visual chaos

Avoid:

random spacing values across features
inconsistent container widths
mixing many layout strategies in one screen
deeply nested layout wrappers

These patterns make screens harder to reason about and harder to edit.

Final rule

Screens should follow a simple, predictable structure that makes UI hierarchy obvious and modifications safe.