eng-ui-screenshot

Captures deterministic PNG screenshots of Storybook stories and local UI URLs via headless Chrome CDP.

2.7k|171|Updated Mar 28, 2026
One-click install
npx skills add https://github.com/compozy/compozy --skill eng-ui-screenshot
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: eng-ui-screenshot
Source: https://github.com/compozy/compozy/tree/main/.agents/skills/eng/eng-ui-screenshot
Command: npx skills add https://github.com/compozy/compozy --skill eng-ui-screenshot

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires chrome-launcher, chrome-remote-interface, pixelmatch, pngjs, and includes scripts (resource) and references (resource) components.

What problem does it solve?

Visual audits and design-parity checks need reproducible screenshot evidence, but ad-hoc captures suffer from unsettled fonts, wrong viewports, stale Storybook servers, and unverifiable story IDs. This Skill standardizes the entire capture workflow so every PNG is deterministic, inspectable, and backed by a validated evidence bundle.

Core Features & Use Cases

  • Deterministic CDP capture: Drives headless Chrome through the Chrome DevTools Protocol with explicit load-event waits, font readiness checks, and pinned viewport emulation for consistent PNG output.
  • Storybook story resolution: Lists real story IDs from a running Storybook's index.json so captures never land on the "Couldn't find story" fallback frame.
  • Visual-contract evidence bundles: Generates side-by-side images, pixel diffs, and comparison metrics, then validates the full bundle (reference.png, implementation.png, diff.png, comparison.json, review.md) against a strict schema before parity is claimed.
  • Use Case: When implementing a UI from a trusted design mock, capture the reference and implementation at matched viewports, generate the diff artifacts, and produce a validated review proving zero blocking divergences.

Quick Start

Use the eng-ui-screenshot skill to capture the systems-tasks-routes-tasks--default-list Storybook story at 1440x900 and save the PNG evidence.

Frequently Asked Questions about eng-ui-screenshot

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I screenshot a Storybook story with headless Chrome?

Resolve the story ID from the server's index.json, then capture the iframe URL (iframe.html?id=<story-id>&viewMode=story) through the CDP helper with an explicit viewport and wait time. The helper waits for the load event and document.fonts.ready before writing the PNG.

Why use Chrome DevTools Protocol instead of chrome --screenshot?

The --screenshot flag hangs on Storybook iframes and cannot wait for fonts or React settling. CDP provides explicit loadEventFired waits, font readiness evaluation, viewport override, and reuse of one Chrome instance across many shots.

Why is my Storybook screenshot only 5-10 KB?

A sub-20 KB PNG almost always means the story ID does not exist and Storybook rendered its "Couldn't find story" fallback. List valid IDs with the list-stories helper against the server's index.json and match the exact case-sensitive ID.

How do I fix screenshots rendering in fallback fonts?

Fallback fonts mean document.fonts.ready resolved before the web fonts decoded or timed out. Increase the wait from 2200 ms to 4000 ms and confirm the Storybook server is serving its font assets correctly.

What is a visual-contract evidence bundle?

It is a directory containing reference.png, implementation.png, side-by-side.png, diff.png, comparison.json, and a review.md with strict YAML frontmatter. The validator rejects bundles with missing files, mismatched dimensions, or a verdict other than PASS with zero blocking divergences.

When should I not use this screenshot skill?

Do not use it for interactive E2E flows, remote authenticated sites, or running Storybook tests. It is scoped to deterministic static captures of local Storybook stories and local UI URLs for visual evidence.