documentation-screenshots

Documentation and Release Notes Screenshots

Turns raw VS Code captures of the extension into framed images with one shared look. The style was established for the 1.0 release notes and announcement (docs/release-notes/1.0.md, docs/blog-posts/2026-10-release-1.0/). Follow the recipe below so new images match the existing set.

• Tool: scripts/frame.py (Python 3, pip install pillow numpy, Segoe UI fonts)
• Example jobs file: references/example-jobs.json (the complete 1.0 set)

When to Use

• Release notes (writing-release-notes Step 1 asks whether screenshots are planned)
• User manual pages and blog posts with product screenshots
• Re-capturing an existing screenshot after a UI change

Generated graphics (hero images, diagrams) are not framed, but they get the same rounded outer corners (see Generated graphics).

Workflow

0. Ask which theme the images are for, unless the operator already said so:

   • Light (default): this repo's release notes, user manual, blog posts, README and Marketplace page. This is the style of every image committed here.
   • Dark: dark-themed sites, such as the documentdb.io blog. See Dark Theme.
   • Both: render each image twice, from the same originals.

1. Collect captures. Capture VS Code in the light theme at about 1920 px wide (Windows at 125% scaling gives about 1920 x 1160). Cropped captures of a tree, dialog or quick pick are fine. Blue highlight rectangles drawn in the capture are kept as captured. Use light-theme captures for both themes.

2. Name them {version}_{feature_name}.png (snake_case), using the version of the release that shows them, for example 1.0.0_query_playground.png. Never reuse a name that already exists in the target images/ folder: older release notes link to those files. Dark-theme output gets a _dark suffix automatically (1.0.0_query_playground_dark.png), so both versions can live side by side.

3. Keep the originals. Put untouched captures in an originals/ folder next to the jobs file, outside the committed images/ folder (keep them locally or in a gitignored scratch folder such as docs/plan/). Only framed output is committed. Never edit originals.

4. Write a jobs file (see references/example-jobs.json). src and out are relative to the jobs file.

5. Pilot one image, show it to the operator, and agree on the look before running the rest. Ask for approval image by image for small crops and annotated images.

6. Run python .github/skills/documentation-screenshots/scripts/frame.py path/to/jobs.json (or add file names to run a subset). Each image takes about 5 seconds. For the dark theme, add --theme dark before the jobs file, or set "theme": "dark" in the jobs file.

7. Reference the images in Markdown. Every framed image is 1920 px wide, so all use the same display width:

   <p align="center"><img src="./images/X.Y.Z_feature_name.png" alt="Describe what the image shows" width="800" style="max-width:100%;height:auto;"></p>
   

8. Verify every image reference resolves, and delete preview and temporary files.

Preview tip: render previews to a new file name each time (_preview_a.png, _preview_b.png), because image viewers cache by path. To check the transparent corners, preview on a dark background.

The Recipe

All values are output pixels on the 1920 px canvas. They are defined as constants at the top of frame.py.

Canvas

• Width is always 1920 px. Smaller captures are not enlarged to fill it; they get more background, so the set looks structured.
• Height is the content height plus 64 px margin at the top and bottom. With a legend: 64 px above the screenshot, a 48 px gap, the 96 px legend, and 48 px below it.
• Outer corners are 32 px, transparent (RGBA PNG), about 13 px at the 800 px display width. This is intentionally twice the inner screenshot radius, so both read as equally round.
• No titles or captions inside images. They don't localize; text belongs in the Markdown.

Background

Light theme (for the dark theme, see Dark Theme):

• Diagonal gradient, position t = 0.6 * x / width + 0.4 * y / height, with three stops: #EEF5FD at 0, #EBF3FC at 0.45, #E9F8FE at 1.
• Dot grid: 32 px pitch starting at 16 px, 2 px dot radius, brand blue #0070E0 at alpha 26 (about 10%).

Screenshot card

• Full 1920 px captures are scaled to 1792 px wide (scale 0.9333) and centered.
• Corner radius 16 px, hairline border rgba(0, 0, 0, 30) at 2 px.
• Shadow: Fluent 2 shadow16 at 2x, an ambient 0 0 4px black at 12% plus a key 0 16px 32px black at 14%.
• Lanczos resampling for every resize. Masks, borders, badges and arrows are drawn at 4x and downsampled; shadows are blurred at native size.
• Captures with transparent areas are flattened onto white first, so they never leave holes in the card.

Floating panels ("mode": "panels")

