spacing-system

name	spacing-system
description	Use when layout rhythm, density, or gaps feel arbitrary or inconsistent, or when one product needs different reading pressures without splitting into unrelated spacing systems.

Spacing System (the scale nobody owns)

Every gap uses one --space-* scale; named semantic relationships create composition instead of arbitrary margins.

The decision order

1. Publish one 4px-base ladder: 4/8/12/16/24/32/48/64/96px as --space-1 through --space-9, plus --space-section: clamp(48px, 32px + 4vw, 96px).
2. Map attachment, control, task, group, region, and chapter relationships to visibly different steps (roughly ≥1.5× between levels).
3. Choose metronomic or intentional syncopated section rhythm from content pressure.
4. Use gap and one-direction logical margins; do not stack arbitrary margins.

Let content set the rhythm

Map repeated operational tasks to compact predictability and editorial/narrative content to deliberate breathing room; retain one system and state why named roles differ. Use the role map before picking a value:

Relationship	Shared token	Compact operational rhythm	Long-form editorial rhythm
attachment	--space-1 (4px)	icon/state to its label	inline metadata pair
control	--space-2/3 (8/12px)	label-to-control / inside a control	claim-to-citation / tight evidence pair
task	--space-4 (16px)	repeated queue item	adjacent paragraph or evidence group
group	--space-5 (24px)	task-group break	discrete finding
region	--space-6/7/8 (32/48/64px)	console-region break	narrative subsection or causal pivot
chapter	--space-section (fluid)	major workflow view	major account transition

The console may be metronomic; an account may widen only at finding, subsection, and chapter boundaries. That is one vocabulary with different relationships, not two scales.

Non-negotiables

• Audit margin/padding/gap for tokens (except legitimate 0/auto/relative prose).
• Proximity must tell the truth; --space-section is fluid and each context has one base.
• Whitespace is an intentional structural move, never inconsistent leftover space.

Migration and honest audit boundary

Classify every literal by its relationship before replacement: 13px becomes 12px (--space-3), 17px becomes 16px (--space-4), and a bare 24px layout value becomes var(--space-5). Treat 19px as failed until its observed selector establishes task (16px) or group (24px); do not silently round it. The sole prose exception is documented following- paragraph 1em spacing, because it is relative to type rather than a layout primitive.

Use assets/spacing-starter.css as a fixture and starting point. Without a CSS fixture in the target project, mark the audit PENDING, name it and the next audit action; never claim that residual off-scale values are gone. The ladder, map, and migration rules remain required.

Completion evidence

Audit the source before describing it and map each value to a role. Handoff one completed Markdown table with status, reason, remediation, evidence, and provenance, covering scale, off-scale, proximity, rhythm, and handoff. PENDING names its missing source and next action; it blocks that check rather than acting as placeholder proof.

Semantic rhythm map

Name attachment, control, task, group, region, and chapter relationships, then show how compact/editorial contexts select them without parallel scales. Each arbitrary value is replaced, justified as an observed exception, or left PENDING with a source and next action.

Authoritative self-check

Include exactly one labeled Authoritative self-check in the delivery. It confirms the complete ladder and exact section clamp, all six relationships, operational versus editorial role selection, the 13/17/19/bare-24 migration decision, and the honest fixture boundary. This check is evidence-based, not a length target or a duplicate summary.

How to deliver

Deliver base, token scale, role map, context rhythm, off-scale audit, and the one authoritative self-check. Reject responsive-layout as the primary route because it owns breakpoint reflow, not the scale, proximity, or reading-pressure decisions; hand it --space-* and the completed evidence table. Send control and form relationships to component-states or form-ux, rather than re-deciding their behavior.

Reference files

• references/decision-records.md — novel-case ADR rules.
• assets/spacing-starter.css — copy-paste ladder, layout primitives, and migration helpers.

Contract (generated)

Canonical detail: contract.json.

• Route: An interface needs a spacing scale, content-derived rhythm, or gap consistency (+1 in contract.json); avoid: The request is only responsive reflow or component state behavior (+1 in contract.json)
• Exclude: Do not impose one uniform cadence across dissimilar content (+1 in contract.json)
• Stop / handoff: Pause when content hierarchy is absent and spacing would be arbitrary (+1 in contract.json); receives [design-system-interview, improve-existing-website, tasteroll, web-typography] -> sends [responsive-layout, component-states, form-ux]
• Output: A tokenized spacing scale and stated section-rhythm strategy tied to content hierarchy
• Evidence: table_with_evidence with status, reason, remediation, evidence, provenance.