Spacing System

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).

1. Map attachment, control, task, group, region, and chapter relationships to visibly different steps

(roughly ≥1.5× between levels).

1. Choose metronomic or intentional syncopated section rhythm from content pressure.
2. 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](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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: KyaniteLabs
• Source: KyaniteLabs/tastecheck
• License: MIT
• Homepage: https://kyanitelabs.github.io/tastecheck/

Install and usage instructions live in the source repository linked above.