Skip to content

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

TypeScript

[Spec] Proposed lifecycle records for the core breaking changes (#7291)

Cindy Zhang7d4628128657
diff --git a/docs/specs/AST-032/spec.md b/docs/specs/AST-032/spec.md
index 90f6bc1be7..72828c7ead 100644
--- a/docs/specs/AST-032/spec.md
+++ b/docs/specs/AST-032/spec.md
@@ -164,6 +164,38 @@ the one key a complete registry may omit.
Rejected: a permanently optional `upload`, because it would be the only shared
name a complete registry could leave out.
+## Deprecation and cleanup records
+
+### DEP-0012 — Deprecate complete `IconRegistry` types that omit `upload`
+
+| Field | Value |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| id | `DEP-0012` |
+| cleanup | `CLN-0021` |
+| package | `@astryxdesign/core` |
+| surface | The public `IconRegistry` type accepting a complete registry that omits `upload` |
+| old contract | A complete registry typed as `IconRegistry` may omit `upload`; the omitted entry resolves the default artwork |
+| replacement | Add an `upload` entry in the registry's own style; `IconRegistry` already accepts it |
+| direct authority | FR6 and DEC-3. Owners: `spec:AST-032`: `cixzhang`, `imdreamrunner` |
+| warning | Consumer docs and the release notes name `DEP-0012`. No runtime warning (`spec:AST-017` FR29) |
+| migration | Non-mechanical: draw `upload` artwork in the registry's style |
+| codemod | None: icon artwork is bespoke to each theme and cannot be synthesized |
+| downstream | The default registry, every bundled theme, and every CLI theme template supply `upload` |
+| transition | no prior transition |
+| state | `deprecated` |
+| open decision | None beyond listing `CLN-0021` in the minor plan |
+| target plan | `CLN-0021` in the next minor release, as FR6 schedules |
+
+### CLN-0021 — `IconRegistry` requires `upload`
+
+| Field | Value |
+| --------- | ------------------------------------------------------------------------------------------------------------ |
+| id | `CLN-0021` |
+| lifecycle | `DEP-0012` |
+| delta | `IconRegistry` is `Record<IconName, ReactNode>`: a complete registry that omits `upload` fails to type-check |
+| rollback | Restore the transitional optional `upload` from the final-patch baseline |
+| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0021` |
+
## Open questions
None.
diff --git a/docs/specs/AST-066-theme-data-boundary/spec.md b/docs/specs/AST-066-theme-data-boundary/spec.md
index a8dac76b87..5eba96ccd6 100644
--- a/docs/specs/AST-066-theme-data-boundary/spec.md
+++ b/docs/specs/AST-066-theme-data-boundary/spec.md
@@ -519,6 +519,41 @@ The release uses a breaking 0.x minor with regeneration and consumer diagnostics
Rejected: a legacy global-data mode. It would keep new artifacts on the behavior
this decision removes and make runtime/static ownership mode-dependent.
+## Deprecation and cleanup records
+
+### IFIX-0009 — Themes stop emitting raw global data-color defaults
+
+| Field | Value |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `IFIX-0009` |
+| cleanup | `CLN-0016` |
+| package | `@astryxdesign/core`, `@astryxdesign/cli` |
+| surface | The unscoped raw `:root` block of canonical data-color defaults that `Theme` runtime and `theme build` (standalone and family) emit for every theme |
+| authority | FR6 (concrete themes emit only explicitly authored data values), FR7 (theme build never emits raw global data defaults), and FR12 (availability follows StyleX use). Owners: `spec:AST-066`: `cixzhang` |
+| reproducer | With the latest stable packages, a theme that authors no data colors emits every canonical data default in an unscoped root block, in runtime CSS and in `theme build` output |
+| affected | CSS that reads a raw data-color custom property directly, relying on a theme to define it, without compiling a `dataVars` consumer; and stale generated theme CSS checked into an app |
+| matrix | Theme with no authored data colors: every canonical default before; none after. Authored override: emitted before and after, scoped to its theme. StyleX `dataVars` consumers: same painted values before and after. Global `color-scheme` rules: unchanged |
+| coexistence | The public `dataVars` group carries the canonical values before and after, so a consumer that reads `dataVars` gets the same values on both |
+| migration | Read data colors through the public `dataVars` group, or author the needed values in the theme. Regenerate built theme CSS |
+| codemod | `astryx upgrade` runs a validator that reports direct raw consumers and stale generated CSS; the rewrite depends on whether the consumer compiles StyleX |
+| downstream | Maintained docs and templates read data colors through `dataVars` |
+| rollback | Restore the raw default block in runtime and `theme build` output from the final-patch baseline |
+| harm of delay | Every theme keeps shipping a second global palette that survives without any consumer and can disagree with the canonical StyleX group |
+| harm of apply | CSS that reads a raw data variable without `dataVars` or an authored value paints with the variable unset until it migrates |
+| transition | no prior transition |
+| state | `proposed` |
+| open decision | None beyond approving this proposed record and its cleanup |
+
+### CLN-0016 — Remove raw global data-color defaults from theme output
+
+| Field | Value |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `CLN-0016` |
+| lifecycle | `IFIX-0009` |
+| delta | Runtime and built themes emit only authored data values, scoped to their theme. Explicit layer order and global `color-scheme` rules are unchanged |
+| rollback | Restore the raw default block from the final-patch baseline |
+| state | `pending` — lands only in a minor release, once `IFIX-0009` is approved and that release's frozen manifest lists `CLN-0016` |
+
## Open questions
None.
diff --git a/packages/core/src/Banner/Banner.spec.md b/packages/core/src/Banner/Banner.spec.md
index 1760d3070b..5e8b2d68a7 100644
--- a/packages/core/src/Banner/Banner.spec.md
+++ b/packages/core/src/Banner/Banner.spec.md
@@ -48,6 +48,36 @@ separately targetable surface. The status and content targets remain unchanged.
Consumer migration instructions belong in consumer docs and release notes.
+### DEP-0007 — Deprecate live-region roles derived from `status`
+
+| Field | Value |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `DEP-0007` |
+| cleanup | `CLN-0015` |
+| package | `@astryxdesign/core` |
+| surface | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role` |
+| old contract | Visual `status` selects the live-region role of the Banner root |
+| replacement | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root |
+| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner` |
+| warning | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29) |
+| migration | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"` |
+| codemod | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes |
+| downstream | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors |
+| transition | no prior transition |
+| state | `proposed` |
+| open decision | Banner FR and DEC entries that make `status` visual-only |
+| target plan | `CLN-0015` in the next minor release |
+
+### CLN-0015 — Banner renders no live-region role by default
+
+| Field | Value |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `CLN-0015` |
+| lifecycle | `DEP-0007` |
+| delta | `Banner` renders no `role` and no `aria-live` unless the caller passes `role`. Visual status styling, icons, theming targets, and explicit `role` forwarding are unchanged |
+| rollback | Restore the `status`-to-role map from the final-patch baseline |
+| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0015` |
+
## Ownership boundary
**Owns**
diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.md
index 74b21deeb8..794fd67591 100644
--- a/packages/core/src/BottomSheet/BottomSheet.spec.md
+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md
@@ -53,6 +53,36 @@ scrolling, theming reachability, and the Content area's container padding.
Consumer migration instructions belong in consumer docs and release notes.
+### DEP-0009 — Deprecate the unpadded default Content area of `BottomSheet`
+
+| Field | Value |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `DEP-0009` |
+| cleanup | `CLN-0018` |
+| package | `@astryxdesign/core` |
+| surface | Default inset of the `BottomSheet` Content area when no `padding` prop and no theme padding are set |
+| old contract | The Content area has no padding |
+| replacement | `padding={0}` keeps the unpadded Content area; `padding` and theme padding already resolve before the default |
+| direct authority | `component:BottomSheet` Compatibility and migration. Owners: `cixzhang` |
+| warning | Consumer docs and the release notes name `DEP-0009` and `padding={0}`. No runtime warning (`spec:AST-017` FR29) |
+| migration | Mechanical: add `padding={0}` to a BottomSheet that sets no padding, unless its only child is a padded Section or a Layout |
+| codemod | `astryx upgrade` adds `padding={0}` before any spread, skips sheets whose only child is a core Section or Layout, and marks a nested padding-less Layout for review |
+| downstream | In-repo sheets that supply their own inset pass `padding={0}`; consumer examples rely on the default inset |
+| transition | no prior transition |
+| state | `proposed` |
+| open decision | This record is draft and needs approval |
+| target plan | `CLN-0018` in the next minor release |
+
+### CLN-0018 — BottomSheet pads its Content area by default
+
+| Field | Value |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| id | `CLN-0018` |
+| lifecycle | `DEP-0009` |
+| delta | With no `padding` prop and no theme padding, the Content area insets by `--spacing-4` on every logical edge and publishes that inset |
+| rollback | Restore the unpadded default from the final-patch baseline |
+| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0018` |
+
## Ownership boundary
**Owns**
diff --git a/packages/core/src/Grid/Grid.spec.md b/packages/core/src/Grid/Grid.spec.md
index 9b38d05482..2988faaae6 100644
--- a/packages/core/src/Grid/Grid.spec.md
+++ b/packages/core/src/Grid/Grid.spec.md
@@ -44,6 +44,36 @@ layout, targets, or public API.
Consumer migration instructions belong in consumer docs and release notes.
+### DEP-0010 — Deprecate the fixed meaning of numeric `Grid` `columns`
+
+| Field | Value |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `DEP-0010` |
+| cleanup | `CLN-0019` |
+| package | `@astryxdesign/core` |
+| surface | `Grid` `columns={N}`, which renders exactly N equal tracks (`repeat(N, 1fr)`) |
+| old contract | A numeric `columns` value is an explicit equal-width track count at every width |
+| replacement | `columns={{count: N, isFixed: true}}` keeps exactly N tracks |
+| direct authority | `component:Grid`, with `family:layout-primitives` representative matrix row "Grid / fixed columns". Owners: `cixzhang` (`component:Grid`); `cixzhang`, `imdreamrunner` (`family:layout-primitives`) |
+| warning | Consumer docs and the release notes name `DEP-0010` and the fixed shape. No runtime warning (`spec:AST-017` FR29) |
+| migration | Mechanical where the fixed count is wanted: rewrite `columns={N}` to `columns={{count: N, isFixed: true}}`. Keeping the number accepts the new reflow |
+| codemod | None yet. A preserving codemod is mechanical, but it would opt every caller out of the change it exists to deliver |
+| downstream | In-repo fixed rows such as week rows use the fixed shape |
+| transition | no prior transition |
+| state | `proposed` |
+| open decision | This record is draft and lists new responsive behavior as a non-goal; the family matrix pins numeric columns as fixed. Both need an owner ruling |
+| target plan | `CLN-0019` in the next minor release |
+
+### CLN-0019 — Numeric `columns` means at most N columns
+
+| Field | Value |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `CLN-0019` |
+| lifecycle | `DEP-0010` |
+| delta | A numeric `columns` value renders up to N columns of at least 12rem and fewer when the grid is narrower; a `GridSpan` in such a grid takes the full row once the grid has fewer columns than it spans |
+| rollback | Restore `repeat(N, 1fr)` for numeric `columns` from the final-patch baseline |
+| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0019` |
+
## Ownership boundary
**Owns**
diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.md
index 4ee5fa009b..7a0fc511ad 100644
--- a/packages/core/src/Selector/Selector.spec.md
+++ b/packages/core/src/Selector/Selector.spec.md
@@ -62,6 +62,36 @@ connection between the closed trigger and its selection surface.
editing affordances. `isDisabled` takes precedence when both are set.
- `spec:AST-004/DEC-1` governs the state-derived indicator-space behavior in FR3.
+### DEP-0011 — Deprecate the `popover` default presentation
+
+| Field | Value |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `DEP-0011` |
+| cleanup | `CLN-0020` |
+| package | `@astryxdesign/core` |
+| surface | Default `presentation` of `Selector`, `MultiSelector`, and `DropdownMenu` with `items` (and `MoreMenu`, which forwards to it): the anchored popover on every device |
+| old contract | With no `presentation`, the option or action list opens in an anchored, non-modal popover on every device |
+| replacement | `presentation="popover"` keeps the anchored popover on every device; `adaptive` is released and already accepted |
+| direct authority | `component:Selector` DEC-1. Owners: `cixzhang`, `imdreamrunner`. `MultiSelector` and `DropdownMenu` have no current contract that sets this default |
+| warning | Consumer docs and the release notes name `DEP-0011` and `presentation="popover"`. No runtime warning (`spec:AST-017` FR29) |
+| migration | Mechanical where the popover is wanted on every device: add `presentation="popover"` |
+| codemod | None by default: pinning `popover` everywhere would opt every caller out of the change. A preserving codemod is mechanical if an owner wants one |
+| downstream | Guidance says to keep the default and pin `popover` only when product policy needs it |
+| transition | no prior transition |
+| state | `proposed` |
+| open decision | Current authority for the `MultiSelector` and `DropdownMenu` defaults |
+| target plan | `CLN-0020` in the next minor release |
+
+### CLN-0020 — Selector, MultiSelector, and data-driven DropdownMenu default to `adaptive`
+
+| Field | Value |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `CLN-0020` |
+| lifecycle | `DEP-0011` |
+| delta | With no `presentation`, a compact coarse-pointer screen opens a modal bottom sheet (trigger `aria-haspopup="dialog"`, focus moves in and returns on close); every other device keeps the anchored popover. Compound DropdownMenus are unchanged |
+| rollback | Restore the `popover` default from the final-patch baseline |
+| state | `pending` — lands only in a minor release whose frozen manifest lists `CLN-0020` |
+
## Ownership boundary
**Owns**