From 7d1d8f24ac43debbad9020ce9d8b16da04a8a501 Mon Sep 17 00:00:00 2001 From: Johnny Greco Date: Tue, 29 Sep 2026 20:05:32 +0000 Subject: [PATCH 1/3] docs: streamline visual review skill --- .agents/skills/docs-visual-review/SKILL.md | 111 ++++++++------------- 1 file changed, 43 insertions(+), 68 deletions(-) diff --git a/.agents/skills/docs-visual-review/SKILL.md b/.agents/skills/docs-visual-review/SKILL.md index 50a996f3..3fecc962 100644 --- a/.agents/skills/docs-visual-review/SKILL.md +++ b/.agents/skills/docs-visual-review/SKILL.md @@ -5,104 +5,79 @@ description: Use for docs visual audits, layout, typography, heroes, CSS, naviga # Documentation visual review -Run commands from the OpenShell Research repository root. Read -`docs/development/index.md` and applicable `AGENTS.md` instructions first. -Browser validation is on demand, not a CI gate. Preserve the ordinary renderer, -JavaScript, and clean-build checks; do not add browser runs back to CI. +Run commands from the repository root. Read `docs/development/index.md` and any +applicable `AGENTS.md` instructions before changing the site. -## Choose the scope +## Choose pages and checks -Use `tests/test_dev_notes_layout.py` and its adjacent uv lock rather than writing -another browser harness. It discovers current Dev Notes and covers Chromium and -WebKit, light (`default`) and dark (`slate`) themes, and desktop, tablet, and phone -viewports. Start with tests relevant to the change. Run the full suite when -changing shared layout or when the user requests a comprehensive review. +Review the pages affected by the change and representative pages that share their +styles or templates. Include both `default` and `slate` themes and desktop, +tablet, and phone widths. Check Chromium and WebKit for affected surfaces. -Examples of focused selections with pytest's `-k`: +Use the existing browser suite, `tests/test_dev_notes_layout.py`, for layout and +interaction checks. It discovers current Dev Notes and saves screenshots. Select +relevant tests with pytest's `-k`; run the full suite for a site-wide audit or a +shared layout change. Useful selections include: -- Index hierarchy, title, subtitle, featured card: `index_reading_proportions`. -- Hero or card changes: `post_reading_proportions or featured_image_also_works_as_a_thumbnail`. -- Filters, author links, history, no-JavaScript fallback: `filters or bylines or without_javascript`. -- Breadcrumbs, footer, mobile drawer, tables: `shared_documentation_navigation`. -- Embedded recordings: `embedded_video_playback`. +- Index and featured cards: `index_reading_proportions or featured_image_also_works_as_a_thumbnail`. +- Articles and heroes: `post_reading_proportions`. +- Filters and byline links: `filters or bylines or without_javascript`. +- Shared navigation and search: `shared_documentation_navigation or search_and_saved_navigation`. +- Images, transcripts, or video: select the corresponding test names with `--collect-only -q`. -For a single note, use `--collect-only -q` to find its parametrized test IDs, -then select the relevant filename with `-k`. Keep both browsers, themes, and -screen sizes for final validation of affected surfaces. A quick single-browser -run is useful during iteration but does not establish cross-browser correctness. +For a single article, use `--collect-only -q` to find its parametrized test ID, +then select its filename with `-k`. -## Build and run +## Build and inspect -Build the current sources before testing; browser tests read `site/` and do not -rebuild it: +Build before running browser tests; they read the generated `site/` directory: ```sh scripts/build-docs.sh ``` -Install browsers once per environment, or again if the locked Playwright version -changes. This installs Chromium, WebKit, and their system dependencies: +Install the browsers if they are not already available: ```sh uv run --locked --script tests/test_dev_notes_layout.py --install-browser ``` -For example, check the index across the browser/theme/viewport matrix: +Run focused checks during iteration, then validate the affected surfaces across +the complete browser, theme, and viewport matrix. For example: ```sh uv run --locked --script tests/test_dev_notes_layout.py -q -k index_reading_proportions ``` -For a comprehensive review: +For a site-wide audit: ```sh uv run --locked --script tests/test_dev_notes_layout.py -q ``` -The full suite can take about six minutes. It starts and stops its own local HTTP -server. Screenshots from page-fixture tests are saved to -`.cache/dev-notes-layout/`, with test and parameter names in the filenames. -Inspect files produced by the current run; other screenshots may be stale. -External requests are blocked for deterministic checks, so separately inspect -external avatars or embeds when those are relevant to the task. +The suite serves `site/` locally and writes screenshots to +`.cache/dev-notes-layout/`. Inspect screenshots from the current run; older files +may still be present. The suite blocks external requests, so inspect relevant +external avatars or embeds separately. -## Inspect the rendered result - -Open the relevant screenshots with an available image-viewing tool. Passing -geometry assertions does not establish visual quality or diagram-label -readability. For a visual audit, also serve the complete built site and interact -with the affected pages in an available browser: +Open the affected pages in a browser and interact with them. To serve the built +site manually: ```sh python3 -m http.server 8000 --directory site ``` -Reuse an existing artifact preview when available. On a remote machine, -localhost alone is not a user-accessible preview; report a verified forwarded or -published preview URL if the user needs to view it. - -Judge the result against these established design decisions: - -- The Dev Notes masthead has a prominent serif title and readable subtitle with - breathing room. Divider lines separate filters from the introduction and - posts. The featured note is larger than archive entries; the archive scrolls - naturally rather than shrinking or acquiring its own scroll panel. -- Article titles, subtitles, and complete heroes fit the opening viewport using - shared styles. Heroes preserve their proportions without cropping, stretching, - overflowing figures, or overlapping the byline. Inspect both theme variants - and the full-size asset for detailed diagrams. Author thumbnails stay left; - sidebar post links contain titles only. -- Text columns remain readable, phones have no page-wide horizontal overflow, - tables scroll within the article, and navigation labels do not clip or overlap. -- Exercise category and author combinations, empty results, clear filters, - refresh, Back/Forward, and byline links when filtering changes. Check mobile - navigation and video playback when those surfaces change. - -Fix shared styles, templates, or source metadata rather than hand-editing -renderer-owned HTML or adding per-post sizing overrides. Rebuild after changes -and rerun affected checks. Do not weaken assertions solely to silence failures; -update a constraint only when the requested design has intentionally changed. - -Report the tested pages and scope, browser results, screenshots inspected, and -any unverified surfaces or blocked checks. Do not claim a visual review based -only on passing tests or test collection. +Inspect the rendered pages, not just test results. Check visual hierarchy, +readability, spacing, image detail and proportions, theme contrast, clipping, +overlap, and horizontal overflow. Confirm that tables and navigation work at +narrow widths. On the Dev Notes index, confirm that the featured card is +prominent, the archive scrolls naturally, and category and author filters work +together, clear correctly, and survive refresh and browser history. On articles, +check that the title, subtitle, and complete hero fit the opening viewport, images +keep their proportions, and diagram labels remain legible at full size. Exercise +mobile navigation, search, transcripts, and video where relevant. + +If you make a fix, change the source styles, templates, or metadata, rebuild, +and rerun the affected checks. Report the pages, themes, widths, and browsers +reviewed, the screenshots inspected, and any surfaces or checks you could not +verify. From a75a7c017e9f5cf3d38351b348fcc060ac0d5140 Mon Sep 17 00:00:00 2001 From: Johnny Greco Date: Tue, 29 Sep 2026 20:07:57 +0000 Subject: [PATCH 2/3] docs: include thumbnail check for hero reviews --- .agents/skills/docs-visual-review/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/skills/docs-visual-review/SKILL.md b/.agents/skills/docs-visual-review/SKILL.md index 3fecc962..c138187f 100644 --- a/.agents/skills/docs-visual-review/SKILL.md +++ b/.agents/skills/docs-visual-review/SKILL.md @@ -19,8 +19,8 @@ interaction checks. It discovers current Dev Notes and saves screenshots. Select relevant tests with pytest's `-k`; run the full suite for a site-wide audit or a shared layout change. Useful selections include: -- Index and featured cards: `index_reading_proportions or featured_image_also_works_as_a_thumbnail`. -- Articles and heroes: `post_reading_proportions`. +- Index and featured cards: `index_reading_proportions`. +- Articles and heroes: `post_reading_proportions or featured_image_also_works_as_a_thumbnail`. - Filters and byline links: `filters or bylines or without_javascript`. - Shared navigation and search: `shared_documentation_navigation or search_and_saved_navigation`. - Images, transcripts, or video: select the corresponding test names with `--collect-only -q`. From c81c273ea98d2dfa1544f0aeccce8e7cf0dedd1e Mon Sep 17 00:00:00 2001 From: Johnny Greco Date: Tue, 29 Sep 2026 20:08:52 +0000 Subject: [PATCH 3/3] docs: cover card roles in visual review --- .agents/skills/docs-visual-review/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/docs-visual-review/SKILL.md b/.agents/skills/docs-visual-review/SKILL.md index c138187f..e5f1839d 100644 --- a/.agents/skills/docs-visual-review/SKILL.md +++ b/.agents/skills/docs-visual-review/SKILL.md @@ -19,7 +19,7 @@ interaction checks. It discovers current Dev Notes and saves screenshots. Select relevant tests with pytest's `-k`; run the full suite for a site-wide audit or a shared layout change. Useful selections include: -- Index and featured cards: `index_reading_proportions`. +- Index and featured cards: `index_reading_proportions or featured_image_also_works_as_a_thumbnail`. - Articles and heroes: `post_reading_proportions or featured_image_also_works_as_a_thumbnail`. - Filters and byline links: `filters or bylines or without_javascript`. - Shared navigation and search: `shared_documentation_navigation or search_and_saved_navigation`.