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.mdindex 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 sharedname 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 questionsNone.diff --git a/docs/specs/AST-066-theme-data-boundary/spec.md b/docs/specs/AST-066-theme-data-boundary/spec.mdindex 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 diagnosticsRejected: a legacy global-data mode. It would keep new artifacts on the behaviorthis 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 questionsNone.diff --git a/packages/core/src/Banner/Banner.spec.md b/packages/core/src/Banner/Banner.spec.mdindex 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.mdindex 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.mdindex 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.mdindex 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**