Skip to content

aspiers/ai-config / .agents/skills/presenting-ui-previews

presenting-ui-previews

Verified

Builds a clickable before/after screenshot gallery of web UI work, at desktop and phone widths in light and dark, where clicking any screenshot opens the actual page it came from, with a full-length screenshot one link away. Use when showing the user screenshots or previews of UI changes for review, comparing pages before and after a change, or when screenshots handed over were cropped to the first screen. For a single image or page, open it directly as orca-cli-local or open-in-user-browser describes.

FileKindSize
SKILL.mdskill md3.7 KB
scripts/ui-gallery.pyexecutablescript16.1 KB

scripts/ui-gallery.py

View on GitHub
#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# dependencies = ["playwright"]
# ///
"""Build a before/after screenshot gallery of web pages for review.

For every phase (before, after), page, width and colour scheme it saves a
first-screen PNG, a full-page PNG and an HTML page showing the full-length
shot at real size. For every phase and page it saves the actual page as an
MHTML snapshot that opens without the server. index.html shows first-screen
thumbnails: each opens the actual page, with a link to its full-length shot.

Run it with a Python that has Playwright and its Chromium, such as the
project's own environment, or `uv run ui-gallery.py ...` and then
`playwright install chromium` if the browser is missing.
"""

import argparse
import html
import shutil
import sys
from datetime import datetime
from pathlib import Path

from playwright.sync_api import Error as PlaywrightError
from playwright.sync_api import sync_playwright

PHONE_MAX = 480


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--after", required=True, metavar="URL", help="base URL of the server showing the change")
    parser.add_argument("--before", metavar="URL", help="base URL of a server running the code before the change")
    parser.add_argument(
        "--page",
        action="append",
        required=True,
        metavar="ID|LABEL|PATH",
        help='page to capture, e.g. "draft|Draft report|/reports/7"; repeat for more',
    )
    parser.add_argument("--width", action="append", type=int, metavar="PX", help="viewport width; default 1280 and 390")
    parser.add_argument(
        "--scheme",
        action="append",
        choices=["light", "dark"],
        help="colour scheme; default both",
    )
    parser.add_argument(
        "--login",
        metavar="PATH",
        help="path the browser visits first on each server to get a session, e.g. /auth/login",
    )
    parser.add_argument("--wait", metavar="SELECTOR", help="CSS selector that shows the page has rendered")
    parser.add_argument(
        "--link",
        action="append",
        default=[],
        metavar="[PHASE:]ID=TARGET",
        help="the actual page to open instead of the MHTML snapshot: a URL, or a standalone HTML file "
        "(copied into the gallery); PHASE defaults to after",
    )
    parser.add_argument("--title", default="UI preview", help="gallery heading")
    parser.add_argument("--out", required=True, type=Path, help="output directory")
    return parser.parse_args()


def parse_pages(specs: list[str]) -> list[tuple[str, str, str]]:
    pages = []
    for spec in specs:
        parts = spec.split("|")
        if len(parts) != 3 or not all(parts):
            sys.exit(f'--page needs "ID|LABEL|PATH", got {spec!r}')
        pages.append(tuple(parts))
    return pages


def parse_links(specs: list[str], out: Path) -> dict[tuple[str, str], str]:
    """Map (phase, page id) to an href, copying local files into the gallery."""
    links = {}
    for spec in specs:
        key, sep, target = spec.partition("=")
        if not sep or not target:
            sys.exit(f"--link needs [PHASE:]ID=TARGET, got {spec!r}")
        phase, _, page_id = key.rpartition(":")
        phase = phase or "after"
        source = Path(target)
        if source.is_file():
            name = f"{phase}-{page_id}-standalone{source.suffix}"
            shutil.copyfile(source, out / name)
            target = name
        links[(phase, page_id)] = target
    return links


DARK = """color-scheme:dark;--bg:#0f1318;--bg-top:#141a21;--panel:#171d25;--soft:#1d2530;--ink:#e7ecf2;
--muted:#9aa6b5;--line:rgba(220,230,245,.13);--accent:#86adff;--danger:#ff8a80;--shadow:rgba(0,0,0,.4)"""

