review-frontend-variants

Review Frontend Variants

Optimize for one outcome: let the user quickly see the real original UI and the real changed UI under the same screen, state, data, theme, and viewport.

Create a local review surface that shows only what the user asked to review:

• For a current-component catalog, show the live current product components.
• Add external product references only when the user explicitly asks for them.
• Add Before and Candidate only after a real candidate implementation exists.
• Make switching screens and states cheap; do not make each new screen require reverse-engineering product persistence.

Treat “list the components” as “show rendered visual specimens for each relevant component or state,” not “list component names, architecture, responsibilities, or source paths.”

Core rules

• Use scripts/ui_review.mjs for the review page. Do not hand-write a custom showcase HTML unless the user explicitly asks for a custom page.
• When the packaged MCP server is available, use its single visual_review_workbench tool for opening, refreshing, verifying, capturing, and closing the workbench. Keep route scaffolding, fixture handling, measurement, and recording as private script operations rather than separate public tools.
• Keep the page visually neutral and compact. Do not add a hero, marketing copy, statistics, architecture diagrams, inventories, explanatory cards, or decorative sections.
• Import product components into a development-only app review route and render them live with their real providers and styles.
• Drive the review scenario, variant, theme, locale, and other panel-specific state from the URL. Never select a panel's screen by mutating user localStorage, a persisted Zustand/Redux snapshot, or another iframe-shared store.
• When scenario tabs represent interchangeable versions of the same product, preserve the active inner screen across version switches. Configure preserveQueryParams in the review shell and have the app-owned route post ui-review:set-query-param before navigating that screen.
• Do not label anything Candidate unless its implementation actually differs from the current or baseline code. A query parameter by itself is not a candidate.
• Use screenshots or recordings for external closed-source references, not as a shortcut around importing product components.
• Treat raster pixel dimensions as untrusted UI geometry. Before using a screenshot or recording to judge font size, spacing, control size, or viewport density, establish its logical size or mark it structure-only. Never stretch an unnormalized Retina/HiDPI reference to fill a panel.
• Probe every live product route before sharing it. A route that returns an HTTP error or renders the configured error selector is not valid evidence.
• Keep both shell viewing modes available: 适应框内 scales the configured logical viewport into the review panel, while 原始 100% preserves the logical viewport and exposes panel scrollbars for exact-size inspection. For a landscape live-product panel, cap fitted view at 80% and reduce it further only when the panel is too narrow. In fitted mode, keep the review frame fixed and size the iframe viewport to the available frame height after scaling so scrolling occurs inside the real product; do not add a second outer scroll layer. In original mode, preserve the configured logical viewport and use the shell scrollbars for exact-size inspection.
• Keep the review surface height independent from the configured logical viewport height. The fit control must show its computed percentage; original mode must have measurable horizontal or vertical overflow whenever the logical viewport exceeds the surface, otherwise the two modes are not meaningfully different.
• Make long live-product screens scroll inside the product iframe, not only in the review shell. Give the app-owned review route a bounded viewport height, preserve the product's real scroll container, and verify that the screen can be scrolled from top to its actual bottom before delivery.
• Default to horizontal columns. Use vertical rows only when the user asks for it or side-by-side content is genuinely unreadable.
• Do not hand-recreate product UI in the comparison page. The page is a thin alignment frame, not an implementation.
• Keep labels short. Let the visible components carry the comparison.