An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Stack authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-28 owners: [cixzhang] review_triggers: [public-api, layout, theming, accessibility] verified_by: [ packages/core/src/serverSafeComponents.test.ts, .github/visual-baseline/manifest.json, packages/core/src/Stack/Stack.test.tsx, packages/core/src/Stack/StackItem.test.tsx, packages/core/src/hooks/useScrollRegionProps.test.tsx, packages/core/src/hooks/tests/scrollRegionName.a11y.chromium.spec.ts, packages/core/src/HStack/HStack.test.tsx, packages/core/src/VStack/VStack.test.tsx, packages/core/src/theme/themingTargets.test.ts, apps/storybook/stories/Stack.stories.tsx, apps/storybook/stories/HStack.stories.tsx, packages/core/src/HStack/tests/HStackAudit.a11y.chromium.spec.ts, scripts/check-knowledge.mjs, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [family:layout-primitives] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:container-padding, architecture:public-component-api, ] contributing: []
system_specs: []
Stack component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | Stack arranges children on one flex axis with direction, alignment, gap, per-edge padding, sizing, wrap, isScrollable, and as. HStack and VStack fix the direction; StackItem controls one child's participation. |
| Behavior | Alignment props resolve to the main or cross axis from the direction; padding resolves per logical edge; padding stays local and publishes no container inset. |
| End-user impact | Readers see consistent spacing and alignment that follows the writing direction. |
| Builder impact | None: no API change; a scrolling div or span StackItem gains a role and a name with no code change (AR2). |
| Compatibility/readiness | No API or default changes; the role and name of a scrolling div or span StackItem (AR2) are a patch [fix]. |
| Review checks | Reject physical left/right padding, an alias that wins over an explicit alignment, padding that publishes container inset, or a StackItem without the flex minimum reset. |
| Governing rules | family:layout-primitives/FR1–FR6,FR8; architecture:container-padding/INV8; architecture:public-component-api/INV5,INV6,INV8. |
This table is a review projection; the body below is authoritative.
Intent
Stack is the one-dimensional layout primitive. It owns direction, axis-aware alignment, gap, local padding, sizing, wrapping, and scrolling for a flex container, and StackItem owns one child's growth, alignment, and scrolling inside it.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: patch. No public prop, default, or styling output
changes. While it scrolls, a scrollable
divorspanStackItem with no callerrolegainsrole="group"and anaria-label(DOM; AR2,[fix]underspec:AST-017FR53) - Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- Stack, and HStack, VStack, and StackItem, which
Stack.doc.mjsdocuments as inlinecomponents:entries. This record covers all four; none has its own consumer doc or record. - The Stack container and its
stacktarget; the StackItem wrapper and itsstack-itemtarget. - Axis resolution for alignment, per-edge padding resolution, gap, sizing, wrapping, and scrolling.
Does not own / non-goals
- Content supplied to Stack or StackItem — owned by the caller.
- Container-inset publication and descendant bleed — owned by publishers under
architecture:container-padding; Stack padding is local. - Two-dimensional layout — owned by
component:Grid; centering — owned bycomponent:Center.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Direction | horizontal, vertical |
Flex row or column. HStack is horizontal; VStack is vertical. | Stack only; fixed on HStack and VStack | vertical |
component:Stack |
Stable | TypeScript rejects other values. |
| Alignment | main axis start, center, end, between, around, evenly; cross axis start, center, end, stretch |
hAlign/vAlign by physical name, or justify/align by axis. |
All stacks | browser default (stretch on the cross axis) |
component:Stack |
Stable | Stack accepts every alignment value on hAlign and vAlign and ignores one that does not apply to the resolved axis; HStack, VStack, justify, and align reject it in TypeScript. |
| Gap | Spacing steps 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10 | Row and column gap. | All stacks | unset | component:Stack |
Stable | TypeScript rejects other values. |
| Padding | Spacing steps per edge, per axis, or uniform | Local inner padding. | All stacks | unset | component:Stack |
Stable | TypeScript rejects other values. |
| Wrap | nowrap, wrap, wrap-reverse |
Flex wrapping. | All stacks | unset (nowrap) |
component:Stack |
Stable | TypeScript rejects other values. |
| Item size | static, fill |
StackItem neither grows nor shrinks, or grows to fill. | StackItem | static |
component:Stack |
Stable | TypeScript rejects other values. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Stack renders the element named by as (default div) as a flex container in the given direction, carrying the stack target, which reflects direction, gap, and wrap. HStack renders Stack with direction="horizontal" and VStack with direction="vertical". |
Current source and tests |
| FR2 | hAlign and vAlign name physical axes: in a horizontal stack hAlign sets main-axis justification and vAlign cross-axis alignment, and in a vertical stack the reverse. justify and align name the main and cross axes and apply only when the matching hAlign or vAlign is absent. Unset alignment leaves the browser defaults. |
Current source and tests |
| FR3 | gap sets equal row and column gaps from the spacing scale. Padding resolves per logical edge: the edge prop, then its axis prop (paddingInline or paddingBlock), then padding; inline edges follow the writing direction. |
Current source and tests |
| FR4 | Stack padding is local: it publishes no container-padding variables, so descendants cannot use it for bleed compensation. | Current source |
| FR5 | width, height, maxWidth, and minHeight apply numbers as pixels and strings as given, as inline styles after the caller's style. wrap sets flex wrapping. isScrollable sets overflow: auto. |
Current source and tests |
| FR6 | StackItem renders the element named by as (default div) carrying the stack-item target, which reflects size; it always resets its minimum width and height to zero, static neither grows nor shrinks, fill grows to share remaining space, crossAlignSelf overrides the stack's cross alignment, and isScrollable sets overflow: auto. |
Current source and tests |
| FR7 | ref reaches the rendered element of Stack, HStack, VStack, and StackItem. Supported DOM, ARIA, data, and event props reach it; xstyle, className, and style merge in that order after component styles. |
Current source and tests |
Allowed variation
- AV1 — Element. Callers choose the element through
as. - AV2 — Theme paint. A theme may restyle
stackandstack-itemwithout changing axis resolution or padding precedence.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Vertical default | Flex column; data-direction="vertical". |
Children. |
| Horizontal with aliases | justify sets the main axis, align the cross axis, unless hAlign/vAlign are set. |
— |
| Per-edge padding | Each edge resolves independently; inline edges mirror in right-to-left. | — |
| Fill and scroll item | StackItem size="fill" isScrollable grows and scrolls its own overflow. |
— |
Transformation and precedence order
- ORD1 — Alignment.
hAlign/vAlign→justify/alignby axis → browser default. - ORD2 — Padding per edge. Edge prop → axis prop →
padding. - ORD3 — Sizing. Caller
style→ sizing props.
Performance and resources
- PR1 — Static render. Stack, HStack, VStack, and StackItem hold no state and
use no hooks. The one exception is a scrollable
divorspanStackItem: it renders through a client island that observes its overflow for AR2.
Accessibility contract
- AR1 — No semantics added. Stack and StackItem add no role, name, or tab
stop of their own; their semantics are those of the
aselement. The one exception is the name of a scrolling StackItem (AR2). - AR2 — A scrolling StackItem is named. While a scrollable
divorspanStackItem scrolls, its element hasrole="group"(unless the caller sets arole) and an accessible name (the caller'saria-label, or a translated "Content"), so a screen reader that reaches it, including as a browser-made Tab stop, announces it; Tab behavior is the browser's (owner decision, 2026-11-04). A caller'sroletakes only the caller'saria-label, and another element keeps its own role and name. Where the browser makes no Tab stop of it, a scrolling region whose content holds nothing focusable can't be scrolled from the keyboard. The caller then adds a focusable child or uses ScrollableArea.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Stack container | The one-dimensional layout container. | Current source, docs, and family contract | Supporting | FR1–FR5 |
| Item | Optionally controls one child's participation. | Current source, docs, and family contract | Supporting | FR6 |
| Content | Caller content in either wrapper. | Caller-supplied content | Context-dependent | AR1 |
Theming anatomy
{
"Stack container": {"target": "stack"},
"Item": {"target": "stack-item"},
"Content": {
"none": {
"reason": "intentional: Caller-supplied content retains its own theming ownership; Stack and StackItem apply no content target."
}
}
}
Family and system relationships
family:layout-primitivesowns the shared spacing, padding precedence, and modifier rules; Stack, HStack, VStack, and StackItem are members, and FR2, FR3, and FR6 apply them.architecture:container-paddingrecords Stack padding as local (FR4).architecture:public-component-apiowns ref, passthrough, and styling-input rules; FR7 applies them.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2 | Stack.test.tsx, HStack.test.tsx, VStack.test.tsx element tests; HStack.test.tsx target, reflection, axis, alias, and precedence tests; HStackAudit Chromium frames of HStack / Alignment Matrix; stable visual baseline core-stack--default |
Default and as elements; default stack |
A wrong default or as element fails; a changed default direction, gap, or alignment comes back changed for review. HStack.test.tsx fails if HStack loses its horizontal direction, the stack target, or its reflection, sends an alignment prop or alias to the wrong Stack prop, or loses alias precedence; the HStackAudit frames fail if the resulting horizontal geometry is wrong, mirrored in right-to-left. Gap: the Stack and VStack direction, alignment, and alias tests assert only that content renders, so the vertical data-direction reflection and Stack's own axis mapping have no unit check. |
audit:Stack/layout |
| FR3 | Stack.test.tsx padding-precedence tests; @astryx/no-physical-properties lint rule |
Uniform, axis, edge, all four edges | A missing padding class, edge over axis on the end edges, edge over uniform on the edges the tests pair, or a physical left/right padding property fails. Gap: edge over axis on the start edges, axis over uniform, any untested edge-over-uniform pairing, and the gap value (the gap test asserts only that content renders) have no check, and no browser right-to-left check covers the edges. | audit:Stack/layout |
| FR5 | Stack.test.tsx sizing and scrolling tests; HStack.test.tsx merge test; HStackAudit wrap frames |
Numeric and string sizes; scrollable | A wrong computed width or height, or no class change for isScrollable, fails. HStack.test.tsx fails if width does not win over caller style, and the HStackAudit frames fail if wrap does not break a row. Gap: height, maxWidth, and minHeight winning over caller style, maxWidth and minHeight themselves, and wrap on Stack and VStack have no check. |
audit:Stack/layout |
| FR6 | StackItem.test.tsx element, scroll, and passthrough tests |
Default and as elements; scrollable; size="fill" with scroll |
A wrong element, or no class change for isScrollable, fails. Gap: the size and crossAlignSelf tests assert only that content renders, so the minimum-size reset, static, fill, cross alignment, and the stack-item target have no check. |
audit:Stack/layout |
| FR7 | Ref and pass-through tests in all four suites; HStack.test.tsx exact-ref and merge tests |
Default and as elements |
A dropped ref fails in all four suites, and a dropped aria-label in the Stack, HStack, and StackItem suites (the VStack pass-through test asserts data-testid only). HStack.test.tsx fails if the ref reaches any element but the rendered one, or if className and style do not merge. Gap: the Stack, VStack, and StackItem ref tests accept any element, so a ref on a wrapper passes there, and the xstyle, className, style order has no check. |
audit:Stack/behavior |
| FR4 | Source review against architecture:container-padding |
Padded stack | Gap: no automated check fails if Stack publishes container-padding variables. | audit:Stack/layout |
| Theming anatomy map | scripts/check-knowledge.mjs |
Consumer anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | audit:Stack/theming |
| AR1, PR1 | serverSafeComponents.test.ts; HStack.test.tsx no-role test; HStackAudit frames; source review |
Every form | A client API (state, an effect, a context read) added without a client directive fails serverSafeComponents.test.ts. HStack.test.tsx and the HStackAudit frames fail if Stack adds a role or tab stop on its horizontal path. Gap: a client API added together with a client directive passes, and no automated check fails if Stack adds a role or tab stop on its vertical path, or StackItem adds either. |
audit:Stack/behavior |
| AR2 | useScrollRegionProps.test.tsx StackItem tests; scrollRegionName.a11y.chromium.spec.ts stack-item-scrolls and stack-item-static |
Scrolling item; caller region role and aria-label; item that is not scrollable |
A group role or name missing while the item overflows, or present on an item that is not scrollable, fails, at Chromium's accessibility tree too; a caller's role or aria-label lost fails. |
audit:Stack/behavior |
| RTL relation | RTL audit curated targets (apps/storybook/rtl-audit/targets.json): Stack and StackItem D2 on Stack / Horizontal and Stack / StackItem fill size, HStack D2 on AspectRatio / Height driven and HStack / Alignment Matrix, VStack D4 on Spinner / Narrow flex host |
Horizontal stacks, static and fill items, and a start-aligned vertical stack; LTR and RTL | A horizontal stack whose first child is not at the inline start, or a start-aligned vertical stack child that does not move to the mirrored side, fails D2 or D4. | audit:Stack/i18n-rtl |
Decision log
None recorded. The record describes shipped behavior.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.