For captures that show quick picks or dialogs floating on white: each panel is lifted out by its bounding box ([x0, y0, x1, y1], inclusive, source pixels) and placed directly on the background, keeping the panels' relative layout. Panels get an 8 px (source) radius and the same shadow, with no outer card. To find the bounds, scan for the panel border color #E2E2E5 (panel fill is #FBFBFD): the box runs from the outermost border pixel on each side, inclusive, and excludes the panel's own shadow.

Tight crops

If text touches the edge of a crop, add "pad": [left, top, right, bottom] (source pixels), only on the sides where text touches and only as much as needed (about 6 to 16 px). Don't pad the other sides for balance. The capture is extended with the color of the pixel near its bottom-right corner; if that pixel is content, set "pad_color": [r, g, b] explicitly.

Text Size (Most Important Rule)

Text in every image should look the same size as text in a full 1920 px capture. Never enlarge a small crop to fill the width: text at double height looks cheap. Small differences are fine.

To choose scale for a capture that is not 1920 px wide:

1. If the capture already has approved values in references/example-jobs.json, reuse them instead of measuring again.
2. Measure the same kind of element in a full capture and in the crop: tree row spacing, the same table, a repeated label or the editor line height. Row heights differ between UI surfaces, so never compare one table with another.
3. scale = 0.9333 * reference / crop.
4. Reference values for full captures (125% scaling): tree rows about 41 px apart, editor lines about 35.5 px, and rows of the Indexes table in the Collection View about 55 px (this value applies to that table only).
5. python frame.py --measure capture.png prints a rough median row spacing. Treat it as a hint and confirm by eye.

Don't scale up

A scale above 1.0 enlarges the capture. Resampling can't add detail, so text, icons and 1 px lines turn soft. It shows on high-DPI screens and when readers open the image at full size. A small mismatch in text size is much less visible than blur.

• If the computed scale is above 1.0, first check that you measured the same kind of element as the reference. A wrong reference is the most common cause.
• If the capture really was taken at a lower zoom, recapture it at 125% scaling (or the matching VS Code zoom). This is the fix.
• If you can't recapture, use 1.0, accept slightly smaller text, and mention it to the operator.
• Scale up only when the operator explicitly approves it, and never above about 1.15. Don't silently clamp a computed value to a maximum.

frame.py warns whenever a job scales up.

Values used for 1.0 (see the example jobs file): tree crop 0.96, Kubernetes tree 0.81 with pad [16, 14, 0, 6] (captured at a higher zoom, text touched the top and left edges), quick picks 0.9333. Cluster Dashboard 1.12 is an approved exception: it was captured at a lower zoom and couldn't be recaptured in time. Recapture it before reusing it for a new image.

Dark Theme

For sites with a dark design, such as the documentdb.io blog, bright framed images glare against the page. The dark theme keeps everything in the recipe above and changes only the background, so the screenshots read as light windows on a dark desktop.

What changes

• Background gradient stops: #273452 at 0, #212D48 at 0.45, #1F314F at 1 (same direction as the light theme). This is a step lighter than the documentdb.io content cards (#111827 to #0A0A0B), so each image keeps a visible edge.
• Dot grid: brand blue #0070E0 at alpha 62 (about 24%), so the grid still reads on navy.
• File names get the _dark suffix.

What stays the same

• Screenshots are not dimmed, tinted or inverted. Tests showed that lowering the white point turns white UI into a dull grey and the result looks washed out, while a light screenshot on a dark frame looks natural.
• Card radius, hairline border, shadow, badges, arrows and the white legend cards.
• Captures are still taken in the light VS Code theme.

Illustrations with their own background

Some illustrations (for example AI-generated ones) already sit on their own pale background with a rounded white panel. Framing them as they are produces two frames. Instead:

1. Start from the original illustration, not a previously framed or rounded copy.
2. Crop it to its own panel, just inside the panel edge, so none of the pale background remains.
3. Frame it with "scale": 1.0 and "radius" set to the panel's own corner radius (in output pixels), so the card corners match the panel. For the 1.0 roadmap, the crop was [45, 39, 1627, 900] of the 1672 x 941 original with "radius": 32.

Generated graphics (hero images)

Re-render the HTML source with dark tokens instead of framing the light version:

Role	Light	Dark
Background	#EEF5FD to #E9F8FE	#273452, #212D48, #1F314F
Dot grid	#0070E0 at 10%	#0070E0 at 24%
Title	#252F3E	#F5F7FB
Body text	#424242	#C3CBD9
Gradient text (version)	#0070E0 to #3CCBF4	#2E8BFF to #3CCBF4 (through #3AA8F5)
Tint badges	#EBF3FC fill, #0070E0	rgba(0,112,224,.18) fill, #8CC8FF text, rgba(140,200,255,.35) outline
DocumentDB logo	Official logo	Icon only, followed by "DocumentDB" as white text

