Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
4.0 KB
Raw Blame

schema_version: 1 template_version: 1 kind: design id: design:spatial-hierarchy authority: draft archive_reason: null superseded_by: null approved_by: null approved_at: null owners: [ernestt, cixzhang] review_triggers: [visual, layout, responsive] verified_by: [] architecture: [architecture:container-padding, architecture:theme-tokens] components: [] families: [family:layout-primitives, family:layout-regions] deciding_specs: []

Spatial hierarchy design specification

User intent

People should understand what belongs together before reading individual labels. A dense surface should remain organized because proximity expresses relationship, not because every group is enclosed by another container.

Design principles

  • DR1 — Proximity communicates relationship. Closely related elements MUST sit closer than separate concerns.
  • DR2 — Separation grows with grouping level. Gaps MUST increase from local content to groups and from groups to sections.
  • DR3 — Space precedes containment. Authors SHOULD use spacing and alignment to establish groups before adding another card or boundary.
  • DR4 — Variation is intentional. A composition MUST use enough spatial contrast to reveal its hierarchy rather than applying one gap everywhere.

Anatomy and hierarchy

Role Purpose Required relationship
local gap Joins a label, value, icon, or control to immediate content Smaller than its containing group gap
group gap Separates peer controls or content groups Larger than local gaps and smaller than section separation
section gap Separates distinct concerns Strong enough to survive the squint test
alignment edge Connects related content across rows or regions Repeats consistently within the same grouping level

State representation

Spatial relationships MUST remain perceptible in populated, sparse, empty, and error states. Conditional content must not collapse or invert the grouping order.

Responsive and input behavior

  • DR5 — Reflow preserves grouping. At constrained widths, content MAY stack or move, but local, group, and section relationships MUST remain distinguishable.
  • DR6 — Dynamic content preserves rhythm. Validation, supporting text, and optional actions MUST remain associated with the content they serve.

Accessibility intent

Visual grouping should agree with semantic reading order and programmatic relationships. Space must not be the only signal when a group requires a label, heading, or other semantic boundary.

Representative examples

  • A form uses its tightest relationship between label and field, a larger gap between fields, and the largest gap between sections.
  • A dashboard separates regions through spacing and alignment before adding nested cards.

Visual references

No normative assets are included. Wide and constrained examples should be added under docs/design/assets/spatial-hierarchy/ before promotion.

Component contract links

No component links are asserted. The listed layout families are candidate relationships pending adoption review.

Decision log

No repository design decision has approved this record yet. It distills the spacing intent from the public Design Conventions wiki without copying token values or audit thresholds.

Open questions

  • OQ1 — Evidence set. Which page, form, and collection examples best verify each grouping level?
  • OQ2 — Containment exception. Which component families require visible containment in addition to spatial grouping?

Content boundary

This file defines perceptual grouping. It does not define spacing token values, padding algorithms, component props, DOM structure, or audit scoring.