Skip to content

docs: name each screenshot after its tab instead of a position number - #2342

Merged
laurentiu021 merged 1 commit into
mainfrom
docs/screenshot-slug-names
Sep 17, 2026
Merged

laurentiu021 merged 1 commit into
mainfrom
docs/screenshot-slug-names

Conversation

@laurentiu021

Copy link
Copy Markdown
Owner

Problem

The 43 files in docs/screenshots/ were prefixed with the tab's position on the left rail, and that prefix re-broke on every insertion: adding one tab shifts every tab below it and touches no filename. 23 of the 43 were numbered for a different tab than the one they showed, one of them by eight places — and nothing could notice, because a wrong number looks exactly like a right one. TheScreenshotInventory_MatchesWhatIsOnDisk says so in its own remarks: it deliberately did not check which screenshot covers which tab, because with a number in the name there was no rule to check against.

Three filenames also named a tab that no longer goes by that name, the newest being from the previous release.

What changed

Naming. Each file is named for its tab alone: the sidebar label lowercased, with each run of non-alphanumeric characters collapsed to one hyphen. 42-debloater.pngpreinstalled-apps.png, 21-app-alerts.pngnew-app-alerts.png, 22-file-lock.pngfile-lock-detector.png, 16-cpu-affinity.pngcpu-core-affinity.png, 14-standby-cleaner.pngstandby-list-cleaner.png, and 38 more. Adding a tab now touches nothing that already exists. All 43 are pure renames — git reports 100% similarity on every one, no image was re-encoded.

A new guard, which is what the convention buys. EveryScreenshotSlug_NamesARealTab:

  • every filename on disk must reduce from a real sidebar label;
  • every gallery image's alt text must name the same tab its filename does;
  • two tabs reducing to one slug is reported as its own failure, because that would leave one of them permanently unable to have a shot.

The alt text is the half that matters most. It is what someone using a screen reader gets instead of the picture, so an alt text left on an old name has nothing else to correct it, while a sighted reader can at least read the header inside the image. All 43 are correct today, which is why the assertion was free to add.

The cost, stated on purpose. Renaming a tab leaves its screenshot orphaned until the file is renamed too. That is the point rather than a side effect: a renamed tab means the header rendered inside the image says the old name as well, so the file needs recapturing and not just moving. The guard names the file that has to change, and docs/screenshots/README.md now says so where a contributor will read it.

Two stale doc comments. The inventory guard's remarks explained why the slug check could not be written; the tab-count regex cited 52-system-logs.png as the shape its "tabs" requirement exists to exclude. Neither shape exists any more.

Verification

Red ritual on the new guard — all four cases red for the right reason, green after restore, every file restored from saved bytes rather than from git:

Mutation Result
a screenshot renamed to a name no tab has RED, names the orphan
an alt text captioned for a different tab RED, names the file and the caption
a tab renamed in MainWindowViewModel, no file touched RED, names battery-health.png and says to recapture
the gallery markup stops parsing RED on the vacuity floor, not a silent empty loop
  • Unit suite: 5775 passed, 0 failed (5774 before, +1 new guard).
  • dotnet build -c Release on app + tests: 0 errors, 0 warnings.
  • dotnet format --verify-no-changes: clean.
  • git grep finds no surviving numbered screenshot reference anywhere in the tree.
  • Line endings unchanged on all three text files (i/lf w/crlf, as tracked).

Scope

Refs #1664 — this settles the naming half. The 16 missing captures stay open; they need a machine that runs the application.

The 43 files in docs/screenshots/ were prefixed with the tab's position on the
left rail, and that prefix re-broke on every insertion: adding one tab shifts
every tab below it and touches no filename. 23 of the 43 were numbered for a
different tab than the one they showed, one of them by eight places, and there
was no mechanical way to notice because a wrong number looks exactly like a
right one (#1664).

Each file is now named for its tab alone: the sidebar label lowercased, with
each run of non-alphanumeric characters collapsed to one hyphen. Adding a tab
now touches nothing that already exists. Three of the renames also stop the
file naming a tab that no longer goes by that name — 42-debloater.png is
preinstalled-apps.png after v1.109.2, 21-app-alerts.png is new-app-alerts.png,
and 22-file-lock.png is file-lock-detector.png.

What the convention buys is a guard. EveryScreenshotSlug_NamesARealTab asserts
every filename on disk reduces from a real sidebar label, and that every
gallery image's alt text names the same tab its filename does. The alt text is
the half that matters most: it is what a screen-reader user gets instead of the
picture, so one left on an old name has nothing else to correct it, while a
sighted reader can at least read the header in the image.

The cost is that renaming a tab leaves its screenshot orphaned until the file is
renamed too, and that is deliberate. A renamed tab means the header rendered
inside the image says the old name as well, so the file needs recapturing rather
than moving, and the guard names the file that has to change.

Red ritual, all four cases red for the right reason and green after restore:
an orphaned filename, an alt text captioning a different tab, a tab renamed in
MainWindowViewModel with no file touched, and the gallery markup ceasing to
parse (which the vacuity floor catches rather than passing an empty loop).

Also corrected two doc comments that had gone stale on the old scheme: the
inventory guard's remarks explained why the slug check could not be written, and
the tab-count regex cited a numbered filename as the shape it must not match.

Refs #1664 — the 16 missing captures stay open, they need a machine that runs
the application.
@laurentiu021
laurentiu021 merged commit 3fd7628 into main Sep 17, 2026
6 checks passed
@laurentiu021
laurentiu021 deleted the docs/screenshot-slug-names branch September 17, 2026 14:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant