diff --git a/docs/assets/custom.css b/docs/assets/custom.css
index a4717786..8cd61541 100644
--- a/docs/assets/custom.css
+++ b/docs/assets/custom.css
@@ -1,13 +1,135 @@
 /* ============================================================
-   TABLE — row & cell hover highlighting
+   SEMANTICA DOCS — PREMIUM DESIGN SYSTEM
+   Dark-first (#080C10 bg, #10B981 emerald accent)
    ============================================================ */
+
+/* ── Keyframes ─────────────────────────────────────────────── */
+@keyframes pageFadeIn {
+  from { opacity: 0; transform: translateY(6px); }
+  to   { opacity: 1; transform: translateY(0);   }
+}
+
+/* ── Global ─────────────────────────────────────────────────── */
+html {
+  scroll-behavior: smooth;
+}
+
+/* Custom text selection */
+::selection {
+  background: rgba(16, 185, 129, 0.22);
+  color: #fff;
+}
+
+/* Custom scrollbar */
+::-webkit-scrollbar        { width: 5px; height: 5px; }
+::-webkit-scrollbar-track  { background: transparent; }
+::-webkit-scrollbar-thumb  {
+  background: rgba(16, 185, 129, 0.2);
+  border-radius: 4px;
+}
+::-webkit-scrollbar-thumb:hover { background: rgba(16, 185, 129, 0.4); }
+
+/* ── Page entrance ──────────────────────────────────────────── */
+main,
+article,
+[class*="content-area"],
+[class*="ContentArea"],
+[class*="prose"] {
+  animation: pageFadeIn 0.35s ease both;
+}
+
+/* ── Focus rings ─────────────────────────────────────────────── */
+*:focus-visible {
+  outline: 2px solid rgba(16, 185, 129, 0.55) !important;
+  outline-offset: 3px !important;
+  border-radius: 4px !important;
+}
+
+/* ── Headings ───────────────────────────────────────────────── */
+h1 {
+  letter-spacing: -0.025em;
+  position: relative;
+  padding-bottom: 0.6rem;
+}
+
+h1::after {
+  content: "";
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  width: 44px;
+  height: 2px;
+  background: linear-gradient(90deg, #10B981 0%, transparent 100%);
+  border-radius: 1px;
+}
+
+h2 { letter-spacing: -0.018em; }
+h3 { letter-spacing: -0.012em; }
+
+/* ── Content links ──────────────────────────────────────────── */
+article a,
+[class*="prose"] a {
+  text-decoration-color: rgba(16, 185, 129, 0.35);
+  text-underline-offset: 3px;
+  transition:
+    text-decoration-color 0.15s ease,
+    color                 0.15s ease;
+}
+
+article a:hover,
+[class*="prose"] a:hover {
+  text-decoration-color: #10B981;
+}
+
+/* ── Blockquote ─────────────────────────────────────────────── */
+blockquote {
+  border-left: 2px solid rgba(16, 185, 129, 0.35) !important;
+  background: rgba(16, 185, 129, 0.04) !important;
+  border-radius: 0 6px 6px 0 !important;
+  padding: 0.9rem 1.2rem !important;
+  font-style: italic;
+  color: rgba(255, 255, 255, 0.68) !important;
+  transition:
+    border-color     0.2s ease,
+    background-color 0.2s ease !important;
+}
+
+blockquote:hover {
+  border-left-color: rgba(16, 185, 129, 0.65) !important;
+  background: rgba(16, 185, 129, 0.07) !important;
+}
+
+/* ── HR / Divider ────────────────────────────────────────────── */
+hr {
+  border: none !important;
+  height: 1px !important;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    rgba(16, 185, 129, 0.25) 25%,
+    rgba(16, 185, 129, 0.25) 75%,
+    transparent 100%
+  ) !important;
+  margin: 2.5rem 0 !important;
+}
+
+/* ── TABLE ───────────────────────────────────────────────────── */
+table thead th {
+  color: #10B981 !important;
+  font-weight: 600 !important;
+  letter-spacing: 0.04em !important;
+  font-size: 0.72rem !important;
+  text-transform: uppercase !important;
+  border-bottom: 1px solid rgba(16, 185, 129, 0.18) !important;
+}
+
 table tbody tr {
   transition: background-color 0.15s ease;
   cursor: default;
 }
 
 table tbody tr:hover {
-  background-color: rgba(16, 185, 129, 0.07) !important;
+  background-color: rgba(16, 185, 129, 0.06) !important;
 }
 
 table tbody tr:hover td {
@@ -19,65 +141,66 @@ table th {
   transition: background-color 0.15s ease;
 }
 
-/* ============================================================
-   CODE BLOCKS — glow on hover
-   ============================================================ */
+/* ── CODE BLOCKS ─────────────────────────────────────────────── */
 pre,
 [class*="codeblock"],
 [class*="code-group"],
 [class*="CodeBlock"],
 [data-rehype-pretty-code-fragment] {
-  transition: box-shadow 0.2s ease, border-color 0.2s ease !important;
+  transition:
+    box-shadow   0.22s ease,
+    border-color 0.22s ease !important;
 }
 
 pre:hover,
 [class*="codeblock"]:hover,
 [class*="CodeBlock"]:hover,
 [data-rehype-pretty-code-fragment]:hover {
-  box-shadow: 0 0 0 1.5px rgba(16, 185, 129, 0.35),
-              0 4px 24px rgba(16, 185, 129, 0.09) !important;
+  box-shadow:
+    0 0 0 1px rgba(16, 185, 129, 0.28),
+    0 4px 24px rgba(16, 185, 129, 0.09) !important;
+  border-color: rgba(16, 185, 129, 0.28) !important;
 }
 
-/* ============================================================
-   CARDS — lift + glow on hover
-   ============================================================ */
+/* ── CARDS ───────────────────────────────────────────────────── */
 [class*="card"],
 [class*="Card"],
 [data-card],
 .group\/card {
-  transition: transform 0.2s ease,
-              box-shadow 0.2s ease,
-              border-color 0.2s ease !important;
+  transition:
+    transform    0.22s ease,
+    box-shadow   0.22s ease,
+    border-color 0.22s ease !important;
 }
 
 [class*="card"]:hover,
 [class*="Card"]:hover,
 [data-card]:hover,
 .group\/card:hover {
-  transform: translateY(-2px) !important;
-  box-shadow: 0 8px 32px rgba(16, 185, 129, 0.13),
-              0 0 0 1px rgba(16, 185, 129, 0.28) !important;
+  transform: translateY(-3px) !important;
+  box-shadow:
+    0 8px 28px rgba(0, 0, 0, 0.18),
+    0 0 0 1px rgba(16, 185, 129, 0.22) !important;
+  border-color: rgba(16, 185, 129, 0.28) !important;
 }
 
-/* ============================================================
-   CALLOUTS / NOTES / TIPS — subtle left-border highlight
-   ============================================================ */
+/* ── CALLOUTS / ADMONITIONS ──────────────────────────────────── */
 [class*="callout"],
 [class*="Callout"],
 [class*="admonition"] {
-  transition: box-shadow 0.2s ease !important;
+  transition:
+    box-shadow   0.2s ease,
+    border-color 0.2s ease !important;
 }
 
 [class*="callout"]:hover,
 [class*="Callout"]:hover,
 [class*="admonition"]:hover {
-  box-shadow: inset 3px 0 0 rgba(16, 185, 129, 0.55),
-              0 2px 12px rgba(16, 185, 129, 0.06) !important;
+  box-shadow: 0 2px 16px rgba(16, 185, 129, 0.08) !important;
+  border-color: rgba(16, 185, 129, 0.35) !important;
 }
 
-/* ============================================================
-   STEPS — highlight active step on hover
-   ============================================================ */
+/* ── STEPS ───────────────────────────────────────────────────── */
 [class*="step"],
 [class*="Step"] {
   transition: background-color 0.15s ease !important;
@@ -88,71 +211,77 @@ pre:hover,
   background-color: rgba(16, 185, 129, 0.04) !important;
 }
 
-/* ============================================================
-   INLINE CODE — subtle green tint on hover
-   ============================================================ */
+/* ── INLINE CODE ─────────────────────────────────────────────── */
 :not(pre) > code {
-  transition: background-color 0.15s ease, color 0.15s ease !important;
+  transition:
+    background-color 0.15s ease,
+    color            0.15s ease !important;
   cursor: text;
 }
 
 :not(pre) > code:hover {
-  background-color: rgba(16, 185, 129, 0.15) !important;
+  background-color: rgba(16, 185, 129, 0.16) !important;
 }
 
-/* ============================================================
-   NAV / SIDEBAR LINKS — subtle hover underline accent
-   ============================================================ */
+/* ── NAVIGATION / SIDEBAR ────────────────────────────────────── */
 nav a,
 [class*="sidebar"] a,
 [class*="Sidebar"] a {
   transition: color 0.15s ease !important;
+  text-decoration: none;
+  position: relative;
 }
 
-/* ============================================================
-   BULLET POINTS — cursor-animated hover (premium feel)
-   ============================================================ */
+nav a::after,
+[class*="sidebar"] a::after,
+[class*="Sidebar"] a::after {
+  content: "";
+  position: absolute;
+  bottom: -1px;
+  left: 0;
+  width: 0;
+  height: 1px;
+  background: #10B981;
+  transition: width 0.2s ease;
+}
+
+nav a:hover::after,
+[class*="sidebar"] a:hover::after,
+[class*="Sidebar"] a:hover::after {
+  width: 100%;
+}
+
+/* ── TEXT / LIST ITEMS ───────────────────────────────────────── */
 ul > li,
 ol > li {
-  position: relative;
-  transition:
-    background-color 0.18s ease,
-    box-shadow 0.18s ease,
-    color 0.15s ease;
-  border-radius: 4px;
-  cursor: default;
+  border-radius: 3px;
+  transition: background-color 0.12s ease;
 }
 
 ul > li:hover,
 ol > li:hover {
-  background-color: rgba(16, 185, 129, 0.06);
-  box-shadow: inset 3px 0 0 #10B981;
-  color: rgba(255, 255, 255, 0.95);
-}
-
-/* Animate the bullet marker green on hover */
-ul > li:hover::marker,
-ol > li:hover::marker {
-  color: #10B981;
-}
-
-/* Slide-in left accent bar for nested lists */
-ul > li > ul > li:hover,
-ol > li > ul > li:hover {
   background-color: rgba(16, 185, 129, 0.04);
-  box-shadow: inset 2px 0 0 rgba(16, 185, 129, 0.6);
 }
 
-/* Strong text inside list items — subtle green tint on parent hover */
-ul > li:hover > strong,
-ol > li:hover > strong {
-  color: #10B981;
-  transition: color 0.15s ease;
+/* ── PRIMARY BUTTON / CTA ────────────────────────────────────── */
+button[class*="primary"],
+a[class*="primary"],
+[class*="btn-primary"],
+[class*="ButtonPrimary"] {
+  transition:
+    box-shadow 0.2s ease,
+    transform  0.2s ease !important;
 }
 
-/* ============================================================
-   HIDE THEME TOGGLE (moon / sun emoji button)
-   ============================================================ */
+button[class*="primary"]:hover,
+a[class*="primary"]:hover,
+[class*="btn-primary"]:hover,
+[class*="ButtonPrimary"]:hover {
+  box-shadow: 0 0 22px rgba(16, 185, 129, 0.28) !important;
+  transform: translateY(-1px) !important;
+}
+
+/* ── HIDE THEME TOGGLE ───────────────────────────────────────── */
 button[aria-label="Switch to light mode"],
 button[aria-label="Switch to dark mode"],
 button[aria-label*="theme"],