docs: recommend before and after screenshots for UI pull requests

.agents/docs/visual-explanations.md

@@ -130,6 +130,34 @@ function expandSkill(command: string): string {
 Bash(open path/to/show-me-{description}.html)
 ```
 
+## UI screenshots
+
+For a PR that changes visible UI, we recommend a labeled **Before / After**
+screenshot pair in the template's matching section, with a short caption explaining
+the change. Agent authors should try to capture the baseline before editing and the
+final result after verification as part of their implementation loop. Use the
+actual running UI or its owning Storybook fixture, with synthetic data and
+comparable viewport, theme, and interaction state so the difference is clear.
+
+Prepare a safe scene before capture: prefer demo or synthetic fixtures and an
+isolated development data directory over a personal workspace. Crop to the
+relevant UI while retaining enough context to judge the change. Inspect both
+images before uploading or committing for conversation text, source contents,
+names, avatars, local paths, repository details, notifications, credentials, and
+other private content. If cropping or redaction is needed, inspect the final
+export and share only that sanitized file; do not upload or commit the private
+original alongside it. Follow the repository's prohibition on captured user or
+agent transcripts.
+
+Attach safe images inline or link to an artifact reviewers can access; a local
+filesystem path alone is not reviewable in a PR. A small side-by-side table works
+well for a pair. Captions should identify the relevant state and any deliberate
+comparison differences.
+
+Screenshots are recommended, not mandatory, and add no submission requirement or
+automated gate. Authors may omit screenshots without explanation. The existing
+structural-view rules still apply independently.
+
 ## Choosing and placing a view
 
 Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.

.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.md

@@ -0,0 +1,46 @@
+# Recommend before and after screenshots for UI pull requests
+
+Status: implemented
+Translation: current
+PR: [#1744](https://github.com/LodyAI/Lody/pull/1744)
+
+[中文](2026-10-20-ui-pr-comparison-screenshots.zh.md)
+
+## Abstract
+
+UI pull requests can describe a visible change without showing the result,
+leaving reviewers to reproduce both versions. The PR template now recommends
+labeled before/after screenshots, and the visual guide explains how Agents can
+capture them during implementation using synthetic data. Privacy takes priority:
+authors inspect the exported images before sharing. Screenshots are optional
+and may be omitted without explanation; this guidance adds no automated gate.
+
+## Decision
+
+The existing [visual explanation decision](2026-09-08-required-pr-visual-explanations.md)
+requires a structural view for complex changes. Screenshot comparison answers a
+different question: what a reviewer will see before and after a UI change. The
+recommendation lives in the PR template's existing Before / after section, which
+Agents already read through the GitHub contribution instructions. The
+[visual guide](../../../docs/visual-explanations.md#ui-screenshots) owns practical
+capture, privacy, and presentation advice. No new instruction is added to the
+nearly full root or GitHub `AGENTS.md` files.
+
+The comparison uses real UI or owning Storybook fixtures with comparable state,
+viewport, and theme. Synthetic data and an isolated development scene reduce
+exposure before capture; inspection of the final crop or redacted export catches
+private content before either a public upload or a commit. Captured user/agent
+transcripts remain prohibited. Reviewers receive accessible safe artifacts, not
+local-only paths.
+
+Authors decide whether to include screenshots and may omit them without
+explanation. Existing required template headings and the structural-view
+validator remain unchanged.
+
+## Verification
+
+The change is documentation only. All 23 existing PR-template and policy tests
+passed, including complete and rejected bodies. `pnpm format` and the full
+`pnpm check` passed. Documentation checking retains only the six existing missing
+Kimi/Pi submodule links in the bilingual subagent-events note, with no new errors
+or SHA-protected topic changes. No UI rendering change is claimed.

.agents/notes/implemented/process/2026-10-20-ui-pr-comparison-screenshots.zh.md

@@ -0,0 +1,37 @@
+# 推荐不含私人数据的 UI 前后对比截图
+
+Status: implemented
+Translation: current
+PR: [#1744](https://github.com/LodyAI/Lody/pull/1744)
+
+[English](2026-10-20-ui-pr-comparison-screenshots.md)
+
+## 摘要
+
+UI PR 有时只描述可见变化而不展示结果，评审者需要自行复现前后两个版本。
+现在 PR 模板推荐附上标注清楚的修改前后截图，可视化指南说明 Agent 如何在实现过程中
+使用合成数据采集对比。隐私优先：作者在分享前检查导出图片。截图并非强制要求，
+不提供也无需解释；这条建议没有增加自动检查门槛。
+
+## 决定
+
+现有的[可视化说明决定](2026-09-08-required-pr-visual-explanations.zh.md)要求复杂改动
+提供结构图。截图对比回答的是另一个问题：评审者在 UI 修改前后会看到什么。
+建议放在 PR 模板已有的 Before / after 部分，GitHub 贡献规范已经要求 Agent 阅读模板。
+[可视化指南](../../../docs/visual-explanations.md#ui-screenshots)负责说明采集、隐私和展示方式。
+没有向接近大小上限的根目录或 GitHub `AGENTS.md` 增加新的指令。
+
+截图使用真实 UI 或所属的 Storybook 示例，并保持可比较的界面状态、视口和主题。
+使用合成数据和隔离的开发场景，可以在截图前减少隐私暴露；提交或公开上传前，
+检查最终裁剪或遮盖后的导出图片，确认其中没有私人内容。禁止提交捕获的用户或 Agent
+对话记录的规则继续有效。评审者应能访问安全的图片，不能只有本地路径。
+
+作者自行决定是否附上截图，不提供也无需解释。现有必填模板标题和结构图校验器
+均保持不变。
+
+## 验证
+
+本次仅修改文档。已有 PR 模板与策略测试共 23 项全部通过，包含完整正文和拒绝案例。
+`pnpm format` 和完整 `pnpm check` 均已通过。文档检查仅保留 subagent-events 双语笔记中
+原有的六个 Kimi/Pi 子模块缺失链接，没有新增错误或需要审阅的 SHA 保护主题变化。
+本次没有改变 UI 渲染行为。

.github/PULL_REQUEST_TEMPLATE.md

@@ -47,6 +47,16 @@ Any supporting artifact must be reachable by reviewers; a local HTML file is not
 
 ## Before / after
 
+<!--
+For UI changes, consider adding labeled Before/After screenshots of the actual UI.
+Agents: capture the baseline and final result during the implementation loop when
+practical, using synthetic data and comparable viewport, theme, and UI state.
+Inspect both images for private content before uploading or committing.
+Screenshots are encouraged, not mandatory; authors may omit them without explanation.
+This recommendation adds no automated check.
+Capture and privacy guidance: .agents/docs/visual-explanations.md#ui-screenshots
+-->
+
 | Before | After |
 | ------ | ----- |
 | ...    | ...   |