Web Gallery Screenshot Maintenance

Web Gallery Screenshot Maintenance

Overview

Use this skill to keep gbdraw Web Gallery tutorials visually and textually truthful: every operation screenshot should show the actual UI the reader operates, every caption should name the action or selected value, tutorial text should match the real workflow, and repeated-field content should use structured display.

Read First

Before editing or reviewing Gallery tutorial screenshots, writing, or structured content, read:

• CLAUDE.md
• gbdraw/web/CLAUDE.md
• docs/WEB_GALLERY_OPERATION_SCREENSHOTS_PLAN.md, if present
• docs/WEB_GALLERY_REAL_UI_SCREENSHOT_ROLLOUT_PLAN.md, if present
• docs/WEB_GALLERY_DROPDOWN_SCREENSHOT_PLAN.md, if present
• docs/internal/WEB_GALLERY_OPERATION_SCREENSHOT_REGISTER.md, if present
• docs/WEB_GALLERY_SCREENSHOT_RECAPTURE_PLAN.md, if present

Then inspect the target tutorial JSON and media directory:

• gbdraw/web/gallery/tutorials/<example-id>.json
• gbdraw/web/gallery/media/<example-id>/

Overwrite Policy

• Treat gbdraw/web/gallery/sessions/, sources/, examples/, thumbnails/, and examples.json as generator-owned outputs. When a Gallery refresh is in scope, overwrite all dirty or uncommitted copies in those paths with the current generator output; do not preserve, merge, or restore their previous bytes.
• Inspect the target inventory before running a broad refresh and regenerate from the declared source inputs. If correctness also requires a code, test, or documentation change, replace the dirty in-scope implementation as needed.
• Keep unrelated working-tree files out of scope. The overwrite rule does not authorize broad cleanup elsewhere in the repository.

Audit Workflow

1. Audit screenshots, tutorial writing, and structured content together. Do not treat a screenshot pass as complete until the tutorial also satisfies the Writing Rules and Structured Content Rules below.
2. Enumerate only media referenced by tutorial JSON first. Treat unreferenced media as cleanup candidates after visible screenshots are fixed.
3. Compare each referenced screenshot with its operation text and caption.
4. In the audited scope, mark task-specific input, setting, and record-row operations with dataDependent: true. Their media must live under the current example's media directory, and their capture metadata must declare the exact session, expected app state, and values visible in the crop. Mark a cross-example mode or other data-independent crop with genericMedia: true; never use that escape hatch for a file, organism, accession, result, or example-specific setting.
5. Check adjacent operation screenshots for parent/child duplication. Remove the child operation/media only when the broader crop is already compact and readable at Gallery size, clearly shows the child controls, and adds no unrelated area merely to absorb the child image. Otherwise keep focused crops or recrop the shared panel.
6. Hash or otherwise compare referenced screenshots after the visual pass. Pixel-identical screenshots inside the same tutorial are acceptable only when they are intentionally reused across non-adjacent, clearly different contexts; otherwise consolidate the operation, recrop one image, or delete the duplicate media.
7. Classify each screenshot as:
   • keep: real UI/result crop, readable, caption matches.
   • recrop: correct state but poor extent, blurry text, missing context, or too much page.
   • replace: final preview or stale/empty crop used for an input/edit/upload/setting operation.
   • add: operation needs an extra crop to avoid one overloaded screenshot.
