Skip to content

docs(decisions): add the spacing roles decision record - #735

Open
wemra3 wants to merge 3 commits into
mainfrom
docs/spacing-roles
Open

wemra3 wants to merge 3 commits into
mainfrom
docs/spacing-roles

Conversation

@wemra3

@wemra3 wemra3 commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Motivation

Part of tailor-inc/platform-planning#2484.

AppShell has no spacing rule. Each component writes its own padding, gap and margin classes, so most values agree but some do not: 16 sibling gaps use a 2px step, several components set a margin on their own root, nine places cancel the parent's inset with a negative margin, and containers such as Card.Content and Form have no gap, so pages write space-y-* by hand (488 classes in 131 of 418 erp-kit template files). This PR proposes one rule for spacing and records the points already agreed.

Summary

This PR adds decisions/spacing-roles.md and six figures. It changes no code.

The rule, from the record:

Space shows how closely things are related. A box owns only its inset. The parent owns the space between siblings. All steps are on a 4px scale, and each role uses its own range. A control's height is its line box plus its block inset. Density is a separate axis that moves only the block inset, and it does not depend on screen width. Screen width changes only the page's outer spacing.

What this decides

Point Decision
D1 Density A separate axis from size. An ancestor marker sets CSS variables for the block inset of controls and rows (Carbon's model). Under pointer: coarse, the same variables get larger values (Primer's model). Box insets do not move.
D2 2px steps 2, 6 and 10px only inside a component. Never between siblings.
D3 Role API A gap prop (none / tight / normal / loose = 0 / 8 / 16 / 24) on Card.Content, Form, Fieldset.Root, Tabs.Panel, Dialog.Content and Sheet.Content, and a new Inline primitive for horizontal rows. No Stack primitive.
Defaults The new gap props default to none until the next major, so no page moves. Docs and templates pass the value explicitly.
Other details Two density variable groups (control, row). Toolbar.Group stays a toolbar part and its gap becomes 8. The space between a label and its control is inside a component.

What is not decided

  • The values of the density variables at each level and under pointer: coarse.
  • The order of the implementation changes. Rewriting control heights as line box + 2 × inset (pillar 6) has to come before density.
  • Breakpoints for multi-column layouts (tailor-inc/platform-planning#2207), card family insets other than 24, and Grid's default gap of 12.

Figures

Real components from the vite example at b4ede51, 1280px. Blue lines frame elements; red dimension lines show inset, gap, margin or inside, with the measured value. Panels marked "proposed" or "simulated" add CSS to show a state that does not exist yet.

Figure Shows
1 Inset and gap roles A form in a card: inset 24, inside a field 4, gap 16 between fields (written by the page today)
2 Density moves inset only Comfortable and compact: control 36 to 28, row 36.5 to 28.5; card inset and gap unchanged
3 No 2px between siblings Capsule Tabs 2 to 4, Toolbar.Group 6 to 8
4 Container gap and compatibility Why the default is none: a default of 16 plus an existing space-y-4 gives 32
5 Height equals line plus inset Button 8 + 20 + 8; Input today is a fixed 36 with 3px left over
6 Padding instead of negative margin ActionPanel with a −12 margin, and the same rows with an inset of 20 and no margin

How to review

  • For discussion: the rule and the table of seven pillars. Are these the right principles for AppShell?
  • Proposals: D1 to D3 and the decided details. They come from the measurements in the Context section; please say if any of them does not fit a case you know.
  • The Consequences section lists every place that would change (file and line on b4ede51). It is the input for the implementation issues, not part of this PR.
  • References were checked against the original pages on 2026-11-16.

🤖 Generated with Claude Code

Propose one rule for spacing inside and between components: a box owns
only its inset, the parent owns the space between siblings, steps are on
a 4px scale, a control's height is its line box plus its block inset,
and density moves only that inset. Record three agreed points (density,
2px steps, the role API) and the details decided with them. Add six
figures rendered from real components with measured redline overlays.

No code changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (e4b5616) #735 (840a6be) +/-
Coverage 62.9% 62.9% 0.0%
Test Execution Time 4m29s 4m31s +2s
Details
  |                     | main (e4b5616) | #735 (840a6be) | +/-  |
  |---------------------|----------------|----------------|------|
  | Coverage            |          62.9% |          62.9% | 0.0% |
  |   Files             |            294 |            294 |    0 |
  |   Lines             |          13513 |          13513 |    0 |
  |   Covered           |           8505 |           8505 |    0 |
- | Test Execution Time |          4m29s |          4m31s |  +2s |

Reported by octocov

@wemra3
wemra3 marked this pull request as ready for review November 18, 2026 00:10
@wemra3
wemra3 requested a review from a team as a code owner November 18, 2026 00:10
Hiroki Uemura and others added 2 commits November 18, 2026 09:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant