@flamingo-stack/openframe-frontend-core 0.0.296-snapshot.20260621021605 → 0.0.296

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.296-snapshot.20260621021605",
+  "version": "0.0.296",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -78,12 +78,6 @@
       "require": "./dist/components/contact/index.cjs",
       "default": "./dist/components/contact/index.js"
     },
-    "./components/case-studies": {
-      "types": "./dist/components/case-studies/index.d.ts",
-      "import": "./dist/components/case-studies/index.js",
-      "require": "./dist/components/case-studies/index.cjs",
-      "default": "./dist/components/case-studies/index.js"
-    },
     "./schemas/contact-schema": {
       "types": "./dist/schemas/contact-schema.d.ts",
       "import": "./dist/schemas/contact-schema.js",

package/src/components/chat/embeddable-chat.tsx

@@ -1127,7 +1127,7 @@ function EmbeddableChatInner({
   // falls back to the platform default here) — instead it sets a truthy baseRoute +
   // `chipBasePlatform` so doc chips with no externalUrl resolve cross-platform to that
   // platform's public knowledge hub (`getBaseUrl(chipBasePlatform)/knowledge-base/…`),
-  // exactly like the hub's openframe config (baseRoute:'/', chipBasePlatform:'openframe').
+  // exactly like the hub's openframe config (baseRoute:'/', chipBasePlatform:'flamingo').
   const resolvedBaseRoute =
     baseRoute || (source === 'flamingo' ? '/knowledge-base' : '/data-room')
 

package/src/components/docs/doc-viewer.tsx

@@ -2,10 +2,7 @@
 
 import React, { useMemo } from "react"
 import { MultiLevelNavigation, MobileNavigationDropdown } from "../navigation/multi-level-navigation"
-import { PageHeader } from "../layout/page-header"
-import { PageLayout } from "../layout/page-layout"
-import { PageShell } from "../layout/article-detail-layout"
-import { useRouter } from "../../embed-shims/next-navigation"
+import { PageHeading } from "../layout/page-heading"
 import { PersistentSidebar, PersistentMobileDropdown } from "../persistent-filter-controls"
 import { CategorySidebarSkeleton } from "../loading/page-layout-skeleton"
 import { DocSearchBar, useDocSearch } from "../shared/doc-search"
@@ -15,7 +12,6 @@ import { useScrollSpy } from "./use-scroll-spy"
 import { useDocNavigation } from "./doc-navigation-context"
 import { findDocNodeByPath } from "../../utils/doc-tree-nav"
 import type { DocContent, DocNode, DocRenderHandlers, DocSourceId } from "../../types/doc-source"
-import { useDocsResolveLink } from "./use-docs-resolve-link"
 
 /** Color tokens for the doc-viewer chrome. Hub-side `DocViewer` callers share
  *  this constant; no need to override per source — the palette is intentionally
@@ -34,7 +30,7 @@ export const DEFAULT_DOC_VIEWER_PALETTE = {
 export interface DocViewerProps {
   /**
    * Registry source id (`'openframe-docs'`, `'data-room-docs'`, …). Flowed through
-   * `renderContent`'s handlers for `/api/docs/resolve-link` POSTs.
+   * `renderContent`'s handlers for `/api/resolve-link` POSTs.
    */
   sourceId: DocSourceId
 
@@ -59,24 +55,7 @@ export interface DocViewerProps {
    */
   chatSource: string
 
-  /** Page title — rendered via the shared `<PageHeader>` primitive
-   *  so the doc-viewer chrome matches every other lib page
-   *  (DevSectionPage / LegalDocumentPage / OnboardingGuideDetailView)
-   *  pixel-for-pixel. ReactNode is intentionally not supported here —
-   *  every consumer renders the same typography. */
-  title?: string
-  /** Optional icon rendered inline before the title text — same slot
-   *  `<DevSectionView>`'s hero uses (Map for Roadmap, Rocket for Releases,
-   *  etc.). Pass a pre-rendered React element styled with
-   *  `SECTION_HERO_ICON_CLASS` (`h-10 w-10 text-ods-accent`) for visual
-   *  parity with other lib pages. */
-  titleIcon?: React.ReactNode
-  /** Subtitle (h6, secondary text) rendered beneath the title. */
-  subtitle?: string
-  /** Render a yellow accent dot (`.`) after the title — same flag as
-   *  the hub's legacy `<AdminPageHeader accentDot>` so the docs-hub
-   *  surface keeps its existing accent styling after the migration. */
-  accentDot?: boolean
+  title: string | React.ReactNode
   /** Override the default ODS palette. Optional — most callers should omit. */
   colorPalette?: typeof DEFAULT_DOC_VIEWER_PALETTE
   className?: string
@@ -95,17 +74,6 @@ export interface DocViewerProps {
   structureEndpoint?: string
   /** Same shape as `structureEndpoint`. Defaults to `/api/docs/sources/${sourceId}/content`. */
   contentEndpoint?: string
-  /** RAG-search endpoint that backs the in-source search bar (when `showAIChat`
-   *  is on). Defaults to `/api/docs/search`. Override for proxy-prefix embeds —
-   *  same injectability pattern as `structureEndpoint` / `contentEndpoint`. */
-  searchEndpoint?: string
-  /** POST internal-link resolver. The viewer threads an async `onResolveLink`
-   *  into `renderContent`'s `handlers` that posts `{ link, currentPath, source }`
-   *  here. Defaults to `/api/docs/resolve-link`. Override for proxy-prefix embeds —
-   *  same injectability pattern as `structureEndpoint` / `contentEndpoint` /
-   *  `searchEndpoint`, with `ChatRuntime.endpoints.docsResolveLinkUrl` as a
-   *  runtime fallback (prop → runtime → default). */
-  resolveLinkEndpoint?: string
   /** Base route path for URL navigation. */
   baseRoute: string
 
@@ -117,13 +85,6 @@ export interface DocViewerProps {
 
   /** Folder-index filename (default `'README.md'`). */
   folderIndexFile?: string
-
-  /** Back-button shown above the title. Mirrors `<DevSectionPage>` /
-   *  `<HelpCenterList>` / `<LegalDocumentPage>` so every embeddable surface
-   *  shares the same chrome. Defaults to `{ label: 'Back to home', href: '/' }`.
-   *  Pass `false` to hide; pass `{ href: '/docs' }` etc. when the embed's
-   *  home isn't `/`. */
-  backButton?: { label?: string; href?: string } | false
 }
 
 export function DocViewer(props: DocViewerProps) {
@@ -136,22 +97,16 @@ function DocViewerContent({
   renderSkeleton,
   chatSource,
   title,
-  titleIcon,
-  subtitle,
-  accentDot,
   colorPalette = DEFAULT_DOC_VIEWER_PALETTE,
   className = "",
   docPath,
   sidebarLabel = "DOCUMENTATION",
   structureEndpoint,
   contentEndpoint,
-  searchEndpoint,
-  resolveLinkEndpoint,
   baseRoute,
   emptyStateText,
   showAIChat = false,
   folderIndexFile,
-  backButton,
 }: DocViewerProps) {
   // Default endpoints derived from sourceId. Hub callers omit the props in 99%
   // of cases; the override is for embed contexts where the doc-viewer sits
@@ -160,13 +115,6 @@ function DocViewerContent({
     structureEndpoint ?? `/api/docs/sources/${sourceId}/structure`
   const resolvedContentEndpoint =
     contentEndpoint ?? `/api/docs/sources/${sourceId}/content`
-  // Resolve-link endpoint chain (prop → ChatRuntime.endpoints → hub default)
-  // + the full fetch + JSON-parse pipeline live in `useDocsResolveLink`.
-  // Keeping it factored out as a proper hook makes the contract reusable
-  // by any embedder rendering doc content outside `<DocViewer>` (custom
-  // markdown renderers, link-resolver previews, etc.) and keeps this
-  // component focused on layout + state.
-  const resolveLink = useDocsResolveLink(sourceId, resolveLinkEndpoint)
   const {
     structure,
     selectedPath,
@@ -191,23 +139,9 @@ function DocViewerContent({
   const { activeSection, handleSectionClick } = useScrollSpy(content?.sections)
 
   const docNav = useDocNavigation()
-
-  // Back-button config — mirrors `<DevSectionPage>` so the docs surface
-  // matches every other embeddable page's chrome. Default target is `/`
-  // (the embed's home); pass `backButton: false` to hide entirely, or
-  // override the href when the embed's home isn't `/`.
-  const router = useRouter()
-  const backCfg =
-    backButton === false
-      ? null
-      : {
-          label: backButton?.label ?? 'Back to home',
-          onClick: () => router.push(backButton?.href ?? '/'),
-        }
   const docSearch = useDocSearch({
     source: chatSource,
     baseRoute,
-    searchEndpoint,
     onNavigate: (path) => navigateToDoc(path, { fromInternalLink: true }),
     onInPageSwap: (path) => docNav.navigate(path),
   })
@@ -218,9 +152,8 @@ function DocViewerContent({
       onInternalLinkClick: navigateToDoc,
       currentPath: selectedPath,
       sourceId,
-      onResolveLink: resolveLink,
     })
-  }, [content, selectedPath, renderContent, navigateToDoc, sourceId, resolveLink])
+  }, [content, selectedPath, renderContent, navigateToDoc, sourceId])
 
   // Selected node's documentType drives:
   //   - which skeleton the caller renders during fetch (markdown vs embed)
@@ -259,32 +192,15 @@ function DocViewerContent({
   const resolvedEmptyText = emptyStateText || defaultEmptyText
 
   return (
-    // STRUCTURAL UNIFICATION: render through the IDENTICAL wrapper chain
-    // `<DevSectionPage>` uses (PageShell → PageLayout → `gap-10 flex-col`),
-    // not a hand-rolled custom container with similar-looking spacing.
-    // PageLayout owns the back-button row; the inner `gap-10` div +
-    // `<PageHeader noTopPadding noBottomMargin>` renders the title section
-    // the same way `<DevSectionView>`'s hero does. This is the only way to
-    // guarantee /knowledge-base sits at pixel-identical vertical rhythm to
-    // /roadmap / /releases / /onboarding-guides — same components, same DOM,
-    // not "same CSS classes that look similar on paper."
-    //
-    // `colorPalette` / `className` / `bgStyle` flow through PageShell's
-    // contentClassName + an inner style-passthrough wrapper so legacy
-    // palette overrides still apply (none in the codebase today; the API
-    // surface is preserved).
-    <PageShell contentClassName={`${bgClass} ${className}`}>
-      <div style={{ ...bgStyle, ...containerBgStyle }}>
-        <PageLayout backButton={backCfg ?? undefined}>
-          <div className="w-full flex flex-col gap-10">
-            <PageHeader
-              title={title}
-              titleIcon={titleIcon}
-              subtitle={subtitle}
-              accentDot={accentDot}
-              noTopPadding
-              noBottomMargin
-            />
+    <section className={`${bgClass} ${className}`} style={bgStyle}>
+      <div
+        className="max-w-[1920px] px-6 md:px-20 py-6 md:py-10 mx-auto"
+        style={containerBgStyle}
+      >
+        <div className="flex flex-col gap-6">
+          <div className="flex flex-col gap-4">
+            {typeof title === 'string' ? <PageHeading>{title}</PageHeading> : title}
+          </div>
 
           {showAIChat && (
             <DocSearchBar
@@ -355,16 +271,9 @@ function DocViewerContent({
               <div className="flex-1 min-w-0 w-full">
                 <div
                   className={`grid grid-cols-1 ${
-                    // "On this page" right column only makes sense for
-                    // MARKDOWN content (PDFs / Sheets / Figma / file have no
-                    // sections to navigate to). Gating the grid template on
-                    // `isMarkdownContent` also suppresses the section-skeleton
-                    // bars during embed loads — the user-reported "skeleton
-                    // shouldn't be on file pages" bug.
-                    isMarkdownContent &&
-                    ((showStickyNav && stickyNavSections.length > 0) ||
-                      isLoadingContent ||
-                      isLoadingStructure)
+                    (showStickyNav && stickyNavSections.length > 0) ||
+                    isLoadingContent ||
+                    isLoadingStructure
                       ? 'lg:grid-cols-[1fr_280px]'
                       : ''
                   } gap-8`}
@@ -383,7 +292,7 @@ function DocViewerContent({
                     </article>
                   </div>
 
-                  {isMarkdownContent && (isLoadingContent || isLoadingStructure) && (
+                  {(isLoadingContent || isLoadingStructure) && (
                     <div className="hidden lg:block">
                       <div className="sticky top-24">
                         <div className="h-[14px] w-28 bg-ods-border rounded animate-pulse mb-5" />
@@ -429,9 +338,8 @@ function DocViewerContent({
               </div>
             </div>
           )}
-          </div>
-        </PageLayout>
+        </div>
       </div>
-    </PageShell>
+    </section>
   )
 }

package/src/components/docs/index.ts

@@ -3,11 +3,6 @@
 export { DocViewer } from './doc-viewer'
 export type { DocViewerProps } from './doc-viewer'
 
-export { DocsHubPage } from './docs-hub-page'
-export type { DocsHubPageProps, DocumentTypeRenderers } from './docs-hub-page'
-
-export { MarkdownSkeleton, EmbedSkeleton } from './skeletons'
-
 export { useDocumentTree } from './use-document-tree'
 export type { UseDocumentTreeConfig } from './use-document-tree'
 
@@ -15,15 +10,3 @@ export { useScrollSpy } from './use-scroll-spy'
 
 export { DocNavigationProvider, useDocNavigation } from './doc-navigation-context'
 export type { DocNavigator } from './doc-navigation-context'
-
-// Re-export the doc-source types embedders need to implement the
-// `/api/docs/sources/[sourceId]/{structure,content}` + `/api/docs/resolve-link`
-// API contract.
-export type {
-  DocNode,
-  DocContent,
-  DocRenderHandlers,
-  DocSourceId,
-  DocumentType,
-  ResolveLinkResult,
-} from '../../types/doc-source'

package/src/components/docs/use-document-tree.ts

@@ -102,27 +102,6 @@ export function useDocumentTree(
     return () => window.removeEventListener('popstate', handlePopState)
   }, [normalizedBaseRoute, folderIndexFile])
 
-  // External-URL → state sync. The popstate listener above catches browser
-  // back/forward, but client-side routers (react-router, Next App Router…)
-  // change the URL via `history.pushState` which does NOT fire popstate.
-  // The host re-renders the viewer with a new `initialPath` prop instead, so
-  // we mirror the popstate logic here against the (memoized) `cleanInitialPath`.
-  // Without this, a chat-card click that soft-navigates via react-router
-  // updates the URL but the viewer stays on the previously-selected doc.
-  useEffect(() => {
-    if (cleanInitialPath === selectedPathRef.current) return
-    setSelectedPath(cleanInitialPath)
-    if (cleanInitialPath) {
-      const parentPath = cleanInitialPath.includes('/')
-        ? cleanInitialPath.substring(0, cleanInitialPath.lastIndexOf('/'))
-        : cleanInitialPath
-      setExpandedNodes(new Set(getDocAncestorNodeIds(parentPath)))
-    }
-    // Match popstate's scroll-to-content delay; the targeted content fetch
-    // dispatched by the selectedPath effect lands before this fires.
-    setTimeout(scrollToContent, 150)
-  }, [cleanInitialPath])
-
   useEffect(() => {
     if (!isInitialized) {
       // Kick off the speculative content fetch IN PARALLEL with the structure

package/src/components/embeds/embed-iframe.tsx

@@ -2,17 +2,19 @@
 
 import React, { useState, useCallback, useRef, useEffect } from 'react'
 
-/** Loading skeleton for iframe embeds — clean iframe-sized rectangle.
- *  Uses `bg-ods-card` (visible token) rather than `bg-ods-skeleton`
- *  which resolves to transparent in this build (the same gotcha
- *  documented in `chat-message-row.tsx`'s skeleton). No fake inner
- *  placeholder cruft — a real loading iframe shows a blank rectangle. */
+/** Loading skeleton for iframe embeds — matches project skeleton pattern */
 function EmbedLoadingSkeleton({ height }: { height?: string }) {
   return (
     <div
-      className="w-full rounded-lg border border-ods-border overflow-hidden bg-ods-card animate-pulse"
+      className="w-full rounded-lg border border-ods-border overflow-hidden bg-ods-skeleton animate-pulse"
       style={{ height: height || 'calc(100vh - 250px)' }}
-    />
+    >
+      <div className="flex flex-col items-center justify-center h-full gap-4">
+        <div className="w-12 h-12 rounded-lg bg-ods-card" />
+        <div className="h-4 w-48 rounded bg-ods-card" />
+        <div className="h-3 w-32 rounded bg-ods-card" />
+      </div>
+    </div>
   )
 }
 

package/src/components/embeds/index.ts

@@ -16,33 +16,3 @@ export type {
   OGData,
   BuildPlaceholderUrl,
 } from './og-link-preview'
-
-export { FileDownloadCard } from './file-download-card'
-export type { FileDownloadCardProps } from './file-download-card'
-
-// Satellite embeds wired into `<RichMarkdownRenderer>` (`components/ui`).
-// Exported individually so embedders can compose them outside the renderer
-// (e.g. a release page that wants a single reddit card without parsing
-// markdown). The runtime knobs (proxy endpoints, image transformer) are
-// shared via `RichMarkdownRuntimeProvider` — call sites that mount a
-// satellite directly should wrap with the provider when they need
-// overrides; otherwise the defaults match the hub's existing endpoints.
-export { RedditEmbedClient } from './reddit-embed-client'
-export { TwitterEmbedClient } from './twitter-embed-client'
-export { LinkedInEmbedClient } from './linkedin-embed-client'
-export { MarkdownImage } from './markdown-image'
-export {
-  EmbedContainer,
-  YouTubeContainer,
-  TwitterContainer,
-  RedditContainer,
-  LinkPreviewContainer,
-  LinkedInContainer,
-  EMBED_SIZES,
-  type EmbedSize,
-} from './embed-container'
-export {
-  RichMarkdownRuntimeProvider,
-  useRichMarkdownRuntime,
-  type RichMarkdownRuntime,
-} from './rich-markdown-runtime'

package/src/components/embeds/og-link-preview.tsx

@@ -262,34 +262,34 @@ export const OGLinkPreview: React.FC<OGLinkPreviewProps> = ({
   const renderSkeleton = () => isCompact ? (
     <div className="my-4">
       <div className="flex flex-row border border-ods-border rounded-lg overflow-hidden bg-ods-card h-[120px]">
-        <div className="w-[200px] h-full flex-shrink-0 bg-ods-border animate-pulse" />
+        <div className="w-[200px] h-full flex-shrink-0 bg-ods-skeleton animate-pulse" />
         <div className="flex-1 p-3 flex flex-col justify-center">
-          <div className="bg-ods-border rounded animate-pulse h-4 w-3/4 mb-2" />
-          <div className="bg-ods-border rounded animate-pulse h-3 w-full mb-1" />
-          <div className="bg-ods-border rounded animate-pulse h-3 w-2/3 mb-2" />
-          <div className="bg-ods-border rounded animate-pulse h-3 w-1/3" />
+          <div className="bg-ods-skeleton rounded animate-pulse h-4 w-3/4 mb-2" />
+          <div className="bg-ods-skeleton rounded animate-pulse h-3 w-full mb-1" />
+          <div className="bg-ods-skeleton rounded animate-pulse h-3 w-2/3 mb-2" />
+          <div className="bg-ods-skeleton rounded animate-pulse h-3 w-1/3" />
         </div>
       </div>
     </div>
   ) : (
     <div className="my-6">
       <div className="block border border-ods-border rounded-lg overflow-hidden bg-ods-card">
-        <div className="aspect-video w-full bg-ods-border overflow-hidden relative animate-pulse" />
+        <div className="aspect-video w-full bg-ods-skeleton overflow-hidden relative animate-pulse" />
         <div className="p-4">
           <div className="flex items-start gap-3">
-            <div className="w-6 h-6 bg-ods-border rounded flex-shrink-0 mt-0.5 animate-pulse" />
+            <div className="w-6 h-6 bg-ods-skeleton rounded flex-shrink-0 mt-0.5 animate-pulse" />
             <div className="flex-1 min-w-0">
               <div className="h-[2.5rem] leading-[1.25rem] mb-2 overflow-hidden">
-                <div className="bg-ods-border rounded animate-pulse" style={{ height: '1.25rem', marginBottom: '0.25rem' }} />
-                <div className="bg-ods-border rounded animate-pulse w-3/4" style={{ height: '1.25rem' }} />
+                <div className="bg-ods-skeleton rounded animate-pulse" style={{ height: '1.25rem', marginBottom: '0.25rem' }} />
+                <div className="bg-ods-skeleton rounded animate-pulse w-3/4" style={{ height: '1.25rem' }} />
               </div>
               <div className="h-[2.5rem] leading-[1.25rem] mb-2 overflow-hidden">
-                <div className="bg-ods-border rounded animate-pulse" style={{ height: '1.25rem', marginBottom: '0.25rem' }} />
-                <div className="bg-ods-border rounded animate-pulse w-5/6" style={{ height: '1.25rem' }} />
+                <div className="bg-ods-skeleton rounded animate-pulse" style={{ height: '1.25rem', marginBottom: '0.25rem' }} />
+                <div className="bg-ods-skeleton rounded animate-pulse w-5/6" style={{ height: '1.25rem' }} />
               </div>
               <div className="flex items-center gap-2">
-                <div className="bg-ods-border rounded animate-pulse" style={{ height: '0.75rem', width: '6rem' }} />
-                <div className="bg-ods-border rounded animate-pulse" style={{ height: '0.75rem', width: '5rem' }} />
+                <div className="bg-ods-skeleton rounded animate-pulse" style={{ height: '0.75rem', width: '6rem' }} />
+                <div className="bg-ods-skeleton rounded animate-pulse" style={{ height: '0.75rem', width: '5rem' }} />
               </div>
             </div>
           </div>

package/src/components/layout/page-layout.tsx

@@ -10,11 +10,6 @@ export interface PageLayoutProps {
   children: React.ReactNode
   title?: string
   subtitle?: string
-  /** Inline icon rendered before the title text — forwarded to
-   *  TitleBlock/PageHeader. Same shape as DevSectionPage's hero icon. */
-  titleIcon?: React.ReactNode
-  /** Yellow accent dot after the title — forwarded to TitleBlock/PageHeader. */
-  accentDot?: boolean
   image?: { src: string; alt?: string }
   backButton?: { label?: string; onClick: () => void }
   actions?: PageActionButton[]
@@ -38,8 +33,6 @@ export function PageLayout({
   children,
   title,
   subtitle,
-  titleIcon,
-  accentDot,
   image,
   backButton,
   actions,
@@ -53,16 +46,14 @@ export function PageLayout({
 }: PageLayoutProps) {
   const hasActions = actions && actions.length > 0
   const needsBottomPadding = hasActions && actionsVariant === 'primary-buttons'
-  const hasHeader = showHeader && (title || subtitle || titleIcon || image || backButton || hasActions || selector)
+  const hasHeader = showHeader && (title || subtitle || image || backButton || hasActions || selector)
 
   return (
     <div className={cn('flex flex-col w-full', className)}>
       {hasHeader && (
         <TitleBlock
           title={title}
-          titleIcon={titleIcon}
           subtitle={subtitle}
-          accentDot={accentDot}
           image={image}
           backButton={backButton}
           actions={actions}
@@ -83,8 +74,4 @@ export function PageLayout({
 export type { PageActionButton } from '../ui/page-actions'
 export { TitleBlock } from './title-block'
 export type { TitleBlockProps } from './title-block'
-export { PageHeader } from './page-header'
-export type { PageHeaderProps } from './page-header'
-export { PageWithHeader } from './page-with-header'
-export type { PageWithHeaderProps } from './page-with-header'
 export default PageLayout

package/src/components/layout/title-block.tsx

@@ -1,29 +1,15 @@
 'use client'
 
 import React from 'react'
+import { cn } from '../../utils/cn'
 import type { ActionsMenuGroup } from '../ui/actions-menu'
+import { EntityImage } from '../ui/entity-image'
 import { PageActions, type PageActionButton } from '../ui/page-actions'
-import { PageHeader } from './page-header'
+import { BackButton } from './back-button'
 
-/**
- * `<TitleBlock>` — thin adapter over `<PageHeader>` that turns the
- * `actions: PageActionButton[]` / `menuActions` / `selector` API into
- * a `ReactNode` slot that PageHeader can render. Kept as a separate
- * component for backwards compatibility (`PageLayout` consumes it,
- * external callers may too) — all the DOM/CSS lives in PageHeader.
- *
- * If a new consumer doesn't need the `PageActions` wiring, prefer
- * `<PageHeader>` directly.
- */
 export interface TitleBlockProps {
   title?: string
   subtitle?: string
-  /** Inline icon rendered before the title text (e.g. HelpCircle on /faqs,
-   *  BookOpen on /knowledge-base, Map on /roadmap). Forwarded verbatim to
-   *  `<PageHeader>`. */
-  titleIcon?: React.ReactNode
-  /** Yellow accent dot after the title — same flag as PageHeader. */
-  accentDot?: boolean
   image?: { src: string; alt?: string }
   backButton?: { label?: string; onClick: () => void }
   actions?: PageActionButton[]
@@ -43,8 +29,6 @@ export interface TitleBlockProps {
 export function TitleBlock({
   title,
   subtitle,
-  titleIcon,
-  accentDot,
   image,
   backButton,
   actions,
@@ -56,29 +40,67 @@ export function TitleBlock({
 }: TitleBlockProps) {
   const hasActions = actions && actions.length > 0
   const hasMenuActions = !!menuActions && menuActions.some(g => g.items.length > 0)
-  const hasActionsSlot = hasActions || hasMenuActions || !!selector
-
-  const actionsNode = hasActionsSlot ? (
-    <PageActions
-      variant={actionsVariant}
-      actions={actions ?? []}
-      menuActions={menuActions}
-      selector={selector}
-    />
-  ) : undefined
 
   return (
-    <PageHeader
-      title={title}
-      titleIcon={titleIcon}
-      subtitle={subtitle}
-      accentDot={accentDot}
-      image={image}
-      backButton={backButton}
-      actions={actionsNode}
-      variant={variant}
-      className={className}
-    />
+    <div
+      className={cn(
+        'flex items-end justify-between gap-[var(--spacing-system-m)]',
+        'md:flex-col md:items-start md:justify-start lg:flex-row lg:items-end lg:justify-between',
+        'pt-[var(--spacing-system-l)]',
+        variant === 'card'
+          ? cn(
+              'bg-ods-card border-b border-ods-border',
+              'px-[var(--spacing-system-l)] pb-[var(--spacing-system-l)]',
+              'md:bg-transparent md:border-b-0',
+              'md:px-0 md:pb-0',
+              'md:mb-[var(--spacing-system-l)]',
+            )
+          : 'mb-[var(--spacing-system-l)]',
+        className,
+      )}
+    >
+      <div className="flex flex-col gap-[var(--spacing-system-xs)] flex-1 min-w-0">
+        {backButton && (
+          <BackButton
+            onClick={backButton.onClick}
+            label={backButton.label}
+            className="hidden md:inline-flex"
+          />
+        )}
+        {(image || subtitle) ? (
+          <div className="flex items-center gap-[var(--spacing-system-m)] min-w-0 w-full">
+            {image && (
+              <EntityImage
+                src={image.src}
+                alt={image.alt}
+                fallbackText={image.alt || title}
+              />
+            )}
+            <div className="flex flex-col justify-center min-w-0 flex-1">
+              {title && (
+                <h1 className="text-h2 text-ods-text-primary truncate" title={title}>{title}</h1>
+              )}
+              {subtitle && (
+                <p className="text-h6 text-ods-text-secondary truncate" title={subtitle}>{subtitle}</p>
+              )}
+            </div>
+          </div>
+        ) : (
+          title && <h1 className="text-h2 text-ods-text-primary">{title}</h1>
+        )}
+      </div>
+
+      {(hasActions || hasMenuActions || selector) && (
+        <div className="flex gap-2 items-center shrink-0">
+          <PageActions
+            variant={actionsVariant}
+            actions={actions ?? []}
+            menuActions={menuActions}
+            selector={selector}
+          />
+        </div>
+      )}
+    </div>
   )
 }
 

package/src/components/onboarding-guides/onboarding-guide-detail-view.tsx

@@ -29,7 +29,7 @@ import { EntityVideoSection } from '../features/entity-video-section'
 import { VideoBitesDisplay } from '../features/video-bites-display'
 import { useVideoWarmup } from '../features/use-video-warmup'
 import { getCaptionsUrl } from '../features/captions-url'
-import { RichMarkdownRenderer } from '../ui/rich-markdown-renderer'
+import { SimpleMarkdownRenderer } from '../ui/simple-markdown-renderer'
 import { EntityTagBadges } from '../features/entity-tag-badges'
 import { LoadError } from '../ui/error-state'
 import { ArticleAuthorByline } from '../shared/article-author-byline'
@@ -62,7 +62,7 @@ export interface OnboardingGuideDetailViewProps {
    *  byline renders nothing below the name when the bio is empty. */
   fallbackBio?: string | null
   /** Optional markdown renderer override. Defaults to lib
-   *  `<RichMarkdownRenderer>`. */
+   *  `<SimpleMarkdownRenderer>`. */
   MarkdownRenderer?: ComponentType<{ content: string }>
   /** Optional per-row related-card renderer override. */
   renderRelatedCard?: (guide: OnboardingGuide) => ReactNode
@@ -83,7 +83,7 @@ export function OnboardingGuideDetailView({
   slug,
   guideEndpoint,
   related = [],
-  MarkdownRenderer = RichMarkdownRenderer,
+  MarkdownRenderer = SimpleMarkdownRenderer,
   renderRelatedCard,
   backHref,
   backLabel = 'Back to Getting Started',