style(docs): comprehensive fhirworx editorial theme for Docusaurus

350+ lines of component-level styling matching the Gitea theme:
- Playfair Display 800 h1 with 3px navy underline
- Source Serif 4 body at 1.75 line-height, 75ch max-width
- JetBrains Mono for nav links, breadcrumbs, table headers, code
- Eyebrow treatment on breadcrumbs, pagination sublabels, admonitions
- Amber (#C8702A) accent on active sidebar, footer, pagination hover
- Tables: mono uppercase column headers, 2px primary border, hover rows
- Navy navbar with no box-shadow, mono uppercase nav links
- Sidebar: 3px amber active indicator, mono uppercase category labels
- Code blocks: bordered, compact, matching body background
- WCAG 2.2 AA: focus-visible, reduced-motion, min target size

docs/src/css/custom.css

@@ -1,46 +1,77 @@
-/* fhirworx design system for Docusaurus
+/* =============================================================================
-   Matches the editorial palette from assets/css/fhirworx.css
+   Fhirworx — Docusaurus theme
-   Design: Federal Register Meets Data Journalism */
+   =============================================================================
+   Mirrors the editorial design system from assets/css/fhirworx.css and the
+   Gitea theme (infra/gitea/theme/theme-fhirworx.css). Design reference:
+   Federal Register meets data journalism (ProPublica, Marshall Project).
 
-@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;600;700&family=Source+Serif+4:ital,wght@0,300;0,400;0,600;1,400&family=JetBrains+Mono:wght@400;500;600&display=swap');
+   Font stack: Playfair Display (headings), Source Serif 4 (body),
+   JetBrains Mono (code).
+   ========================================================================== */
 
-/* ── Light theme (default) ─────────────────────────────────── */
+@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;600;700;800&family=Source+Serif+4:ital,wght@0,300;0,400;0,600;1,400&family=JetBrains+Mono:wght@400;500;600&display=swap');
+
+/* ── Light theme ───────────────────────────────────────────── */
 
 :root {
+  /* Core palette */
   --ifm-color-primary: #1C2B3A;
   --ifm-color-primary-dark: #162230;
   --ifm-color-primary-darker: #131e2a;
   --ifm-color-primary-darkest: #0e1620;
-  --ifm-color-primary-light: #253748;
+  --ifm-color-primary-light: #2E4A63;
-  --ifm-color-primary-lighter: #2d4052;
+  --ifm-color-primary-lighter: #3F6683;
-  --ifm-color-primary-lightest: #3d5570;
+  --ifm-color-primary-lightest: #5684A3;
 
+  /* Surfaces */
   --ifm-background-color: #F7F5F0;
-  --ifm-background-surface-color: #FAFAF7;
+  --ifm-background-surface-color: #FFFFFF;
+  --ifm-navbar-background-color: #1C2B3A;
+  --ifm-footer-background-color: #1C2B3A;
+
+  /* Text */
   --ifm-font-color-base: #1A1A18;
   --ifm-heading-color: #1A1A18;
-  --ifm-link-color: #5B8FA8;
+  --ifm-font-color-secondary: #6B6B68;
-  --ifm-navbar-background-color: #1C2B3A;
+  --ifm-link-color: #2D5F7F;
-  --ifm-navbar-link-color: #B8C5D0;
+  --ifm-link-hover-color: #1C2B3A;
-  --ifm-navbar-link-hover-color: #F7F5F0;
+  --ifm-navbar-link-color: #F0F4F8;
-  --ifm-footer-background-color: #1C2B3A;
+  --ifm-navbar-link-hover-color: #FFFFFF;
   --ifm-footer-color: #B8C5D0;
-  --ifm-menu-color: #2D2D2B;
+  --ifm-menu-color: #1A1A18;
+  --ifm-menu-color-active: #1C2B3A;
   --ifm-toc-link-color: #6B6B68;
-  --ifm-code-background: #EDEBE6;
-  --ifm-hr-border-color: #D4D0C8;
 
+  /* Borders */
+  --ifm-border-color: #B8B3A4;
+  --ifm-hr-border-color: #D4D0C8;
+  --ifm-global-border-width: 1px;
+  --ifm-global-radius: 0.2rem;
+
+  /* Code */
+  --ifm-code-background: #EDEBE6;
+  --ifm-code-border-color: #D4D0C8;
+  --ifm-code-padding-vertical: 0.1rem;
+  --ifm-code-padding-horizontal: 0.3rem;
+  --prism-background-color: #F7F5F0;
+  --docusaurus-highlighted-code-line-bg: rgba(28, 43, 58, 0.08);
+
+  /* Typography */
   --ifm-font-family-base: "Source Serif 4", Georgia, serif;
-  --ifm-font-family-monospace: "JetBrains Mono", "Fira Code", monospace;
+  --ifm-font-family-monospace: "JetBrains Mono", "Fira Code", ui-monospace, monospace;
   --ifm-heading-font-family: "Playfair Display", Georgia, serif;
   --ifm-code-font-size: 88%;
   --ifm-font-size-base: 16px;
   --ifm-line-height-base: 1.65;
 
-  --ifm-border-color: #D4D0C8;
+  /* Spacing */
-  --ifm-global-radius: 0.2rem;
+  --ifm-global-spacing: 1rem;
+  --ifm-navbar-height: 3.5rem;
 
-  --docusaurus-highlighted-code-line-bg: rgba(28, 43, 58, 0.08);
+  /* Accent: amber for editorial emphasis */
+  --fw-accent: #C8702A;
+  --fw-accent-light: #D4884A;
+  --fw-destructive: #C0392B;
 }
 
 /* ── Dark theme ────────────────────────────────────────────── */
@@ -53,26 +84,41 @@
   --ifm-color-primary-darker: #47768d;
   --ifm-color-primary-darkest: #3b6174;
   --ifm-color-primary-light: #6BA0B8;
-  --ifm-color-primary-lighter: #72A5BC;
+  --ifm-color-primary-lighter: #7BB8D0;
   --ifm-color-primary-lightest: #8FB8CC;
 
   --ifm-font-color-base: #EEE9E0;
   --ifm-heading-color: #EEE9E0;
+  --ifm-font-color-secondary: #8898A8;
   --ifm-link-color: #7BB8D0;
+  --ifm-link-hover-color: #A5D2E6;
   --ifm-navbar-background-color: #0A1219;
-  --ifm-navbar-link-color: #B8C5D0;
   --ifm-footer-background-color: #060D14;
   --ifm-footer-color: #8898A8;
   --ifm-menu-color: #B8C5D0;
+  --ifm-menu-color-active: #EEE9E0;
   --ifm-toc-link-color: #8898A8;
   --ifm-code-background: #1A2A3D;
-  --ifm-hr-border-color: #253748;
+  --ifm-code-border-color: #253748;
   --ifm-border-color: #253748;
+  --ifm-hr-border-color: #253748;
+  --prism-background-color: #0F1923;
 
   --docusaurus-highlighted-code-line-bg: rgba(91, 143, 168, 0.15);
 }
 
