docs: refine interface tour screenshot

Author: ovvesley

docs/docs/guides/interface-tour.mdx

@@ -13,13 +13,14 @@ AkôFlow Desktop is the visual client for the AkôFlow daemon. The application d
 
 <AnnotatedScreenshot
   src="/img/interface/overview.png"
+  darkSrc="/img/interface/overview-dark.png"
   alt="AkôFlow Desktop overview with the sidebar, global search, notifications, instance status, and workflow summary identified"
-  caption="The overview is a current snapshot of the connected daemon. Counts and workflow names change with the selected instance; use a workflow row or View all to continue into the record rather than treating the dashboard as a report export."
+  caption="A current Desktop overview. The numbered markers identify the navigation and status controls; counts and workflow names change with the selected instance. Open a workflow row or select View all to continue into a record."
   callouts={[
-    {number: 1, label: 'The sidebar groups workflows, infrastructure, runs, artifacts, provenance, and audit.'},
-    {number: 2, label: 'Global search opens entities without first visiting their list page.'},
-    {number: 3, label: 'Notifications report operations that need attention.'},
-    {number: 4, label: 'The instance indicator confirms which daemon the client is using.'},
+    {number: 1, x: 4.8, y: 16.0, label: 'The sidebar groups workflows, infrastructure, runs, artifacts, provenance, and audit.'},
+    {number: 2, x: 50.0, y: 7.5, label: 'Global search opens entities without first visiting their list page.'},
+    {number: 3, x: 92.1, y: 7.5, label: 'Notifications report operations that need attention.'},
+    {number: 4, x: 8.2, y: 91.5, label: 'The instance indicator confirms which daemon the client is using.'},
   ]}
 />
 

docs/src/components/AnnotatedScreenshot.tsx

@@ -1,24 +1,34 @@
 import React from 'react';
+import {useColorMode} from '@docusaurus/theme-common';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 
 type Callout = {
   number: number;
   label: string;
+  x?: number;
+  y?: number;
 };
 
 type AnnotatedScreenshotProps = {
   src?: string;
+  darkSrc?: string;
   alt: string;
   caption?: string;
   callouts?: Callout[];
 };
 
 export default function AnnotatedScreenshot({
   src,
+  darkSrc,
   alt,
   caption,
   callouts = [],
 }: AnnotatedScreenshotProps) {
-  if (!src) {
+  const {colorMode} = useColorMode();
+  const activeSrc = colorMode === 'dark' && darkSrc ? darkSrc : src;
+  const resolvedSrc = useBaseUrl(activeSrc ?? '');
+
+  if (!activeSrc) {
     return (
       <aside className="akoflow-media-placeholder" aria-label={alt}>
         <strong>Screenshot planned</strong>
@@ -29,7 +39,21 @@ export default function AnnotatedScreenshot({
 
   return (
     <figure className="akoflow-annotated-screenshot">
-      <img src={src} alt={alt} loading="lazy" />
+      <div className="akoflow-annotated-screenshot__image">
+        <img src={resolvedSrc} alt={alt} loading="lazy" />
+        {callouts
+          .filter((callout) => callout.x !== undefined && callout.y !== undefined)
+          .map((callout) => (
+            <span
+              key={callout.number}
+              className="akoflow-annotated-screenshot__marker"
+              style={{left: `${callout.x}%`, top: `${callout.y}%`}}
+              aria-hidden="true"
+            >
+              {callout.number}
+            </span>
+          ))}
+      </div>
       {(caption || callouts.length > 0) && (
         <figcaption>
           {caption && <p>{caption}</p>}

docs/src/css/custom.css

@@ -308,6 +308,39 @@ html {
   box-shadow: 0 12px 30px rgba(0, 0, 0, 0.08);
 }
 
+.akoflow-annotated-screenshot__image {
+  position: relative;
+  overflow: hidden;
+  border-radius: 12px;
+}
+
+.akoflow-annotated-screenshot__image img {
+  border-radius: 12px;
+}
+
+.akoflow-annotated-screenshot__marker {
+  position: absolute;
+  display: grid;
+  width: 1.65rem;
+  height: 1.65rem;
+  place-items: center;
+  transform: translate(-50%, -50%);
+  border: 2px solid #fff;
+  border-radius: 999px;
+  background: #111;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.35);
+  color: #fff;
+  font-size: 0.78rem;
+  font-weight: 800;
+  line-height: 1;
+}
+
+[data-theme='dark'] .akoflow-annotated-screenshot__marker {
+  border-color: #111;
+  background: #fff;
+  color: #111;
+}
+
 .akoflow-annotated-screenshot figcaption,
 .akoflow-demo-video figcaption {
   margin-top: 0.75rem;