Best practices

Structuring a screen: row vs col vs grid

Three layout elements cover almost every screen. Here’s how to pick between them without guessing.

Most screens are built from three layout elements. Picking the right one is mostly about which direction the content actually flows in — not a stylistic choice.

row and col — direction

row arranges children left to right; col arranges children top to bottom. Both belong to the same underlying stack family and both take gap and standard spacing/alignment attributes (see Spacing and gaps). Default to whichever matches the actual reading direction of the content — a settings list is a col of rows; a button toolbar is a row.

A settings screen: col of rows

<col gap="12">
  <row gap="8" role="list-item">
    <text>Notifications</text>
  </row>
  <row gap="8" role="list-item">
    <text>Privacy</text>
  </row>
</col>

grid — fixed multi-track layout

Reach for grid when content repeats across more than one axis at once — a photo gallery, a dashboard of cards, anything that would otherwise be a row of cols (or vice versa) faked to look like a grid. grid takes its own track and gap attributes and expresses the two-axis relationship directly instead of nesting stacks to fake it.

A card gallery: grid, not nested rows

<grid columns="3" gap="16">
  <rect role="card"/>
  <rect role="card"/>
  <rect role="card"/>
</grid>

A quick rule of thumb

Content shape	Use
One direction, one axis (a list, a toolbar)	`row` or `col`
Repeats across rows and columns at once	`grid`
A fixed positioned container or canvas root	`frame`

Nesting a row inside a col to fake a grid is exactly the kind of over-nesting the Clean CCAC level penalizes (see Common agent mistakes) — if the content is genuinely two-axis, grid is the correct element, not a workaround.

Frequently asked

When should I use grid instead of nesting row and col?

When content repeats across two axes at once — a card gallery, a dashboard — grid expresses that directly. Nesting row inside col to fake the same layout is unnecessary and gets flagged as over-nesting by the Clean CCAC level.

What’s the difference between row/col and the stack family mentioned in the spec?

row and col are the two directional members of the same underlying stack family — row lays out left to right, col lays out top to bottom. Both share the same spacing and alignment attributes.