8. Review tutorial writing and structure: remove generic Requirements, avoid unnecessary Files tab steps, keep pre-generation setup, generated-result inspection, and post-generation edits separate, and omit redundant operation title/body when a clear step plus media caption already conveys the action.
9. Review structured content: convert repeated-field setup lists, file mappings, record metadata, track recipes, and color rules to tables when rows share the same fields; keep simple one-column checklists as bullets.
10. For sweeping audits, make a temporary contact sheet of referenced media for each tutorial and inspect the updated contact sheet after fixes. For every recrop or replacement, also compare the old and new images side by side at the same displayed size. Reject the replacement when it makes the operated control less compact, removes a useful selected target, or adds page area without adding information needed for the documented action.
11. Record screenshot, writing, and structured-content decisions in the operation register or the active screenshot plan before replacing files. If no active register exists, create or update docs/internal/WEB_GALLERY_OPERATION_SCREENSHOT_REGISTER.md.
12. After tutorial references are fixed, scan gbdraw/web/gallery/media/ for WebP files unreferenced by tutorial JSON. If tests or docs still refer to an otherwise stale media fixture, update them to use current referenced media before deleting the stale file.
13. Keep batches small. Do not migrate every tutorial in one risky change. For an explicitly exhaustive audit, batching must not reduce semantic coverage: do not omit required captures, assertions, or focused crops to save model tokens, runtime, or image count.

Screenshot Rules

Use the real UI the user operates.

