docs: visual refresh — theme-aware SVGs + design system + contributing/security#15
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. Adds a hero banner SVG at the top of all 5 READMEs containing the wordmark, tagline, and framework chips. Diagram 4 (framework_grid) is removed across all 5 READMEs — the markdown comparison table directly under it already covers the same content. The matplotlib generator (generate_diagrams.py, ~700 lines) is retired in favour of the hand-authored SVG system. All 5 READMEs (en, zh-CN, ja-JP, ko-KR, hi-IN) updated in lockstep. Resolves the design-review finding that PNG diagrams with baked-in colors render poorly on GitHub's dark theme. Mirrors the visual refresh shipped to the sister project AICertify.
Establish the visual system as a documented, contributable asset:
- diagrams/STYLE.md — palette, type, shape language, light/dark
pattern, naming, and the contribution flow for new diagrams. Shared
with sister project AICertify so the two repos visually echo each
other. Hand-authored SVG only; no automated generator.
- diagrams/logo_{light,dark}.svg — standalone square mark, the hexagon
+ {} curly braces signalling "policy as code". Distinct from
AICertify's hexagon + checkmark but in the same family.
- 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 now documents the visual refresh,
brand assets, and removed generator.
Two doc additions that the repo has been missing: - CONTRIBUTING.md — policy-authoring conventions (package paths, default deny, METADATA blocks, report composition), the local-checks recipe (opa check + regal lint + tests), PR review criteria, and a step-by-step "adding a new framework" guide. Resolves the broken link the README has been carrying in all 5 language variants. - SECURITY.md — private vulnerability-disclosure flow at security@principledevolution.ai, 5-business-day acknowledgement, coordinated disclosure. Explicitly separates security issues (CI workflows, supply chain, helper_functions bugs) from policy- correctness disputes (which are public discussions, not embargoed vulnerabilities).
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
Apply the same viral-ready treatment to gopal that AICertify just received. Three logical commits, one bundled PR, easy to revert individually if needed.
1.`. Add a hero banner SVG at the top of all 5 READMEs (the repo previously had no top-of-README image). Delete diagram 4 (framework_grid) — the markdown comparison table directly under it already covers the same content. Retire the matplotlib generator.
chore(diagrams)— replace 5 baked-in-color PNGs with 10 paired light/dark SVGs embedded via `2.
docs(diagrams)— establish the design system: `diagrams/STYLE.md` (palette, type, shape language, light/dark pattern), standalone `logo_{light,dark}.svg` (hexagon + `{}` curly braces), and a 1200×630 OG card for GitHub Social Preview upload. Add an AGENTS.md section so future agents follow the system. CHANGELOG updated.3. `docs` — write `CONTRIBUTING.md` (was a broken link in all 5 READMEs!) and `SECURITY.md` (private disclosure flow at security@principledevolution.ai).
Plus repo-metadata polish: description set, 16 GitHub topics added (ai-governance, opa, rego, eu-ai-act, nist-ai-rmf, faa, easa, icao, ferpa, fair-lending, …).
The design system is intentionally shared with AICertify — the two repos visually echo each other while staying distinct (AICertify = hexagon + check; gopal = hexagon + braces).
Test plan