docs(readme): visual refresh — theme-aware SVGs + design system#61
Merged
Conversation
Convert all README diagrams from baked-in PNGs to hand-authored, theme-aware SVGs paired as _light.svg + _dark.svg and embedded via <picture>, so GitHub light-theme and dark-theme readers each see the variant that matches their canvas. The top-of-README aic.png logo is replaced with a hero banner SVG containing the logo, wordmark, tagline, and framework chips. Diagram 4 (comparison) is removed across all 5 READMEs — the markdown comparison table that lived directly under it is now the single source of truth. The matplotlib generator (generate_diagrams.py, ~1000 lines) is retired in favour of the hand-authored SVG system. All 5 READMEs (en, zh-CN, ja-JP, ko-KR, hi-IN) are updated in lockstep. Resolves the design review finding that PNG diagrams with baked-in colors render poorly on GitHub's dark theme.
Establish the visual system as a documented, contributable asset rather
than tribal knowledge:
- diagrams/STYLE.md — palette, type, shape language, light/dark pattern,
naming, and the contribution flow for new diagrams. Hand-authored SVG
only; no automated generator.
- diagrams/logo_{light,dark}.svg — standalone square mark extracted
from the hero banner, for favicons, GitHub avatar, sidebar contexts.
- diagrams/og_card_{light,dark}.svg + og_card.png — 1200×630 social
preview card. PNG must be uploaded via GitHub Settings → General →
Social preview; it cannot be set automatically.
- AGENTS.md — new "Diagrams and visual assets" section pointing future
agents at STYLE.md and explicitly retiring the matplotlib generator.
- CHANGELOG.md — Unreleased section documents the visual refresh; the
v0.7.0 entry is updated to historically-honest prose without the now-
broken link to the deleted generator script.
github-actions
Bot
added
📝 documentation
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replace all README marketing diagrams with hand-authored, theme-aware SVGs paired as
_light.svg+_dark.svgand embedded via<picture>. GitHub light- and dark-theme readers each see the variant that matches their canvas — the previous PNGs with baked-in colors rendered poorly on dark mode.Two commits, separable for clean revert:
chore(diagrams)— the asset swap: 10 paired diagram SVGs, hero banner replacesaic.pngat the top of all 5 READMEs (en + zh-CN + ja-JP + ko-KR + hi-IN), comparison diagram (diagram 4) deleted in favour of the markdown table that lived next to it,generate_diagrams.pymatplotlib generator retired.docs(diagrams)— the design system:diagrams/STYLE.md(palette, type, shape language, light/dark pattern), standalonelogo_{light,dark}.svgfor favicons / avatar,og_card_{light,dark}.svg+ 68 KBog_card.pngfor GitHub Social Preview upload, AGENTS.md guidance for future agents, CHANGELOG.md updated.aicertify/assets/aic.pngis intentionally kept — it is embedded inside generated PDF reports, not the README.Test plan
diagram*.pngorgenerate_diagrams.pyreferences anywhere in the repo<picture>markup patterndiagrams/og_card.pngvia Settings → General → Social preview