• Treat a good existing screenshot as the semantic-crop baseline. Prefer the smallest truthful crop that keeps the operated control, selected value, and only the neighboring context needed to locate it. A larger crop is not an improvement merely because it contains more real UI.
• Tutorial media must render as appropriately scaled thumbnails in the Gallery, while click-to-open behavior must show the original image itself at natural bitmap size. Do not use a framed page-like modal, captions, headers, or extra white shell around the opened image.
• If a screenshot is unreadable in the Gallery, fix the source capture density, crop extent, or thumbnail/lightbox behavior. Do not rely on browser zoom, CSS upscaling, or a larger wrapper around the same low-resolution bitmap.
• Mode selector screenshots must show the real Circular/Linear control with the active choice readable.
• Do not reuse another example's data-dependent crop. A shared mode selector or equally data-independent control may be reused only when the operation declares genericMedia: true and the crop contains no example-specific file, metadata, setting, or result.
• File uploads must show the real uploader/input card the user operates, not a reconstructed list of file chips. The crop must include the uploaded file and the neighboring per-record controls that are visible in the actual row.
• When the session or command uses per-record metadata that affects the figure, such as --record_label, --record_subtitle, definition, record_subtitle, organism/strain, subtitle/title, region, reverse complement, or LOSAT filename, include those fields in both the tutorial table/text and the upload-row crop. Do not split file upload and record label/title entry into disconnected screenshots when the values live in the same input card.
• For tall multi-file upload workflows, keep the full file order and metadata as a tutorial table and use one representative real row crop with the file chip and relevant metadata fields, rather than one unreadable crop of every row.
• Dropdown/select operations must show the select in context plus a capture-only opened-option overlay with the chosen option highlighted.
• Text and number inputs must show labels, values, units, and nearby related controls. Highlight changed fields when multiple inputs are visible.
• When one operation sentence lists several pre-generation settings, include an overview crop that shows the actual text inputs, selects, toggles, or selected chips, even if separate dropdown crops also show individual menu choices.
• Plot title operations must keep the Plot Title input and Plot Title Position control in the same readable context. If a long title cannot fit at the normal compact sidebar width, put the exact copyable value in tutorial text or a table and let the screenshot identify the real input without implying that its visible substring is complete. Widen only enough to make the control recognizable; do not turn a compact operation crop into a page-wide image solely to expose every character of a long title.
• Checkboxes, toggles, and radio groups must show selected state in context.
• Track slots, conservation rings, record labels, record positions, and color rules must show the actual row/panel where values are typed or edited.
• Feature-specific color rule operations must show the real SPECIFIC RULES (-t) controls, not a generated plot preview.
• When several color rules are entered before one final generation, use one focused crop showing all entered rule rows if it is readable; otherwise use focused per-row input crops. Do not place a full-plot screenshot after each rule.
• If a control screenshot looks too wide because rows have large unused horizontal gaps, treat the capture source as wrong. Compare sibling operation images in the same example, then recapture the real UI with a compact sidebar/panel width that matches their density. Do not fix this by changing Gallery display CSS or by cropping only the already-wide bitmap.
• Show the generated plot only once after all required pre-generation inputs and rules have been entered, unless a later step is explicitly about inspecting a popup or visual result.
• Toolbar actions must show the actual toolbar, not an isolated or reconstructed button.
• Crops with highlighted toolbar buttons, track slots, drawer rows, or other position-sensitive controls must include enough surrounding controls above, below, left, or right for the highlight to convey where the target sits. Do not crop exactly to only the highlighted box when neighboring items define the action context.
• Popups must come from real clicks in the restored session whenever possible.
• Popup crops must be tight enough that the highlighted clicked feature, match ribbon, orthogroup ribbon, or collinear block and the popup text are readable in the rendered Gallery. Do not use a full generated-preview crop when the inspected target is only a small part of the figure.
• If the popup covers the highlighted feature, orthogroup ribbon, or collinear block, move the popup during capture and then crop the real UI state. Do not accept a crop where the popup is readable but the highlighted diagram target is hidden.
• Before recapturing a popup from a restored session, verify the saved SVG and session metadata agree with the tutorial's intended label rules. Stale session artifacts can make popups fall back to product even when the rendered figure or tutorial expects gene; fix the session/result metadata first, then recapture.
• Feature editor popup crops must keep the relevant affected item(s) or multi-target controls readable, including apply-to-all/scope icons or dialogs when they are the point of the operation. Crop or move the popup so these controls are not cut off at the image edge.
• Judge readability at the rendered Gallery size, not at the source bitmap's full size. A source image that looks readable only when opened standalone is a recrop if Gallery CSS downscales it enough to make popup text, highlighted targets, or affected item(s) hard to read.
• Generated preview crops are appropriate only for final result checks, visual inspection, legends, popups, or rendered-output comparisons.
• Generated preview screenshots with floating controls must leave enough capture-time breathing room around the SVG content so zoom/original/search controls do not cover top records, labels, or legends, and bottom titles do not visually collide with legends. If the visible crop is cramped, recapture with a larger viewport or SVG canvas instead of accepting overlap.
• Do not show the same generated preview or popup twice in immediate succession as both step-level media and operation media. If the operation already carries the result or popup crop, omit step-level media or make the two crops visibly different and purposeful.
• More generally, omit step-level media when the operation media already shows the same UI state, Files tab, generated preview, or popup without adding new context.
• When one operation crop already includes another operation's entire control area, keep the broader crop only if it remains compact at Gallery size and every extra area helps explain the action. Otherwise keep the narrower crop or recrop the shared panel. Prefer a single truthful panel crop over consecutive screenshots that repeat the same controls, but do not trade away compactness merely to reduce the image count.
• Post-generation editor screenshots must come from the exact restored session for that example. Before capturing drawers such as Legend, Features, or Orthogroups, verify the restored editor state matches the example-specific generated result. A generic or stale drawer state, such as a BGC legend editor showing only CDS, is a replace, even if it is a real drawer crop.
• Drawer screenshots must show the named active drawer tab and must not be overlapped by a popup or another drawer's controls. Legend drawer crops should be scrolled so the entries named by the caption are visible.
• If a restored session's saved editor state and rendered SVG disagree, fix the app restore behavior or refresh the session artifact before capturing. Do not document the broken intermediate state as the tutorial screenshot.
• If a restored session's UI controls disagree with the tutorial command or rendered output, fix the app restore behavior or refresh the session artifact before capturing. This includes settings that may exist only in cliInvocation.args in older sessions, such as multi-record --multi_record_position tokens.
• Treat capture metadata as executable documentation even when the current bitmap is retained. Its active tab, selected values, target selector, and crop composition must reproduce the visible screenshot state; do not leave a recipe that would silently replace a Details image with Qualifiers or otherwise change the documented action on the next refresh.
• For ordered or movable controls such as track slots, comparison series, and record rows, replay the tutorial steps against the reset/default state and compare the resulting order with the saved Gallery session. Document every required move explicitly instead of relying on a pre-arranged restored session.
• When capturing a drawer, keep the actual drawer controls visible, but exclude unrelated floating preview controls if they visually overlap the drawer; use temporary capture-only CSS rather than permanent app changes.

Reject preview screenshots for non-final input/edit operations even if the generated result is visually correct.