An open source design system that's fully customizable and agent ready
TypeScript
docs: make review contraction-first (#6256)
Cindy Zhangbc1ddba39311
diff --git a/docs/architecture/interaction-modality.md b/docs/architecture/interaction-modality.mdindex a26ae96fc2..9a964b757e 100644--- a/docs/architecture/interaction-modality.md+++ b/docs/architecture/interaction-modality.md@@ -131,7 +131,10 @@ work.modality. Evidence names the lost or stale outcome and verifies representativenormal or legacy paths remain unchanged by the remedy. Aesthetic preference,speculative unsupported states, and a claim that an action merely could be easier- to discover do not establish a violation.+ to discover do not establish an interaction violation. This does not bar a visual+ correction already settled by current component, family, design, theme, or+ objective accessibility authority; that correction uses rendered-pixel evidence+ and its direct owner rather than being recast as interaction reachability.## Allowed variation@@ -155,9 +158,11 @@ authorize one.`architecture:knowledge-contracts` alone defines change disposition. INV7 and INV8may supply the current outcome a change restores, but they do not authorize anotherobservable public delta. New APIs, exceptions, defaults, interaction models, icon or-control sizing, sticky behavior, and caller-owned layout remain with their direct-current owner unless evidence proves that exact mechanism is necessary to restore-the invariant and representative unaffected paths remain unchanged.+control sizing, sticky behavior, caller-owned layout, and new visual representations+remain with their direct current owner unless evidence proves that exact mechanism is+necessary to restore the invariant and representative unaffected paths remain+unchanged. A separable delta is removed or split before this interaction restoration+is asked to carry a new decision.## Change couplingdiff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex a6471bca6c..33131d6723 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -142,6 +142,17 @@ Every record is either:record requires a distinct fact boundary and an explicit explanation of why noexisting owner can contain it. Open pull requests coordinate overlapping work;they remain non-authoritative evidence.+- **INV14 — Current authority is claim-scoped.** `authority: current` approves the+ explicit claims inside a record's stated ownership boundary. It does not promise+ that every behavior of the named component, module, family, or code path has been+ specified. Review MUST NOT expand one narrow decision into adjacent uncontracted+ behavior unless the pull request's exact delta depends on that behavior.+- **INV15 — Review contracts toward one landing-ready intent.** Authors identify one+ primary intent and reviewers classify each observable delta separately. A+ separable delta that violates current authority or requires a new human decision+ is removed or split before review asks the primary change to carry new authority.+ A specification is the path for an intentional durable decision, not the default+ remedy for unrelated scope discovered during review.## Writing specifications and contracts@@ -162,6 +173,8 @@ Then write the contract:- Use familiar words and short, direct sentences.- State each rule once, beside the conditions and exceptions that control it.+- Contract only the semantic slice being decided. Name adjacent behavior as a+ non-goal or uncontracted gap; do not fill it merely to make the record `current`.- Use readable tables for branches or state matrices when they improve scanning.Never remove contract content merely to shorten a record.@@ -242,7 +255,8 @@ Before any component, module, family, design, theme, or architecture record beco1. The record names the code surface that can affect it and the checks thatverify it.2. A pull request touching that surface triggers a focused contract review.-3. The review records one of five results:+3. Review starts from the pull request's declared primary intent and classifies+ each public delta independently as one of five results:- `preserves`: the exact delta restores or retains current authority withoutadding public API or behavior beyond it;- `settled`: an existing current human decision covers the exact delta and is@@ -253,14 +267,25 @@ Before any component, module, family, design, theme, or architecture record beco- `out-of-scope`: another component, module, family, system, or product owns it.4. `preserves` and `settled` enter normal correctness review. They are eligiblefor approval only when the implementation and evidence also pass.-5. `violates` receives request-changes. The implementation conforms to current- authority, or an owner-approved current spec update lands before acceptance.-6. `novel-human` enters a private human hold. No contributor-facing verdict or- approval is published until the owning record contains the exact decision and- becomes current.+5. `violates` receives request-changes with the smallest conforming remedy:+ change or remove the violating delta. Review does not recommend a specification+ merely to rescue contradictory implementation; an owner may separately choose+ to propose a policy change.+6. A separable `novel-human` tagalong is removed or split from the primary intent.+ Review may request that contraction without deciding the tagalong's semantics,+ then continue reviewing the remaining change. A `novel-human` delta enters a+ private human hold only when it is the primary intent, is inseparable from it,+ or the author or owner explicitly chooses to pursue it.7. A bug fix is `preserves` only when it restores existing current authority- without changing public API or public behavior beyond that contract.-8. Audit freshness is computed from the same code and test relationship, so a+ without changing public API or public behavior beyond that contract. Any+ separable API, visual, layout, or interaction tagalong follows step 5 or 6+ rather than making the restoration wait for a broader specification.+8. A visual correction may be `preserves` or `settled` when current component,+ family, design, theme, or objective accessibility authority covers its exact+ outcome. Real rendered evidence must prove the affected state and representative+ unchanged states. A new visual representation remains `novel-human`; calling it+ an improvement does not settle it.+9. Audit freshness is computed from the same code and test relationship, so arelevant code change cannot leave an audit looking current.Audit-storage migration is a separate contract change. It requires a versioned@@ -269,12 +294,34 @@ named source of truth during transition, sandbox-reader cutover, and rollbackevidence. Repository-local per-component files are not a migration plan bythemselves.+### Contract before escalation++Review and build should converge on the smallest ideal change that can land:++1. State the pull request's primary intent and partition its observable deltas.+2. Apply current authority to each delta. Existing design and objective standards+ can settle a visual correction even when a component record does not enumerate+ its exact paint.+3. For a contradiction, conform or remove it. Do not propose changing the+ specification unless changing policy is itself an intentional, separately+ reviewable goal.+4. For an unsettled but separable delta, remove or split it. Continue the primary+ change without asking the contributor to solve adjacent system design.+5. Escalate only a surviving, intentional `novel-human` delta. Record only the+ exact decision needed for that delta; adjacent module behavior may stay+ uncontracted.++The actionable review result names the acceptance criteria for that landing-ready+contraction. It does not merely report that authority is missing.+### Recording a new human decision-1. A contributor explains the intended behavior in normal pull-request language- and responds to review. They do not need to know the repository's spec system.-2. A reviewer or agent identifies any `novel-human` question. The contributor- does not invent the answer.+1. A contributor explains the intended behavior and primary intent in normal+ pull-request language and responds to review. They do not need to know the+ repository's spec system.+2. A reviewer or agent applies the contraction path above. Only a surviving,+ intentional `novel-human` question proceeds; the contributor does not invent+ the answer or specify unrelated adjacent behavior.3. An authorized owner answers in the pull-request review.4. A maintainer or agent records that ruling in the canonical owning record.- Prefer a commit in the same pull request when maintainers can update the@@ -319,10 +366,15 @@ Examples:Result: `settled`; cite that `DEC` and continue to normal correctness review.- A package-exported context changes a required function parameter while itscurrent contract preserves the earlier operation shape. Result: `violates`;- request changes or land an owner-approved compatibility decision first.-- Selector removes empty indicator space, but no current decision says whether- option labels must stay aligned. Result: `novel-human`; hold privately while the- owner decides and records the alignment contract.+ request the smallest conforming change. A new compatibility policy is a separate+ proposal, not the default repair.+- A scroll-overflow fix also introduces a new hover disclosure. The overflow+ restoration proceeds under its current layout authority. If disclosure lacks+ authority, remove or split that separable visual tagalong; do not require the bug+ fix to specify the whole interaction module.+- Selector removes empty indicator space as its primary intent, but no current+ decision says whether option labels must stay aligned. Result: `novel-human`;+ hold privately while the owner decides the exact alignment contract.- A product requests a one-off width prop for a family-owned input layout rule.Result: `out-of-scope`; route the change to the family contract rather thancreating a component-specific API.@@ -409,6 +461,34 @@ different title, and open work may already be changing the same owner before itlands. Open pull requests coordinate work and provide evidence; they do not becomeauthority.+### DEC-4 — Contraction precedes new authority++**Reference:** `architecture:knowledge-contracts/DEC-4`+**Decider:** `cixzhang`, `2026-09-11`++When an otherwise reviewable change carries a separable contradiction or unsettled+decision, remove or split that delta and keep the primary intent moving. Recommend+a specification only when the surviving delta is intentionally pursued as durable+behavior, not because review discovered adjacent incompleteness.++Rejected: turning every uncontracted tagalong into a specification project, because+that makes a narrow repair absorb unrelated design work and leaves the contributor+without a landing-ready path.++### DEC-5 — Current approval is claim-scoped++**Reference:** `architecture:knowledge-contracts/DEC-5`+**Decider:** `cixzhang`, `2026-09-11`++A current record authorizes only its explicit claims within its stated ownership+boundary. It may deliberately leave adjacent behavior uncontracted. Reviewers do+not treat `current` as certification that a whole component or public module is+fully specified, and do not demand unrelated coverage before applying a narrow+approved decision.++Rejected: requiring a narrow visual or behavior decision to contract every API,+composition, accessibility, and implementation fact of the named module.+## Verification| Invariant | Evidence | Failure signal |@@ -419,6 +499,7 @@ authority.| INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves || INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority || INV13 | Blinded spec-authorship fixture plus overlap-search receipt | An author creates parallel authority, searches only landed records or filenames, misses open work on the canonical owner, or treats an open PR as authority |+| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |Current enforcement gap: no checked-in gate yet proves the open-pull-requestsearch. Until one exists, the pull-request summary records the search terms,diff --git a/docs/specs/AST-002/spec.md b/docs/specs/AST-002/spec.mdindex 0b84a6d12f..a668c2a51a 100644--- a/docs/specs/AST-002/spec.md+++ b/docs/specs/AST-002/spec.md@@ -151,10 +151,12 @@ A public API proposal is admitted only when it passes both gates:- **FR19 — Bug fixes do not smuggle API design.** A bug fix that can restore currentbehavior without changing public API or behavior beyond current authority MUST doso. Any additional public delta follows `architecture:knowledge-contracts`- independently: existing current authority may already settle it, and only absent- authority requires a new owner decision. Implementation convenience, removal of- an internal wrapper, or exposure of existing internal fields is not evidence that- an API should exist.+ independently. A separable contradictory or unsettled tagalong MUST be removed or+ split before review asks the repair to carry a new owner decision. Existing current+ authority may settle an intentional remaining delta; only a surviving, intentional+ gap requires owner judgment. Implementation convenience, removal of an internal+ wrapper, or exposure of existing internal fields is not evidence that an API should+ exist.### Platform support@@ -228,22 +230,22 @@ still determine whether the implementation satisfies it.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ---------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |-| FR1, FR5 | Blinded historical API review benchmark | recent utility, mid-range, and composition API additions | Reviewer accepts a prop without identifying caller-owned semantic variation |-| FR2, FR3 | Component tests and real-browser layout evidence | content, container, viewport, parent context, and platform variation | Public API exposes a value the component can derive reliably |-| FR4, FR6 | API surface review for utility, mid-range, and composition components | existing slot, theme, style, layout, and behavior seams | High-level component accumulates one-off tuning props instead of using its owning layer |-| FR7, FR8 | Consumer examples and behavior tests | default, each public value, composed use, and unsupported use | Meaning depends on implementation knowledge or tests assert only classes/data attributes |-| FR9, FR10 | Component ownership and accessibility review | owned content, external sibling content, missing or incorrect context | A state is correct only when the caller fulfills a promise the component cannot verify |-| FR11 | Public and package-internal operation inventory; PR #5373 | one component module and one semantic action | One semantic action gains parallel operation names distinguished only by implementation needs |-| FR12, FR13 | Public-delta/canonical-owner check and exact authority routing | missing delta/update; matching, contradictory, draft-only, or absent authority | Missing delta/owner update passes, contradiction is accepted, draft becomes policy, or automation decides semantics |-| FR14 | Focused regression tests against the current contract or standard | defect state, representative unchanged states, and any adjacent public delta | A restoration invents a new decision, lacks regression evidence, or hides an additional public change under a bug-fix label |-| FR15 | Type-level constraints plus runtime validation and behavior tests | invalid values, unsupported combinations, and legitimate composition | The API silently renders a broken state or prevents a valid composition |-| FR16 | Full value-domain, input-shape, and parallel-combination contract review | semantic variants, raw or palette values, explicit overrides, and defaults | One value or shape switches the controlled axis, or a parallel input silently changes precedence |-| FR17 | Public module/utility export inventory plus implementation, test, consumer, and release-history review | construction, inspection, lookup, conversion, registration, hooks, and released compatibility | A verb hides the returned value or side effect, two public roles are fused, a non-hook utility uses `use*`, or a released mismatch is silently renamed |-| FR18 | Multi-caller composition scenarios plus owning-contract review | shared semantic operation, internal-only mechanism, and two representative consumers | Product builders cannot compose stable behavior, or implementation fields are exposed without caller-owned semantics |-| FR19 | Bug-fix before/after authority diff plus public-surface and behavior inventory | pure restoration, restoration plus novel API, and internal-wrapper removal | A bug-fix label bypasses human hold, or internal mechanics become public because exposure is convenient |-| Burden | Benchmark classification: allow, correct pause, false block, not applicable | recent accepted and rejected API changes | Clearly justified APIs are repeatedly paused or blocked without surfacing a real decision |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ---------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |+| FR1, FR5 | Blinded historical API review benchmark | recent utility, mid-range, and composition API additions | Reviewer accepts a prop without identifying caller-owned semantic variation |+| FR2, FR3 | Component tests and real-browser layout evidence | content, container, viewport, parent context, and platform variation | Public API exposes a value the component can derive reliably |+| FR4, FR6 | API surface review for utility, mid-range, and composition components | existing slot, theme, style, layout, and behavior seams | High-level component accumulates one-off tuning props instead of using its owning layer |+| FR7, FR8 | Consumer examples and behavior tests | default, each public value, composed use, and unsupported use | Meaning depends on implementation knowledge or tests assert only classes/data attributes |+| FR9, FR10 | Component ownership and accessibility review | owned content, external sibling content, missing or incorrect context | A state is correct only when the caller fulfills a promise the component cannot verify |+| FR11 | Public and package-internal operation inventory; PR #5373 | one component module and one semantic action | One semantic action gains parallel operation names distinguished only by implementation needs |+| FR12, FR13 | Public-delta/canonical-owner check and exact authority routing | missing delta/update; matching, contradictory, draft-only, or absent authority | Missing delta/owner update passes, contradiction is accepted, draft becomes policy, or automation decides semantics |+| FR14 | Focused regression tests against the current contract or standard | defect state, representative unchanged states, and any adjacent public delta | A restoration invents a new decision, lacks regression evidence, or hides an additional public change under a bug-fix label |+| FR15 | Type-level constraints plus runtime validation and behavior tests | invalid values, unsupported combinations, and legitimate composition | The API silently renders a broken state or prevents a valid composition |+| FR16 | Full value-domain, input-shape, and parallel-combination contract review | semantic variants, raw or palette values, explicit overrides, and defaults | One value or shape switches the controlled axis, or a parallel input silently changes precedence |+| FR17 | Public module/utility export inventory plus implementation, test, consumer, and release-history review | construction, inspection, lookup, conversion, registration, hooks, and released compatibility | A verb hides the returned value or side effect, two public roles are fused, a non-hook utility uses `use*`, or a released mismatch is silently renamed |+| FR18 | Multi-caller composition scenarios plus owning-contract review | shared semantic operation, internal-only mechanism, and two representative consumers | Product builders cannot compose stable behavior, or implementation fields are exposed without caller-owned semantics |+| FR19 | Bug-fix before/after authority diff plus public-surface and behavior inventory | pure restoration, restoration plus separable novel API/visual change, and internal-wrapper removal | A bug-fix label bypasses authority, a removable tagalong forces a broader spec, or internal mechanics become public because exposure is convenient |+| Burden | Benchmark classification: allow, correct pause, false block, not applicable | recent accepted and rejected API changes | Clearly justified APIs are repeatedly paused or blocked without surfacing a real decision |## Decision log@@ -393,9 +395,10 @@ contract as current before accepting the public surface.A bug fix does not create an exception. When it restores current authority, keepits API and behavior within that contract. Any additional public primitive or-observable behavior follows `architecture:knowledge-contracts`: reuse an existing-current decision when one settles the delta, and ask the owner only when authority-is absent.+observable behavior follows `architecture:knowledge-contracts`: first conform,+remove, or split a separable contradiction or unsettled tagalong; then reuse an+existing current decision when one settles an intentional surviving delta. Ask the+owner only for a surviving decision the team actually wants to pursue.Rejected: promoting internal focus targets, gesture memory, DOM slots, timers, orother existing fields merely because removing an internal wrapper or fixing one