An open source design system that's fully customizable and agent ready
TypeScript
docs: keep one-off PR evidence outside the source tree (#7651)
Xinzi Zhoub5841076df01
diff --git a/.gitignore b/.gitignoreindex 018869fd43..7a200d4462 100644--- a/.gitignore+++ b/.gitignore@@ -8,6 +8,9 @@ dist/# Storybookstorybook-static/+# One-off PR evidence is attached or linked from the PR, not source assets.+/docs/pr-assets/+# Test coveragecoverage/diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex 9d76379778..cd9916d477 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -250,6 +250,39 @@ Every record is either:authority. A human request supplies intent but becomes committed currentauthority only through exact-head owner approval.+### Review evidence placement++- **INV22 — One-off evidence stays with the change.** Ad-hoc screenshots,+ recordings, measurements, sensor receipts, and run logs are attached or linked+ from the pull request that uses them, not committed to `main` as disposable+ assets under `docs/pr-assets/` or another source directory. Public GitHub+ attachments are the preferred home for manually published one-off evidence.+ Standing records keep durable conclusions and verification relationships, not+ individual run inventories. Accepted visual baselines, reusable stories and+ test fixtures, shipped documentation media, and repository-owned receipts+ explicitly permitted by their current owner remain versioned with the code.+- **INV23 — Cleanup preserves historical evidence.** Removing disposable assets+ from the current tree MUST NOT rewrite history or break existing commit-pinned+ evidence links. Before deletion, every removed file has a verified public+ retained copy. A linked commit outside retained `main` history needs a durable+ retention anchor at that exact commit; a commit hash or a temporary branch+ alone is insufficient. An immutable non-release `evidence/` tag may retain+ historical Git-hosted evidence when attachment publication is unavailable.+ Its name stays outside release-tag conventions and automated pruning, and it+ MUST NOT be moved or removed while the evidence is referenced. Cleanup verifies+ the remote anchor, exact bytes, and existing links before removing source files.+- **INV24 — Storage does not change proof or authority.** The pull request's text+ states the claim, tested build, relevant state, observed result, and evidence+ links; an image or expiring artifact is not the only record of the conclusion.+ Attachments remain evidence under INV16, not authority. Owner-specific receipt+ requirements, operational audit stores, and CI artifact lifetimes remain with+ their current owners. [AST-009](../specs/AST-009/spec.md) owns real-AT receipts;+ INV12 owns the operational audit datastore. [AST-029](../specs/AST-029/spec.md)+ FR5 and FR10 own the audit pull request's evidence receipt and exact-head+ eligibility report. [AST-030](../specs/AST-030/spec.md) FR12 owns shared+ visual-regression execution and baseline adoption. This placement rule does+ not add a capture owner or require permanent archiving of every CI run.+## Global review applicabilityUse this optional block only when named claims apply across otherwise unrelated@@ -848,6 +881,14 @@ clear.| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only || DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate |+| Invariant | Evidence | Failure signal |+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV22–INV24 | Contributor/reviewer evidence inventory; public-link and byte verification; retained remote refs; unchanged fixture/baseline/media paths | Disposable captures enter the source tree, cleanup loses a referenced image, a temporary branch is called durable, or storage changes overwrite an owner's proof or retention contract |++Evidence placement is enforced by contributors and reviewers. The local+`docs/pr-assets/` ignore prevents accidental staging; it is not a blocking CI+check and does not prevent force-added evidence elsewhere.+Current enforcement gap: no checked-in gate yet proves the open-pull-requestsearch. Until one exists, the pull-request summary records the search terms,canonical owner/path, and overlapping open work inspected.diff --git a/docs/contributing/pull-requests.md b/docs/contributing/pull-requests.mdindex e045c8718d..0dcd66617c 100644--- a/docs/contributing/pull-requests.md+++ b/docs/contributing/pull-requests.md@@ -94,6 +94,15 @@ authority only after exact-head owner approval.A new visual representation, subjective direction, or interaction model remains a design decision. Put a shared decision in its own design specification; keep a durable component-local decision in the owning component/module table.+## Review evidence++[Knowledge contracts: review evidence placement](../architecture/knowledge-contracts.md#review-evidence-placement)+owns where one-off evidence lives and how cleanup preserves historical links.+Attach manual screenshots and their receipts to the pull request, or link a+public retained copy outside the implementation branch. Keep reusable fixtures,+accepted baselines, and media used by public documentation in their owning source+paths. Evidence storage does not relax the matching template's evidence bar.+## Public repository boundaryDescriptions, screenshots, commits, tests, and specification records are public. Do not include internal links, identifiers, hostnames, tools, or operational context.diff --git a/docs/pr-assets/4808/community-design-section.png b/docs/pr-assets/4808/community-design-section.pngdeleted file mode 100644index 1f8ffc5acf..0000000000Binary files a/docs/pr-assets/4808/community-design-section.png and /dev/null differdiff --git a/docs/pr-assets/6652/item-document-tabs-dark.png b/docs/pr-assets/6652/item-document-tabs-dark.pngdeleted file mode 100644index 9e24b3225b..0000000000Binary files a/docs/pr-assets/6652/item-document-tabs-dark.png and /dev/null differdiff --git a/docs/pr-assets/6652/item-document-tabs-light.png b/docs/pr-assets/6652/item-document-tabs-light.pngdeleted file mode 100644index 83673bc802..0000000000Binary files a/docs/pr-assets/6652/item-document-tabs-light.png and /dev/null differdiff --git a/docs/pr-assets/6708/chat-message-320.png b/docs/pr-assets/6708/chat-message-320.pngdeleted file mode 100644index 251936de99..0000000000Binary files a/docs/pr-assets/6708/chat-message-320.png and /dev/null differdiff --git a/docs/pr-assets/6708/chat-message-390.png b/docs/pr-assets/6708/chat-message-390.pngdeleted file mode 100644index 60ff4e88e6..0000000000Binary files a/docs/pr-assets/6708/chat-message-390.png and /dev/null differdiff --git a/docs/pr-assets/6708/realistic-tables-390.png b/docs/pr-assets/6708/realistic-tables-390.pngdeleted file mode 100644index a410267ea6..0000000000Binary files a/docs/pr-assets/6708/realistic-tables-390.png and /dev/null differdiff --git a/docs/pr-assets/6708/short-columns-320-after.png b/docs/pr-assets/6708/short-columns-320-after.pngdeleted file mode 100644index a540583f55..0000000000Binary files a/docs/pr-assets/6708/short-columns-320-after.png and /dev/null differdiff --git a/docs/pr-assets/6708/short-columns-320-before.png b/docs/pr-assets/6708/short-columns-320-before.pngdeleted file mode 100644index 1104730180..0000000000Binary files a/docs/pr-assets/6708/short-columns-320-before.png and /dev/null differdiff --git a/docs/pr-assets/6708/short-columns-390-after.png b/docs/pr-assets/6708/short-columns-390-after.pngdeleted file mode 100644index e47a6a3acf..0000000000Binary files a/docs/pr-assets/6708/short-columns-390-after.png and /dev/null differdiff --git a/docs/pr-assets/6708/short-columns-390-before.png b/docs/pr-assets/6708/short-columns-390-before.pngdeleted file mode 100644index ecae17af47..0000000000Binary files a/docs/pr-assets/6708/short-columns-390-before.png and /dev/null differdiff --git a/docs/pr-assets/6708/table-scroll-390-filmstrip.png b/docs/pr-assets/6708/table-scroll-390-filmstrip.pngdeleted file mode 100644index df99e149b5..0000000000Binary files a/docs/pr-assets/6708/table-scroll-390-filmstrip.png and /dev/null differdiff --git a/docs/pr-assets/6708/wide-content-320-after.png b/docs/pr-assets/6708/wide-content-320-after.pngdeleted file mode 100644index bd6ad0d3d5..0000000000Binary files a/docs/pr-assets/6708/wide-content-320-after.png and /dev/null differdiff --git a/docs/pr-assets/6708/wide-content-320-before.png b/docs/pr-assets/6708/wide-content-320-before.pngdeleted file mode 100644index 79b2449ebd..0000000000Binary files a/docs/pr-assets/6708/wide-content-320-before.png and /dev/null differdiff --git a/docs/pr-assets/6708/wide-content-390-after.png b/docs/pr-assets/6708/wide-content-390-after.pngdeleted file mode 100644index b314bc7540..0000000000Binary files a/docs/pr-assets/6708/wide-content-390-after.png and /dev/null differdiff --git a/docs/pr-assets/6708/wide-content-390-before.png b/docs/pr-assets/6708/wide-content-390-before.pngdeleted file mode 100644index c7452f2b3d..0000000000Binary files a/docs/pr-assets/6708/wide-content-390-before.png and /dev/null differdiff --git a/docs/pr-assets/6856/docs-1440-scrolled-after.png b/docs/pr-assets/6856/docs-1440-scrolled-after.pngdeleted file mode 100644index 64be88b04d..0000000000Binary files a/docs/pr-assets/6856/docs-1440-scrolled-after.png and /dev/null differdiff --git a/docs/pr-assets/6856/docs-1440-scrolled-before.png b/docs/pr-assets/6856/docs-1440-scrolled-before.pngdeleted file mode 100644index 6c5ecf50ca..0000000000Binary files a/docs/pr-assets/6856/docs-1440-scrolled-before.png and /dev/null differdiff --git a/docs/pr-assets/6856/home-1440-banner-after.png b/docs/pr-assets/6856/home-1440-banner-after.pngdeleted file mode 100644index 8245685361..0000000000Binary files a/docs/pr-assets/6856/home-1440-banner-after.png and /dev/null differdiff --git a/docs/pr-assets/6856/home-1440-banner-before.png b/docs/pr-assets/6856/home-1440-banner-before.pngdeleted file mode 100644index b295ad2d84..0000000000Binary files a/docs/pr-assets/6856/home-1440-banner-before.png and /dev/null differdiff --git a/docs/pr-assets/6856/home-390-banner-after.png b/docs/pr-assets/6856/home-390-banner-after.pngdeleted file mode 100644index 7ab44bf1e1..0000000000Binary files a/docs/pr-assets/6856/home-390-banner-after.png and /dev/null differdiff --git a/docs/pr-assets/6856/home-390-banner-before.png b/docs/pr-assets/6856/home-390-banner-before.pngdeleted file mode 100644index f48c79f7eb..0000000000Binary files a/docs/pr-assets/6856/home-390-banner-before.png and /dev/null differdiff --git a/docs/pr-assets/6883/container-padding-390.png b/docs/pr-assets/6883/container-padding-390.pngdeleted file mode 100644index dec81ec395..0000000000Binary files a/docs/pr-assets/6883/container-padding-390.png and /dev/null differdiff --git a/docs/pr-assets/6898/center-tabs-after.png b/docs/pr-assets/6898/center-tabs-after.pngdeleted file mode 100644index 52715a41a7..0000000000Binary files a/docs/pr-assets/6898/center-tabs-after.png and /dev/null differdiff --git a/docs/pr-assets/6898/center-tabs-before.png b/docs/pr-assets/6898/center-tabs-before.pngdeleted file mode 100644index 2869d5c335..0000000000Binary files a/docs/pr-assets/6898/center-tabs-before.png and /dev/null differdiff --git a/docs/pr-assets/6898/focus-ring-after.png b/docs/pr-assets/6898/focus-ring-after.pngdeleted file mode 100644index ef65d859fe..0000000000Binary files a/docs/pr-assets/6898/focus-ring-after.png and /dev/null differdiff --git a/docs/pr-assets/6898/focus-ring-before.png b/docs/pr-assets/6898/focus-ring-before.pngdeleted file mode 100644index 5b056a4e02..0000000000Binary files a/docs/pr-assets/6898/focus-ring-before.png and /dev/null differdiff --git a/docs/pr-assets/6898/shadow-after.png b/docs/pr-assets/6898/shadow-after.pngdeleted file mode 100644index f46dd5e6db..0000000000Binary files a/docs/pr-assets/6898/shadow-after.png and /dev/null differdiff --git a/docs/pr-assets/6898/shadow-before.png b/docs/pr-assets/6898/shadow-before.pngdeleted file mode 100644index bbdcfae1a9..0000000000Binary files a/docs/pr-assets/6898/shadow-before.png and /dev/null differdiff --git a/docs/pr-assets/6898/squeezed-after.png b/docs/pr-assets/6898/squeezed-after.pngdeleted file mode 100644index eacecc36fc..0000000000Binary files a/docs/pr-assets/6898/squeezed-after.png and /dev/null differdiff --git a/docs/pr-assets/6898/squeezed-before.png b/docs/pr-assets/6898/squeezed-before.pngdeleted file mode 100644index 6197ea4043..0000000000Binary files a/docs/pr-assets/6898/squeezed-before.png and /dev/null differdiff --git a/docs/pr-assets/7192/pinch-before-after.png b/docs/pr-assets/7192/pinch-before-after.pngdeleted file mode 100644index 77aff942e0..0000000000Binary files a/docs/pr-assets/7192/pinch-before-after.png and /dev/null differdiff --git a/docs/pr-assets/7193/pinch-before-after.png b/docs/pr-assets/7193/pinch-before-after.pngdeleted file mode 100644index 87653ca1d2..0000000000Binary files a/docs/pr-assets/7193/pinch-before-after.png and /dev/null differ