docs(readme): visual refresh — theme-aware SVGs + design system

AGENTS.md

@@ -69,6 +69,15 @@ black aicertify/
 - **Reports are user-facing legal artifacts** — when changing report generation, run the quickstart and inspect the output PDF before claiming success.
 - **Avoid breaking the public API** — anything re-exported from `aicertify/__init__.py` is part of the user-facing contract. Bump the version and note in CHANGELOG.md if you must.
 
+## Diagrams and visual assets
+
+All README diagrams live in [`diagrams/`](diagrams/) as paired **light and dark SVGs**, embedded via `<picture>` for GitHub theme switching. The full design system (palette, type, shape language, naming, contribution flow) is documented in [`diagrams/STYLE.md`](diagrams/STYLE.md). Read it before adding or modifying any diagram.
+
+- **Edit existing diagrams in place** — they are hand-authored SVGs, not generated. Open the file, change it, validate with `python3 -c "import xml.etree.ElementTree as ET; ET.parse('<path>')"`.
+- **Do not reintroduce a matplotlib generator** — the previous `generate_diagrams.py` was deliberately removed. Hand-authored SVGs are the source of truth.
+- **New diagrams must ship both `_light.svg` and `_dark.svg` variants.** Use `<picture>` markup; verify GitHub theme switching by viewing the rendered README on both light and dark settings.
+- **The logo `aicertify/assets/aic.png`** is *not* the README asset — it is bundled into generated PDF reports via [`aicertify/report_generation/report_generator.py`](aicertify/report_generation/report_generator.py). Don't delete it. README assets are the SVGs in `diagrams/`.
+
 ## What NOT to do
 
 - Don't pin new dependencies aggressively — many users will install AICertify alongside their own stack; tight pins create conflicts.

CHANGELOG.md

@@ -7,7 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-_No unreleased changes._
+### Changed
+
+- **Visual refresh** — all README diagrams replaced with hand-authored, theme-aware SVGs in [`diagrams/`](diagrams/). Each diagram now ships as a paired `_light.svg` + `_dark.svg` and is embedded via `<picture>` so GitHub light- and dark-theme readers each see the variant that matches their canvas. The top-of-README logo is replaced with a hero banner SVG. The previous matplotlib generator (`diagrams/generate_diagrams.py`) and 5 baked-in PNG diagrams have been removed in favour of the hand-authored SVG system documented in [`diagrams/STYLE.md`](diagrams/STYLE.md).
+- **OG / social card** — added [`diagrams/og_card.png`](diagrams/og_card.png) (1200×630) for GitHub Settings → Social preview, plus its `_light` / `_dark` SVG sources.
+- **AGENTS.md** — added a "Diagrams and visual assets" section pointing future agents at the new style system.
 
 ## [0.7.0] — 2026-05-14 (first PyPI release)
 
@@ -17,7 +21,7 @@ This is the first AICertify release on PyPI (`pip install aicertify`). It bundle
 
 - **First-party Claude Code skills** under [`skills/`](skills/): `run-compliance-check`, `evaluate-contract`, `explain-regulation`, `draft-policy`. Install with `cp -r skills/* ~/.claude/skills/`.
 - **AGENTS.md and CLAUDE.md** for AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, Copilot, …).
-- **Marketing diagrams** (5 PNG, regenerable via [`diagrams/generate_diagrams.py`](diagrams/generate_diagrams.py)) embedded in the README.
+- **Marketing diagrams** — five PNG diagrams generated by a matplotlib script, embedded in the README. _(Superseded in the next release by hand-authored, theme-aware SVGs; see Unreleased.)_
 - **Translated READMEs** for Simplified Chinese, Japanese, Korean, and Hindi.
 - **SECURITY.md** with a private vulnerability-disclosure flow at `security@principledevolution.ai`.
 - **docs/why-aicertify.md** — long-form positioning doc covering the gap, the shift, the artefact AICertify produces, and the honest scope of what it does not do.

README.hi-IN.md

@@ -1,5 +1,8 @@
 <div align="center">
-  <img src="aicertify/assets/aic.png" alt="AICertify" width="180"/>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/hero_banner_dark.svg">
+    <img src="diagrams/hero_banner_light.svg" alt="AICertify — Compliance-as-code for AI systems" width="100%">
+  </picture>
 </div>
 
 <h1 align="center">AICertify</h1>
@@ -32,7 +35,10 @@
 </p>
 
 <p align="center">
-  <img src="diagrams/diagram1_hero_flow.png" alt="AI ऐप से ऑडिट-तैयार रिपोर्ट तक: AI Application -> AICertify Contract -> OPA Policy Evaluation -> Compliance Report" width="85%" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram1_hero_flow_dark.svg">
+    <img src="diagrams/diagram1_hero_flow_light.svg" alt="AI ऐप से ऑडिट-तैयार रिपोर्ट तक: AI Application -> AICertify Contract -> OPA Policy Evaluation -> Compliance Report" width="85%" />
+  </picture>
 </p>
 
 <br>
@@ -108,10 +114,6 @@ await app.evaluate(regulations=regs, report_format="pdf", output_dir="reports")
 
 AICertify उसी आर्टिफैक्ट के लिए बनाया गया है।
 