# The viewer's choice (data-theme) wins over the system setting; "system" removes the attribute.
STYLE = f"""<style>
:root{{color-scheme:light;--bg:#f2f4f8;--bg-top:#f9fafc;--panel:#fff;--soft:#f5f7fa;--ink:#18202b;
--muted:#5b6676;--line:rgba(23,32,48,.12);--accent:#2457c5;--danger:#b42318;--shadow:rgba(16,24,40,.07)}}
@media (prefers-color-scheme:dark){{:root:not([data-theme=light]){{{DARK}}}}}
:root[data-theme=dark]{{{DARK}}}
*{{box-sizing:border-box}}
.topbar{{display:flex;justify-content:flex-end;margin-bottom:12px}}
.theme{{display:inline-flex;padding:3px;gap:2px;border-radius:999px;background:var(--panel);
border:1px solid var(--line);box-shadow:0 6px 18px var(--shadow)}}
.theme button{{font:inherit;font-size:.85rem;color:var(--muted);background:none;border:0;border-radius:999px;
padding:4px 12px;cursor:pointer}}.theme button[aria-pressed=true]{{background:var(--accent);color:var(--panel)}}
.theme button:focus-visible{{outline:2px solid var(--accent);outline-offset:2px}}"""
STYLE += """
body{margin:0;background:linear-gradient(180deg,var(--bg-top),var(--bg));color:var(--ink);
font:15px/1.6 "Avenir Next","Segoe UI",system-ui,sans-serif}
main{width:min(1360px,calc(100% - 28px));margin:18px auto 48px}
h1,h2{font-family:"Iowan Old Style","Palatino Linotype",Georgia,serif;font-weight:600;line-height:1.15}
h1{font-size:clamp(1.8rem,4vw,2.6rem);margin:.2rem 0 .4rem}h2{font-size:1.6rem;margin:0 0 .3rem}
h3{font-size:1rem;margin:0}a{color:var(--accent)}.muted{color:var(--muted)}
.panel{background:var(--panel);border:1px solid var(--line);border-radius:22px;padding:20px;
box-shadow:0 14px 40px var(--shadow)}.panel+.panel{margin-top:16px}
.pills{display:flex;flex-wrap:wrap;gap:10px;margin:.6rem 0}
.pill{display:inline-flex;align-items:center;gap:8px;min-height:34px;padding:0 12px;border-radius:999px;
background:var(--soft);border:1px solid var(--line);color:var(--muted);font-size:.9rem}
.pill strong{color:var(--ink)}.pill.danger,.pill.danger strong{color:var(--danger)}
.filter{position:sticky;top:8px;z-index:1;margin:16px 0}.filter .pill{box-shadow:0 6px 18px var(--shadow)}
.filter select{font:inherit;color:var(--ink);background:var(--panel);border:1px solid var(--line);
border-radius:999px;padding:2px 10px}
.row{display:grid;grid-template-columns:repeat(var(--phases),minmax(0,1fr));gap:14px;align-items:start;
margin-top:18px}.row[hidden]{display:none}.row h3{grid-column:1/-1}
figure{margin:0;padding:12px;background:var(--soft);border:1px solid var(--line);border-radius:16px}
figcaption{font-size:.78rem;font-weight:600;letter-spacing:.06em;text-transform:uppercase;color:var(--muted);
margin-bottom:8px}
.thumb{display:block}.thumb img{display:block;max-width:100%;border:1px solid var(--line);border-radius:10px;
background:#fff}.phone .thumb img{max-width:min(100%,390px)}
a:hover img,a:focus-visible img{outline:3px solid var(--accent);outline-offset:2px}
figure .thumb+a{display:inline-block;margin-top:8px;font-size:.9rem}
.shot{overflow-x:auto}.shot img{display:block;max-width:none;border-radius:10px}
.failed{color:var(--danger);margin:0}
</style>"""

# Applies the saved theme before the page paints, so it never flashes the other theme.
THEME_HEAD = """<script>
try {
  const theme = localStorage.getItem("ui-gallery-theme");
  if (theme === "light" || theme === "dark") document.documentElement.dataset.theme = theme;
} catch {}
</script>"""

THEME_TOGGLE = (
    '<div class="topbar"><div class="theme" role="group" aria-label="Colour theme">'
    + "".join(f'<button type="button" data-choice="{c.lower()}">{c}</button>' for c in ("Light", "Dark", "System"))
    + "</div></div>"
)

