Skip to content

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/.gitignore
index 018869fd43..7a200d4462 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,9 @@ dist/
# Storybook
storybook-static/
+# One-off PR evidence is attached or linked from the PR, not source assets.
+/docs/pr-assets/
+
# Test coverage
coverage/
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index 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 current
authority 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 applicability
Use 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-request
search. 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.md
index 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 boundary
Descriptions, 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.png
deleted file mode 100644
index 1f8ffc5acf..0000000000
Binary files a/docs/pr-assets/4808/community-design-section.png and /dev/null differ
diff --git a/docs/pr-assets/6652/item-document-tabs-dark.png b/docs/pr-assets/6652/item-document-tabs-dark.png
deleted file mode 100644
index 9e24b3225b..0000000000
Binary files a/docs/pr-assets/6652/item-document-tabs-dark.png and /dev/null differ
diff --git a/docs/pr-assets/6652/item-document-tabs-light.png b/docs/pr-assets/6652/item-document-tabs-light.png
deleted file mode 100644
index 83673bc802..0000000000
Binary files a/docs/pr-assets/6652/item-document-tabs-light.png and /dev/null differ
diff --git a/docs/pr-assets/6708/chat-message-320.png b/docs/pr-assets/6708/chat-message-320.png
deleted file mode 100644
index 251936de99..0000000000
Binary files a/docs/pr-assets/6708/chat-message-320.png and /dev/null differ
diff --git a/docs/pr-assets/6708/chat-message-390.png b/docs/pr-assets/6708/chat-message-390.png
deleted file mode 100644
index 60ff4e88e6..0000000000
Binary files a/docs/pr-assets/6708/chat-message-390.png and /dev/null differ
diff --git a/docs/pr-assets/6708/realistic-tables-390.png b/docs/pr-assets/6708/realistic-tables-390.png
deleted file mode 100644
index a410267ea6..0000000000
Binary files a/docs/pr-assets/6708/realistic-tables-390.png and /dev/null differ
diff --git a/docs/pr-assets/6708/short-columns-320-after.png b/docs/pr-assets/6708/short-columns-320-after.png
deleted file mode 100644
index a540583f55..0000000000
Binary files a/docs/pr-assets/6708/short-columns-320-after.png and /dev/null differ
diff --git a/docs/pr-assets/6708/short-columns-320-before.png b/docs/pr-assets/6708/short-columns-320-before.png
deleted file mode 100644
index 1104730180..0000000000
Binary files a/docs/pr-assets/6708/short-columns-320-before.png and /dev/null differ
diff --git a/docs/pr-assets/6708/short-columns-390-after.png b/docs/pr-assets/6708/short-columns-390-after.png
deleted file mode 100644
index e47a6a3acf..0000000000
Binary files a/docs/pr-assets/6708/short-columns-390-after.png and /dev/null differ
diff --git a/docs/pr-assets/6708/short-columns-390-before.png b/docs/pr-assets/6708/short-columns-390-before.png
deleted file mode 100644
index ecae17af47..0000000000
Binary files a/docs/pr-assets/6708/short-columns-390-before.png and /dev/null differ
diff --git a/docs/pr-assets/6708/table-scroll-390-filmstrip.png b/docs/pr-assets/6708/table-scroll-390-filmstrip.png
deleted file mode 100644
index df99e149b5..0000000000
Binary files a/docs/pr-assets/6708/table-scroll-390-filmstrip.png and /dev/null differ
diff --git a/docs/pr-assets/6708/wide-content-320-after.png b/docs/pr-assets/6708/wide-content-320-after.png
deleted file mode 100644
index bd6ad0d3d5..0000000000
Binary files a/docs/pr-assets/6708/wide-content-320-after.png and /dev/null differ
diff --git a/docs/pr-assets/6708/wide-content-320-before.png b/docs/pr-assets/6708/wide-content-320-before.png
deleted file mode 100644
index 79b2449ebd..0000000000
Binary files a/docs/pr-assets/6708/wide-content-320-before.png and /dev/null differ
diff --git a/docs/pr-assets/6708/wide-content-390-after.png b/docs/pr-assets/6708/wide-content-390-after.png
deleted file mode 100644
index b314bc7540..0000000000
Binary files a/docs/pr-assets/6708/wide-content-390-after.png and /dev/null differ
diff --git a/docs/pr-assets/6708/wide-content-390-before.png b/docs/pr-assets/6708/wide-content-390-before.png
deleted file mode 100644
index c7452f2b3d..0000000000
Binary files a/docs/pr-assets/6708/wide-content-390-before.png and /dev/null differ
diff --git a/docs/pr-assets/6856/docs-1440-scrolled-after.png b/docs/pr-assets/6856/docs-1440-scrolled-after.png
deleted file mode 100644
index 64be88b04d..0000000000
Binary files a/docs/pr-assets/6856/docs-1440-scrolled-after.png and /dev/null differ
diff --git a/docs/pr-assets/6856/docs-1440-scrolled-before.png b/docs/pr-assets/6856/docs-1440-scrolled-before.png
deleted file mode 100644
index 6c5ecf50ca..0000000000
Binary files a/docs/pr-assets/6856/docs-1440-scrolled-before.png and /dev/null differ
diff --git a/docs/pr-assets/6856/home-1440-banner-after.png b/docs/pr-assets/6856/home-1440-banner-after.png
deleted file mode 100644
index 8245685361..0000000000
Binary files a/docs/pr-assets/6856/home-1440-banner-after.png and /dev/null differ
diff --git a/docs/pr-assets/6856/home-1440-banner-before.png b/docs/pr-assets/6856/home-1440-banner-before.png
deleted file mode 100644
index b295ad2d84..0000000000
Binary files a/docs/pr-assets/6856/home-1440-banner-before.png and /dev/null differ
diff --git a/docs/pr-assets/6856/home-390-banner-after.png b/docs/pr-assets/6856/home-390-banner-after.png
deleted file mode 100644
index 7ab44bf1e1..0000000000
Binary files a/docs/pr-assets/6856/home-390-banner-after.png and /dev/null differ
diff --git a/docs/pr-assets/6856/home-390-banner-before.png b/docs/pr-assets/6856/home-390-banner-before.png
deleted file mode 100644
index f48c79f7eb..0000000000
Binary files a/docs/pr-assets/6856/home-390-banner-before.png and /dev/null differ
diff --git a/docs/pr-assets/6883/container-padding-390.png b/docs/pr-assets/6883/container-padding-390.png
deleted file mode 100644
index dec81ec395..0000000000
Binary files a/docs/pr-assets/6883/container-padding-390.png and /dev/null differ
diff --git a/docs/pr-assets/6898/center-tabs-after.png b/docs/pr-assets/6898/center-tabs-after.png
deleted file mode 100644
index 52715a41a7..0000000000
Binary files a/docs/pr-assets/6898/center-tabs-after.png and /dev/null differ
diff --git a/docs/pr-assets/6898/center-tabs-before.png b/docs/pr-assets/6898/center-tabs-before.png
deleted file mode 100644
index 2869d5c335..0000000000
Binary files a/docs/pr-assets/6898/center-tabs-before.png and /dev/null differ
diff --git a/docs/pr-assets/6898/focus-ring-after.png b/docs/pr-assets/6898/focus-ring-after.png
deleted file mode 100644
index ef65d859fe..0000000000
Binary files a/docs/pr-assets/6898/focus-ring-after.png and /dev/null differ
diff --git a/docs/pr-assets/6898/focus-ring-before.png b/docs/pr-assets/6898/focus-ring-before.png
deleted file mode 100644
index 5b056a4e02..0000000000
Binary files a/docs/pr-assets/6898/focus-ring-before.png and /dev/null differ
diff --git a/docs/pr-assets/6898/shadow-after.png b/docs/pr-assets/6898/shadow-after.png
deleted file mode 100644
index f46dd5e6db..0000000000
Binary files a/docs/pr-assets/6898/shadow-after.png and /dev/null differ
diff --git a/docs/pr-assets/6898/shadow-before.png b/docs/pr-assets/6898/shadow-before.png
deleted file mode 100644
index bbdcfae1a9..0000000000
Binary files a/docs/pr-assets/6898/shadow-before.png and /dev/null differ
diff --git a/docs/pr-assets/6898/squeezed-after.png b/docs/pr-assets/6898/squeezed-after.png
deleted file mode 100644
index eacecc36fc..0000000000
Binary files a/docs/pr-assets/6898/squeezed-after.png and /dev/null differ
diff --git a/docs/pr-assets/6898/squeezed-before.png b/docs/pr-assets/6898/squeezed-before.png
deleted file mode 100644
index 6197ea4043..0000000000
Binary files a/docs/pr-assets/6898/squeezed-before.png and /dev/null differ
diff --git a/docs/pr-assets/7192/pinch-before-after.png b/docs/pr-assets/7192/pinch-before-after.png
deleted file mode 100644
index 77aff942e0..0000000000
Binary files a/docs/pr-assets/7192/pinch-before-after.png and /dev/null differ
diff --git a/docs/pr-assets/7193/pinch-before-after.png b/docs/pr-assets/7193/pinch-before-after.png
deleted file mode 100644
index 87653ca1d2..0000000000
Binary files a/docs/pr-assets/7193/pinch-before-after.png and /dev/null differ