Identifies this entity as a style.
Machine-readable identifier for the style (e.g., 'color', 'typography', 'spacing', 'elevation', 'motion', 'shape'). MUST be unique within the documentation group.
Pattern: ^[a-z][a-z0-9-]*$
Human-readable name for display in docs (e.g., 'Color', 'Typography', 'Spacing', 'Elevation').
Modular metadata entries. Each entry is a typed object with a `kind` discriminator. Types include status, since, tags, category, aliases, summary, thumbnail, preview, extends, and links.
All structured docs for this style as an ordered array of typed document block objects. Accepts style-specific types (principles, scale) and general types (guideline, use-cases, accessibility, examples). Each document block entry has a `type` property that determines its shape. Ordering is significant: tools SHOULD preserve it for display. Express internal artifact relationships (e.g., token group references) through a links metadata entry, not as document block entries.
Agent-optimized context for this style — intent, constraints, disambiguation, anti-patterns, examples, and keywords for efficient agentic consumption.
References:
entityMetadata, styleDocumentBlock, agents, extensions
{
"kind": "style",
"name": "spacing",
"displayName": "Spacing",
"metadata": [
{
"kind": "description",
"value": "A spatial system built on a 4px base unit. Defines the scale and rules for all whitespace, padding, margin, and gap values across the system. Eliminates ad hoc pixel values and reduces visual inconsistency caused by individual interpretation of spatial relationships."
},
{
"kind": "status",
"status": "stable"
},
{
"kind": "since",
"value": "1.0.0"
},
{
"kind": "tags",
"items": [
"layout",
"spatial",
"whitespace",
"padding",
"margin",
"gap"
]
},
{
"kind": "category",
"value": "spacing"
},
{
"kind": "summary",
"value": "A constrained spacing scale built on a 4px base unit."
},
{
"kind": "links",
"items": [
{
"kind": "token-group",
"name": "spacing",
"role": "Provides all spatial tokens from space-0 (0px) through space-8 (48px), built on a 4px base unit."
},
{
"kind": "source",
"url": "https://code.acme.com/design-system/src/tokens/spacing.tokens.json",
"label": "Token source file"
},
{
"kind": "design",
"url": "https://design-tool.acme.com/file/abc123?node-id=200:1",
"label": "Design file — spacing variables"
},
{
"kind": "documentation",
"url": "https://design.acme.com/style/spacing",
"label": "Documentation site"
},
{
"kind": "related",
"url": "https://design.acme.com/style/typography",
"label": "Typography style"
},
{
"kind": "related",
"url": "https://design.acme.com/components/stack",
"label": "Stack component"
}
]
}
],
"documentBlocks": [
{
"kind": "principles",
"items": [
{
"title": "Use the scale",
"description": "Every spacing value must reference a token from the spacing scale. No hard-coded values."
},
{
"title": "Density over decoration",
"description": "Spacing exists to create clear relationships between elements, not to fill empty areas."
},
{
"title": "Consistent internal, flexible external",
"description": "Internal spacing within a component is fixed by the component's design specification. External spacing between components is determined by the layout context."
}
],
"agents": {
"intent": "State the foundational beliefs that govern spacing decisions across the design system.",
"keywords": [
"principles",
"consistency",
"rhythm",
"density",
"spatial model"
]
}
},
{
"kind": "scale",
"name": "spacing-scale",
"displayName": "Spacing Scale",
"description": "A geometric spacing scale based on a 4px unit.",
"steps": [
{
"token": "space-0",
"label": "0",
"value": "0px"
},
{
"token": "space-1",
"label": "4xs",
"value": "2px"
},
{
"token": "space-2",
"label": "3xs",
"value": "4px"
},
{
"token": "space-3",
"label": "2xs",
"value": "8px"
},
{
"token": "space-4",
"label": "xs",
"value": "12px"
},
{
"token": "space-5",
"label": "sm",
"value": "16px"
},
{
"token": "space-6",
"label": "md",
"value": "24px"
},
{
"token": "space-7",
"label": "lg",
"value": "32px"
},
{
"token": "space-8",
"label": "xl",
"value": "48px"
}
],
"agents": {
"intent": "Define the ordered progression of spacing values from the smallest to the largest step.",
"constraints": [
{
"rule": "Always use scale tokens instead of arbitrary pixel values.",
"level": "must"
},
{
"rule": "Do not skip more than two scale steps between adjacent elements.",
"level": "should-not"
}
],
"keywords": [
"scale",
"steps",
"tokens",
"4px grid",
"progression",
"spacing values"
]
}
},
{
"kind": "motion",
"description": "Easing curves used when spacing values are animated — for example, when a container expands from space-0 to space-6 or when layout gaps transition between density settings.",
"items": [
{
"name": "expand",
"displayName": "Expand Ease",
"description": "Used when a spatial value increases — a container opening, a gap growing, or a panel expanding. The curve starts slow and accelerates into the final position, making the expansion feel deliberate rather than abrupt.",
"function": [
0.05,
0.7,
0.1,
1
],
"token": "motion-ease-expand",
"usage": "container expansion, gap growth, panel open",
"duration": {
"min": "200ms",
"max": "400ms",
"description": "Scale duration with the distance traveled — use 200ms for small spacing transitions (space-2 to space-4) and up to 400ms for large layout changes."
}
},
{
"name": "collapse",
"displayName": "Collapse Ease",
"description": "Used when a spatial value decreases — a container closing, a gap shrinking, or a panel collapsing. The curve accelerates early and decelerates into the final position, making the collapse feel responsive.",
"function": [
0.3,
0,
0.8,
0.15
],
"token": "motion-ease-collapse",
"usage": "container collapse, gap shrink, panel close",
"duration": {
"min": "150ms",
"max": "300ms",
"description": "Collapse transitions should be faster than expand transitions to feel snappy."
}
}
],
"agents": {
"intent": "Define easing curves and durations used when spacing changes are animated.",
"keywords": [
"easing",
"duration",
"animation",
"transition",
"layout shift"
]
}
},
{
"kind": "guideline",
"items": [
{
"guidance": "Use the spacing scale tokens for all padding, margin, and gap properties. Do not use hard-coded values.",
"rationale": "Hard-coded values create visual inconsistency and are not responsive to system-wide spacing changes. Tokens enable global adjustment of spatial density from a single source of truth.",
"kind": "required",
"category": "visual-design"
},
{
"guidance": "Components must not apply external margin. Margin between components is the responsibility of the parent layout.",
"rationale": "Components that own their margins create unpredictable spacing when composed. A button with built-in margin-bottom behaves differently depending on what follows it. Delegating margin to layout makes spacing composable and predictable.",
"kind": "required",
"category": "visual-design"
},
{
"guidance": "Select spacing based on the relationship between elements, not their size. Related elements use smaller spacing. Unrelated elements use larger spacing.",
"rationale": "Gestalt proximity principle: objects that are closer together are perceived as related. Spacing encodes information hierarchy. A label 4px from its input is clearly associated with it. A label 32px from an input appears disconnected.",
"kind": "encouraged",
"category": "visual-design"
},
{
"guidance": "Do not use spacing tokens for non-spatial properties such as border-width, font-size, or icon-size. Use the tokens designated for those properties.",
"rationale": "Spacing tokens are tuned for whitespace. A spacing scale step that works well as padding produces incorrect results as a border-width or icon-size. Using the wrong token category couples unrelated visual properties.",
"kind": "prohibited",
"category": "development"
},
{
"guidance": "Use CSS gap (in Flexbox or Grid) as the primary mechanism for spacing between sibling elements. Reserve margin for spacing between non-sibling elements or layout-level offset.",
"rationale": "Gap applies spacing uniformly between children without affecting the first or last child. Margin requires :first-child/:last-child overrides to prevent unwanted space at container edges.",
"kind": "encouraged",
"category": "development"
},
{
"guidance": "For responsive layouts, reduce spacing density at smaller breakpoints by stepping down the scale. Do not introduce arbitrary breakpoint-specific values.",
"rationale": "Stepping down the scale (e.g., space-7 at desktop becoming space-5 at mobile) maintains proportional relationships while conserving space. Arbitrary values break out of the scale and undermine system consistency.",
"kind": "encouraged",
"category": "visual-design"
},
{
"guidance": "Ensure all interactive elements maintain a minimum 44x44 CSS pixel touch target, inclusive of padding.",
"rationale": "Users with motor impairments and touch device users require a minimum target size to interact reliably. WCAG 2.5.8 requires 24x24px minimum and recommends 44x44px. The spacing system's role is to ensure padding contributes to meeting this target.",
"kind": "required",
"category": "accessibility",
"criteria": [
{
"url": "https://www.w3.org/TR/WCAG22/#target-size-minimum"
}
]
},
{
"guidance": "When users increase text size to 200% via browser settings, spacing must not collapse to zero or cause content to overlap.",
"rationale": "Users with low vision enlarge text. If spacing is defined in fixed pixel units that do not scale, text enlargement causes overlap and loss of content. Use rem-based spacing tokens where possible, and test all layouts at 200% text zoom.",
"kind": "required",
"category": "accessibility",
"criteria": [
{
"url": "https://www.w3.org/TR/WCAG22/#resize-text"
}
]
}
],
"agents": {
"intent": "Enforce correct spacing usage rules in layouts and component composition.",
"constraints": [
{
"rule": "Use spacing tokens from the scale — never hard-code pixel values.",
"level": "must"
},
{
"rule": "Apply comfortable density by default; compact density only in data-dense views.",
"level": "should"
}
],
"keywords": [
"rules",
"layout",
"density",
"tokens",
"consistency"
]
}
},
{
"kind": "purpose",
"useCases": [
{
"description": "When defining padding, margin, or gap values for any layout or component. All spatial values in production code must reference the spacing scale.",
"kind": "positive"
},
{
"description": "When establishing vertical rhythm between content sections, form groups, or card layouts.",
"kind": "positive"
},
{
"description": "When setting internal padding for containers such as cards, dialogs, panels, and page regions.",
"kind": "positive"
},
{
"description": "When controlling the gap between sibling elements in Flexbox or Grid layouts.",
"kind": "positive"
},
{
"description": "When defining border widths, outline offsets, or stroke values.",
"kind": "negative",
"alternative": {
"name": "border-width",
"rationale": "Border tokens are tuned for visual weight at sub-pixel and single-pixel sizes. Spacing tokens start at 0px and jump to values optimized for whitespace, which produce incorrect visual results when applied to borders."
}
},
{
"description": "When setting font sizes or line heights.",
"kind": "negative",
"alternative": {
"name": "typography",
"rationale": "Typographic tokens follow a modular scale designed for readability and vertical rhythm. Spacing tokens follow a geometric scale designed for whitespace. The two scales serve different purposes and should not be interchanged."
}
},
{
"description": "When sizing icons or illustration containers.",
"kind": "negative",
"alternative": {
"name": "icon-size",
"rationale": "Icon size tokens are calibrated to optical alignment with adjacent text at each type scale step. Spacing tokens do not account for optical sizing and produce misaligned icons."
}
}
],
"agents": {
"intent": "Clarify when the spacing style applies versus component-internal spacing.",
"disambiguation": [
{
"entity": "component padding",
"distinction": "The spacing style governs space between elements in layouts; component-internal padding is defined in each component's design specifications."
}
],
"keywords": [
"when to use",
"layout spacing",
"margins",
"gaps"
]
}
}
],
"agents": {
"intent": "Document spacing scale tokens and enforce their consistent application across layout, components, and typography.",
"constraints": [
{
"rule": "Do not substitute spacing tokens with typography or icon-size tokens.",
"level": "must-not"
},
{
"rule": "Always use the next scale step up or down rather than custom values.",
"level": "should"
}
],
"disambiguation": [
{
"entity": "typography style",
"distinction": "Spacing governs whitespace and layout gaps; typography governs type size, weight, and line height."
}
],
"keywords": [
"spacing",
"scale",
"gap",
"padding",
"margin",
"whitespace",
"layout",
"density"
]
}
}
Design System Documentation Standard (DSDS) 0.1 — Draft Specification
GitHub