Skip to content

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

TypeScript

docs: define layout primitives family (#5743)

Cindy Zhangb5656ff75a5c
diff --git a/docs/families/layout-primitives.md b/docs/families/layout-primitives.md
new file mode 100644
index 0000000000..b42f07d308
--- /dev/null
+++ b/docs/families/layout-primitives.md
@@ -0,0 +1,230 @@
+---
+schema_version: 1
+template_version: 1
+kind: family
+id: family:layout-primitives
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+owners: [cixzhang, imdreamrunner]
+review_triggers: [public-api, layout, theming]
+verified_by:
+ [
+ packages/core/src/Stack/Stack.test.tsx,
+ packages/core/src/Stack/StackItem.test.tsx,
+ packages/core/src/Grid/Grid.test.tsx,
+ packages/core/src/Center/Center.test.tsx,
+ ]
+members:
+ [
+ component:Stack,
+ component:HStack,
+ component:VStack,
+ component:StackItem,
+ component:Grid,
+ component:GridSpan,
+ component:Center,
+ ]
+architecture:
+ [
+ architecture:container-padding,
+ architecture:public-component-api,
+ architecture:component-theming-surface,
+ ]
+contributing: []
+deciding_specs: []
+---
+
+# Layout primitives contract
+
+## Intent
+
+Builders should be able to arrange arbitrary content in one or two dimensions,
+center it, size its layout box, and express spatial relationships with the same
+small vocabulary. Choosing Stack, Grid, or Center changes the arrangement model;
+it does not create a second spacing scale or a new meaning for shared prop names.
+
+## Membership rule
+
+A component belongs when its primary public purpose is arranging arbitrary child
+content through the shared layout-primitive vocabulary. A modifier belongs with
+its parent when it changes one child's participation in that arrangement.
+
+- **Members:** Stack, its HStack and VStack convenience forms, StackItem, Grid,
+ GridSpan, and Center.
+- **Collaborators:** shared `SpacingStep` and `SizeValue` types; Stack and
+ StackItem style utilities; `padding.stylex.ts`; the container-padding
+ architecture; component `.doc.mjs` theming metadata and runtime
+ `themeProps()` emission.
+- **Excluded:** Section, Layout and its regions, and Toolbar own structural
+ regions rather than general composition. FormLayout owns field arrangement
+ and form-level optionality. AspectRatio constrains one child's box rather than
+ arranging arbitrary children. Card and Dialog are surfaces. AppShell and
+ navigation components compose higher-level structure.
+
+Membership follows public responsibility, not implementation mechanism. A
+component does not join merely because its source uses flexbox or grid.
+
+## Shared owner
+
+- `SpacingStep` owns the public numeric spacing vocabulary used by member gap
+ and padding props.
+- `SizeValue` owns the number-as-pixels/string-as-CSS-value contract for member
+ box dimensions.
+- Stack owns one-dimensional direction, wrapping, and main/cross-axis
+ alignment. HStack and VStack are fixed-direction forms of that contract.
+- Grid owns fixed and intrinsic/fluid track construction. GridSpan owns one
+ child's row and column participation.
+- Center owns centering along one or both axes.
+- `architecture:container-padding` owns bleed geometry. Applying local padding
+ does not by itself publish that protocol.
+
+## Canonical concepts
+
+| Concept | Values or states | Default semantics | Stability |
+| ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------- | --------------- |
+| spacing step | `0`, `0.5`, `1`, `1.5`, `2`, `3`, `4`, `5`, `6`, `8`, `10` | A token-backed distance for supported gap or padding props | current |
+| box size | number or CSS value string | Numbers are pixels; strings pass through as CSS values | current |
+| flow direction | horizontal or vertical | Stack defaults to vertical; HStack/VStack fix the direction | current |
+| alignment | main/cross axis or physical horizontal/vertical aliases | The active arrangement model resolves the axis | current |
+| gap | uniform, row, or column where supported | Space between arranged items, not container inset | current |
+| padding | uniform, axis, or logical edge where supported | Space inside the member's own box | current |
+| item participation | intrinsic, fill, self-aligned, column span, or row span | A modifier changes one child's role in its parent arrangement | current |
+| responsiveness | intrinsic, wrapping, or consumer-authored | Each member documents its own available mechanism | component-owned |
+
+## Cross-component invariants
+
+- **FR1 — Shared names keep shared value semantics.** A member prop typed as
+ `SpacingStep` or `SizeValue` follows the shared value and coercion contract.
+ Members expose only the capabilities their arrangement model supports.
+- **FR2 — Logical spacing follows writing direction.** Inline start and end are
+ logical edges. A member does not reinterpret them as fixed left and right.
+- **FR3 — Padding precedence is per edge.** On members with the full padding
+ ladder, an explicit edge value wins over its axis value, which wins over
+ uniform `padding`; an override changes only that edge.
+- **FR4 — Gap and padding stay distinct.** Gap separates arranged items. Padding
+ insets content inside a member. Grid's `rowGap` and `columnGap` override its
+ uniform gap only on their axis.
+- **FR5 — Alignment follows the arrangement model.** Stack resolves main and
+ cross axes from direction. Grid aligns items in tracks. Center controls which
+ axis or axes are centered. One member does not copy another's props when their
+ meanings would differ.
+- **FR6 — Modifier components require their parent model.** StackItem controls
+ participation in Stack; GridSpan controls participation in Grid. Their
+ component contracts own behavior outside the expected parent.
+- **FR7 — Responsive behavior is explicit.** Grid may reflow from intrinsic
+ track math; Stack wraps only when configured; Center does not create a
+ breakpoint. The family does not promise a shared breakpoint or automatic
+ region swap.
+- **FR8 — Local padding is not a bleed signal.** Stack and Center currently
+ apply padding without publishing container inset geometry. Descendants may
+ rely on bleed compensation only under a publisher named by
+ `architecture:container-padding`.
+- **FR9 — The public contract does not prescribe source structure.** Components
+ may use member utilities or direct platform layout when their observable API
+ and behavior remain correct.
+
+## Allowed component variation
+
+- **AV1 — Arrangement model.** Stack uses one-dimensional flow, Grid uses
+ two-dimensional tracks, and Center uses one- or two-axis alignment.
+- **AV2 — Available props.** Stack, HStack, VStack, and Center expose the full
+ logical-edge padding ladder. Grid exposes axis-specific gaps. Modifier
+ components expose parent-specific participation instead of box-level layout
+ controls.
+- **AV3 — Element ownership.** Stack, HStack, VStack, and StackItem are
+ polymorphic. Grid, GridSpan, and Center currently own fixed div elements.
+- **AV4 — Overflow.** Stack, HStack, VStack, and StackItem expose their current
+ scroll behavior; Grid and Center do not gain it through family membership.
+- **AV5 — Responsiveness.** Grid's intrinsic columns, Stack wrapping, and
+ consumer-authored responsive styles remain component-specific.
+- **AV6 — Implementation.** Raw flex/grid and shared utilities are both allowed.
+ Family membership does not create migration debt for implementation-only
+ choices.
+- **AV7 — Theming.** Current component `.doc.mjs` metadata documents shipped
+ targets and capabilities, and runtime `themeProps()` calls emit them.
+ `architecture:component-theming-surface` owns the cross-component rules.
+ A component spec may add optional anatomy-mapping metadata when one exists;
+ this family does not assume or replace such a spec.
+
+## Representative matrix
+
+| Member and state | Shared invariant | Deliberate variation |
+| ------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Stack / vertical or horizontal | Shared spacing and sizing values; direction resolves alignment axes | May wrap, scroll, or render a chosen element |
+| HStack or VStack | Same Stack contract with a fixed direction | Narrower alignment types match the fixed axes |
+| StackItem / `size="fill"` | One child may consume remaining Stack space | `isScrollable` pairs overflow with StackItem's flex minimum reset |
+| Grid / fixed columns | Shared size and gap values | Explicit equal-width track count |
+| Grid / intrinsic columns | Shared size and gap values | `minWidth`, optional count cap, and fill/fit construct fluid tracks |
+| GridSpan / columns or rows | Modifier participates in Grid | Spans tracks rather than controlling parent geometry |
+| Center / one or both axes | Shared size and padding values | Needs available size on an axis before centering is observable |
+
+## Adoption and exceptions
+
+| Component or concern | Adoption | Current gap or exception |
+| --------------------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
+| Stack, HStack, VStack | Shared one-dimensional contract | Gap token mapping is implemented separately from Grid's mapping |
+| StackItem | Shared modifier contract | No family-wide flex-item grow/shrink/basis vocabulary exists |
+| Grid, GridSpan | Shared two-dimensional contract | No cross-component test proves Grid and Stack resolve equal gap steps equally |
+| Center | Shared sizing and padding vocabulary | Like Stack, its padding is local and does not publish bleed geometry |
+| Shared verification | Per-component unit coverage | No computed-style matrix proves every shared spacing and sizing value across members |
+
+These are shipped coverage or adoption gaps, not authorization to add props or
+change layout behavior in a documentation pull request.
+
+## Change coupling
+
+- Adding or changing a shared spatial prop checks whether its name, value type,
+ coercion, logical direction, and precedence still match this family.
+- Changing `SpacingStep` or `SizeValue` reviews every member that exposes the
+ affected type and updates representative cross-component evidence.
+- Changing Stack direction/alignment updates HStack and VStack in the same
+ reviewed change.
+- Changing intrinsic Grid track construction preserves its documented fixed,
+ fill, fit, and capped states with focused tests.
+- Enrolling a member in container bleed is a separate
+ `architecture:container-padding` change with rendered compatibility evidence.
+- A new component joins only when its public responsibility satisfies the
+ membership rule; use of flexbox, grid, or a shared utility is insufficient.
+
+## Verification map
+
+| Contract | Verification | What the evidence proves | Missing evidence |
+| -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR3 | Stack and Center source plus their padding class-set tests | The current merge order selects edge over axis over uniform padding for the exercised values, and equivalent spellings emit equal functional class sets | No browser matrix compares computed values across members or both writing directions |
+| FR2 | Logical-property source declarations in Stack and Center | The implementation uses inline-start/end properties rather than physical left/right properties | Current tests do not render the padding ladder under both LTR and RTL |
+| FR4 | Stack/Grid source and their local tests | The APIs keep gap separate from padding; Grid accepts uniform and axis gap props | Grid's gap/rowGap/columnGap tests assert render success, not computed spacing, and no test compares a step with Stack |
+| FR5 | Stack, Grid, and Center source plus local render tests | Each member currently routes alignment through its own arrangement model | Stack/Grid tests do not assert computed alignment for the accepted values |
+| FR6 | StackItem and GridSpan source plus local tests | Source maps `size="fill"` into StackItem's fill style; scrolling changes class output; GridSpan asserts exact inline row/column spans | StackItem's fill test asserts only rendered content, not fill behavior; no integration test proves modifiers across every parent state |
+| FR7 | Exact Grid track-output tests plus Stack/Center source | Grid's fixed and intrinsic track strings are pinned; Stack wraps only when configured; Center has no breakpoint path | No cross-member responsive integration matrix exists |
+| FR8 | Source review against `architecture:container-padding` | Stack and Center apply local padding without publishing container inset variables | No browser assertion demonstrates the resulting non-bleed behavior for Divider/Table descendants |
+
+The tests are component-local and several assert only render success or class
+change. They do not prove computed gap, alignment, logical-direction, or
+cross-component parity. Those are named verification gaps, not implied coverage.
+
+## Decision links
+
+### DEC-1 — Composition primitives and structural regions have separate owners
+
+**Decider:** `cixzhang`, `2026-08-30`
+
+Stack, Grid, Center, and their modifiers form the layout-primitives family.
+Section, Layout regions, and Toolbar have a separate structural-region owner.
+This keeps membership predictive: primitive rules describe arbitrary-child
+composition without forcing slot, surface, or toolbar semantics into the same
+contract.
+
+## Open questions
+
+None. The adoption table names missing capabilities and verification; it does
+not turn them into unresolved family policy.
+
+## Content boundary
+
+This record owns only shared composition vocabulary and behavior. It does not
+repeat component prop tables, prescribe implementation mechanisms, define
+structural regions, assign responsive breakpoints, or own theming anatomy and
+targets.