An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): define cross-surface deprecation behavior (#7106)
Cindy Zhang36cf0f2724ee
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex e22d2a0997..1eddf55e69 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-10-02+approved_at: 2026-10-07phase: acceptedowners: [cixzhang, josephfarina]affects_architecture:@@ -66,6 +66,10 @@ affects_consumer_docs: [release-process, templates]"FR27","FR28","FR29",+ "FR29a",+ "FR29b",+ "FR29c",+ "FR29d","FR30","FR31","FR32",@@ -87,7 +91,8 @@ affects_consumer_docs: [release-process, templates]"FR48","FR49","FR50",- "DEC-15"+ "DEC-15",+ "DEC-16"]}}@@ -393,31 +398,78 @@ change shape because one removal merged ahead of the decision to allow it.experimental routes. An omitted opt-in MUST leave stable defaults, output, routes,data, and behavior unchanged. Promotion requires owner approval and a `[feat]`Changeset; withdrawal uses `[experimental]` and MUST prove no stable spillover.-- **FR28 — Deprecation is replacement-first and machine-readable.** A deprecation- patch ships the working replacement while old usage remains equivalent. A public- record assigns a stable `DEP-*` id and a distinct `CLN-*` cleanup id and names the- package, surface kind, old contract, replacement, direct authority, warning,- migration, codemod or non-mechanical reason, downstream proof, state, and target- plan. Prose alone does not create removal eligibility.-- **FR29 — Warnings fit the surface without changing success.** Declarations use- `@deprecated`; CLI aliases expose the deprecation id and replacement in their- machine result and emit at most one human-readable stderr warning per invocation;- runtime and build APIs use deduplicated development warnings; CSS and tokens use- static diagnostics. Warnings MUST NOT change production behavior, successful exit- status, canonical output, or machine-readable stdout.+- **FR28 — Deprecation is replacement-first, actionable, and machine-readable.** A+ deprecation patch ships the working replacement while old usage remains equivalent.+ Before a surface enters `deprecated`, its supported modernization route MUST be+ available: an exact migration command or codemod when the rewrite is mechanical, or+ ordered and testable instructions when it is not. A public record assigns a stable+ `DEP-*` id and a distinct `CLN-*` cleanup id and names the package, surface kind, old+ contract, replacement, direct authority, warning, migration, codemod or non-mechanical+ reason, downstream proof, state, and target plan. Prose alone does not create removal+ eligibility.+- **FR29 — Deprecation adds no production-runtime behavior.** Marking a surface+ deprecated MUST NOT add a production runtime branch, log, byte, network action,+ changed render, or changed output. Compatibility code needed to keep an already+ released old contract working is separate from warning delivery and MUST preserve+ that contract. A development-only runtime diagnostic is permitted only when runtime+ information is necessary to explain an ambiguous coexistence state, such as both an+ old and replacement prop being supplied; it explains the direct owner's precedence+ rule and is not the primary deprecation channel.+- **FR29a — Warnings live at the earliest accurate authoring surface.** TypeScript+ declarations use static `@deprecated` metadata. Build-interpreted source and+ configuration warn in the authoring, validation, or build reader that can name the+ exact source use. CLI commands and options expose the deprecation id and replacement+ in their machine result and emit at most one human-readable stderr warning per+ invocation. CSS and tokens use static diagnostics. Rendered applications never emit+ a warning merely because a deprecated surface is used. Warnings MUST NOT change a+ successful exit status, canonical output, machine-readable stdout, generated output,+ or rendered behavior.+- **FR29b — Guidance teaches one modern path.** Every warning names the `DEP-*` id,+ exact replacement, stable versioned instructions, and exact migration command when+ one exists. Maintained API docs, generated docs, templates, examples, stories,+ starter output, and agent-facing guidance teach only the replacement. Explicit+ reference remains available for the deprecated surface, visibly labeled with the+ same replacement and modernization route. A warning MUST NOT ship before those+ instructions and that route exist.+- **FR29c — Modernization is safe and verifiable.** A mechanical migration is+ previewable, idempotent, evidence-scoped, and complete under `spec:AST-040`; it+ preserves the old observable result as its baseline and reports every uncertain or+ blocked case. Non-mechanical migration gives short, ordered, testable instructions+ rather than saying only to update manually. The direct owner names the applicable+ source, type, build, runtime, visual, accessibility, and CLI proof. Maintained Astryx+ packages and authoring surfaces migrate in the deprecation patch.+- **FR29d — Each public surface projects the lifecycle without inventing another one.**+ Whole components remain exported, renderable, accessible, themeable, and explicitly+ discoverable, but leave recommendations and copyable examples; their exports and+ docs carry the replacement and modernization route, with no render-time deprecation+ warning. Deprecated props and values keep old-only behavior, declare deterministic+ old-plus-new precedence, and statically name the replacement; codemods rewrite proven+ static uses and report spreads or dynamic expressions they cannot prove. Theme API+ fields, helpers, tokens, targets, and source keep identical normalization and rendered+ output; declarations use `@deprecated`, and theme build or validation reports exact+ source uses without `defineTheme`, theme mounting, or applications warning at+ runtime. Deprecated CLI commands and options remain accepted with their released+ exit status, canonical stdout, JSON envelope, and side effects; help and explicit+ lookup label them, human mode warns once on stderr, machine mode carries the+ deprecation metadata, and generated examples use the replacement. When old and new+ CLI controls coexist, their direct command contract defines precedence or rejects+ the ambiguous combination identically in text and JSON modes.- **FR30 — Deprecation minima come only from direct authority.** This global specimposes no elapsed-time or release-count minimum. The structural minimum is that thefinal patch preserves old and new behavior together. A direct current spec MAYrequire a duration or number of stable releases for its own surface; the `DEP-*`record cites that exact requirement and CI enforces it. Release cadence MUST NOT beinterpreted as a deprecation clock or eligibility gate.-- **FR31 — Cleanup is one-to-one with approved ids.** A removal or default switch is- allowed only when its applicable lifecycle record id (`DEP-*` for deprecation or- `IFIX-*` for correction) and distinct `CLN-*` id appear in the frozen minor- manifest. Each incompatible delta maps to exactly one applicable lifecycle record- and one cleanup id, and each cleanup id maps to the old contract, replacement,- migration, proof, and rollback. Newly introduced incompatibility cannot be legalized- by adding it directly to a plan.+- **FR31 — Cleanup is one-to-one with approved ids and proven modernization.** A+ removal or default switch is allowed only when its applicable lifecycle record id+ (`DEP-*` for deprecation or `IFIX-*` for correction) and distinct `CLN-*` id appear in+ the frozen minor manifest. Each incompatible delta maps to exactly one applicable+ lifecycle record and one cleanup id, and each cleanup id maps to the old contract,+ replacement, migration, proof, and rollback. Cleanup evidence MUST show that+ maintained sources no longer teach or use the old surface and that a latest-stable+ consumer can follow the supported old-to-new route; uncertain cases remain reported+ rather than guessed. Newly introduced incompatibility cannot be legalized by adding+ it directly to a plan.- **FR32 — Behavior-correcting incompatibility is a distinct classification.** An`incompatible-fix` exists when pre-existing current authority proves releasedbehavior wrong, unsafe, or nonconforming AND a valid latest-stable consumer relies@@ -646,12 +698,13 @@ incompatible.## Current-state impact-Existing classification remains in force. This amendment adds the missing durable-lifecycle around it:+Public lifecycle classification remains in force with these operational effects:- stable changes default to compatible patch treatment;- experimental containment extends to every public surface kind;-- deprecations and behavior corrections become machine-readable and cleanup-owned;+- deprecations are replacement-first, machine-readable, and cleanup-owned; warnings+ stay at authoring surfaces, production runtime stays unchanged, and an executable+ modernization route precedes warning delivery;- planned minors use a locked final-patch baseline while admitting only approvedcleanup, closed release metadata, and independently patch-compatible fixes;- minor frequency remains planning guidance and creates no deprecation or pair wait;@@ -661,44 +714,42 @@ lifecycle around it:`docs` command and machine-readable schemas stay contractual; and- exact-main release comparison rejects unclassified deltas.-This amendment adds the admission gate those lifecycle rules were missing. FR31 and-FR37 already require an owner-approved plan before a removal ships, but they are-evaluated by the release owner at freeze, and nothing evaluated them when a-`[breaking]` Changeset merged into main. Because the fixed group publishes as one-version, a single such Changeset moves the whole release to a minor. FR46–FR50 make-the patch the default, require a minor to be scheduled before its breaking work-lands, and otherwise change nothing: the gate answers patch-versus-minor admission-only, and adds no per-change record, manifest, or approval path.+Main targets a patch by default. A scheduled minor makes breaking work admissible+before that work lands; a pending `[breaking]` Changeset cannot retarget its own+release. Because the fixed package group publishes as one version, this admission gate+prevents one unapproved removal from moving the whole release to a minor. It does not+add a per-change approval path: lifecycle, cleanup, migration, and freeze requirements+remain independently enforceable.-These are specification changes only. They do not alter a published package and need-no Changeset. Authoring helpers, validators, manifests, compatibility snapshots,-release workflows, and contributor documentation are follow-up implementation. Until-they land, maintainers apply these requirements in review and release approval.+These requirements alter no published package by themselves and need no Changeset.+Authoring helpers, validators, metadata projections, compatibility snapshots, release+workflows, and contributor guidance implement the contract. Until each projection+lands, maintainers apply its requirement in review and release approval.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |-| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |-| FR7–FR8 | `pnpm check:changesets` plus migration review | existing `[fix]`, `[feat]`, `[breaking]`, and `[experimental]` tags paired with compatible, deprecation, planned-removal, or incompatible-fix metadata | A new lifecycle replaces an established tag, tag/metadata/bump diverge, an incompatible correction uses bare `[fix]`, or migration is unusable |-| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |-| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |-| FR14 | Help/manifest snapshots, public API and consumer docs, and focused contract tests | command, option, API/config, private rollout/test hook | Supported behavior is hidden, an environment variable changes behavior, or automation lacks a documented API |-| FR15 | Full manifest-derived command matrix, supported-consumer evidence, and scope-specific contract tests | global invariant, scoped command group, single command, programmatic API | A global control is a no-op for any command, has different meanings, or replaces a narrower owning surface |-| FR16–FR18 | Boundary inventory, hostile side-effect probes, response snapshots, and concurrent API tests | known and new extension, partial result, text/JSON/API parity, independent concurrent calls | A route bypasses the guarantee, omitted work looks complete, or one invocation changes another |-| FR19–FR20 | Proposal evidence with a regression fixture for the detection failure, plus composition and provenance tests | convention covers the case, detection fails, app plus two integrations, refusal, failing contribution, repeated load | A key ships without a reproduced detection failure, a contribution displaces the app or applies twice, a part of the effective value has no inspectable source, or a failure silently weakens protection |-| FR21–FR24 | Published-surface comparison, declaration/doc metadata checks, import-boundary checks, and Changeset classification review | experimental prop object, experimental subpath, patch evolution, promotion, unpublished adjacent field, stable warning behavior, integration theme | A prose-only marker excludes a stable API, adjacency falsely publishes a new field, an experimental export leaks through a stable path, a patch changes stable behavior, or a promoted API remains unprotected |-| FR25–FR27 | Stable-surface inventory and experimental-boundary matrix | package/API, CSS/token, CLI/config, persistence, build tooling, docs, whole Lab component | An unmarked experiment changes stable defaults or a stable surface bypasses compatibility review |-| FR28–FR31 | Closed-schema deprecation and cleanup records plus old/new compatibility fixtures | replacement first, warning projections, explicit direct-spec minimum, one-to-one cleanup | Prose creates eligibility, cadence invents a wait, old behavior degrades early, or a cleanup id covers more than one incompatible delta |-| FR32–FR35 | Latest-stable victim fixture, pre-existing authority, owner reviews, correction record, record-to-surface state mapping, and emergency attestation | victim-free `[fix]`, `[fix]` plus incompatible-fix metadata, coexistence, cleanup transition, critical-harm emergency | A released victim uses bare `[fix]`, a new Changeset tag replaces metadata, a correction record disagrees with its public-surface state, or urgency bypasses migration |-| FR36–FR40 | Minor plan, locked final-patch receipt, three-way delta classification, and separated release notes | ordinary cadence, immediate pair, cleanup, release metadata, pre/post-lock compatible fix | Cadence becomes eligibility, the final patch is recut for bookkeeping, a feature or incompatible fix enters the incidental-fix lane, or release notes merge cleanup with fixes |-| FR41–FR44 | Schema validation, PR declaration, semantic stable/base/head comparisons, exact-main gate, and immutable publish/rollback receipt | duplicate ids, missing evidence, route/schema removal, old-client metadata, partial publish, safe rollback | A label passes without semantics, a delta maps zero or multiple times, fixed-group membership drifts, or a release rebuilds under one identity |-| FR45 | Docs route inventory, repository-reference checks, and Changeset review | catalog entry rename, former-route miss, stable command and JSON schema | Catalog routing is frozen as API, or a rename silently changes the contractual command or response schema |-| FR46–FR47 | Admission tests pairing the default mode and an explicit scheduled minor with each Changeset category | no target statement, a scheduled minor, a pending `[breaking]` entry with no statement | A pending Changeset switches the mode by itself, or the default requires a file to be the default |-| FR48 | Category and classification admission under each mode | patch default with `[breaking]`, patch default with a deprecation, scheduled minor with `[breaking]` | Incompatible work passes under the patch default, or a deprecation is refused under it |-| FR49 | Malformed, inconsistent, expired, and mixed-version target fixtures | unknown field, non-semver version, version that is not the minor successor, past scheduled day, disagreeing published versions, canary identifier | An untrustworthy statement grants the minor mode, or a past schedule still admits work |-| FR50 | Removal of the statement, and message assertions on the rejection text | statement removed after the minor ships, rejection under the patch default | Returning to the default needs its own approval, or the refusal omits the target or either remedy |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, behavior, CLI command; unreleased and private surface | A change is labeled from diff size or possibility alone, or a released contract change is missed |+| FR4–FR6 | Old-usage type/runtime/CLI regression test | alias retained, deprecation warning, broad rewrite, low-adoption caller | Contractual old usage fails despite a nonbreaking label, or risk is substituted for compatibility |+| FR7–FR8 | `pnpm check:changesets` plus migration review | existing `[fix]`, `[feat]`, `[breaking]`, and `[experimental]` tags paired with compatible, deprecation, planned-removal, or incompatible-fix metadata | A new lifecycle replaces an established tag, tag/metadata/bump diverge, an incompatible correction uses bare `[fix]`, or migration is unusable |+| FR9–FR13 | CLI contract tests, response-schema/type snapshots, text projections, generated consumer docs, and template catalog/output tests | slug rename, metadata edit, source rebuild, optional field addition, command or schema change | Catalog data is frozen as API, a command/schema incompatibility is mislabeled as catalog-only, or a response field lacks a complete projection |+| FR12 | Minimum and representative supported-version tests plus manifest and release-note review | retained range, narrowed range, adapter, coordinated upgrade | An in-range combination breaks under a nonbreaking label, or release coordination hides the affected package or migration |+| FR14 | Help/manifest snapshots, public API and consumer docs, and focused contract tests | command, option, API/config, private rollout/test hook | Supported behavior is hidden, an environment variable changes behavior, or automation lacks a documented API |+| FR15 | Full manifest-derived command matrix, supported-consumer evidence, and scope-specific contract tests | global invariant, scoped command group, single command, programmatic API | A global control is a no-op for any command, has different meanings, or replaces a narrower owning surface |+| FR16–FR18 | Boundary inventory, hostile side-effect probes, response snapshots, and concurrent API tests | known and new extension, partial result, text/JSON/API parity, independent concurrent calls | A route bypasses the guarantee, omitted work looks complete, or one invocation changes another |+| FR19–FR20 | Proposal evidence with a regression fixture for the detection failure, plus composition and provenance tests | convention covers the case, detection fails, app plus two integrations, refusal, failing contribution, repeated load | A key ships without a reproduced detection failure, a contribution displaces the app or applies twice, a part of the effective value has no inspectable source, or a failure silently weakens protection |+| FR21–FR24 | Published-surface comparison, declaration/doc metadata checks, import-boundary checks, and Changeset classification review | experimental prop object, experimental subpath, patch evolution, promotion, unpublished adjacent field, stable warning behavior, integration theme | A prose-only marker excludes a stable API, adjacency falsely publishes a new field, an experimental export leaks through a stable path, a patch changes stable behavior, or a promoted API remains unprotected |+| FR25–FR27 | Stable-surface inventory and experimental-boundary matrix | package/API, CSS/token, CLI/config, persistence, build tooling, docs, whole Lab component | An unmarked experiment changes stable defaults or a stable surface bypasses compatibility review |+| FR28–FR31 | Closed-schema deprecation/cleanup records; declaration/doc/build/CLI warning projections; old/new fixtures; dry-run/idempotence/migration tests; maintained-source and latest-stable upgrade evidence | whole component, prop/value, theme field/helper/token/target/source, CLI command, CLI option; old-only, new-only, both, static/dynamic/uncertain migration, text/JSON, development/production | A warning has no usable modernization route, production runtime changes for deprecation, maintained guidance teaches the old surface, a migration guesses, old behavior degrades early, cadence invents a wait, or one cleanup id covers multiple incompatible deltas |+| FR32–FR35 | Latest-stable victim fixture, pre-existing authority, owner reviews, correction record, record-to-surface state mapping, and emergency attestation | victim-free `[fix]`, `[fix]` plus incompatible-fix metadata, coexistence, cleanup transition, critical-harm emergency | A released victim uses bare `[fix]`, a new Changeset tag replaces metadata, a correction record disagrees with its public-surface state, or urgency bypasses migration |+| FR36–FR40 | Minor plan, locked final-patch receipt, three-way delta classification, and separated release notes | ordinary cadence, immediate pair, cleanup, release metadata, pre/post-lock compatible fix | Cadence becomes eligibility, the final patch is recut for bookkeeping, a feature or incompatible fix enters the incidental-fix lane, or release notes merge cleanup with fixes |+| FR41–FR44 | Schema validation, PR declaration, semantic stable/base/head comparisons, exact-main gate, and immutable publish/rollback receipt | duplicate ids, missing evidence, route/schema removal, old-client metadata, partial publish, safe rollback | A label passes without semantics, a delta maps zero or multiple times, fixed-group membership drifts, or a release rebuilds under one identity |+| FR45 | Docs route inventory, repository-reference checks, and Changeset review | catalog entry rename, former-route miss, stable command and JSON schema | Catalog routing is frozen as API, or a rename silently changes the contractual command or response schema |+| FR46–FR47 | Admission tests pairing the default mode and an explicit scheduled minor with each Changeset category | no target statement, a scheduled minor, a pending `[breaking]` entry with no statement | A pending Changeset switches the mode by itself, or the default requires a file to be the default |+| FR48 | Category and classification admission under each mode | patch default with `[breaking]`, patch default with a deprecation, scheduled minor with `[breaking]` | Incompatible work passes under the patch default, or a deprecation is refused under it |+| FR49 | Malformed, inconsistent, expired, and mixed-version target fixtures | unknown field, non-semver version, version that is not the minor successor, past scheduled day, disagreeing published versions, canary identifier | An untrustworthy statement grants the minor mode, or a past schedule still admits work |+| FR50 | Removal of the statement, and message assertions on the rejection text | statement removed after the minor ships, rejection under the patch default | Returning to the default needs its own approval, or the refusal omits the target or either remedy |## Decision log@@ -1005,6 +1056,27 @@ Rejected: leaving the schedule open-ended. A statement with no date would outlivrelease and quietly keep main in minor mode. Expiry makes a forgotten statement failback to the patch default instead of silently widening what may land.+### DEC-16 — Deprecation acts at authoring surfaces, not production runtime++**Reference:** `spec:AST-017/DEC-16`+**Decider:** `cixzhang`, `2026-10-07`++A deprecation reaches a builder where the obsolete choice is authored: declarations,+generated reference, theme validation or build, CLI help and invocation, and supported+migration tooling. The working replacement and executable modernization route exist+before warnings begin. Maintained guidance teaches the replacement, while explicit+lookup keeps the deprecated surface and its exact route discoverable.++Production runtime behavior and bytes remain unchanged merely because a surface is+deprecated. The old contract continues working until its separately approved cleanup;+a runtime-only coexistence conflict may receive a development diagnostic explaining+the direct owner's precedence rule. Cleanup follows only after the migration can+preserve or explicitly account for every observable result it owns.++Rejected: a runtime compatibility flag or branch used only to acknowledge deprecation,+a warning without an available modernization path, copyable guidance that keeps+teaching the old surface, and a migration that guesses at uncertain consumer intent.+## Open questionsNone.