Capture Usage4claude Screenshots

Usage4Claude Documentation Images

Everything the READMEs show of the app is rendered, not captured. scripts/render_docs_images.sh compiles the whole app plus scripts/docs-images/main.swift into a command-line tool and draws the real SwiftUI views into PNGs. It is deterministic, needs no GUI, and does not disturb whoever is using the machine.

./scripts/render_docs_images.sh [output-dir]      # default: docs/images

One run emits 28 files: 7 languages × 2 scenes × light/dark. Expect a couple of minutes — the tool is rebuilt from scratch every time.

Render into a scratch directory first, look at the results, and only then write to docs/images/. Never overwrite the committed images with an unreviewed batch.

Output And Where It Goes

All images live in docs/images/.

• <lang> is en, ja, zh-CN, zh-TW, ko, fr, de. These follow the existing docs/images and README.zh-CN.md spelling and deliberately differ from AppLanguage's raw values (zh-Hans, zh-Hant). The mapping lives in docsLanguageCode.
• <variant> is light or dark.
• @2x matches renderer.scale = 2; always display at the logical point width so the image stays crisp without being upscaled.
• Settings heights differ by language because the descriptions wrap differently. That is expected; do not treat it as a defect.

Path references differ by README: the root README.md uses docs/images/…, while docs/README.<lang>.md uses images/….

README Integration

Pair the variants and let the browser pick:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="images/hero.zh-CN.dark@2x.png">
  <img src="images/hero.zh-CN.light@2x.png" width="948" alt="Usage4Claude">
</picture>

GitHub's README content area is about 948px wide inside the 1012px container.

• Hero: width="948", at the very top, in place of a large app icon. The icon already appears twice inside the image; repeating it above only pushes the product below the fold.
• Settings: width="500". The page renders full height (~1250pt) rather than being clipped to the real 550pt window, so every card is visible — including ones a user would have to scroll for. Narrower than 500 makes the body text too small to read.

To preview, serve a mock README page over HTTP (python3 -m http.server) and open it in the browser pane. file:// renders as a static snapshot that page tools cannot drive. Check dark mode in that page, never from the standalone PNG.

How The Pipeline Is Wired

Four non-obvious things make it work; breaking any one yields blank or broken output.

1. The entry file must be named main.swift. Swift only allows top-level code there.
2. Sparkle must come from the SPM artifact. MenuBarManager imports it, and the copy embedded in Usage4Claude.app/Contents/Frameworks has its Headers/Modules stripped by Xcode. The script globs DerivedData for Sparkle.xcframework/macos-arm64_x86_64.
3. @main is stripped from a copy of ClaudeUsageMonitorApp.swift. The original is never modified.
4. The binary runs from inside the app bundle (Contents/MacOS/), which is what makes Bundle.main resolve to the app so Assets.xcassets and the seven .lproj folders load.

The script picks the app bundle by modification time, and rebuilds when any source is newer than the binary. Do not change this to sort by name: build/ accumulates version directories, the alphabetically last one is not necessarily the newest, and rendering against a stale bundle silently produces images with outdated strings and assets.

Adding A Scene

In scripts/docs-images/main.swift, inside the language loop:

1. Add mock data to MockUsage if needed (see the data rules).
2. Set UserSettings.shared to the state the scene needs.
3. Render to a bitmap with renderImage(...) immediately, before touching settings again.
4. Compose and write(...) with the <name>.<code>.<variant>@2x.png convention.

Reset any setting the previous scene changed. Scenes run in sequence and share one UserSettings, so a scene that forgets to reset inherits the last one's state.

Adding a language means extending docsLanguageCode and heroLabels. The hero captions live in the renderer, not in the app's Localizable.strings — that file is for strings the UI actually shows.

Pitfalls

Each of these cost real debugging time.

Views read settings lazily

SwiftUI views read UserSettings.shared when they render, not when they are constructed. Building two views under different settings and rendering them together makes both use whatever is in effect at render time — the first side-by-side hero came out with two pace graphs for this reason. Always renderImage(...) per scene, then compose bitmaps.

Never judge a render from a standalone PNG thumbnail

Dark-variant PNGs are transparent and draw white content; viewers composite transparency onto white, so white text, hairlines and the monochrome icon all look missing. Small elements are just as deceptive — a 20pt icon in a 950pt canvas is easy to misread. This produced several rounds of chasing bugs that did not exist.

Use the bundled previewer before concluding anything is wrong. It needs no dependencies — this is a Swift repo, swift runs a single file directly. Do not install Pillow or ImageMagick for this.

S=.agents/skills/capture-usage4claude-screenshots/scripts/preview_on_background.swift

# whole image on GitHub's dark background (use ffffff for light)
swift $S docs/images/hero.zh-CN.dark@2x.png /tmp/check.png 0d1117

# top 50pt only, enlarged 3x — for the menu bar icon and other small elements
swift $S docs/images/hero.zh-CN.dark@2x.png /tmp/check.png 0d1117 50

ImageRenderer cannot draw AppKit-backed controls

They render as a yellow "unsupported" block. Usage4Claude/Helpers/DocsRenderMode.swift holds the stand-ins, all inert in the shipping app:

• DocsRenderMode.isActive — the flag.
• DocsScrollView — ScrollView renders its content as blank, with no error. Out of scroll mode the content lays out fully and the enclosing frame clips it.
• DocsSegmentedPicker — replaces .pickerStyle(.segmented). Size it to its content; NSSegmentedControl does not stretch to fill the row.
• UsageDetailView.menuButtonLabel(rotated:) — replaces the three-dot Menu.

When writing a stand-in, copy what the control looks like on screen, not what its source says. That Menu label carries .rotationEffect(.degrees(90)) which AppKit ignores, so the replica must not rotate.

SettingsView also drops its fixed height under DocsRenderMode so the whole page renders.