@eventcatalog/core 3.48.4 → 4.0.0-beta.1

package/eventcatalog/src/components/MDX/ContextDiagram/ContextDiagramPortal.tsx

@@ -0,0 +1,21 @@
+/**
+ * Placeholder div the Context Diagram graph is portaled into.
+ *
+ * Mirrors NodeGraphPortal, but uses a distinct `-context-diagram-portal` id so a
+ * system page can render both its System Diagram (the default `<NodeGraph />`)
+ * and its Context Diagram (`<ContextDiagram />`) without the two graphs fighting
+ * over the same portal target.
+ */
+const ContextDiagramPortal = (props: any) => {
+  return (
+    <div
+      className="not-prose h-[30em] my-6 mb-12 w-full relative border! border-[rgb(var(--ec-page-border))]! rounded-md overflow-hidden"
+      id={`${props.id}-context-diagram-portal`}
+      style={{
+        maxHeight: props.maxHeight ? `${props.maxHeight}em` : `30em`,
+      }}
+    />
+  );
+};
+
+export default ContextDiagramPortal;

package/eventcatalog/src/components/MDX/NodeGraph/AstroNodeGraph.tsx

@@ -38,6 +38,7 @@ interface AstroNodeGraphProps {
   maxTextSize?: number;
   isDevMode?: boolean;
   resourceKey?: string;
+  disableMessageAnimation?: boolean;
 }
 
 const AstroNodeGraph = ({ isDevMode = false, resourceKey, ...otherProps }: AstroNodeGraphProps) => {

package/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.astro

@@ -7,14 +7,17 @@ import {
   getNodesAndEdgesForEvents,
   getNodesAndEdgesForQueries,
 } from '@utils/node-graphs/message-node-graph';
-import {
-  getNodesAndEdges as getNodesAndEdgesForDomain,
-  getNodesAndEdgesForDomainContextMap,
-} from '@utils/node-graphs/domains-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForDomain } from '@utils/node-graphs/domains-node-graph';
 import { getNodesAndEdges as getNodesAndEdgesForDomainEntityMap } from '@utils/node-graphs/domain-entity-map';
 import { getDomainsCanvasData } from '@utils/node-graphs/domains-canvas';
 import { getNodesAndEdges as getNodesAndEdgesForFlows } from '@utils/node-graphs/flows-node-graph';
 import { getNodesAndEdges as getNodesAndEdgesForDataProduct } from '@utils/node-graphs/data-products-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForSystem } from '@utils/node-graphs/systems-node-graph';
+import {
+  getNodesAndEdges as getNodesAndEdgesForSystemContext,
+  getNodesAndEdgesForDomainSystems as getNodesAndEdgesForDomainSystemsContext,
+  getNodesAndEdgesForAllSystems as getNodesAndEdgesForSystemContextMap,
+} from '@utils/node-graphs/system-context-node-graph';
 import { buildUrl } from '@utils/url-builder';
 import { getVersionFromCollection } from '@utils/collections/versions';
 import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
@@ -40,6 +43,12 @@ interface Props {
   showSearch?: boolean;
   showLegend?: boolean;
   zoomOnScroll?: boolean;
+  // Override the DOM portal the graph mounts into. Defaults to `${id}-portal`.
+  // Needed when more than one graph for the same resource is on the page
+  // (e.g. the System Diagram and the Context Diagram on a system page).
+  portalId?: string;
+  // Disable + hide the "Simulate Messages" animation (e.g. on the Context Diagram).
+  disableMessageAnimation?: boolean;
 }
 
 const {
@@ -54,6 +63,8 @@ const {
   showSearch = true,
   showLegend = true,
   zoomOnScroll = false,
+  portalId,
+  disableMessageAnimation,
 } = Astro.props;
 
 let nodes = [],
@@ -69,6 +80,7 @@ const getNodesAndEdgesFunctions = {
   flows: getNodesAndEdgesForFlows,
   containers: getNodesAndEdgesForContainer,
   'data-products': getNodesAndEdgesForDataProduct,
+  systems: getNodesAndEdgesForSystem,
 };
 
 let links: { label: string; url: string }[] = [];
@@ -81,6 +93,8 @@ if (collection in getNodesAndEdgesFunctions) {
     version,
     mode,
     channelRenderMode: config.visualiser?.channels?.renderMode === 'single' ? 'single' : 'flat',
+    // The standalone System Diagram wraps the system's nodes in one parent boundary node.
+    wrapInSystemGroup: collection === 'systems',
   });
 
   nodes = fetchedNodes;
@@ -111,8 +125,8 @@ if (collection in getNodesAndEdgesFunctions) {
   }
 }
 
-if (collection === 'domain-context-map') {
-  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForDomainContextMap({});
+if (collection === 'system-context-map') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForSystemContextMap({ mode });
   nodes = fetchedNodes;
   edges = fetchedEdges;
 }
@@ -123,6 +137,26 @@ if (collection === 'domains-canvas') {
   edges = fetchedEdges;
 }
 
+if (collection === 'systems-context') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForSystemContext({
+    id,
+    version,
+    mode,
+  });
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+}
+
+if (collection === 'domains-systems-context') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForDomainSystemsContext({
+    id,
+    version,
+    mode,
+  });
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+}
+
 if (collection === 'domains-entities') {
   const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForDomainEntityMap({
     id,
@@ -179,6 +213,8 @@ const nodesWithLayout = applyLayoutToNodes(nodes as any[], savedLayout);
     maxTextSize={config.mermaid?.maxTextSize}
     isDevMode={isDevMode()}
     resourceKey={resourceKey}
+    portalId={portalId}
+    disableMessageAnimation={disableMessageAnimation ?? collection === 'systems-context'}
   />
 </div>
 

package/eventcatalog/src/components/MDX/Prompt/Prompt.astro

@@ -1,4 +1,5 @@
 ---
+import { ChevronDown } from 'lucide-react';
 import { LUCIDE_ICON_MAP } from '@utils/icon-map';
 
 type ActionType = 'copy' | 'cursor';
@@ -37,6 +38,7 @@ const promptText = (slotHtml ?? '')
   .trim();
 
 const cursorUrl = `https://cursor.com/link/prompt?text=${encodeURIComponent(promptText)}`;
+const promptBodyId = `ec-prompt-body-${Math.random().toString(36).slice(2)}`;
 ---
 
 <ec-prompt
@@ -49,6 +51,20 @@ const cursorUrl = `https://cursor.com/link/prompt?text=${encodeURIComponent(prom
       <div class="text-sm font-medium text-[rgb(var(--ec-page-text))] leading-snug">{description}</div>
     </div>
     <div class="flex items-center gap-1.5 shrink-0">
+      <button
+        type="button"
+        data-prompt-toggle
+        aria-expanded="false"
+        aria-controls={promptBodyId}
+        class="inline-flex items-center gap-1.5 px-2 py-1 text-xs font-medium rounded-md border transition-all duration-150 border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]"
+      >
+        <span data-prompt-toggle-text>Show prompt</span>
+        <ChevronDown
+          className="w-3.5 h-3.5 shrink-0 transition-transform duration-150 data-[expanded=true]:rotate-180"
+          data-prompt-toggle-icon
+          data-expanded="false"
+        />
+      </button>
       {
         showCopy && (
           <button
@@ -123,6 +139,15 @@ const cursorUrl = `https://cursor.com/link/prompt?text=${encodeURIComponent(prom
       }
     </div>
   </div>
+  <div
+    id={promptBodyId}
+    data-prompt-body
+    hidden
+    class="border-t border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))]/70"
+  >
+    <pre
+      class="m-0 max-h-96 overflow-auto whitespace-pre-wrap break-words px-4 py-3 text-sm leading-6 text-[rgb(var(--ec-page-text))]"><code>{promptText}</code></pre>
+  </div>
   <div hidden><slot /></div>
 </ec-prompt>
 
@@ -130,16 +155,28 @@ const cursorUrl = `https://cursor.com/link/prompt?text=${encodeURIComponent(prom
   if (!customElements.get('ec-prompt')) {
     class ECPromptElement extends HTMLElement {
       private resetTimer: number | null = null;
-      private button: HTMLButtonElement | null = null;
+      private copyButton: HTMLButtonElement | null = null;
+      private toggleButton: HTMLButtonElement | null = null;
+      private promptBody: HTMLElement | null = null;
+      private toggleText: HTMLElement | null = null;
+      private toggleIcon: HTMLElement | null = null;
       private boundHandler = this.handleCopy.bind(this);
+      private boundToggleHandler = this.handleToggle.bind(this);
 
       connectedCallback() {
-        this.button = this.querySelector<HTMLButtonElement>('[data-prompt-copy]');
-        this.button?.addEventListener('click', this.boundHandler);
+        this.copyButton = this.querySelector<HTMLButtonElement>('[data-prompt-copy]');
+        this.toggleButton = this.querySelector<HTMLButtonElement>('[data-prompt-toggle]');
+        this.promptBody = this.querySelector<HTMLElement>('[data-prompt-body]');
+        this.toggleText = this.querySelector<HTMLElement>('[data-prompt-toggle-text]');
+        this.toggleIcon = this.querySelector<HTMLElement>('[data-prompt-toggle-icon]');
+
+        this.copyButton?.addEventListener('click', this.boundHandler);
+        this.toggleButton?.addEventListener('click', this.boundToggleHandler);
       }
 
       disconnectedCallback() {
-        this.button?.removeEventListener('click', this.boundHandler);
+        this.copyButton?.removeEventListener('click', this.boundHandler);
+        this.toggleButton?.removeEventListener('click', this.boundToggleHandler);
         if (this.resetTimer != null) {
           window.clearTimeout(this.resetTimer);
           this.resetTimer = null;
@@ -158,12 +195,28 @@ const cursorUrl = `https://cursor.com/link/prompt?text=${encodeURIComponent(prom
         this.resetTimer = window.setTimeout(() => this.setCopied(false), 1500);
       }
 
+      private handleToggle() {
+        if (!this.promptBody || !this.toggleButton) return;
+
+        const expanded = this.toggleButton.getAttribute('aria-expanded') === 'true';
+        this.setExpanded(!expanded);
+      }
+
+      private setExpanded(expanded: boolean) {
+        if (!this.promptBody || !this.toggleButton) return;
+
+        this.promptBody.hidden = !expanded;
+        this.toggleButton.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+        if (this.toggleText) this.toggleText.textContent = expanded ? 'Hide prompt' : 'Show prompt';
+        if (this.toggleIcon) this.toggleIcon.dataset.expanded = expanded ? 'true' : 'false';
+      }
+
       private setCopied(copied: boolean) {
-        if (!this.button) return;
-        this.button.dataset.copied = copied ? 'true' : 'false';
-        this.button.setAttribute('aria-label', copied ? 'Copied to clipboard' : 'Copy prompt');
-        const idle = this.button.querySelector<HTMLElement>('[data-prompt-copy-idle]');
-        const done = this.button.querySelector<HTMLElement>('[data-prompt-copy-done]');
+        if (!this.copyButton) return;
+        this.copyButton.dataset.copied = copied ? 'true' : 'false';
+        this.copyButton.setAttribute('aria-label', copied ? 'Copied to clipboard' : 'Copy prompt');
+        const idle = this.copyButton.querySelector<HTMLElement>('[data-prompt-copy-idle]');
+        const done = this.copyButton.querySelector<HTMLElement>('[data-prompt-copy-done]');
         if (idle) idle.style.display = copied ? 'none' : '';
         if (done) done.style.display = copied ? '' : 'none';
       }

package/eventcatalog/src/components/MDX/ResourceRef/ResourceRef.astro

@@ -30,9 +30,11 @@ interface Props {
     | 'channel'
     | 'diagram'
     | 'container'
+    | 'system'
     | 'user'
     | 'team'
     | 'doc'
+    | 'adr'
     | 'data-product';
   version?: string;
 }
@@ -72,9 +74,11 @@ const typeLabels: Record<string, string> = {
   channel: 'Channel',
   diagram: 'Diagram',
   container: 'Container',
+  system: 'System',
   user: 'User',
   team: 'Team',
   doc: 'Custom Doc',
+  adr: 'Decision Record',
   'data-product': 'Data Product',
 };
 
@@ -106,6 +110,9 @@ const typeIcons: Record<string, string> = {
   doc: '<path stroke-linecap="round" stroke-linejoin="round" d="M14 2v4a2 2 0 002 2h4" /><path stroke-linecap="round" stroke-linejoin="round" d="M15 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V7z" /><path stroke-linecap="round" stroke-linejoin="round" d="M10 9H8" /><path stroke-linecap="round" stroke-linejoin="round" d="M16 13H8" /><path stroke-linecap="round" stroke-linejoin="round" d="M16 17H8" />', // FileText
   'data-product':
     '<path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25M21 7.5v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />', // Cube
+  system:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M2.25 7.125C2.25 6.504 2.754 6 3.375 6h6c.621 0 1.125.504 1.125 1.125v3.75c0 .621-.504 1.125-1.125 1.125h-6a1.125 1.125 0 01-1.125-1.125v-3.75zM14.25 8.625c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v8.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 01-1.125-1.125v-8.25zM3.75 16.125c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v2.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 01-1.125-1.125v-2.25z" />', // Group (systems)
+  adr: '<path stroke-linecap="round" stroke-linejoin="round" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" /><path stroke-linecap="round" stroke-linejoin="round" d="M9 7h2" />', // ClipboardList-ish (ADR)
 };
 
 const label = typeLabels[type] || typeLabels.entity;
@@ -176,7 +183,7 @@ const truncatedSummary = summary.length > maxSummaryLength ? summary.slice(0, ma
 const isVersionedResource = type !== 'doc';
 
 // Only these types have visualizers
-const hasVisualizer = ['agent', 'domain', 'service', 'event', 'query', 'command', 'container'].includes(type);
+const hasVisualizer = ['agent', 'domain', 'service', 'event', 'query', 'command', 'container', 'system'].includes(type);
 
 // Check deprecation status
 const deprecation = resource ? getDeprecatedDetails(resource) : null;

package/eventcatalog/src/components/MDX/SystemContextMap/SystemContextMapPortal.tsx

@@ -0,0 +1,22 @@
+/**
+ * Placeholder div the global System Context Map graph is portaled into.
+ *
+ * Mirrors NodeGraphPortal, but uses a fixed `system-context-map-portal` id so the
+ * homepage (and any other page) can embed the global system context map without an
+ * id/version. The matching <NodeGraph collection="system-context-map" /> renders the
+ * graph into this portal.
+ */
+const SystemContextMapPortal = (props: any) => {
+  return (
+    <div
+      className="not-prose my-6 mb-12 w-full relative border! border-[rgb(var(--ec-page-border))]! rounded-md overflow-hidden"
+      id="system-context-map-portal"
+      style={{
+        height: props.height ? `${props.height}em` : '36em',
+        maxHeight: props.maxHeight ? `${props.maxHeight}em` : '36em',
+      }}
+    />
+  );
+};
+
+export default SystemContextMapPortal;

package/eventcatalog/src/components/MDX/components.tsx

@@ -17,6 +17,7 @@ import ChannelInformation from '@components/MDX/ChannelInformation/ChannelInform
 import Attachments from '@components/MDX/Attachments.astro';
 import AgentTools from '@components/MDX/AgentTools/AgentTools.astro';
 import MessageTable from '@components/MDX/MessageTable/MessageTable.astro';
+import ADRTable from '@components/MDX/ADRTable/ADRTable.astro';
 import ResourceGroupTable from '@components/MDX/ResourceGroupTable/ResourceGroupTable.astro';
 import EntityPropertiesTable from '@components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro';
 import Tabs from '@components/MDX/Tabs/Tabs.astro';
@@ -34,6 +35,8 @@ import MermaidFileLoader from '@components/MDX/MermaidFileLoader/MermaidFileLoad
 import LikeC4View from '@components/MDX/LikeC4View/LikeC4View.astro';
 //  Portals: required for server/client components
 import NodeGraphPortal from '@components/MDX/NodeGraph/NodeGraphPortal';
+import ContextDiagramPortal from '@components/MDX/ContextDiagram/ContextDiagramPortal';
+import SystemContextMapPortal from '@components/MDX/SystemContextMap/SystemContextMapPortal';
 import SchemaViewerPortal from '@components/MDX/SchemaViewer/SchemaViewerPortal';
 import { jsx } from 'astro/jsx-runtime';
 import RemoteSchema from '@components/MDX/RemoteSchema.astro';
@@ -54,8 +57,12 @@ const components = (props: any) => {
     Flow,
     Link: (mdxProp: any) => jsx(Link, { ...props, ...mdxProp }),
     MessageTable: (mdxProp: any) => jsx(MessageTable, { ...props, ...mdxProp }),
+    ADRTable: (mdxProp: any) => jsx(ADRTable, { ...props, ...mdxProp }),
     EntityPropertiesTable: (mdxProp: any) => jsx(EntityPropertiesTable, { ...props, ...mdxProp }),
     NodeGraph: (mdxProp: any) => jsx(NodeGraphPortal, { ...props.data, ...mdxProp, props, mdxProp }),
+    ComponentDiagram: (mdxProp: any) => jsx(NodeGraphPortal, { ...props.data, ...mdxProp, props, mdxProp }),
+    ContextDiagram: (mdxProp: any) => jsx(ContextDiagramPortal, { ...props.data, ...mdxProp, props, mdxProp }),
+    SystemContextMap: (mdxProp: any) => jsx(SystemContextMapPortal, { ...mdxProp }),
     EntityMap: (mdxProp: any) => jsx(EntityMap, { ...props, ...mdxProp }),
     OpenAPI,
     Prompt: (mdxProp: any) => jsx(Prompt, { ...props, ...mdxProp }),

package/eventcatalog/src/components/SchemaExplorer/SchemaExplorer.tsx

@@ -422,7 +422,7 @@ export default function SchemaExplorer({ schemas, apiAccessEnabled = false }: Sc
             )}
           </div>
 
-          {showFormatFilters && (
+          {showFormatFilters && latestMessages.length > 0 && (
             <div className="flex-shrink-0 border-b border-[rgb(var(--ec-page-border))] px-4 py-3">
               <div className="rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] p-3">
                 <div className="mb-3 flex items-center justify-between gap-3">

package/eventcatalog/src/components/SideNav/NestedSideBar/index.tsx

@@ -2,7 +2,7 @@
 
 import { useState, useEffect, useCallback, useMemo } from 'react';
 import * as LucideIcons from 'lucide-react';
-import { ChevronRight, ChevronLeft, ChevronDown, Home, Star, FileQuestion } from 'lucide-react';
+import { ChevronRight, ChevronLeft, ChevronDown, Home, Star } from 'lucide-react';
 import type { NavNode, ChildRef } from '@stores/sidebar-store/state';
 import { saveState, loadState, saveCollapsedSections, loadCollapsedSections } from './storage';
 import { useStore } from '@nanostores/react';
@@ -218,6 +218,12 @@ export default function NestedSideBar() {
         { pattern: /^\/docs\/domains\/([^/]+)\/([^/]+)/, type: 'domain' },
         { pattern: /^\/visualiser\/domains\/([^/]+)\/([^/]+)/, type: 'domain' },
         { pattern: /^\/architecture\/domains\/([^/]+)\/([^/]+)/, type: 'domain' },
+        // Systems (key prefix is `system`, url segment is `systems`).
+        // The visualiser pattern also matches the System Diagram
+        // (/visualiser/systems/:id/:version/context) since it is not end-anchored.
+        { pattern: /^\/docs\/systems\/([^/]+)\/([^/]+)/, type: 'system' },
+        { pattern: /^\/visualiser\/systems\/([^/]+)\/([^/]+)/, type: 'system' },
+        { pattern: /^\/architecture\/systems\/([^/]+)\/([^/]+)/, type: 'system' },
         // Agents
         { pattern: /^\/docs\/agents\/([^/]+)\/([^/]+)/, type: 'agent' },
         { pattern: /^\/visualiser\/agents\/([^/]+)\/([^/]+)/, type: 'agent' },
@@ -584,6 +590,19 @@ export default function NestedSideBar() {
     });
   };
 
+  /**
+   * Count entries that actually resolve to a visible node. Some refs (e.g. unresolved
+   * `list:` aliases on an empty catalog) sit in `entries` but render nothing — those
+   * must not count, otherwise the empty state is suppressed and the rail looks blank.
+   * Mirrors the filtering in `renderEntries`.
+   */
+  const hasVisibleEntries = currentLevel.entries.some((ref) => {
+    const node = resolveRef(ref);
+    if (!isVisible(node)) return false;
+    if (isGroup(node!)) return hasVisibleChildren(node!);
+    return true;
+  });
+
   /**
    * Handle drilling down into an item with children
    */
@@ -734,37 +753,37 @@ export default function NestedSideBar() {
         const child = resolveRef(childRef);
         return child && isVisible(child);
       }) ?? [];
-    const shouldFlattenSubtleChildren =
-      !isSubtleGroup &&
-      visibleChildren.length > 0 &&
-      visibleChildren.every((childRef) => {
-        const child = resolveRef(childRef);
-        return !!child && isGroup(child) && child.subtle === true;
-      });
 
     const groupId = groupKey || `group-${index}`;
     const canCollapse = visibleChildren.length > 3;
     const isCollapsed = collapsedSections.has(groupId);
 
+    // When a group's children are subtle subgroups (e.g. Resources > Services/Flows/Data Stores),
+    // they render flush under the parent icon instead of inside the indented border guide.
+    const hasSubtleChildren = visibleChildren.some((childRef) => {
+      const child = resolveRef(childRef);
+      return child && isGroup(child) && child.subtle === true;
+    });
+
     const headerContent = (
       <>
         <div className="flex items-center gap-2">
           {GroupIcon && (
             <span
               className={cn(
-                'flex items-center justify-center',
+                'flex items-center justify-center w-5 h-5 rounded',
                 isSubtleGroup
-                  ? 'w-4 h-4 text-[rgb(var(--ec-content-text-muted))]'
-                  : 'w-5 h-5 rounded bg-[rgb(var(--ec-group-icon-bg))] text-[rgb(var(--ec-group-icon-text))]'
+                  ? 'bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-content-text-muted))]'
+                  : 'bg-[rgb(var(--ec-group-icon-bg))] text-[rgb(var(--ec-group-icon-text))]'
               )}
             >
-              <GroupIcon className={cn(isSubtleGroup ? 'w-3 h-3' : 'w-3 h-3')} />
+              <GroupIcon className="w-3 h-3" />
             </span>
           )}
           <span
             className={cn(
               isSubtleGroup
-                ? 'text-[10px] font-semibold uppercase tracking-[0.12em] text-[rgb(var(--ec-content-text-muted))]'
+                ? 'text-[9px] font-semibold uppercase tracking-[0.1em] text-[rgb(var(--ec-content-text-muted))]'
                 : 'text-[12px] font-semibold tracking-tight text-[rgb(var(--ec-content-text))]'
             )}
           >
@@ -791,14 +810,14 @@ export default function NestedSideBar() {
             className={cn(
               'flex items-center justify-between w-full rounded-md transition-colors cursor-pointer',
               isSubtleGroup
-                ? 'px-1.5 py-1 hover:bg-[rgb(var(--ec-content-hover))]/60'
+                ? 'px-2 py-1 hover:bg-[rgb(var(--ec-content-hover))]/60'
                 : 'px-2 py-1.5 hover:bg-[rgb(var(--ec-content-hover))]'
             )}
           >
             {headerContent}
           </button>
         ) : (
-          <div className={cn('flex items-center justify-between', isSubtleGroup ? 'px-1.5 py-1' : 'px-2 py-1.5')}>
+          <div className={cn('flex items-center justify-between', isSubtleGroup ? 'px-2 py-1' : 'px-2 py-1.5')}>
             {headerContent}
           </div>
         )}
@@ -806,7 +825,7 @@ export default function NestedSideBar() {
           <div
             className={cn(
               'flex flex-col gap-0.5 border-[rgb(var(--ec-content-border))]',
-              isSubtleGroup ? 'mt-0.5' : shouldFlattenSubtleChildren ? 'mt-1' : 'border-l ml-4 mt-1'
+              isSubtleGroup ? 'border-l ml-4 mt-1' : hasSubtleChildren ? 'mt-1' : 'border-l ml-4 mt-1'
             )}
           >
             {visibleChildren.map((childRef, childIndex) => {
@@ -822,19 +841,16 @@ export default function NestedSideBar() {
                 return (
                   <div
                     key={`nested-group-${childKey || childIndex}`}
-                    className={cn(
-                      child.subtle
-                        ? shouldFlattenSubtleChildren
-                          ? 'ml-5 mt-0.5'
-                          : 'ml-1.5 mt-1 pl-1.5'
-                        : 'ml-3 mt-1.5 pl-3 border-l border-[rgb(var(--ec-content-border))]'
-                    )}
+                    className={cn(child.subtle ? 'mt-1' : 'ml-3 mt-1.5 pl-3 border-l border-[rgb(var(--ec-content-border))]')}
                   >
                     {renderGroup(child, childKey, childIndex)}
                   </div>
                 );
               }
-              return renderItem(child, childKey, childIndex);
+              // Inside a subtle subgroup (e.g. a domain's Resources > Services list) the
+              // section header already conveys the resource type, so suppress the default
+              // per-item icon and only keep a custom icon if one is defined.
+              return renderItem(child, childKey, childIndex, isSubtleGroup);
             })}
           </div>
         )}
@@ -845,14 +861,22 @@ export default function NestedSideBar() {
   /**
    * Render a single item
    */
-  const renderItem = (item: NavNode, itemKey: string | null, index: number) => {
+  const renderItem = (item: NavNode, itemKey: string | null, index: number, suppressDefaultIcon = false) => {
     const itemHasChildren = hasChildren(item);
     const isActive = urlsMatch(item.href, currentPath) || (itemKey !== null && itemKey === activeNodeKey);
     const isFav = isFavorited(itemKey);
     const canFavorite = itemKey !== null; // Only items with keys can be favorited
 
-    // Get icon component from lucide-react
-    const IconComponent = item.icon ? (LucideIcons as unknown as Record<string, LucideIcons.LucideIcon>)[item.icon] : null;
+    // Get icon component from lucide-react. When suppressDefaultIcon is set (e.g. items
+    // listed under a typed subtle subgroup) the default per-collection glyph is hidden;
+    // a custom icon (item.leftIcon) is always still shown.
+    const IconComponent =
+      item.icon && !suppressDefaultIcon ? (LucideIcons as unknown as Record<string, LucideIcons.LucideIcon>)[item.icon] : null;
+    // Some glyphs fill their box more than others, so they read larger at the shared
+    // item size. Render these ~25% smaller (matching the ADR icon) to visually balance:
+    // ClipboardList (ADRs) and the message glyphs (events/commands/queries).
+    const smallerIcons = ['ClipboardList', 'Zap', 'MessageSquare', 'Search', 'Mail'];
+    const iconSizeClass = item.icon && smallerIcons.includes(item.icon) ? 'w-3 h-3' : 'w-4 h-4';
 
     const handleStarClick = (e: React.MouseEvent) => {
       e.preventDefault();
@@ -870,7 +894,7 @@ export default function NestedSideBar() {
                 isActive ? 'text-[rgb(var(--ec-accent-text))]' : 'text-[rgb(var(--ec-content-text-muted))]'
               )}
             >
-              <IconComponent className="w-4 h-4" />
+              <IconComponent className={iconSizeClass} />
             </span>
           )}
           {item.leftIcon && <img src={resolveIconUrl(item.leftIcon)} alt="" loading="lazy" className="w-4 h-4 flex-shrink-0" />}
@@ -1183,19 +1207,25 @@ export default function NestedSideBar() {
         )}
 
         {/* Empty State */}
-        {currentLevel.entries.length === 0 && favorites.length === 0 && (
-          <div className="flex flex-col items-center justify-center px-6 py-12 text-center">
-            <div className="mb-4 p-3 rounded-full bg-[rgb(var(--ec-group-icon-bg))]">
-              <FileQuestion className="w-8 h-8 text-[rgb(var(--ec-icon-color))]" />
-            </div>
-            <h3 className="text-[12px] font-semibold text-[rgb(var(--ec-content-text))] mb-2">Your catalog is empty</h3>
-            <p className="text-[11px] text-[rgb(var(--ec-content-text-muted))] leading-relaxed max-w-[240px]">
-              Navigation will appear here when you add resources to your EventCatalog.
+        {!hasVisibleEntries && favorites.length === 0 && (
+          <div className="flex min-h-full flex-col items-center justify-center p-8 text-center">
+            <h3 className="mb-1 text-sm font-semibold text-[rgb(var(--ec-page-text))]">Your catalog is empty</h3>
+            <p className="max-w-[220px] text-sm font-light leading-relaxed text-[rgb(var(--ec-page-text-muted))]">
+              Navigation will appear here when you add resources.{' '}
+              <a
+                href="https://www.eventcatalog.dev/docs/tutorial/install-eventcatalog"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="font-medium text-[rgb(var(--ec-accent))] hover:underline"
+              >
+                Add your first resource
+              </a>
+              .
             </p>
           </div>
         )}
 
-        {currentLevel.entries.length > 0 && renderEntries(currentLevel.entries)}
+        {hasVisibleEntries && renderEntries(currentLevel.entries)}
       </nav>
 
       {/* Animation keyframes */}