The official DocumentDB logo has a dark wordmark that disappears on navy. Use the icon on its own (public/images/DocumentDB Logo - background removed.png in the documentdb.io repo) with the product name as live white text, as the documentdb.io site header does.

Publishing on documentdb.io

• The blog CSS stretches every image to the content width (about 776 CSS px), rounds it and adds its own border. Use plain Markdown images there, not the centered <img width="800"> markup.
• Large illustrations can be saved as JPEG, quality 85, at 1552 px wide (2x the content width). Flatten transparent corners onto the site's card color first; the site's own rounding hides them. Keep screenshots as PNG so text stays sharp.

Annotations

Use annotations only when they explain a sequence. By default, add none.

Numbered step badges

• 56 px rounded square, radius 12, 4 px white border, fill brand blue #0070E0.
• Label in Segoe UI Semibold at 31 px, white, centered. Number the badges 1, 2, 3 in the order the user performs the steps.
• Shadow: Fluent shadow8 at 2x.
• Coordinates ([x, y, "1"]) are the badge center in source pixels. Place badges next to the element they refer to, never covering text or icons:
  • Tree items and menu entries: on the right, just past the end of the label (or past the inline buttons and the highlight), where there is free space.
  • Dialogs and quick picks: on the left, just outside the panel edge (about 48 source px), level with the line that asks the question or the item the user selects.
  • Prefer the side with free space; if both sides are free, follow the reading direction (right of tree items, left of panels).

Legend cards

Only when badges alone are not self-explanatory (as in 1.0.0_copy_and_paste.png): a row of equal-width white cards under the screenshot, 48 px below it, 96 px high, 24 px apart, with radius 16, a #E0E0E0 outline and shadow16. Each card has a badge, then text in Segoe UI 24 px, navy #252F3E, with UI names in Semibold. Keep the wording short and imperative, using real UI labels, for example "Right-click the source collection and choose Copy Collection…". At most two lines per card (the script warns if text overflows). When the operator supplies legend text, use it verbatim; only split it into regular and Semibold segments.

Arrows

To show that one choice leads to the next screen:

• A quadratic Bezier [[start], [control], [end]] in source pixels. A corner point such as [end_x, start_y] as the control gives a smooth quarter curve.
• Stroke 6 px in brand blue #0070E0 with a round start cap, a 22 px filled arrowhead at a 28° half-angle, and a thin white halo so it reads over both UI and background.
• Start just right of the chosen item, end just above the next panel. For the landing point, choose end_x in the right third of the next panel, over empty header space (away from its title text), so the curve is wide and reads as "continue here". For two-step flows, combine badges and an arrow (as in 1.0.0_authentication_methods.png).

Colors

Role	Value
Brand blue (badges, arrows, dot grid)	#0070E0
Mid blue (gradients in graphics)	#2892DF
Azure cyan (gradient end in graphics)	#3CCBF4
Navy (legend text, headings)	#252F3E
Background gradient stops (light)	#EEF5FD, #EBF3FC, #E9F8FE
Background gradient stops (dark)	#273452, #212D48, #1F314F

Fonts: Segoe UI and Segoe UI Semibold, read from the Windows fonts folder. On other systems, set DOCS_FONT_DIR to a folder containing segoeui.ttf and seguisb.ttf.

Generated Graphics

Hero images, diagrams and other rendered graphics are not framed. After rendering:

• Check the outermost 1 px rows and columns for capture artifacts (a grey line appeared on HTML renders) and crop them.
• Round the outer corners: python frame.py --round graphic.png. The radius scales with the image width. Skip images that already have their own shape, such as the install button.
• For the dark theme, re-render with the dark tokens (see Generated graphics (hero images)).

Validation Checklist

• [ ] Theme agreed with the operator (light, dark or both)
• [ ] Originals kept outside the committed images/ folder
• [ ] File names follow {version}_{feature_name}.png and don't overwrite existing images; dark versions end in _dark
• [ ] Every framed image is 1920 px wide, with transparent rounded corners
• [ ] Text size matches full captures (no blown-up crops)
• [ ] No job scales above 1.0 unless the operator approved it
• [ ] Badges and arrows don't cover UI text or icons
• [ ] All images referenced with width="800" and descriptive alt text (plain Markdown images on documentdb.io)
• [ ] Every image reference resolves; preview files deleted