THEME_SCRIPT = """<script>
const themeButtons = document.querySelectorAll(".theme button");
function markTheme() {
  const current = document.documentElement.dataset.theme || "system";
  for (const button of themeButtons) button.setAttribute("aria-pressed", button.dataset.choice === current);
}
for (const button of themeButtons) {
  button.addEventListener("click", () => {
    const choice = button.dataset.choice;
    if (choice === "system") delete document.documentElement.dataset.theme;
    else document.documentElement.dataset.theme = choice;
    try { localStorage.setItem("ui-gallery-theme", choice); } catch {}
    markTheme();
  });
}
markTheme();
</script>"""

# Hides the rows whose width and scheme don't match the chosen view; remembers the choice per viewer.
FILTER_SCRIPT = """<script>
const pick = document.getElementById("view");
function show(view) {
  const wanted = view.split(" ").filter(Boolean);
  for (const row of document.querySelectorAll(".row")) {
    const tags = row.dataset.view.split(" ");
    row.hidden = !wanted.every((tag) => tags.includes(tag));
  }
}
let saved = "";
try { saved = localStorage.getItem("ui-gallery-view") || ""; } catch {}
if ([...pick.options].some((option) => option.value === saved)) pick.value = saved;
show(pick.value);
pick.addEventListener("change", () => {
  show(pick.value);
  try { localStorage.setItem("ui-gallery-view", pick.value); } catch {}
});
</script>"""


def layout_name(width: int) -> str:
    return f"{'Phone' if width <= PHONE_MAX else 'Desktop'} {width} px"


def view_filter(widths: list[int], schemes: list[str]) -> str:
    options = [("", "All layouts")]
    if len(schemes) > 1:
        options += [(str(width), f"{layout_name(width)}, all schemes") for width in widths]
    if len(widths) > 1:
        options += [(scheme, f"All widths, {scheme}") for scheme in schemes]
    if len(widths) > 1 or len(schemes) > 1:
        options += [(f"{w} {s}", f"{layout_name(w)}, {s}") for w in widths for s in schemes]
    choices = "".join(f'<option value="{value}">{html.escape(text)}</option>' for value, text in options)
    return f'<div class="filter"><label class="pill">Show <select id="view">{choices}</select></label></div>'


def document(title: str, body: str) -> str:
    return (
        '<!doctype html><html lang="en"><head><meta charset="utf-8">'
        '<meta name="viewport" content="width=device-width,initial-scale=1">'
        f"<title>{html.escape(title)}</title>{THEME_HEAD}{STYLE}</head><body><main>"
        f"{THEME_TOGGLE}{body}</main>{THEME_SCRIPT}</body></html>"
    )


def real_links(actual: str, live: str, which: str = "") -> str:
    return (
        f'<a href="{html.escape(actual)}">Open the actual {which}page</a> · '
        f'<a href="{html.escape(live)}">live {which}page (while its server runs)</a>'
    )


def capture(page, base: str, path: str, login: str | None, wait: str | None, stem: Path, snapshot: Path) -> None:
    if login:
        page.goto(base + login)
    page.goto(base + path)
    if wait:
        page.locator(wait).first.wait_for()
    else:
        page.wait_for_load_state("networkidle")
    page.wait_for_timeout(300)
    page.screenshot(path=f"{stem}-top.png")
    page.screenshot(path=f"{stem}-full.png", full_page=True)
    if not snapshot.exists():
        # MHTML keeps the rendered page with its styles, so it opens after the server stops.
        cdp = page.context.new_cdp_session(page)
        snapshot.write_text(cdp.send("Page.captureSnapshot", {"format": "mhtml"})["data"], "utf-8")
        cdp.detach()


