An open source design system that's fully customizable and agent ready
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
{
"scope": "global",
"triggers": {
"layout": ["INV1", "INV2", "INV3", "INV4", "INV5", "INV9"]
}
}
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:
- A participating consumer accepts the standard
sm | md | lgelement-size axis and resolves it through the shared size context. - A provider owner establishes a default size for documented eligible descendants.
- A component default supplies the fallback when no explicit or inherited value applies.
A consumer resolves one effective size in this order:
- explicit component prop;
- nearest active provider value; and
- 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
sizedoes 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
nullsuppresses 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, andSizeProviderare public exports and the current transport. Their public compatibility belongs toarchitecture: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
useSizeorSizeProviderfrom 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
ElementSizetype; 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.tsowns shared resolution and transport.packages/core/src/ButtonGroup/,packages/core/src/InputGroup/,packages/core/src/Toolbar/, andpackages/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-apiowns export reachability and compatibility forSizeContext,useSize, andSizeProvider.architecture:component-theming-surfaceand 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
nullprovider 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 |