-/* ── Typography ────────────────────────────────────────────── */
+/* =============================================================================
+   Component overrides
+   ============================================================================= */
+
+/* ── Global ────────────────────────────────────────────────── */
+
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* ── Headings ──────────────────────────────────────────────── */
 
 h1, h2, h3, h4, h5, h6 {
   font-family: var(--ifm-heading-font-family);
@@ -82,90 +128,308 @@ h1, h2, h3, h4, h5, h6 {
 }
 
 .markdown h1:first-child {
-  font-size: 2.2rem;
+  font-size: 2.4rem;
+  font-weight: 800;
+  border-bottom: 3px solid var(--ifm-color-primary);
+  padding-bottom: 0.5rem;
+  margin-bottom: 1.5rem;
 }
 
-code, kbd, pre {
+.markdown h2 {
-  font-family: var(--ifm-font-family-monospace);
+  font-size: 1.6rem;
+  margin-top: 2.5rem;
+  padding-bottom: 0.3rem;
+  border-bottom: 1px solid var(--ifm-hr-border-color);
+}
+
+.markdown h3 {
+  font-size: 1.25rem;
+  margin-top: 2rem;
 }
 
 /* ── Navbar ────────────────────────────────────────────────── */
 
 .navbar {
   box-shadow: none;
-  border-bottom: 1px solid var(--ifm-border-color);
+  border-bottom: none;
+  padding: 0 1rem;
 }
 
 .navbar__title {
   font-family: var(--ifm-heading-font-family);
   font-weight: 700;
-  letter-spacing: 0.03em;
+  font-size: 1.15rem;
-  color: #F7F5F0;
+  letter-spacing: 0.04em;
+  color: var(--ifm-navbar-link-color);
+}
+
+.navbar__link {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.8rem;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.navbar__search-input {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.8rem;
+  background-color: rgba(255, 255, 255, 0.1);
+  border: 1px solid rgba(255, 255, 255, 0.15);
+  border-radius: var(--ifm-global-radius);
 }
 
 /* ── Sidebar ───────────────────────────────────────────────── */
 
+.theme-doc-sidebar-container {
+  border-right: 1px solid var(--ifm-border-color) !important;
+}
+
+.menu__link {
+  font-size: 0.9rem;
+  border-radius: 0;
+  padding: 0.4rem 0.75rem;
+  transition: background-color 0.15s, border-color 0.15s;
+}
+
 .menu__link--active:not(.menu__link--sublist) {
-  border-left: 3px solid #C8702A;
+  background: transparent;
+  border-left: 3px solid var(--fw-accent);
   font-weight: 600;
+  color: var(--ifm-menu-color-active);
+  padding-left: calc(0.75rem - 3px);
 }
 
-.menu__link:hover {
+.menu__link:hover:not(.menu__link--active) {
-  color: var(--ifm-color-primary);
+  background-color: var(--ifm-code-background);
 }
 
-/* ── Footer ────────────────────────────────────────────────── */
+.menu__link--sublist-caret::after {
-
+  background-size: 1.2em 1.2em;
-.footer--dark {
-  border-top: 3px solid #C8702A;
 }
 
-/* ── Hero / landing ────────────────────────────────────────── */
+.menu__list-item-collapsible .menu__link {
-
+  font-family: var(--ifm-font-family-monospace);
-.hero {
+  font-size: 0.82rem;
-  border-bottom: 3px solid #C8702A;
+  font-weight: 600;
-}
+  text-transform: uppercase;
-
+  letter-spacing: 0.06em;
-/* ── Code blocks ───────────────────────────────────────────── */
+  color: var(--ifm-font-color-secondary);
-
-.prism-code {
-  border: 1px solid var(--ifm-border-color);
-  border-radius: var(--ifm-global-radius);
 }
 
 /* ── Breadcrumbs (eyebrow style) ───────────────────────────── */
 
 .breadcrumbs__link {
   font-family: var(--ifm-font-family-monospace);
-  font-size: 0.75rem;
+  font-size: 0.7rem;
+  font-weight: 500;
   text-transform: uppercase;
-  letter-spacing: 0.1em;
+  letter-spacing: 0.12em;
+  color: var(--ifm-font-color-secondary);
 }
 
-/* ── Table of contents ─────────────────────────────────────── */
+.breadcrumbs__item--active .breadcrumbs__link {
-
+  color: var(--ifm-font-color-base);
-.table-of-contents__link--active {
-  color: var(--ifm-color-primary);
-  font-weight: 600;
 }
 
-/* ── Blockquotes (editorial pull-quote style) ──────────────── */
+.breadcrumbsContainer_PW3S {
+  margin-bottom: 1.5rem;
+}
+
+/* ── Content area ──────────────────────────────────────────── */
+
+.markdown {
+  max-width: 75ch;
+}
+
+.markdown p {
+  line-height: 1.75;
+  margin-bottom: 1.25rem;
+}
+
+.markdown li {
+  line-height: 1.65;
+  margin-bottom: 0.3rem;
+}
+
+/* ── Code blocks ───────────────────────────────────────────── */
+
+.prism-code {
+  border: 1px solid var(--ifm-code-border-color);
+  border-radius: var(--ifm-global-radius);
+  font-size: 0.85rem;
+  line-height: 1.5;
+}
+
+code {
+  border: 1px solid var(--ifm-code-border-color);
+  border-radius: var(--ifm-global-radius);
+}
+
+pre code {
+  border: none;
+}
+
+/* ── Blockquotes (editorial pull-quote) ────────────────────── */
 
 blockquote {
   border-left: 3px solid var(--ifm-color-primary);
   background: transparent;
+  padding: 0.5rem 1rem;
   font-style: italic;
+  color: var(--ifm-font-color-secondary);
+}
+
+/* ── Tables ────────────────────────────────────────────────── */
+
+table {
+  font-size: 0.9rem;
+  border-collapse: collapse;
+}
+
+table thead th {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--ifm-font-color-secondary);
+  border-bottom: 2px solid var(--ifm-color-primary);
+  padding: 0.6rem 0.75rem;
+}
+
+table tbody td {
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid var(--ifm-hr-border-color);
+}
+
+table tbody tr:hover {
+  background-color: var(--ifm-code-background);
+}
+
+/* ── Table of contents ─────────────────────────────────────── */
+
+.table-of-contents {
+  font-size: 0.85rem;
+}
+
+.table-of-contents__link {
+  color: var(--ifm-toc-link-color);
+}
+
+.table-of-contents__link--active,
+.table-of-contents__link:hover {
+  color: var(--ifm-color-primary);
+  font-weight: 600;
+}
+
+/* ── Footer ────────────────────────────────────────────────── */
+
+.footer--dark {
+  border-top: 3px solid var(--fw-accent);
+}
+
+.footer__title {
+  font-family: var(--ifm-heading-font-family);
+  font-weight: 700;
+}
+
+.footer__link-item {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.8rem;
+  letter-spacing: 0.04em;
 }
 
 /* ── Admonitions ───────────────────────────────────────────── */
 
 .alert {
   border-radius: var(--ifm-global-radius);
+  border-width: 1px;
+  border-left-width: 4px;
+  font-size: 0.92rem;
 }
 
-/* ── Accent color: amber (#C8702A) for editorial emphasis ──── */
+.alert .admonitionHeading_tbUL {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.78rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+/* ── Pagination (prev/next) ────────────────────────────────── */
+
+.pagination-nav__link {
+  border: 1px solid var(--ifm-border-color);
+  border-radius: var(--ifm-global-radius);
+  transition: border-color 0.15s;
+}
 
-.table-of-contents__link--active,
 .pagination-nav__link:hover {
-  border-color: #C8702A;
+  border-color: var(--fw-accent);
+}
+
+.pagination-nav__sublabel {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--ifm-font-color-secondary);
+}
+
+.pagination-nav__label {
+  font-family: var(--ifm-heading-font-family);
+  font-weight: 600;
+}
+
+/* ── Hero / landing ────────────────────────────────────────── */
+
+.hero {
+  background: var(--ifm-color-primary);
+  color: var(--ifm-color-primary-contrast, #F7F5F0);
+  border-bottom: 4px solid var(--fw-accent);
+}
+
+.hero__title {
+  font-family: var(--ifm-heading-font-family);
+  font-weight: 800;
+  font-size: 3rem;
+}
+
+.hero__subtitle {
+  font-family: var(--ifm-font-family-base);
+  font-size: 1.15rem;
+  line-height: 1.6;
+  opacity: 0.85;
+}
+
+/* ── Scrollbar ─────────────────────────────────────────────── */
+
+.thin-scrollbar::-webkit-scrollbar-thumb {
+  background: var(--ifm-border-color);
+}
+
+.thin-scrollbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+/* ── Back to top button ────────────────────────────────────── */
+
+.theme-back-to-top-button {
+  background-color: var(--ifm-color-primary) !important;
+}
+
+/* ── WCAG 2.2 AA ───────────────────────────────────────────── */
+
+:focus-visible {
+  outline: 2px solid var(--ifm-color-primary) !important;
+  outline-offset: 2px !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
 }