tui-screenshots
Use for generating or refreshing TUI screenshots for docs — "regenerate the screenshots", "the README screenshots are stale". Drives a Textual/TUI app headlessly and exports SVG. Not for reading a user's screenshot — that is `screenshot`.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tui-screenshots
- description
- Use for generating or refreshing TUI screenshots for docs — "regenerate the screenshots", "the README screenshots are stale". Drives a Textual/TUI app headlessly and exports SVG. Not for reading a user's screenshot — that is `screenshot`.
03 SKILL.md 正文
TUI screenshots
Docs screenshots of a terminal app go stale silently. Nothing fails, nothing lints — the README just shows an app that no longer exists. This is the workflow that makes regenerating them a single command instead of an afternoon.
Do not reach for a desktop screen capture. Photographing a real terminal window bakes in the user's font, theme, window size, and whatever real data was on screen. Drive the app instead.
The shape
Four pieces, in order. Skipping any one of them is where these efforts usually fail:
- A fake data source. Never screenshot real data — it is the user's private life, and it also produces a different picture every run.
- A headless driver. Run the app in-process at a fixed terminal size.
- An export step. Write a vector image per screen.
- A drift guard. Something that fails when a new screen exists and no one screenshotted it.
1. Fake data, in a real store
The tempting shortcut is to mock the data layer. Resist it: a mock screenshots the mock, not the app, and it drifts from the real schema without telling you.
Seed a real but separate store instead — a demo database, a scratch directory, a throwaway namespace. Then point the app at it with the same environment variable a real user would set. The app has no idea it is being screenshotted, so the picture is honest.
Rules for the seed script:
- It must never write to the real store. Take the real store's ID only to find out where to put the sibling demo one.
- Cache the demo store's ID in a gitignored file, so a rerun reseeds rather than piling up a new demo store every time.
- Make the fake data cover every screen, including the empty and the crowded case. A tab that is empty in the demo data screenshots as a blank box, which teaches the reader nothing.
- Fictional names only. "Call Rachel about the mortgage" is fine; a real contact is not.
2. Driving it headlessly
For Textual, the test harness is the driver — no extra dependency:
app = MyApp()
async with app.run_test(size=(130, 45)) as pilot:
await pilot.pause(2) # let async/threaded data loads land
tabs = app.query_one('#tabs', TabbedContent)
for tab_id, name in TABS:
tabs.active = tab_id
await pilot.pause(0.5)
Path(f'docs/screenshots/{name}.svg').write_text(
app.export_screenshot(title='app'),
)
Two failure modes account for nearly every bad capture:
- Screenshotting before the data arrives. Anything loading on a worker thread or a network call is still a spinner at frame zero. Pause generously once after mount, and again after each navigation. A slow script is cheaper than eight screenshots of a loading state.
- A variable terminal size. Pin it.
size=(130, 45)is a good wide-docs default. If the size changes between runs, every image in the diff churns and review becomes useless.
For a non-Textual TUI, the equivalents are asciinema rec + agg for a moving picture, or
termtosvg for a still. Prefer the app's own harness whenever it has one — anything that
records a real terminal reintroduces the font and theme problem.
3. Export SVG, not PNG
SVG is text, so a diff shows what actually changed, it stays sharp at any width, and the
reader can select the text. GitHub renders it inline in a README via <img src="...">.
One caveat: GitHub strips scripts and external references from SVG. Textual's export is self-contained, so this is fine — but do not hand-edit an exported file to pull in a font.
4. The drift guard
This is the part everyone skips, and it is the reason the screenshots were stale in the first place. A hardcoded list of screens will fall behind the app.
Best: derive the screen list from the app, not from a constant. Query the real widget tree for the tabs and iterate whatever is there. A new tab then screenshots itself.
If a hardcoded list is unavoidable, add a test that asserts the list matches the app's actual screens, so adding a screen fails the suite until someone captures it.
Wiring it up
Two scripts, chained by an ID the first one prints:
seed_demo_data.py ──prints demo store id──▶ capture_screenshots.py ──▶ docs/screenshots/*.svg
Keep them as two commands, not one. Seeding hits the network hard and rarely needs redoing; capture gets rerun over and over while you fix a layout.
Document the chain in the repo's own CLAUDE.md or a project skill, including the exact
environment variables. The whole point is that the next person does not have to rediscover it.
Before you finish
- Look at the images. Read one of the SVGs, or open the directory — a capture that "succeeded" can still be eight pictures of an empty tab.
- Check the README references every image, and every image is referenced.
- Say plainly in the README that the data is fictional.
04 同仓库更多 Skills
wait-what
Stop. Your plan/idea did not land. Re-pitch it.
verify
Verify before answering whether something works, still passes, is gone, is used, or is correct — and whenever the user says "can you confirm", "are you sure", "did that actually work", or reports something is "still" broken. Produces the answer plus the evidence that would have falsified it. A failed GitHub Actions run is skill-tree:debug-ci instead.
ui-designer
Design or restyle a web UI — landing pages, dashboards, docs sites, app chrome — or when the user asks why a site "looks generic", "looks like a template", or wants it to feel intentional. A running list of design lessons learned, applied as rules rather than suggestions.
two-axis-review
Two-axis review of changes since a fixed point (commit, tag, HEAD~N, or default HEAD~1): Standards (does the code follow this repo's conventions?) and Spec (does the code do what it should?). Axes run as parallel sub-agents so neither masks the other. Use when the user says "review against the spec", "does this follow our conventions", "standards and spec review", or "two-axis review". Not a correctness bug hunt — that's the built-in `/code-review`.
to-tickets
Break a spec, plan, or conversation into tracer-bullet vertical-slice tickets with blocking edges — "turn this into tickets", "break this down", "what's the work?". Pairs with skill-tree:to-spec upstream and skill-tree:handoff downstream.
to-spec
A conversation has settled on what to build and it's time to turn it into a written spec — "turn this into a spec", "write this up", "spec this out". Synthesis only: no interview. Pairs well with skill-tree:grill-for-planning, which is where the settled understanding usually comes from.