Grouping by space
beginner·7 min·Markdown for agents
What this lesson teaches
Show what belongs together with space before lines or boxes, keep controls looking like controls, and line everything up on a few shared edges.
This form has two groups, and right now you can't tell. Every gap is 16px. Drag the second slider to 32px.
Profile
Notifications
Suddenly there are two sections, and you never added a line, a card or a heading color. That's , and it's the cheapest structure in design.
Space, then shape, then line
Our eyes read things that sit close together as one group. Designers call it . A divider, a card and a tinted background all say "these belong together"; space says it without adding a single pixel of ink.
The skill's order, from Jakub Krehel's layout rules:
Space
The gap between groups is at least 2× the gap inside one. 8px inside means 16px or more between.
A background shape
Only when space alone is ambiguous: a sunken well, a raised card.
A line
Last, where neither works: a dense table, a long settings list. A divider that space could carry is a deletion.
Turn on the divider switch in the demo with the ratio already at 2×. It adds nothing; the space had already done the job.
Controls look like controls
Clean screens sometimes strip buttons down until they look like plain text. Every interactive thing needs something that says "press me": a background shape, a border, an underline, or a consistent home such as a toolbar.
✕ Before
"Edit · Share · Delete" in the same gray text as the paragraph above them. They read as a sentence.
✓ After
Three small buttons with a quiet background shape, in a toolbar row. They read as things you can press.
A few shared edges
Pick a small set of and put everything on them. Text that starts on six different vertical lines looks ragged even when every element is fine on its own.
Use one spacing step per level of nesting (16px is a useful default), and take your steps from a if the project has one. If it does, use its steps; the numbers in this lesson are starting points for projects that don't.
Clearance between controls
How far apart should two buttons be? It depends on whether you can see their edges.
| Between | Starting gap |
|---|---|
| Bordered or filled controls (buttons, inputs) | 12px |
| The visible glyphs of borderless text or icon buttons | 24px |
| Unrelated groups of controls | 24px or more |
With borderless buttons nothing marks where one ends, so the space is the boundary. Tap areas can be bigger than the visible glyph, but they never overlap.
Edges, bleeds and the one primary action
- Inset buttons from the screen edge. A full-width button on a phone sits about 16px in from each side, with the bottom safe area added below it. Glued to three edges, it looks like system chrome and clips on curved corners.
- Content bleeds, controls float. Backgrounds and images can run to the edge of the screen (); text and buttons stay inside the margins.
- One per view. Past three secondary actions, the rest go behind a menu.
A full-bleed image inside an article, in one line of grid:
.article { display: grid; grid-template-columns: 1fr min(65ch, calc(100% - 48px)) 1fr; }
.article > * { grid-column: 2; }
.article > .full-bleed { grid-column: 1 / -1; }Rework the spacing on this screen: - Group with space first: gaps between groups at least 2× the gaps inside a group (e.g. 8px inside, 16–24px between). Use our spacing scale's steps. - Remove dividers and cards that space already carries; keep lines only for dense tables and long lists. - Every control must look interactive: a background shape, border, underline or a toolbar zone. - 12px between bordered controls, 24px between borderless text/icon buttons. - Put text on a small number of shared left edges. One primary action per view.
Quick check
Fields inside each form section are 12px apart, and sections are 12px apart too. What's the smallest fix that makes the sections readable?
In the skill
The nodes your agent reads when it does this work.
- MOC — LayoutPage-level layout, grids, viewports, sticky and scroll tells.
layout/MOC-layout - Grouping by spaceGroup with space first, a background shape second, a separator line last; the gap between groups is at least twice the gap inside one. Controls look like controls, everything sits on a few shared edges, borderless controls get 24px between glyphs (bordered ones 12px), buttons inset 16px from the screen edge, content bleeds while controls float, one primary action per view.
layout/grouping-by-space
Connected lessons
What this lesson builds on and leads to, across every course.