GitHub README Visuals

Create a fast, trustworthy visual explanation of the product without replacing its factual README content.

Workflow

1. Inspect the repository before designing.

   • Read the README, product notes, local instructions, existing assets, and available screenshots.
   • For application repositories, prioritize real product screenshots as proof. Do not present generated UI as a real screen.
   • Identify the user journey a first-time visitor should understand in one glance.
   • Build a visual-claim ledger before writing hero copy: every product, pricing, privacy, credential, provider, and deployment claim must be supported by the README, source, or user-confirmed facts. Omit ambiguous claims instead of guessing.

2. Establish visual direction.

   • When Creative Production is available, use its style intake before generating a new direction. Use moodboard-explorer when the user asks for multiple visual territories or concept options.
   • If the user does not choose a direction, use a restrained default: one original hero, product-led composition, readable hierarchy, and a palette derived from the repository's existing UI or brand assets.
   • Directly inspect every supplied reference before production. Record its canvas ratio, major spatial split, dominant visual, screenshot count, overlap, rotation, off-canvas clipping, shadows, typography blocks, and decorative motifs.
   • When the user explicitly requests a layout or style match, preserve the reference's composition grammar and visual hierarchy while replacing its UI, logo, copy, branding, and assets with material from the target repository.
   • Measure repeated screenshot frames instead of estimating them independently. If the reference uses equal-size frames, define one canonical width and aspect ratio for every screenshot; create hierarchy through position, overlap, off-canvas clipping, rotation, contrast, and z-order rather than arbitrary scaling.
   • When the brief says one-to-one, exact, or fully replicated, create a pixel geometry table before editing. Record canvas size; each screenshot's four corners, frame width and height, rotation, off-canvas clipping, and z-order; distances between adjacent frames; and each decorative shape's orientation and anchor point.
   • Derive CSS positions from measured corners and rotation. Do not substitute a visually similar arrangement or independently eyeball each frame.
   • Do not start final production from a moodboard or verbal summary alone when an exact reference image is available.

3. Produce assets.

   • Use deterministic composition for a software hero whose reference is built from real interface screenshots. Image generation may add a non-product polish layer, but it must not invent, redraw, or replace the product UI.
   • Use real captured screenshots for implementation, settings, privacy, or workflow proof. Review each one for secrets, personal data, and legibility.
   • Make the repository's real screenshots the dominant visual whenever the reference does. A screenshot collage may use four to eight captures when that count is part of the requested composition.
   • Use the application's first/default screen as the dominant screenshot unless the user names another primary workflow. Arrange secondary screenshots by user importance, not filename order.
   • Do not repeat the same page, near-identical state, or duplicated crop inside one collage. Each screenshot must prove a distinct interface or capability.
   • Keep decorative shapes outside screenshot bounds and outside the logo clear space. Decorations must never look like product UI, status indicators, annotations, or screenshot content.
   • Use the original transparent application logo directly on the composition background unless an existing brand system explicitly defines a container. Do not add a dark tile, badge, or frame by default.
   • When the repository has multiple README languages, generate one localized hero per README from a shared layout source. Keep geometry, screenshot order, logo treatment, and visual hierarchy identical; localize only verified copy and typography adjustments.
   • Match the language inside product screenshots to the destination README whenever the application supports that locale. A localized headline over screenshots from another language does not count as a localized hero.
   • Use stable language-qualified filenames such as product-hero-zh.png and product-hero-en.png, and point each README only to its matching language asset.
   • Preserve the complete product window. Never use object-fit: cover, clipping, masks, or manual crops merely to force a screenshot into the reference frame ratio.
   • When source and reference aspect ratios differ, recapture the real application at the target ratio. If recapture is impossible, use proportional contain scaling and disclose the resulting empty space; do not silently remove interface content.
   • Reproduce decorative orientation explicitly. For triangles, arrows, slashes, and asymmetric shapes, record the pointing direction or vertex coordinates; matching only color and approximate location is insufficient.
   • Save project-bound final assets in a tracked repository directory, normally docs/images/. Do not leave README assets only in a generated-images or temporary directory.

4. Update README files additively.

   • Keep every existing line unless the user explicitly authorizes removal or rewriting.
   • Place the hero directly after the primary installation or download call to action.
   • Place an interface-preview section after the first workflow explanation, using only the smallest set of screenshots needed to explain the product.
   • Keep language variants factually aligned while writing naturally in each language.
   • Keep localized hero claims semantically equivalent. Do not introduce a capability, provider, pricing, credential, or privacy claim in only one language.
   • Use descriptive alt text and repository-relative image paths.

5. Verify before delivery.

   • Read the visual checklist and complete every applicable item.
   • Inspect the final hero and screenshots at display size. Confirm that the hero conveys the product category and the screenshots remain readable.
   • Compare the final hero against the reference on five structural checks: left/right allocation, dominant screenshot position, screenshot count, overlap/rotation pattern, and text-block hierarchy.
   • Run a duplicate-and-intrusion review: confirm every screenshot is unique, the main screenshot is the intended first screen, and no decoration overlaps a screenshot or logo.
   • Re-check every visible factual claim against the visual-claim ledger. Remove any unsupported API-key, pricing, privacy, offline, provider, or product-capability statement.
   • Inspect every exported language variant independently. A successful render of one locale does not validate another; check for missing images, black render blocks, overflow, unexpected wrapping, and layout drift.
   • Verify both localization layers for every variant: composition copy and in-product screenshot UI. Navigation, headings, tabs, buttons, and settings labels should use the destination README language.
   • For equal-frame references, verify every screenshot has the same rendered width and aspect ratio in the composition source.
   • Confirm every screenshot preserves the complete captured window: title bar, navigation, primary content bounds, and visible window edges must not be removed by the composition.
   • For one-to-one work, render at the reference's exact pixel dimensions and compare reference and output with a 50% opacity overlay or edge overlay. Verify screenshot corner positions, inter-frame gaps, rotation, z-order, canvas-edge clipping, and asymmetric decoration direction before approval.
   • Use a default geometry tolerance of 8 px per measured corner and 0.5 degrees per rotation unless the user specifies a stricter tolerance. Any intentional deviation must be documented and user-driven.
   • Report which images are original generated artwork and which are real product captures.

Decision Rules

• Use a single hero image when the README needs immediate visual identity.
• Use two or three screenshots by default, but follow the reference when a screenshot collage is an explicit part of the requested design.
• Use an abstract generated hero when exact UI would be risky or inaccurate; pair it with real screenshots below.
• Stop and ask for direction only if an unverified visual claim, brand rule, or missing source asset would materially change the result.