Skip to content

docs: give the README figures a dark counterpart - #435

Merged
suguanYang merged 3 commits into
mainfrom
docs/wangbinqi/readme-theme-images
Sep 23, 2026
Merged

suguanYang merged 3 commits into
mainfrom
docs/wangbinqi/readme-theme-images

Conversation

@suguanYang

@suguanYang suguanYang commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • The README now serves light and dark artwork through <picture> elements with
    prefers-color-scheme, so dark-mode readers no longer get white canvases and the
    switch needs no CSS.
  • Figures covered: the top banner, the parsing and retrieval diagrams, and the
    benchmark grid.
  • The banner is centered like the rest of the header, and it carries the headline
    itself: the h1 below it repeated the words already drawn inside the artwork, so
    the h1 is gone and the wording lives on in the banner alt text.
  • The banner no longer carries a height attribute. GitHub's markdown CSS sets
    max-width: 100% but never height: auto, so the attribute kept the box at
    500px while the width shrank to the README column, stretching the artwork and its
    headline by 30%.
  • Adds the benchmark SVG sources under docs/assets/source/, with the palette
    mapping and the render recipe documented next to them.
  • Removes the four figures the current README no longer references.
  • Documentation only: no API, worker, deployment, or migration impact.

Verification

  • Banner scale: reproduced GitHub's rule locally at a 768px column.
    width="1000" height="500" renders 768x500 (ratio 1.536 against the natural
    2.000); width="1000" alone renders 768x384 (ratio 2.000). A template match
    against the artwork in a live page screenshot agreed with the stretched case
    (0.48 horizontal scale, 0.58 vertical), so the attribute is dropped and every
    image in the file now sets width only.
  • Banner content: the light and dark exports OCR to the same lockup and
    headline; the alt text carries the headline that used to be the h1.
  • Benchmark light: rendered from the design SVG at 1600x1120 with
    --force-device-scale-factor=2 (headless Chromium), which yields 3200x2240.
    Compared against the design export: edge correlation 0.79 with mean absolute
    pixel difference 1.26 (the design export is JPEG), and identical OCR values for
    all six metrics.
  • Benchmark dark: derived from the same SVG by remapping six color literals;
    geometry, labels, and numbers are untouched. Color-region pixel counts match the
    light render within 0.7% (background 6,342,136 vs 6,343,012; bars 484,352 vs
    484,288; accent 136,273 vs 136,170; ink 82,545 vs 82,007), the edge correlation
    between the two renders is 0.9963, and every label still OCRs on the dark render.
    Text contrast stays at or above 4.5:1 (primary 17.8:1, secondary 5.5:1, accent
    6.7:1).
  • Every local asset referenced by README.md resolves, no script or workflow reads
    the removed h1, and git diff --check is clean.
  • Not tested here: the rendered README on github.com, which needs this PR's
    preview.

Deployment Notes

  • No environment variables, migrations, queue, or storage changes.
  • Image URLs change: knowhere-banner.png and benchmark.png are gone. External
    pages that hot-link those two paths would break; the self-hosted and dashboard
    repos were checked and do not reference them.
  • Rollback is reverting the commit; the removed images stay in git history.

Checklist

  • Tests were added or updated when behavior changed
  • Public docs, examples, or OpenAPI contracts were updated when needed
  • Database migrations are idempotent and safe to deploy
  • Logs, errors, and validation paths avoid leaking secrets or user data
  • The pull request description explains any breaking or user-visible change

GitHub dark mode painted every figure on a white canvas: the banner, the parsing and retrieval diagrams, and the benchmark grid. Each figure now ships a light and a dark file selected by a <picture> element with prefers-color-scheme, so the switch needs no CSS.

- Banner: the light and dark hero exports replace knowhere-banner.png.
- Parsing and retrieval: refreshed from the new 01/02 designs. Those designs ship light only, so the two diagrams stay single-variant for now.
- Benchmark: re-rendered from the design SVG at 1600x1120 with a 2x device scale. The dark variant comes from the same SVG with color literals remapped and geometry untouched, holding each element relative contrast (bars 1.56:1 to 1.89:1, grid 1.30:1 to 1.56:1, text at or above 4.5:1).
- Sources: both benchmark SVGs live in docs/assets/source/ with the palette mapping and the render recipe.
- Dropped the four figures the README no longer references.

Text in the benchmark SVG is exported as glyph paths, so future metric changes belong in the generating script, not in the SVG.
The banner sat at the left edge while the headline, badges, links, and every figure are centered, because it was the only image in the file without a centering wrapper. Wrap it in the same <p align="center"> the other figures use.
The new hero banner already renders "Prepare unstructured data for AI agents", so the h1 directly below it repeated the same sentence inside the first screen. Drop the h1 and keep the wording in the banner alt text, where screen readers and search still pick it up.
@suguanYang
suguanYang merged commit f252703 into main Sep 23, 2026
6 checks passed
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