An open source design system that's fully customizable and agent ready
TypeScript
spec(compatibility): classify visual-only changes as nonbreaking (#7429)
Cindy Zhang4285bdd33b47
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex a24600f335..2313476ad1 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -650,6 +650,13 @@ This wrapper:3. **Captures the contributor(s)** — defaults to your `gh`/git identity, so credit is recorded at authoring time (not reconstructed from the release bot's commit).4. **Derives the semver bump from the category** — a `[breaking]` change bumps the minor; `[experimental]` and every other category bump the patch (see below).+Choose `[breaking]` only when a valid consumer of the latest stable release must+change source or configuration to keep a supported functional contract working,+or loses a stable public surface. A change only to existing content's appearance,+spacing, typography, layout styling, or visual default uses `[fix]` or `[feat]`+even when its pixels change. Its release note names the old and new appearance+and how to keep the old look when a supported escape exists.+It writes a normal `.changeset/<id>.md` — commit it with your PR. The body looks like:```mddiff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex 28783e9a45..6025d873ef 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -138,27 +138,32 @@ one removal merged ahead of the decision to allow it.## Requirements-- **FR1 — Breaking changes need a released victim.** A change is breaking only+- **FR1 — Breaking changes require caller adaptation.** A change is breaking onlywhen a valid consumer scenario supported by the latest stable release of a- published package no longer works unchanged, or produces an incompatible- result under a documented stable contract. The review names that scenario and- the released surface it uses.+ published package must change source or configuration to keep its code,+ interaction, data, semantic output, or supported workflow working, or loses a+ stable public surface. The review names that scenario and the released surface+ it uses.- **FR2 — Classify against the latest stable release.** A surface added and thenrenamed, removed, or reworked before any stable release has no installedconsumer and is not breaking. Private or ignored packages are outside thepublished compatibility promise. Promotion from a private package into apublished package is additive from the published side.-- **FR3 — Released contracts include behavior, not only types.** Compatibility- covers public exports and import paths; requiredness, accepted values, defaults,- return types, callbacks, and error behavior; documented interaction and+- **FR3 — Released contracts include function and semantics, not exact appearance.**+ Compatibility covers public exports and import paths; requiredness, accepted values,+ defaults, return types, callbacks, and error behavior; documented interaction andaccessibility behavior; stable CLI command names, options, exit behavior, and- machine-readable schemas; and other explicitly documented public extension- points. Internal implementation, undocumented markup, and source layout are not- stable merely because a consumer can observe them. A default change is judged by- one test (DEC-17): it is breaking when a caller who never set the prop sees their- shipped UI or output change, or when a documented contract promised the old default;- otherwise it is nonbreaking. Either way the Changeset names the old and new default- and the prop or option that restores the old default, which is the migration.+ machine-readable schemas; and other explicitly documented public extension points.+ Internal implementation, undocumented markup, source layout, and exact appearance are+ not stable merely because a consumer can observe them. A change only to existing+ content's appearance, spacing, typography, layout styling, or visual default is+ nonbreaking when public API, accepted inputs, interaction, accessibility semantics,+ data, and machine-readable output keep working. It uses `[fix]` when it restores+ current visual authority and `[feat]` when it intentionally changes visual direction.+ Its Changeset names the old and new appearance and how to keep the old look when a+ supported escape exists. A default that changes a functional or semantic contract is+ judged under FR1 instead. Its Changeset names the old and new default and the prop or+ option that restores the old default, which is the migration.- **FR4 — Preserved old usage is nonbreaking.** A rename or replacement isnonbreaking when the old released call, import, option, identifier, or inputcontinues to work with equivalent meaning through a compatibility alias or@@ -755,7 +760,7 @@ lands, maintainers apply its requirement in review and release approval.| 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 default change with and without a restoring prop | A change is labeled from diff size or possibility alone, a released contract change is missed, or a default-only change is tagged `[breaking]` without a named victim |+| FR1–FR3 | PR compatibility statement plus latest stable package inspection | released export, narrowed type, changed interaction default; unreleased and private surface; visual-only spacing, typography, layout styling, or default appearance | A change is labeled from diff size or possibility alone, a functional contract loss is hidden as visual-only, or a pixel-only change is tagged `[breaking]` even though callers need no source or configuration change || 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` (tag, bump, contributors, declared tier) plus FR8 migration review of `[breaking]` text | 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 |@@ -1095,24 +1100,26 @@ Rejected: a runtime compatibility flag or branch used only to acknowledge depreca warning without an available modernization path, copyable guidance that keepsteaching the old surface, and a migration that guesses at uncertain consumer intent.-### DEC-17 — A default change is breaking when an untouched caller sees it+### DEC-17 — Visual-only changes are compatible even when pixels change**Reference:** `spec:AST-017/DEC-17`-**Decider:** `cixzhang`, `2026-10-11`--A default change is not breaking by itself and not compatible by itself; it is judged-by a caller who never set the prop. If that caller's UI or output visibly changes —-content gains padding, a grid lays out differently, a popover becomes a sheet on-touch — the change is breaking and ships as `[breaking]` in a declared minor. If that-caller sees nothing different, it is a `[feat]` or `[fix]`. In both cases the-Changeset names the old and new default and the prop or option that restores the old-default; that restoring prop is the migration, so a default change needs no-deprecation path beyond it.--Rejected: classifying every default change as breaking, which routes invisible-changes through the minor for nothing; and classifying every default change as-compatible, which lets a visible change reach callers in a patch without the minor's-announcement.+**Decider:** `cixzhang`, `2026-10-12`++Compatibility asks whether a valid latest-stable caller must edit source or+configuration to keep a supported functional contract working. Removing or renaming a+public surface, narrowing an accepted type, or changing interaction, accessibility+semantics, data, machine-readable output, or another behavior contract can therefore be+breaking. A functional default change's Changeset names the old and new default and the+prop or option that restores the old default; that restoring input is its migration.+Changing only the appearance, spacing, typography, layout styling, or visual default of+existing content is not: it ships as `[feat]` or `[fix]` under FR3 even when an untouched+caller sees different pixels. Its release note names the old and new+appearance and how to keep the old look when a supported escape exists; that escape is+guidance, not a required compatibility migration.++Rejected: treating any pixel difference as a released victim; and calling an+interaction, semantic, data, or machine-output change visual-only because its UI also+looks different.### DEC-18 — Two rules and one gate