Skip to content

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

TypeScript
28.6 KB
Raw Blame

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 div or span StackItem with no caller role gains role="group" and an aria-label (DOM; AR2, [fix] under spec:AST-017 FR53)
  • 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.mjs documents as inline components: entries. This record covers all four; none has its own consumer doc or record.
  • The Stack container and its stack target; the StackItem wrapper and its stack-item target.
  • 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 by component: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 stack and stack-item without 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/align by 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 div or span StackItem: 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 as element. The one exception is the name of a scrolling StackItem (AR2).
  • AR2 — A scrolling StackItem is named. While a scrollable div or span StackItem scrolls, its element has role="group" (unless the caller sets a role) and an accessible name (the caller's aria-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's role takes only the caller's aria-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-primitives owns the shared spacing, padding precedence, and modifier rules; Stack, HStack, VStack, and StackItem are members, and FR2, FR3, and FR6 apply them.
  • architecture:container-padding records Stack padding as local (FR4).
  • architecture:public-component-api owns 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.