def main() -> int:
    args = parse_args()
    pages = parse_pages(args.page)
    widths = args.width or [1280, 390]
    schemes = args.scheme or ["light", "dark"]
    phases = [(name, url.rstrip("/")) for name, url in (("before", args.before), ("after", args.after)) if url]
    args.out.mkdir(parents=True, exist_ok=True)
    links = parse_links(args.link, args.out)
    cells: dict[tuple[str, str, int, str], str] = {}
    failures = 0

    with sync_playwright() as playwright:
        browser = playwright.chromium.launch()
        for phase, base in phases:
            for width in widths:
                for scheme in schemes:
                    # One context per combination: sessions stay apart even when servers share a host.
                    context = browser.new_context(
                        viewport={"width": width, "height": 844 if width <= PHONE_MAX else 800},
                        color_scheme=scheme,
                    )
                    page = context.new_page()
                    for page_id, label, path in pages:
                        name = f"{phase}-{page_id}-{width}-{scheme}"
                        title = f"{label}: {phase}, {width} px, {scheme}"
                        live = base + path
                        actual = links.get((phase, page_id), f"{phase}-{page_id}.mhtml")
                        try:
                            snapshot = args.out / f"{phase}-{page_id}.mhtml"
                            capture(page, base, path, args.login, args.wait, args.out / name, snapshot)
                        except PlaywrightError as error:  # report every failed shot, keep the rest
                            failures += 1
                            message = f"{title}: {str(error).splitlines()[0]}"
                            print(f"failed: {message}", file=sys.stderr)
                            cells[(phase, page_id, width, scheme)] = (
                                f'<p class="failed">Failed: {html.escape(message)}</p>'
                            )
                            continue
                        (args.out / f"{name}.html").write_text(
                            document(
                                title,
                                f'<header class="panel"><p><a href="index.html">Back to all screenshots</a> · '
                                f"{real_links(actual, live)}</p>"
                                f'<h1>{html.escape(title)}</h1><p class="muted">Full-length screenshot. '
                                "Click it to open the actual page.</p></header>"
                                f'<div class="panel shot"><a href="{html.escape(actual)}"><img src="{name}-full.png" '
                                f'alt="{html.escape(title)}, full length"></a></div>',
                            ),
                            "utf-8",
                        )
                        cells[(phase, page_id, width, scheme)] = (
                            f'<a class="thumb" href="{html.escape(actual)}"><img src="{name}-top.png" '
                            f'alt="{html.escape(title)}, first screen; opens the actual page"></a>'
                            f'<a href="{name}.html">Full-length screenshot</a>'
                        )
                    context.close()
        browser.close()

    sections = []
    for page_id, label, path in pages:
        rows = []
        for width in widths:
            for scheme in schemes:
                figures = "".join(
                    f"<figure><figcaption>{phase.capitalize()}</figcaption>"
                    f"{cells[(phase, page_id, width, scheme)]}</figure>"
                    for phase, _ in phases
                )
                size = "phone" if width <= PHONE_MAX else "desktop"
                rows.append(
                    f'<div class="row {size}" data-view="{width} {scheme}" style="--phases:{len(phases)}">'
                    f"<h3>{layout_name(width)}, {scheme}</h3>{figures}</div>"
                )
        page_links = " · ".join(
            real_links(links.get((phase, page_id), f"{phase}-{page_id}.mhtml"), base + path, f"{phase} ")
            for phase, base in phases
        )
        sections.append(
            f'<section class="panel"><h2>{html.escape(label)}</h2><p>{page_links}</p>{"".join(rows)}</section>'
        )

    now = datetime.now().astimezone()
    shots = len(cells) - failures
    failed_tone = " danger" if failures else ""
    summary = (
        f'<div class="pills"><span class="pill"><strong>{shots}</strong> screenshots</span>'
        f'<span class="pill{failed_tone}"><strong>{failures}</strong> failed</span>'
        f'<span class="pill"><strong>{" and ".join(p for p, _ in phases)}</strong></span>'
        f'<span class="pill">generated <strong>{now.day} {now:%b %Y, %H:%M}</strong></span></div>'
    )
    index = args.out / "index.html"
    index.write_text(
        document(
            args.title,
            f'<header class="panel"><h1>{html.escape(args.title)}</h1>{summary}'
            '<p class="muted">Each picture is the first screen of a page: click it to open the actual page, '
            "or use the link under it for a full-length screenshot.</p></header>"
            + view_filter(widths, schemes)
            + "".join(sections)
            + FILTER_SCRIPT,
        ),
        "utf-8",
    )
    print(index.resolve())
    return 1 if failures else 0


if __name__ == "__main__":
    sys.exit(main())
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall