fix: real scan output, a scalable sidebar, and a11y for the rules docs - #85
Merged
Conversation
🦋 Changeset detectedLatest commit: 0474df9 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
The latest Docker Doctor scan for this pull request. Learn more about Docker Doctor.
Score: 84 / 100 · 3 issues
Scanned by Docker Doctor for commit |
Contributor
|
React Doctor found no new issues. 🎉 Reviewed by React Doctor for commit |
PunGrumpy
force-pushed
the
fix/docs-interface-review
branch
from
August 23, 2026 08:47
6aeedb9 to
8ee4b5d
Compare
PunGrumpy
force-pushed
the
fix/docs-interface-review
branch
from
August 23, 2026 08:57
8ee4b5d to
79c9e08
Compare
The 25 rule summaries mixed four grammatical moods -- "Container should not run as root user" beside "Consider using...", "Always pin..." and "Ensure ... is used" -- forcing a re-parse per line anywhere the list renders as a unit (rules list, the docs index). Converge on bare imperative, with "Avoid ...ing" as the single negative form. Help strings quoted code with 'single quotes'; backticks let the docs generator render them as real inline code while staying readable in the terminal. Also "deprecated" -> "obsolete" for the Compose version key, matching the Compose specification's own wording.
The rules folder rendered always-expanded: 25 links swallowed most of the sidebar, and Configuration and Scoring sat 26 rows below the Reference heading at the same indent, reading as Rules entries. Nested folders now collapse behind a native <details> that opens when the current page is inside them, indented one step per level on the TOC's dashed-rail idiom, and Reference lists Rules last so its leaf pages stay adjacent to their heading. Wayfinding and input fixes in the same chrome: aria-current="page" and scroll-into-view on the active sidebar link (a deep link to a late rule left it offscreen), aria-current="location" on the active TOC item, Escape dismisses the mobile TOC popover, the drawer footer clears iOS safe areas, drawer positioning uses logical properties so it mirrors under RTL, the drawer buttons get 44px hit areas and the shared 0.96 press scale, and the sticky sidebar top-aligns with the article column.
The marketing base style for ul/ol (muted, 14px, flex) leaked into MDX prose, so the rules index -- a page that is almost entirely list -- rendered its primary content smaller and grayer than its own intro; docs lists now reset to body prose. font-synthesis:none erased every <em> (no italic face is loaded), so allow style synthesis. The article measure caps at 70ch for the lg-xl range where the TOC column is hidden, anchored headings clear the sticky header + mobile TOC stack below xl, and inline code sizes in em so the chip scales with context. Code blocks: the fence title rendered only as a hover tooltip and is now a visible header, and the raw-SVG icon meta no longer leaks onto the DOM. The copy button was invisible on touch (hover-revealed), gave screen readers no confirmation, and its press transition was silently dropped by class merging -- it now reveals on coarse pointers, exposes an <output> live region, keeps its 150ms ease, and uses lucide icons matching the rest of the chrome (the bespoke copy/check icons go). Also: focus rings cover <summary>, tables drop the doubled hairline on their last row, a SeverityPill maps rule severities onto the existing badge ramp for the generated index, the stale shadcn blue in the dark sidebar-primary token goes neutral, and the header pills lose their permanent will-change.
Every rule page claimed "Scanning this file reports:" and then showed rule.message -- text no diagnostic ever carries, so all 25 pages displayed output the scanner never prints. The generator now runs the rule against the page's own failing example and renders the message the scanner actually emits. Generation fails if a bad example stops triggering its rule, so the pages cannot drift from the CLI again; use-dockerignore's example is terminal output, so it declares a separate diagnosticSource to scan. The index renders each category as a Rule / What it checks / Severity table instead of 25 ragged bullets, with severity as a labeled pill on the badge ramp. meta.json stops listing "index", so the sidebar shows one Overview link instead of a Rules link duplicating the folder label. Prose escaping now skips backtick code spans, category blurbs share one verb-led shape, and the regenerated pages pick up the new core wording.
The "must not touch the cwd" assertion checked that .github/workflows/docker-doctor.yml does not exist in the cwd -- true when run from the package directory, false from the repo root, which legitimately owns that file. Snapshot the cwd file before the call and assert it is byte-identical after, which keeps the original intent wherever the runner starts.
Turn the placeholder prompts into guidance that produces reviewable descriptions: lead with the problem, show before/after, name the trade-offs. The changeset checkbox now says when it applies, and the screenshot prompt asks for both appearances.
PunGrumpy
force-pushed
the
fix/docs-interface-review
branch
from
August 25, 2026 02:11
79c9e08 to
0474df9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
A cross-discipline review of the rules docs (25 pages and growing) surfaced three blockers and a long tail of hierarchy, navigation, and accessibility issues. This PR fixes all of them.
The docs showed scan output that the scanner never prints. Every rule page said "Scanning this file reports:" and then rendered
rule.message— but diagnostics carry their own message, so all 25 pages displayed fabricated output:The generator now runs each rule against the page's own failing example and renders the real diagnostic. This doubles as a build guard: generation fails if a "bad" example stops triggering its rule, so the pages can't drift from the CLI again.
The sidebar didn't scale. The rules folder rendered always-expanded — 25 links swallowed the tree, and Configuration/Scoring sat 26 rows below the Reference heading looking like rules. Nested folders now collapse behind a native
<details>(open when you're inside them), Reference lists Rules last, the active link getsaria-current+ scroll-into-view, and the duplicated "Rules/Rules" label becomes a single Overview link. The index page swaps 25 ragged bullets for a per-category table with severity pills on the existing badge ramp.Reading-surface and a11y fixes. The marketing
ul, olbase style leaked into docs prose (muted 14px lists on a page that is mostly list),font-synthesis: noneerased every<em>(no italic face is loaded), code-fence titles rendered only as hover tooltips, the copy button was invisible on touch and silent to screen readers, and<summary>had no visible focus ring. All fixed, plus: 70ch measure cap, anchor offsets that clear the sticky stack belowxl, em-scaled inline code, iOS safe areas and RTL-ready positioning on the mobile drawer, and one imperative voice across all 25 rule summaries (the copy lives in core, sorules list/rules explainbenefit too).Deliberately unchanged: the Docs header button keeps its
blue-400/500gradient to match the View on GitHub button, even though the pair sits below AA — flagged during review, kept as a design decision.Related Issues
N/A — found during a holistic interface review of the rules docs.
Checklist
Screenshots (if applicable)
N/A — verified against SSR output; worth a quick visual pass on the preview deployment (sidebar collapse, rules index table, code-block title bars) in both appearances.
Additional Notes
workflow-scaffoldfailure is also fixed here: its "must not touch the cwd" assertion was location-dependent and failed from the repo root, which legitimately owns.github/workflows/docker-doctor.yml; it now snapshots the cwd file before/after instead.@docker-doctor/clipatch changeset; keys, severities, and diagnostic messages are unchanged.use-dockerignore's failing example is terminal output, not a Dockerfile, so it declares a separatediagnosticSourcefor the generator to scan.hover:utilities behind@media (hover: hover)(verified in the built CSS).