-<p align="center">
-  <img src="diagrams/diagram4_comparison.png" alt="AICertify बनाम विकल्प: AICertify एकमात्र ओपन-सोर्स, policy-as-code विकल्प है जिसमें नामित रेगुलेटरी फ्रेमवर्क्स, इंडस्ट्री वर्टिकल्स, और बॉक्स से बाहर ऑडिट-तैयार रिपोर्ट्स हैं" width="85%" />
-</p>
-
 | | AICertify | Fairlearn / AIF360 | MS RAI Toolbox | Credo AI |
 |---|---|---|---|---|
 | ओपन सोर्स | ✅ Apache 2.0 | ✅ MIT | ✅ MIT | ❌ क्लोज़्ड |
@@ -127,7 +129,10 @@ AICertify उसी आर्टिफैक्ट के लिए बनाय
 ## यह कैसे काम करता है
 
 <p align="center">
-  <img src="diagrams/diagram2_architecture.png" alt="AICertify आर्किटेक्चर: आपका AI ऐप एक Contract को फीड करता है, जो Evaluators (Fairness, ContentSafety, RiskManagement, Compliance) के माध्यम से 94 Rego पॉलिसीज़ वाले OPA Engine में जाता है, और Report Generator के द्वारा एक ऑडिट डिलिवरेबल तैयार करता है" width="85%" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram2_architecture_dark.svg">
+    <img src="diagrams/diagram2_architecture_light.svg" alt="AICertify आर्किटेक्चर: आपका AI ऐप एक Contract को फीड करता है, जो Evaluators (Fairness, ContentSafety, RiskManagement, Compliance) के माध्यम से 94 Rego पॉलिसीज़ वाले OPA Engine में जाता है, और Report Generator के द्वारा एक ऑडिट डिलिवरेबल तैयार करता है" width="85%" />
+  </picture>
 </p>
 
 1. **Contract** — आपके AI एप्लिकेशन का एक JSON विवरण: model, version, कैप्चर की गई interactions, metadata।
@@ -142,7 +147,10 @@ AICertify उसी आर्टिफैक्ट के लिए बनाय
 ## रेगुलेटरी कवरेज
 
 <p align="center">
