readme-flow-svg
Animated SVG workflows for GitHub READMEs, made in your browser.
Open the editor · Examples · Report a bug
This demo was generated with the project's own generate_workflow tool. No account, subscription, tracking, or analytics.
Quick start
- Open the editor and choose a preset or gallery example.
- Edit the steps, icons, and appearance. The preview updates as you work.
- Copy Markdown for a hosted image, or download
workflow.svg and choose File in your repo.
For a hosted image, paste a URL directly:
The editor runs entirely in your browser, including SVG downloads. Hosted images use the existing public SVG service and include the workflow settings in their URL. Optional Google Fonts requests send the font family and weight, without workflow text. Built-in fonts and downloaded SVGs work offline. Settings are saved on your device.
Features
- Three to twelve steps, with stage icons, titles, and subtitles.
- Horizontal, vertical, snake, and grid layouts; drag cards or move them with the keyboard.
- Undo/redo, alignment, distribution, canvas fitting, and layout reset.
- Labeled branches, merges, loops, and configurable connection styles.
- Six SVG palettes, custom colors, and eight moving elements.
- Self-contained SVGs with CSS animation and reduced-motion support.
- Hosted embeds, local downloads, editable links, and Markdown alt text.
- JSON import/export for reusable workflows, and light/dark README picture snippets.
- Plain images or links to your documentation, this workflow's editor, or the project repository.
- A responsive editor with system, light, and dark page appearance.
- REST and MCP interfaces using the same renderer as the editor.
Page appearance is independent of SVG appearance. Animation follows connection order; it does not simulate concurrent execution.
Use Export JSON to save workflow.json alongside workflow.svg. Import JSON restores
the steps, icons, connections, manual positions, colors, and font settings. Files stay in your
browser; imports accept workflow configurations up to 16 KB. You can undo an import or reset.
The preview supports Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z (or Ctrl+Y). Text fields keep their native
undo behavior. Arrange cards aligns or distributes all cards; alignment separates cards
along the other axis to prevent overlap. Fit canvas to cards trims excess space, and
Reset positions returns to the selected automatic layout.
Light / dark README generates a <picture> snippet using the built-in Light and Dark
palettes. It keeps the same labels, layout, connections, and font in both versions.
URL parameters
Image links use /svg; editor links use /? with the same parameters. Existing formats are unchanged.
| Parameter | Example | Meaning |
|---|
steps | Upload;Validate;Download | 3–12 labels; JSON arrays also accepted |
preset | deploy | Starting workflow |
theme | github | SVG palette |
traveler | file | Moving element |
duration | 8 | Complete loop, 2–30 seconds |
layout | snake | Horizontal, vertical, snake, or grid |
columns | 3 | 2–6 columns in a wrapped layout |
title | Release%20pipeline | Optional heading |
Use the editor to encode punctuation, custom connections, and palettes correctly. Full parameter reference · Supported options
Run locally
Open the checked-in index.html directly, or use Node.js 22+:
npm ci
npm run build
npm run dev
Visit http://127.0.0.1:4173. Rebuild after changing source files. The editor uses vanilla JavaScript and CSS; server dependencies are kept out of the static editor except the browser font engine.
npm run lint
npm run type-check
npm run format:check
npm test
npm run build
npm run build:api
npx playwright install chromium
npm run test:browser
npm run benchmark
Development, deployment, and AI/MCP setup · Architecture
FAQ
Does animation work in GitHub READMEs? Yes. Embed the SVG as an image; its CSS animation is self-contained. GitHub caches external images, so hosted changes may not appear immediately.
Hosted or in-repo? Hosted images are ready to paste. A checked-in SVG is versioned with your project and needs no image service. Shared URLs are public configuration, so keep secrets out of labels.
Reduced motion? Generated SVGs include prefers-reduced-motion. The preview pause button affects only the editor, not downloads.
File size? It depends on the number of steps and connections. Check the example files; outlined Google Fonts can increase size substantially.
Why not Mermaid or a GIF? Mermaid is useful for text-maintained diagrams. This tool makes small animated workflows with a visual editor. SVG stays sharp when resized; GIF stores raster frames.
Is data sent to a server? Editing and downloading run in your browser. Hosted embeds send settings in the image URL. The editor loads interface fonts from Google; optional workflow fonts go through our font endpoint. There are no accounts or analytics. Read the privacy policy for browser storage, hosting logs, and contact details.
Projects using it
Add your public repository through community/repos.json. Submission guide.
Contributing
Bug reports, documentation fixes, presets, and accessibility improvements are welcome. Read CONTRIBUTING.md, Code of Conduct, and security reporting. Keep generated SVGs self-contained and preserve existing URL behavior.
Roadmap
These are ideas, not delivery commitments:
- Broader keyboard, mobile, and screen-reader regression coverage.
- More real-project workflows contributed by the community.
- Export size feedback and clearer font-loading feedback.
- Expand incremental JavaScript type checking across legacy modules.
See CHANGELOG.md for changes and launch TODOs for repository sharing suggestions.
License and credits
MIT. Icons adapted from Tabler Icons; see third-party notices. Inspired by Readme Typing SVG and archgram.
