From b7e56d19d698f6d881b15500563f8bc3d96e9bea Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Wed, 4 Nov 2026 14:19:11 -0500 Subject: [PATCH 1/2] chore(repo): check verify-mosaic screenshots before attaching --- .changeset/verify-mosaic-screenshot-checks.md | 2 ++ packages/mosaic/.claude/skills/verify-mosaic/SKILL.md | 4 ++++ 2 files changed, 6 insertions(+) create mode 100644 .changeset/verify-mosaic-screenshot-checks.md diff --git a/.changeset/verify-mosaic-screenshot-checks.md b/.changeset/verify-mosaic-screenshot-checks.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/verify-mosaic-screenshot-checks.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/packages/mosaic/.claude/skills/verify-mosaic/SKILL.md b/packages/mosaic/.claude/skills/verify-mosaic/SKILL.md index 3a98db50407..ce739b06e3c 100644 --- a/packages/mosaic/.claude/skills/verify-mosaic/SKILL.md +++ b/packages/mosaic/.claude/skills/verify-mosaic/SKILL.md @@ -88,6 +88,10 @@ Proof standards: - Capture the action and the state it produced: before and after for a toggle, open and closed for an overlay, the knob value and the preview attribute for a prop. - Prove the check can fail. Save your diff to a file, undo the change, confirm the undo took effect, run the same commands into a `CS evidence -control` folder, and show the result differs. Then apply the diff again and run the check once more. A check that passes with and without the change proves nothing. - A screenshot alone proves nothing about state. Pair it with the ARIA snapshot or the attribute dump that shows the claimed value. +- Open every screenshot with the Read tool before you attach it, the control too. Name the part the change touches, such as the footer divider, and confirm it is in frame, uncropped and uncovered. A screenshot that misses that part is not evidence. Retake it. +- Before each screenshot, hide the Next.js dev badge, which floats over the preview: `CS ab eval '(() => { const s = document.createElement("style"); s.textContent = "nextjs-portal{display:none!important}"; document.head.append(s); })()'`. +- Set the viewport taller than the element, and scroll the element into view before `screenshot `. An element screenshot can still come out shifted, with part of the page above it and its bottom cut off. If it does, screenshot the enclosing story preview box instead: the `not-prose` wrapper in `packages/swingset/src/components/StoryPreview.tsx`. Give it an id from `eval` and pass `#`. +- For the control, check that the undo took effect before you capture anything: run `git status`, and read back the value the change moves. In zsh, `$FILES` does not split on spaces, so keep the file list in an array (`F=(a b); git checkout HEAD~1 -- "${F[@]}"`). - For a styling change, check both themes (`Dark mode` switch) and RTL when the change touches layout. - Name the feature file and entry point you used. Report every entry point you could not reach, and why, instead of claiming it through another one. - Evidence lives in `packages/mosaic/.verify/evidence/`, which git ignores. `CS down` keeps it. Each folder's `source.env` records the commit it was made at, whether the tree had uncommitted changes, and whether swingset had an env file loaded. From e6bbd8c5319aca03d4864c2ad85675cb07a597c9 Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Wed, 4 Nov 2026 14:31:17 -0500 Subject: [PATCH 2/2] docs(mosaic): allow screenshot setup in eval and undo controls with a patch --- packages/mosaic/.claude/skills/verify-mosaic/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/mosaic/.claude/skills/verify-mosaic/SKILL.md b/packages/mosaic/.claude/skills/verify-mosaic/SKILL.md index ce739b06e3c..4c3972ca719 100644 --- a/packages/mosaic/.claude/skills/verify-mosaic/SKILL.md +++ b/packages/mosaic/.claude/skills/verify-mosaic/SKILL.md @@ -84,14 +84,14 @@ $ CS ab eval '(() => Object.fromEntries([...document.querySelector("[role=dialog Proof standards: -- Drive the user path: click, type, and press keys on the page. Do not set React state or call story functions from `eval`. Use `eval` only to read. +- Drive the user path: click, type, and press keys on the page. Do not set React state or call story functions from `eval`. Use `eval` to read, and for the screenshot setup below: injecting a style and adding an id. - Capture the action and the state it produced: before and after for a toggle, open and closed for an overlay, the knob value and the preview attribute for a prop. - Prove the check can fail. Save your diff to a file, undo the change, confirm the undo took effect, run the same commands into a `CS evidence -control` folder, and show the result differs. Then apply the diff again and run the check once more. A check that passes with and without the change proves nothing. - A screenshot alone proves nothing about state. Pair it with the ARIA snapshot or the attribute dump that shows the claimed value. - Open every screenshot with the Read tool before you attach it, the control too. Name the part the change touches, such as the footer divider, and confirm it is in frame, uncropped and uncovered. A screenshot that misses that part is not evidence. Retake it. - Before each screenshot, hide the Next.js dev badge, which floats over the preview: `CS ab eval '(() => { const s = document.createElement("style"); s.textContent = "nextjs-portal{display:none!important}"; document.head.append(s); })()'`. - Set the viewport taller than the element, and scroll the element into view before `screenshot `. An element screenshot can still come out shifted, with part of the page above it and its bottom cut off. If it does, screenshot the enclosing story preview box instead: the `not-prose` wrapper in `packages/swingset/src/components/StoryPreview.tsx`. Give it an id from `eval` and pass `#`. -- For the control, check that the undo took effect before you capture anything: run `git status`, and read back the value the change moves. In zsh, `$FILES` does not split on spaces, so keep the file list in an array (`F=(a b); git checkout HEAD~1 -- "${F[@]}"`). +- For the control, undo with `git diff > change.patch && git apply -R change.patch`, and restore with `git apply change.patch`. Use `git checkout HEAD~1 -- ` only when the change is one commit and the tree is otherwise clean. In zsh, `$FILES` does not split on spaces, so keep a file list in an array (`F=(a b); git checkout HEAD~1 -- "${F[@]}"`). Check that the undo took effect before you capture anything: run `git status`, and read back the value the change moves. - For a styling change, check both themes (`Dark mode` switch) and RTL when the change touches layout. - Name the feature file and entry point you used. Report every entry point you could not reach, and why, instead of claiming it through another one. - Evidence lives in `packages/mosaic/.verify/evidence/`, which git ignores. `CS down` keeps it. Each folder's `source.env` records the commit it was made at, whether the tree had uncommitted changes, and whether swingset had an env file loaded.