diff --git a/DESIGN_REVIEW.md b/DESIGN_REVIEW.md
new file mode 100644
index 0000000..600ae0f
--- /dev/null
+++ b/DESIGN_REVIEW.md
@@ -0,0 +1,52 @@
+## Quick wins (top 5)
+
+1) Add `rehype-sanitize` (already applied) and remove unnecessary `set:html` usages to prevent XSS and improve content robustness.
+2) Eliminate CDN for Mermaid; use local dependency (already applied) to improve performance, privacy, and CSP compliance.
+3) Optimize hero and large images using `src/components/common/Image.astro` everywhere; enforce `width`/`height` and lazy loading for non-LCP images.
+4) Reduce JS on static pages by avoiding unnecessary client-side logs and inline scripts; prefer islands.
+5) Improve form UX: ensure visible error messages, labels, and aria-live regions are consistent; keep focus management for spam/manual-review flows.
+
+## Issues table
+
+| ID | Page/Component | Problem | Impact | Fix |
+|---|---|---|---|---|
+| D1 | `Hero/Hero2/HeroText` | `set:html` in multiple slots | Med | Potential rendering inconsistencies and sanitization risk | Prefer rendering plain strings or sanitized HTML only |
+| D2 | `Image.astro` usage | Not consistently used across pages | High | LCP/CLS and bandwidth | Replace `` with `Image.astro` wrapper for optimization |
+| D3 | `Footer.astro` | email obfuscation used `innerHTML` | Low | Minor XSS risk | Switched to `textContent` (applied) |
+| D4 | Typography | Some lines exceed 85ch | Low | Readability | Use `max-w-prose` or `ch`-based widths in content wrappers |
+| D5 | Forms | Inline scripts manage state | Med | Maintainability/perf | Extract to small islands if complexity grows |
+
+## Before/After snippets
+
+Replace `set:html` for simple line breaks:
+
+```astro
+
+
{t.sections.overview.whatIs.content}
+ +your-api-host.com
/api/v1
{t.sections.concepts.terminology.headers.term} | +{t.sections.concepts.terminology.headers.description} | +{t.sections.concepts.terminology.headers.example} | +
---|---|---|
{item.term} | +{item.description} | +{item.example} | +
{t.sections.gettingStarted.authentication.description}
+{t.sections.gettingStarted.authentication.headers}
+
+ {t.sections.gettingStarted.firstCall.description}
+{t.sections.gettingStarted.firstCall.code}
+
+ {t.sections.gettingStarted.dynamicDropdowns.explanation}
+ +{t.sections.gettingStarted.dynamicDropdowns.integration.wrongCode}
+ {t.sections.gettingStarted.dynamicDropdowns.integration.correctCode}
+
+ /api/persons?query=dynamicName=="[Full Name]"
+ {t.sections.apiReference.essentialEndpoints.findUsers.purpose}: {t.sections.apiReference.essentialEndpoints.findUsers.purposeText}
+{t.sections.apiReference.essentialEndpoints.findUsers.returns}: {t.sections.apiReference.essentialEndpoints.findUsers.returnsText}
+{endpoint.path}
+ {endpoint.description}
+/api/incidents
+ {t.sections.apiReference.essentialEndpoints.createTicket.purpose}: {t.sections.apiReference.essentialEndpoints.createTicket.purposeText}
+{t.sections.apiReference.essentialEndpoints.createTicket.requires}: {t.sections.apiReference.essentialEndpoints.createTicket.requiresText}
+/api/knowledgeItems/search?query=[search terms]&lang=en&status=active
+ {t.sections.apiReference.essentialEndpoints.searchKnowledgeBase.purpose}: {t.sections.apiReference.essentialEndpoints.searchKnowledgeBase.purposeText}
+{t.sections.contact.team}: {t.sections.contact.teamName}
+{t.sections.contact.email}: support@example.com
+{t.sections.contact.website}: www.example.com
+{t.sections.contact.supportText}
+