An open source design system that's fully customizable and agent ready
TypeScript
docs: clarify AST-013 browser evidence (#5914)
Cindy Zhangc203bf910d0b
diff --git a/docs/specs/AST-013/spec.md b/docs/specs/AST-013/spec.mdindex 9994b50ef0..afe2487617 100644--- a/docs/specs/AST-013/spec.md+++ b/docs/specs/AST-013/spec.md@@ -49,23 +49,24 @@ requirements. Assistive-technology evidence remains separately owned.public [Browser Support guide](../../../packages/cli/assets/docs/browser-support.doc.mjs)and record their source and refresh date. TypeScript targets, build targets, andfeature tables are not support evidence.-- **FR3 — Two official browser rows are always included.** Independently of the- generated Baseline coverage, Astryx officially supports and tests:+- **FR3 — Two explicit browser support rows are always included.** Independently+ of the generated Baseline coverage, Astryx explicitly supports:- the latest stable Chrome release on desktop; and- Safari on the latest stable iOS release.“Latest” means the current stable release identified and refreshed fromauthoritative browser release data, not a handwritten version. Other browsersmay remain represented by the generated Baseline compatibility rows; this- decision does not name desktop Safari or Firefox as additional official test+ decision does not name desktop Safari or Firefox as additional explicit supportrows.-- **FR4 — Compatibility and test coverage stay distinct.** The Browser Support- guide labels the generated Baseline compatibility rows separately from the- named official test matrix. A browser's presence in generated compatibility- data does not claim that Astryx runs an official browser lane for it.+- **FR4 — Compatibility, explicit support, and test coverage stay distinct.** The+ Browser Support guide labels generated Baseline compatibility, named explicit+ support, and current test coverage separately. A browser's inclusion in+ generated compatibility or explicit support does not imply an automated lane+ or per-pull-request proof in that browser.- **FR5 — Supported browsers receive full required behavior.** Every browser in- the full-support tier and each named official browser row receives the+ the full-support tier and each named explicit support row receives thecomponent's current behavior, accessibility, state, renderer, and interactioncontracts. A missing native feature does not silently narrow those requirements.- **FR6 — Native features are capability-detected.** Components detect the API or@@ -87,16 +88,26 @@ requirements. Assistive-technology evidence remains separately owned.enhancement begins from a usable state and introduces no mismatch, brokenintermediate state, or visible false state.- **FR10 — Browser-owned behavior needs real-browser evidence.** Source, unit, and- jsdom tests may prove guards and deterministic state. Layout, paint, focus,- native Popover or Dialog behavior, top-layer order, browser event timing, and- hydration presentation require evidence in the actual browser that owns the- claim. Chromium does not substitute for iOS Safari, and Playwright WebKit does- not prove Safari behavior.+ jsdom tests may prove guards and deterministic state. Changes to layout, paint,+ focus, native Popover or Dialog behavior, top-layer order, browser event timing,+ or hydration presentation require real-browser evidence. When a change makes a+ claim about a named browser, fixes a defect reproduced only there, or changes+ browser compatibility, that evidence must come from the actual browsers covered+ by the claim. Chromium does not substitute for an iOS Safari claim, and+ Playwright WebKit does not prove Safari behavior.++ Explicit support is a maintenance promise, not a per-change proof obligation.+ Routine changes use evidence appropriate to their claims and do not need to+ prove every supported browser before landing. A defect reproduced in an+ explicitly supported browser remains Astryx's responsibility to investigate+ and fix; missing automation does not narrow support or justify dismissal.+- **FR11 — Raising the floor is compatibility work.** Removing a supported browser,moving it from full behavior to reduced fallback, or removing a documentedfallback requires owner approval, a Changeset, user-impact and migration notes,- updated generated rows, and evidence that every remaining full-support and- named official browser row still receives full required behavior.+ updated generated rows, actual-browser evidence for the browsers affected by the+ compatibility claim, and evidence that every remaining full-support and named+ explicit support row still receives full required behavior.- **FR12 — Component specs inherit the baseline.** Component specs link`spec:AST-013` and record only stricter requirements or explicit exceptions. Anexception names the affected capability, observable reduction, preserved@@ -104,30 +115,33 @@ requirements. Assistive-technology evidence remains separately owned.### Platform support-- Full support: current Web Platform Baseline, plus the named official rows in FR3.+- Full support: current Web Platform Baseline, plus the named explicit support+ rows in FR3.- Reduced fallback: Baseline minus two years, satisfying FR7–FR9.- Unsupported: below Baseline minus two years; Astryx makes no support promise.-- Browser evidence: the actual named browser is required for browser-owned claims.+- Browser evidence: browser-owned behavior requires real-browser evidence. The+ actual named browser is required for claims specific to it, not as a blanket+ gate on every change.## Current-state impact-The public guide currently has handwritten Baseline tiers and version rows, and-routine browser CI primarily exercises Chromium. Generated compatibility rows,-the separately labeled official test matrix, and the latest stable Chrome desktop-and Safari-on-latest-stable-iOS evidence remain implementation work. These gaps do-not change the accepted contract or imply that the future lanes already exist.-Focused bug fixes continue against current contracts without waiting for that-infrastructure.+The public guide currently has handwritten Baseline tiers and version rows. The+required three-way labeling of generated compatibility, explicit support, and+current test coverage remains implementation work. Current automated browser+coverage primarily exercises Chromium; that coverage neither defines nor narrows+support. Routine changes may land with evidence appropriate to their claims.+Defects reproduced in an explicitly supported browser remain actionable whether+or not an automated lane exists.## Verification-| Contract | Required evidence | Failure signal |-| --------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |-| FR1–FR5 | Generated-row check plus guide/package/test-matrix reconciliation | A handwritten/build version becomes a support claim, official rows disappear, or supported behavior is reduced |-| FR6–FR8 | Feature-present/absent tests and active fallback fixtures | Browser sniffing selects ordinary behavior, or fallback is unusable, inaccessible, unstable, or visibly broken |-| FR9 | Server render, hydration, and post-hydration browser fixture | Markup diverges, browser state is read on the server, or a false/broken state flashes |-| FR10 | Actual-browser fixture for every browser-owned claim | Chromium or Playwright WebKit is credited with iOS Safari behavior |-| FR11–FR12 | Release review and knowledge-record checks | A floor/fallback disappears without compatibility treatment, or a component silently overrides the baseline |+| Contract | Required evidence | Failure signal |+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR5 | Generated-row check plus guide/package/support/test reconciliation | A handwritten/build version becomes a support claim, explicit support rows disappear, or supported behavior is reduced |+| FR6–FR8 | Feature-present/absent tests and active fallback fixtures | Browser sniffing selects ordinary behavior, or fallback is unusable, inaccessible, unstable, or visibly broken |+| FR9 | Server render, hydration, and post-hydration browser fixture | Markup diverges, browser state is read on the server, or a false/broken state flashes |+| FR10 | Real-browser evidence for browser-owned behavior; the actual named browser for specific claims, browser-only defects, and compatibility changes | Browser-owned behavior is credited to jsdom, another engine stands in for a named-browser claim, or a supported-browser defect is dismissed for lack of a lane |+| FR11–FR12 | Release review and knowledge-record checks | A floor/fallback disappears without compatibility treatment, or a component silently overrides the baseline |## Decision log@@ -142,6 +156,19 @@ on desktop and Safari on latest stable iOS are always included as official suppoand test rows independently of generated Baseline coverage. Generated compatibilityrows and the named official test matrix remain distinct public facts.+### DEC-2 — Explicit support does not require proof on every change++**Reference:** `spec:AST-013/DEC-2`+**Decider:** `cixzhang`, `2026-09-02`++DEC-1's two named browser rows are explicit support rows, not a required automated+or per-change test matrix. Astryx investigates and fixes defects reproduced in+those browsers, but routine changes do not need to prove every supported browser+before landing. Actual-browser evidence is required when the change makes a+browser-specific claim, fixes a defect reproduced only there, or changes+compatibility. Missing automation neither narrows support nor justifies dismissing+a reproduced defect.+## Open questionsNone.