Skip to content

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

TypeScript

docs: define component size cascade architecture (#6145)

Cindy Zhanga8e7f9f3a017
diff --git a/docs/architecture/component-size-cascade.md b/docs/architecture/component-size-cascade.md
new file mode 100644
index 0000000000..f29c13a521
--- /dev/null
+++ b/docs/architecture/component-size-cascade.md
@@ -0,0 +1,164 @@
+---
+schema_version: 1
+template_version: 1
+kind: architecture
+id: architecture:component-size-cascade
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-07
+owners: [cixzhang]
+applies_to:
+ [
+ packages/core/src/SizeContext/,
+ packages/core/src/ButtonGroup/,
+ packages/core/src/InputGroup/,
+ packages/core/src/Toolbar/,
+ packages/core/src/SideNav/,
+ ]
+verified_by:
+ [
+ packages/core/src/SizeContext/SizeContext.test.tsx,
+ packages/core/src/ButtonGroup/ButtonGroup.test.tsx,
+ packages/core/src/InputGroup/InputGroup.test.tsx,
+ packages/core/src/Toolbar/Toolbar.test.tsx,
+ packages/core/src/SideNav/SideNav.test.tsx,
+ ]
+deciding_specs: []
+---
+
+# Component size cascade architecture
+
+## Purpose
+
+A person should encounter coherent control sizing inside a component-owned group
+without every child repeating the same prop. An explicit child choice must still
+win, and components outside the declared cascade must keep their own size contract.
+
+This record owns the shared runtime precedence and scope of Astryx's standard element
+size cascade. Component and family contracts decide participation, geometry, and
+intentional overrides.
+
+## System model
+
+The standard cascade has three roles:
+
+1. A **participating consumer** accepts the standard `sm | md | lg` element-size
+ axis and resolves it through the shared size context.
+2. A **provider owner** establishes a default size for documented eligible
+ descendants.
+3. A **component default** supplies the fallback when no explicit or inherited
+ value applies.
+
+A consumer resolves one effective size in this order:
+
+1. explicit component prop;
+2. nearest active provider value; and
+3. the consumer's documented component default.
+
+The effective size then flows through the consumer's own geometry, rendered state,
+and theming contract. This architecture does not decide those component-specific
+mappings.
+
+## Boundaries and invariants
+
+- **INV1 — The standard axis is shared.** Participating components use the
+ canonical standard element-size vocabulary `sm | md | lg`. A component with a
+ genuinely different semantic axis remains outside this cascade and documents its
+ own values.
+- **INV2 — Participation is explicit.** A component inherits size only when its
+ current component or family contract adopts the cascade. Merely exposing a prop
+ named `size` does not enroll it.
+- **INV3 — Explicit intent wins.** A participating consumer's explicit size prop
+ MUST override every inherited provider value.
+- **INV4 — The nearest provider wins.** Without an explicit prop, a participating
+ consumer MUST use the nearest active provider's value. Nested provider scopes do
+ not leak through one another.
+- **INV5 — Local default is final.** Without an explicit prop or active provider
+ value, the consumer MUST use its documented component default. The shared helper's
+ generic default does not silently rewrite a component's published default.
+- **INV6 — Null resets the inherited scope.** A provider value of `null` suppresses
+ an outer inherited value for descendants in that scope, causing each consumer to
+ use its own fallback unless another nearer provider applies.
+- **INV7 — Provider ownership is declared.** A group or container provides only to
+ the eligible descendant set named by its current contract. That owner decides
+ whether it first inherits an outer size, resolves an explicit group prop, or
+ intentionally starts a new scope.
+- **INV8 — Propagation does not erase child ownership.** A provider supplies a
+ default, not a forced value. Sibling descendants resolve independently, and one
+ child's explicit override MUST NOT alter another child or the provider.
+- **INV9 — Public, rendered, and visual size agree.** After resolution, a
+ participating component's public value, rendered state, geometry, and theme-facing
+ size metadata MUST describe the same effective size under its own contract.
+- **INV10 — Exported transport is not component admission.** `SizeContext`,
+ `useSize`, and `SizeProvider` are public exports and the current transport.
+ Their public compatibility belongs to `architecture:public-component-api`.
+ Their existence or use does not by itself authorize a new public size axis or
+ enroll a component in the standard cascade.
+
+## Allowed variation
+
+- A provider owner may establish a fixed descendant size without consuming the
+ cascade for its own layout when its current contract says so.
+- A family may constrain which descendants inherit, or intentionally flatten a
+ nested member to preserve connected geometry.
+- A component may use another closed size vocabulary only outside this standard
+ cascade; generic helper typing is implementation capability, not shared semantics.
+- Themes may vary tokens or geometry for a resolved value without changing
+ precedence or provider ownership.
+
+## Change coupling
+
+Focused review triggers when a change:
+
+- adds or removes `useSize` or `SizeProvider` from a component;
+- changes a participating component's explicit, inherited, or fallback precedence;
+- changes a provider's eligible descendants or whether it inherits an outer scope;
+- adds a nonstandard value to the shared `ElementSize` type; or
+- makes rendered/theming size differ from the resolved public value.
+
+Review checks the provider and representative children with explicit, inherited,
+local-default, nested, and null-reset states.
+
+## Owning code
+
+- `packages/core/src/SizeContext/SizeContext.ts` owns shared resolution and
+ transport.
+- `packages/core/src/ButtonGroup/`, `packages/core/src/InputGroup/`,
+ `packages/core/src/Toolbar/`, and `packages/core/src/SideNav/` own the current
+ provider placement, inherited or fixed provider value, and descendant scope.
+- Participating component and family contracts own admission, component defaults,
+ eligible descendants, geometry, and intentional overrides.
+- `architecture:public-component-api` owns export reachability and compatibility
+ for `SizeContext`, `useSize`, and `SizeProvider`.
+- `architecture:component-theming-surface` and component style owners own
+ theme-facing size metadata and visual meaning after resolution.
+
+## Deciding specs
+
+None. Public admission of a new size concept still follows `spec:AST-002`; this
+record governs only the already-adopted shared cascade.
+
+## Promotion evidence gaps
+
+This authority-only draft does not add tests. Before promotion to `current`, focused
+evidence must directly cover:
+
+- a nested `null` provider resetting an outer value to the consumer's local default;
+- ButtonGroup and InputGroup inherited, explicit-group, and explicit-child
+ precedence; and
+- Toolbar intentionally starting a fixed scope beneath an unrelated outer provider.
+
+Current SideNav tests already cover its fixed `sm` footer/action sub-scopes and
+explicit child override. These gaps are verification work, not new semantics.
+
+## Verification
+
+| Invariant | Evidence | Failure signal |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| INV1–INV2 | `ElementSize` plus current component/family adoption records | a nonparticipant inherits accidentally or a participant invents a parallel standard value |
+| INV3–INV6 | `SizeContext.test.tsx` explicit/provider/default, nested-provider, null-reset, sibling, and rerender fixtures | inherited size overrides explicit intent, outer scope crosses a nearer provider, or local fallback is lost |
+| INV7–INV8 | focused ButtonGroup, InputGroup, Toolbar, and SideNav provider-owner tests plus the shared sibling fixture | a provider reaches an ineligible descendant, changes scope silently, or one child changes another |
+| INV9 | the changed participant's owning component/family geometry, rendered-state, and theming evidence; representative, not exhaustive here | resolved size and painted or exposed effective size disagree |
+| INV10 | package export inventory plus `architecture:public-component-api` review | exported transport is treated as private, or transport use is treated as component admission |