-  <img src="diagrams/diagram3_regulatory_coverage.png" alt="रेगुलेटरी कवरेज: 15+ फ्रेमवर्क्स और 5 इंडस्ट्रीज़ में 94 पॉलिसीज़ -- EU AI Act, NIST AI RMF, India DPDP, Brazil AI Bill, RTCA DO-365/366, FAA Part 107, EASA SORA, ICAO Doc 10019, Healthcare, Banking and Financial Services, Automotive, Education, Global, Aviation, AIOps, Corporate" width="85%" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram3_regulatory_coverage_dark.svg">
+    <img src="diagrams/diagram3_regulatory_coverage_light.svg" alt="रेगुलेटरी कवरेज: 15+ फ्रेमवर्क्स और 5 इंडस्ट्रीज़ में 94 पॉलिसीज़ -- EU AI Act, NIST AI RMF, India DPDP, Brazil AI Bill, RTCA DO-365/366, FAA Part 107, EASA SORA, ICAO Doc 10019, Healthcare, Banking and Financial Services, Automotive, Education, Global, Aviation, AIOps, Corporate" width="85%" />
+  </picture>
 </p>
 
 AICertify [gopal](https://github.com/Principled-Evolution/gopal) पॉलिसी लाइब्रेरी के विरुद्ध चलता है — इन फ्रेमवर्क्स में **94 प्रोडक्शन OPA पॉलिसीज़**:
@@ -198,7 +206,10 @@ python -m aicertify.cli \
 ## सैंपल रिपोर्ट्स
 
 <p align="center">
-  <img src="diagrams/diagram5_report_anatomy.png" alt="एक ऑडिट-तैयार रिपोर्ट की संरचना: फ्रेमवर्क नाम, एप्लिकेशन, मॉडल और दिनांक के साथ हेडर; executive summary; policy results table; risk assessment bar chart; remediation guidance; AICertify v0.7.0 का श्रेय देने वाला फुटर" width="85%" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram5_report_anatomy_dark.svg">
+    <img src="diagrams/diagram5_report_anatomy_light.svg" alt="एक ऑडिट-तैयार रिपोर्ट की संरचना: फ्रेमवर्क नाम, एप्लिकेशन, मॉडल और दिनांक के साथ हेडर; executive summary; policy results table; risk assessment bar chart; remediation guidance; AICertify v0.7.0 का श्रेय देने वाला फुटर" width="85%" />
+  </picture>
 </p>
 
 `examples/outputs/` डायरेक्टरी में वास्तविक मूल्यांकनों से जनरेट की गई रिपोर्ट्स हैं जिन्हें आप कुछ भी चलाने से पहले देख सकते हैं:

README.ja-JP.md

@@ -1,5 +1,8 @@
 <div align="center">
-  <img src="aicertify/assets/aic.png" alt="AICertify" width="180"/>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/hero_banner_dark.svg">
+    <img src="diagrams/hero_banner_light.svg" alt="AICertify — Compliance-as-code for AI systems" width="100%">
+  </picture>
 </div>
 
 <h1 align="center">AICertify</h1>
@@ -32,7 +35,10 @@
 </p>
 
 <p align="center">
-  <img src="diagrams/diagram1_hero_flow.png" alt="AI アプリケーションから監査対応レポートまで: AI アプリケーション → AICertify 契約 → OPA ポリシー評価 → コンプライアンスレポート" width="85%" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram1_hero_flow_dark.svg">
+    <img src="diagrams/diagram1_hero_flow_light.svg" alt="AI アプリケーションから監査対応レポートまで: AI アプリケーション → AICertify 契約 → OPA ポリシー評価 → コンプライアンスレポート" width="85%" />
+  </picture>
 </p>
 
 <br>
@@ -108,10 +114,6 @@ await app.evaluate(regulations=regs, report_format="pdf", output_dir="reports")
 
 AICertify はまさにその成果物のために構築されています。
 
-<p align="center">
-  <img src="diagrams/diagram4_comparison.png" alt="AICertify と代替ツールの比較: AICertify は、名前の付いた規制フレームワーク、業種別ポリシー、監査対応レポートを標準装備した唯一のオープンソース・ポリシー・アズ・コード型ツールです" width="85%" />
-</p>
-
 | | AICertify | Fairlearn / AIF360 | MS RAI Toolbox | Credo AI |
 |---|---|---|---|---|
 | オープンソース | ✅ Apache 2.0 | ✅ MIT | ✅ MIT | ❌ クローズド |
@@ -127,7 +129,10 @@ AICertify はまさにその成果物のために構築されています。
 ## 仕組み
 
 <p align="center">
-  <img src="diagrams/diagram2_architecture.png" alt="AICertify のアーキテクチャ: AI アプリが契約を生成し、評価器 (公平性、コンテンツ安全性、リスク管理、コンプライアンス) を経由して 94 個の Rego ポリシーを持つ OPA エンジンに送られ、レポート生成器が監査成果物を出力" width="85%" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram2_architecture_dark.svg">
+    <img src="diagrams/diagram2_architecture_light.svg" alt="AICertify のアーキテクチャ: AI アプリが契約を生成し、評価器 (公平性、コンテンツ安全性、リスク管理、コンプライアンス) を経由して 94 個の Rego ポリシーを持つ OPA エンジンに送られ、レポート生成器が監査成果物を出力" width="85%" />
+  </picture>
 </p>
 
 1. **契約 (Contract)** — AI アプリケーションを記述した JSON です。モデル、バージョン、収集したやり取り、メタデータを含みます。
@@ -142,7 +147,10 @@ AICertify はまさにその成果物のために構築されています。
 ## 規制カバレッジ
 
 <p align="center">
-  <img src="diagrams/diagram3_regulatory_coverage.png" alt="規制カバレッジ: 15 以上のフレームワークと 5 つの業種にわたる 94 ポリシー -- EU AI Act、NIST AI RMF、インド DPDP、ブラジル AI 法案、RTCA DO-365/366、FAA Part 107、EASA SORA、ICAO Doc 10019、医療、銀行・金融サービス、自動車、教育、グローバル、航空、AIOps、コーポレート" width="85%" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram3_regulatory_coverage_dark.svg">
+    <img src="diagrams/diagram3_regulatory_coverage_light.svg" alt="規制カバレッジ: 15 以上のフレームワークと 5 つの業種にわたる 94 ポリシー -- EU AI Act、NIST AI RMF、インド DPDP、ブラジル AI 法案、RTCA DO-365/366、FAA Part 107、EASA SORA、ICAO Doc 10019、医療、銀行・金融サービス、自動車、教育、グローバル、航空、AIOps、コーポレート" width="85%" />
+  </picture>
 </p>
 
 AICertify は [gopal](https://github.com/Principled-Evolution/gopal) ポリシーライブラリ — **本番運用可能な 94 個の OPA ポリシー** — を用いて、以下のフレームワークに対する評価を実行します。
@@ -198,7 +206,10 @@ Python API の全体像は [`examples/quickstart.py`](examples/quickstart.py) 
 ## サンプルレポート
 
 <p align="center">
-  <img src="diagrams/diagram5_report_anatomy.png" alt="監査対応レポートの構成: フレームワーク名・アプリケーション・モデル・日付を含むヘッダー、エグゼクティブサマリー、ポリシー結果テーブル、リスク評価の棒グラフ、是正ガイダンス、AICertify v0.7.0 を示すフッター" width="85%" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram5_report_anatomy_dark.svg">
+    <img src="diagrams/diagram5_report_anatomy_light.svg" alt="監査対応レポートの構成: フレームワーク名・アプリケーション・モデル・日付を含むヘッダー、エグゼクティブサマリー、ポリシー結果テーブル、リスク評価の棒グラフ、是正ガイダンス、AICertify v0.7.0 を示すフッター" width="85%" />
+  </picture>
 </p>
 
 `examples/outputs/` ディレクトリには、実評価から生成されたレポートが含まれており、実行前に内容を確認できます。