Cloud icons in a README: sharp, readable in dark mode, and never stale

GitHub renders README content in a column around 900 pixels wide on a desktop browser. On a high-density display, that column is painted with roughly twice as many device pixels, so an image exported at 900 pixels is being asked to cover 1800 and looks soft. Export at 1800 pixels wide or more and the problem disappears.

The same number covers most other destinations. A Confluence page body and a Notion column are both narrower than a GitHub README, so a single 1800 pixel export serves all three. Going much beyond 2400 buys nothing except a slower page.

Icon sharpness inside the image follows from the same maths. If the source icons are vector, an 1800 pixel export renders them crisply at any node size. If somebody built the diagram from 32 pixel rasters, no export width will rescue them, which is where the SVG or PNG decision actually gets made.

A PNG with a transparent background and dark grey text looks correct in the editor and disappears against GitHub dark theme. It is the most common README diagram bug and it is invisible to the person who shipped it, because they read their own repository in light mode.

The reliable fix is an explicit background. Give the diagram a solid light background so it renders as a light card on a dark page, which every reader can see. It looks deliberate rather than broken, and it needs one file rather than two.

GitHub does support per-theme images through a picture element with prefers-color-scheme media attributes, and it works well. The cost is that you now have two exports to keep current, and the second one is the one that gets forgotten. Take that route only if the diagram is a permanent centrepiece.

## Architecture

![Platform architecture](PASTE_LIVE_EMBED_URL_HERE)

<!-- The embed URL comes from the project share panel.
     The image re-renders from the canvas, so this line
     stays correct after the architecture changes. -->

A blurry diagram is annoying. A confidently wrong diagram sends a new contributor down a path that no longer exists, and it is worse than no diagram, because it carries the authority of being committed to the repository.

A live embed is one markdown image line whose image follows the canvas, and viewers need no account to see it. Update the diagram and every README, wiki page and Notion doc that references it updates with it. There is no export to redo and no binary to re-commit, which also keeps diagram churn out of the diff.

For repositories where the architecture is declared in code, repository sync closes the loop: connect the repository read-only on GitHub, GitLab or Azure DevOps, pick a branch or a tag, and the diagram plus an architecture document regenerate on a daily sync.

The reason that does not turn into daily churn is worth stating precisely, because "regenerates daily" usually means "moves daily". Each sync hashes the parsed draw plan rather than the commit. A commit that touches a README, a test or a comment changes the sha and leaves that fingerprint identical, and a sync with an identical fingerprint skips generation entirely: no redraw, no tokens spent. When the structure genuinely did change, the previous diagram's node ids, labels and zones are handed back to the generator so one new consumer reads as one new node rather than a new composition. And any node somebody dragged more than twelve pixels from where the last sync left it keeps the coordinates they gave it. A README image that only moves when the architecture moves is the difference between a diagram people trust and one they stop looking at.

In a deck you get to narrate. In a README nobody is talking, so recognition has to happen from the image alone. Official service marks let a reader identify a managed Postgres, a queue and an object store without reading a single label, which is the difference between twenty seconds spent understanding the system and twenty seconds spent parsing boxes.

That is also why a README diagram should use the marks the reader already knows rather than a house icon style. The library behind the generator covers 439 AWS, 624 Azure and 226 Google Cloud icons alongside 373 tech-stack marks and 32 data tooling marks, so the ordinary README stack of a web service, a Postgres, a Redis and a Kafka is drawn with the logos a contributor already recognises rather than four identical rectangles.

• Live embeds: diagrams that update in place
• Embed diagrams in a GitHub README
• Embed diagrams in markdown
• Repo to diagram: repository sync
• SVG or PNG for architecture diagrams