A new visitor may understand a project faster when the repository gives them a clear picture of how it fits together. A few well-chosen visuals can explain an architecture, spotlight the code worth noticing, or show what the finished feature does. The goal is useful context: each image or recording should answer a question that would otherwise take a paragraph or a local setup to resolve.
| If readers need to… | Try… | Useful README output |
|---|---|---|
| Understand components or a user flow | Excalidraw or Mermaid Live Editor | Architecture or flow diagram |
| Inspect a small, important code sample | Carbon or Ray.so | Focused code image, with the text version nearby |
| See a feature in action | Loom | Short linked or embedded walkthrough |
1. Excalidraw for sketches and system maps
Excalidraw is a virtual whiteboard for hand-drawn-style diagrams and wireframes. Its open-source project documents exports to PNG, SVG, and the clipboard, along with an editable .excalidraw format. The hosted editor also supports collaborative editing and read-only share links.
Use it when a project needs a quick visual explanation before every box, boundary, or dependency has settled into a formal architecture diagram. A sketch can show how a Flutter client talks to an API, where authentication happens, or which external services a small app relies on. Add the exported image to the README and keep the editable drawing in the repository if you expect the system to change.
One practical note: an image alone can be hard to revise or interpret later. Include a short caption and keep the source drawing alongside the exported asset when that diagram is part of the project documentation.
Official links: Excalidraw editor · Excalidraw project and export details
2. Mermaid Live Editor for diagrams that stay in text
Mermaid Live Editor turns Mermaid syntax into a rendered diagram. Write or edit the diagram code in one panel and see the preview update in the other. Mermaid supports flowcharts, sequence diagrams, class diagrams, entity-relationship diagrams, and other diagram types; the Live Editor includes export options for diagram output.
Choose Mermaid when a diagram belongs with the code and needs to stay easy to diff. A small service flow, request sequence, or database relationship map can live as Mermaid text in the repository, then render in supported Markdown environments. It is especially handy for software architecture diagrams that change as a codebase evolves.
Check where the README will be rendered before relying on an embedded Mermaid block. If the host does not render Mermaid, export the diagram as an image and link to the source text so contributors can still update it.
Official links: Mermaid Live Editor · Mermaid getting started guide
3. Carbon for a code screenshot generator
Carbon creates images from pasted code or a dropped file. Its editor lets you adjust the syntax theme, background, window appearance, and padding; the documented export options include PNG and SVG. It can also save a snippet or copy an image to the clipboard.
Use Carbon when a short code excerpt deserves emphasis in a project announcement, portfolio entry, or README. For example, show the reducer or API call that demonstrates the design idea behind the project, rather than capturing an entire editor window. A clean image gives the snippet a consistent presentation without distracting panes or personal desktop details.
Code images are not searchable or copyable like text. Put the same snippet in a fenced code block nearby, or link to the relevant source file. That keeps the example accessible and useful to someone who wants to reuse it.
Official links: Carbon editor · Carbon features and export options
4. Ray.so for quick, styled code images
Ray.so is a code-image tool from Raycast. Its current site identifies the Code Images tool and offers an export action; the public project repository describes Ray.so as a set of tools that includes creating images of code.
Reach for it when you want to turn one compact example into a shareable visual for a README, portfolio card, or project update. It works well for a highlighted function, a configuration example, or a before-and-after excerpt. Treat the image as a presentation layer: the actual code should remain available as text in the repository or on the page.
The public feature details are concise, so check the current editor for the controls available to your workflow instead of assuming a particular theme or customization option. Keep the example short enough to remain readable at the size where it will appear.
Official links: Ray.so · Raycast’s Ray.so repository
5. Loom for a feature walkthrough
Loom records and shares screen and camera videos. Its Chrome screen recorder page describes quick recording, links generated for sharing, and recording up to 1080p through the extension. Loom also offers desktop and mobile apps; the Chrome page points to its desktop app for 4K recording.
Use a short screen recording when a static screenshot cannot show the interaction: a filter changing results, a Flutter app moving through a flow, or a dashboard updating after an action. For a public project, record a focused walkthrough without private data, then place the link or an embed near the relevant README section.
A video is a hosted dependency, and visibility depends on its sharing settings. Verify the link in a logged-out browser before publishing, and provide a still image or text summary so the project remains understandable if the recording is unavailable.
Official links: Loom · Loom Chrome Screen Recorder
A simple three-part workflow
Start with the question a new reader is likely to have. Draw the system’s main components in Excalidraw, or keep a frequently updated flow in Mermaid text. Export or render that diagram and write a one-sentence caption explaining what the reader should notice.
Next, choose one small code excerpt that proves how a central piece works. Create a code image with Carbon or Ray.so, but include the source as selectable text or link directly to the file. Finish with a short Loom walkthrough if behavior is easier to see than to describe. Link the recording from a labeled thumbnail or a “See the feature in action” line.
This gives a project page three distinct kinds of context: structure, implementation, and behavior. Each visual has a job, and the README still works for readers who skip images or cannot play video.
README visual checklist
- Does each visual answer a specific question about the project?
- Is the architecture or flow diagram current, labeled, and readable at normal screen width?
- Is a code image accompanied by selectable code or a source link?
- Does a demo recording avoid credentials, private data, and unrelated setup steps?
- Does every image have descriptive alt text, and does every video have a useful text summary?
- Do external links and hosted media still resolve?
The most useful README visual is the one that saves a reader from guessing. Start with the diagram that clarifies the system, add a code image only when it adds emphasis, and record a demo when motion is part of the explanation. For more practical developer resources, see our developer websites worth bookmarking and learn about custom software development.