@flamingo-stack/openframe-frontend-core 0.0.764 → 0.0.766

package/src/components/faq/faq-section.tsx

@@ -12,10 +12,11 @@ import { serializeJsonLd } from '../../utils/common';
 import { faqSectionSlug, parseFaqHash, type FaqHashTarget } from '../../utils/faq-anchor';
 import { navigateSamePageHash, STICKY_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav';
 import { buildSuggestionUrl } from '../../utils/suggestion-url';
-import { FaqAccordion, type FaqItem } from '../faq-accordion';
+import { FAQ_ACCORDION_SKELETON_ROWS, FaqAccordion, FaqAccordionSkeleton, type FaqItem } from '../faq-accordion';
 import { SECTION_HEADING_CLASS } from '../layout/page-heading';
 import { LoadingRegion } from '../loading/loading-region';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { TextLineSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from '../ui/loading-scope';
 import { FaqAskCard, faqAskCardShown, type FaqAskOptions } from './faq-ask-card';
 import { buildFaqJsonLdFromFaqs, type FaqSchemaOptions } from './json-ld';
 
@@ -87,10 +88,136 @@ export interface FaqSectionProps {
    * (`onOpen`). An `aside` takes the card's place.
    */
   ask?: false | FaqAskOptions;
+  /**
+   * The loading state's groups of questions, in order: THE one way to say what the skeleton draws (see
+   * `FaqSkeletonShape`). Absent: one group with no category heading, of `minResults` rows (else one screen of rows).
+   */
+  skeletonShape?: FaqSkeletonShape;
+  /**
+   * The host's FAQs fall into named categories, so the loaded block draws its category nav (the platform's full,
+   * categorised list): the loading state draws the nav's row too, so what follows it (the ask card) does not move.
+   * Default false (a nav only when `skeletonShape` names two or more categories).
+   */
+  skeletonNav?: boolean;
 }
 
 const DEFAULT_HEADING_TEXT = 'Frequently Asked Questions';
 
+/** The block's layout, read by the block and by its skeleton, so the skeleton is the block's size. */
+const SECTION_DEFAULT_CLASS = 'space-y-10';
+/** The nav's gap to its neighbour, inside the nav's own wrapper (padding), so the nav takes its gap with it. */
+const NAV_ABOVE_QUESTIONS_CLASS = 'pb-8';
+const NAV_BELOW_HEADING_CLASS = 'pt-8';
+const QUESTIONS_STACK_CLASS = 'space-y-10';
+// `grid-cols-1` (a `minmax(0, 1fr)` track): one column never grows to a child's content width (the nav skeleton's
+// one-line pill row is wider than a phone).
+const ASIDE_GRID_CLASS =
+  'grid grid-cols-1 gap-10 content-lg:grid-cols-[minmax(0,1fr)_minmax(0,2fr)] content-lg:grid-rows-[auto_1fr] content-lg:gap-x-16';
+const ASIDE_QUESTIONS_CELL_CLASS = 'content-lg:col-start-2 content-lg:row-span-2 content-lg:row-start-1';
+const ASIDE_CELL_CLASS = 'content-lg:col-start-1 content-lg:row-start-2';
+const TOPIC_STACK_CLASS = 'space-y-1';
+const TOPIC_CLASS = 'text-ods-text-muted text-h6';
+const CATEGORY_NAV_CLASS = 'flex flex-wrap gap-2';
+/**
+ * The nav's row while the categories are read (`skeletonNav`): which categories there are, and how many, is read data,
+ * so the skeleton draws ONE line of pills, the pills that do not fit cut off at its edge (never wrapped to a second
+ * line). `FAQ_NAV_SKELETON_PILLS` is more than the widest column holds on one line.
+ */
+const CATEGORY_NAV_SKELETON_LINE_CLASS = 'flex min-w-0 flex-nowrap gap-2 overflow-hidden';
+const FAQ_NAV_SKELETON_PILLS = 8;
+const CATEGORY_PILL_CLASS = 'rounded-full border px-4 py-2 transition-colors text-h6';
+const CATEGORY_SECTION_CLASS = 'scroll-mt-24';
+/**
+ * A category's heading, with the gap to its questions inside its own box (padding, not the group's spacing): only a
+ * named group has one, so it is the group's optional part (`data-loading-optional`) and takes its gap with it, unless
+ * the host declared its FAQs categorised (`skeletonNav`): then every group it draws is named, loading and loaded.
+ */
+const CATEGORY_HEADING_CLASS = cn(SECTION_HEADING_CLASS, 'pb-4');
+/** Questions the block's skeleton draws when the host states no count (`minResults`): one screen of the accordion's rows. */
+export const FAQ_SECTION_SKELETON_QUESTIONS = FAQ_ACCORDION_SKELETON_ROWS;
+
+/** One group of questions the FAQ's loading state draws. */
+export interface FaqSkeletonGroup {
+  /** The group is a named category: drawn with its heading bar (and counted for the category nav). Default false. */
+  heading?: boolean;
+  /** Question rows the group draws. Default `FAQ_SECTION_SKELETON_QUESTIONS`, one screen of rows. */
+  rows?: number;
+}
+
+/**
+ * What the FAQ's loading state draws, group by group in order: the one shape `FaqSection`, `FaqSectionSkeleton`,
+ * `FaqDocumentPage` and `TrustCenterPage` take. Stated by the host from what it knows before the read (its FAQs are
+ * filed in categories, the server's page size), never copied from today's FAQs.
+ */
+export type FaqSkeletonShape = readonly FaqSkeletonGroup[];
+
+/**
+ * The block's arrangement, for the loaded list and its skeleton alike: without an aside the category nav above the
+ * questions; with one, heading and nav in a left column, questions on the right, the aside under the left column.
+ */
+function FaqLayout({
+  heading,
+  nav,
+  navDeclared = false,
+  questions,
+  aside,
+}: {
+  heading?: React.ReactNode;
+  nav?: React.ReactNode;
+  /** The host states its FAQs are categorised (`skeletonNav`): the nav is drawn loading and loaded, never optional. */
+  navDeclared?: boolean;
+  questions: React.ReactNode;
+  aside?: React.ReactNode;
+}) {
+  // The category nav is drawn only when the FAQs fall into two or more categories: a part of the record
+  // (`data-loading-optional`), carrying its own gap, unless the host declared it (`navDeclared`).
+  const optional = navDeclared ? undefined : true;
+  if (!aside) {
+    return (
+      <div>
+        {nav && (
+          <div className={NAV_ABOVE_QUESTIONS_CLASS} data-loading-optional={optional}>
+            {nav}
+          </div>
+        )}
+        {questions}
+      </div>
+    );
+  }
+  // One instance of each block, placed by the grid: questions second in the
+  // document (and on a narrow area), in the right column from `lg`.
+  return (
+    <div className={ASIDE_GRID_CLASS}>
+      <div>
+        {heading}
+        {nav && (
+          <div className={NAV_BELOW_HEADING_CLASS} data-loading-optional={optional}>
+            {nav}
+          </div>
+        )}
+      </div>
+      <div className={ASIDE_QUESTIONS_CELL_CLASS}>{questions}</div>
+      <div className={ASIDE_CELL_CLASS}>{aside}</div>
+    </div>
+  );
+}
+
+/** The heading above the questions: the host's node (or the default `<h2>`), with the topic's bare name under it. */
+function faqHeadingNode(heading: React.ReactNode | null | undefined, showTopic: boolean, topic?: string) {
+  // `undefined` → default <h2> title; `null` → the host page owns the <h1>, so no title renders here.
+  const titleNode = heading === undefined ? <h2 className={SECTION_HEADING_CLASS}>{DEFAULT_HEADING_TEXT}</h2> : heading;
+  if (!(showTopic && topic)) return titleNode;
+  // The host's heading may arrive from a server component, still streaming: React cannot check such a
+  // node when it sits in a list of siblings and warns about a missing key. So it is the ONLY child of its
+  // own wrapper, and the two siblings here are this component's own elements.
+  return (
+    <div className={TOPIC_STACK_CLASS}>
+      <div>{titleNode}</div>
+      <p className={TOPIC_CLASS}>{topic}</p>
+    </div>
+  );
+}
+
 /** The id of a page's own FAQ block: what a page's "FAQ" link or section nav points at. */
 export const PAGE_FAQ_SECTION_ID = 'faq';
 
@@ -193,7 +320,10 @@ function GroupedFaqList({
   categoryHeadingAs,
   heading,
   aside,
+  navDeclared,
 }: {
+  /** The host declared the category nav (`skeletonNav`). */
+  navDeclared?: boolean;
   /** With `aside`, the section heading: it sits in the left column above the category nav. */
   heading?: React.ReactNode;
   aside?: React.ReactNode;
@@ -348,7 +478,7 @@ function GroupedFaqList({
   }, []);
 
   const categoryNav = navGroups.length > 1 && (
-    <nav aria-label="FAQ categories" className="flex flex-wrap gap-2">
+    <nav aria-label="FAQ categories" className={CATEGORY_NAV_CLASS}>
       {navGroups.map(group => {
         const isActive = group.slug === activeSlug;
         return (
@@ -358,7 +488,7 @@ function GroupedFaqList({
             aria-current={isActive ? 'true' : undefined}
             onClick={e => handleJump(e, group.slug as string)}
             className={cn(
-              'rounded-full border px-4 py-2 transition-colors text-h6',
+              CATEGORY_PILL_CLASS,
               isActive
                 ? 'border-ods-text-primary bg-ods-card text-ods-text-primary'
                 : 'border-ods-border bg-ods-card text-ods-text-secondary hover:border-ods-text-secondary hover:text-ods-text-primary',
@@ -371,12 +501,21 @@ function GroupedFaqList({
     </nav>
   );
   const questions = (
-    <div className="space-y-10">
+    <div className={QUESTIONS_STACK_CLASS}>
       {groups.map(group => {
         const key = groupKey(group);
         return (
-          <section key={key} id={group.slug ?? undefined} className="scroll-mt-24 space-y-4">
-            {group.section && <CategoryHeading className={SECTION_HEADING_CLASS}>{group.section}</CategoryHeading>}
+          // A category is a record's group: how many there are is the data's (`data-loading-item`, like a list row).
+          <section key={key} id={group.slug ?? undefined} className={CATEGORY_SECTION_CLASS} data-loading-item>
+            {/* Only a named group has a heading (the uncategorized one has none): a part of the record, not of every group. */}
+            {group.section && (
+              <CategoryHeading
+                className={CATEGORY_HEADING_CLASS}
+                data-loading-optional={navDeclared ? undefined : true}
+              >
+                {group.section}
+              </CategoryHeading>
+            )}
             <FaqAccordion
               // Re-key on item-hash changes so the remount picks up the new
               // `defaultOpenIds` (the accordion is uncontrolled). Stable for
@@ -391,47 +530,8 @@ function GroupedFaqList({
     </div>
   );
 
-  if (!aside) {
-    return (
-      <div className="space-y-8">
-        {categoryNav}
-        {questions}
-      </div>
-    );
-  }
-
-  // One instance of each block, placed by the grid: questions second in the
-  // document (and on a narrow area), in the right column from `lg`.
   return (
-    <div className="grid gap-10 content-lg:grid-cols-[minmax(0,1fr)_minmax(0,2fr)] content-lg:grid-rows-[auto_1fr] content-lg:gap-x-16">
-      <div className="space-y-8">
-        {heading}
-        {categoryNav}
-      </div>
-      <div className="content-lg:col-start-2 content-lg:row-span-2 content-lg:row-start-1">{questions}</div>
-      <div className="content-lg:col-start-1 content-lg:row-start-2">{aside}</div>
-    </div>
-  );
-}
-
-function FaqSkeleton({
-  region = true,
-}: {
-  /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
-  region?: boolean;
-} = {}) {
-  return (
-    <LoadingRegion label="Loading questions" announce={region} className="space-y-8">
-      <UnifiedSkeleton className="h-12 w-2/3 rounded content-md:h-14" />
-      <div className="w-full divide-y divide-ods-border overflow-hidden rounded-md border border-ods-border bg-transparent">
-        {Array.from({ length: 8 }).map((_, idx) => (
-          <div key={idx} className="flex items-center justify-between gap-6 px-6 py-4 content-md:gap-10">
-            <UnifiedSkeleton className="h-6 w-5/6 rounded" />
-            <UnifiedSkeleton className="size-6 rounded" />
-          </div>
-        ))}
-      </div>
-    </LoadingRegion>
+    <FaqLayout heading={heading} nav={categoryNav} navDeclared={navDeclared} questions={questions} aside={aside} />
   );
 }
 
@@ -473,8 +573,11 @@ export function FaqSection({
   apiBaseUrl = '',
   aside: asideProp,
   ask,
+  skeletonShape,
+  skeletonNav = false,
 }: FaqSectionProps) {
   const assistant = useAssistantRuntime();
+  const inScope = useLoadingScope();
   // The host's own block wins; else the card, where a chat is there to open and the FAQ has a topic
   // (an empty topic is no topic, as the questions request reads it).
   const askTopic = ask === false ? undefined : ask?.topic || topic || entityType;
@@ -488,7 +591,8 @@ export function FaqSection({
     () => (initialFaqs ? { faqs: initialFaqs } : undefined),
     [initialFaqs],
   );
-  const { data, dataUrl, isLoading, error } = useSelfFetch<FaqsResponse>(url, { initialData });
+  // A loading scope fetches nothing.
+  const { data, dataUrl, isLoading, error } = useSelfFetch<FaqsResponse>(inScope ? null : url, { initialData });
 
   // Only the answer for THIS url: while another topic's questions load, the
   // previous topic's are not this page's. Memoised because the `??` fallback
@@ -499,46 +603,42 @@ export function FaqSection({
   // Grouped before the early returns so the hook order stays stable.
   const groups = useMemo(() => (faqs.length > 0 ? groupFaqsBySection(faqs) : []), [faqs]);
 
-  // `undefined` → default <h2> title; `null` → the host page owns the <h1>, so
-  // no title renders here. `heading === null` also makes the category headings
-  // <h2> (directly under the page <h1>); otherwise they nest as <h3>.
-  const titleNode = heading === undefined ? <h2 className={SECTION_HEADING_CLASS}>{DEFAULT_HEADING_TEXT}</h2> : heading;
-  const headingNode =
-    showTopic && topic ? (
-      // The host's heading may arrive from a server component, still streaming: React cannot check such a
-      // node when it sits in a list of siblings and warns about a missing key. So it is the ONLY child of its
-      // own wrapper, and the two siblings here are this component's own elements.
-      <div className="space-y-1">
-        <div>{titleNode}</div>
-        <p className="text-ods-text-muted text-h6">{topic}</p>
-      </div>
-    ) : (
-      titleNode
-    );
+  // `heading === null` also makes the category headings <h2> (directly under the page <h1>); otherwise they nest
+  // as <h3>.
+  const headingNode = faqHeadingNode(heading, showTopic, topic);
 
   // Degrade silently — never show an error banner or an empty section shell
   // where FAQs would be (host pages and the standalone surface both rely on it).
   if (error) return null;
-  if (!isLoading && faqs.length === 0) return null;
-  if (isLoading && faqs.length === 0) {
+  // In a loading scope, or while its own request is unanswered, the block is its skeleton.
+  if (inScope || (isLoading && faqs.length === 0)) {
     return (
-      <div className={className}>
-        <FaqSkeleton />
-      </div>
+      <FaqSectionSkeleton
+        heading={heading}
+        topic={topic}
+        showTopic={showTopic}
+        aside={aside}
+        shape={skeletonShape ?? [{ rows: minResults }]}
+        navRow={skeletonNav}
+        className={className}
+        id={id}
+      />
     );
   }
+  if (faqs.length === 0) return null;
 
   const schema = emitJsonLd ? buildFaqJsonLdFromFaqs(faqs, jsonLd) : null;
 
   return (
     <>
-      <section id={id} data-faq-topic={topic} className={className ?? 'space-y-10'}>
+      <section id={id} data-faq-topic={topic} className={className ?? SECTION_DEFAULT_CLASS}>
         {!aside && headingNode}
         <GroupedFaqList
           groups={groups}
           categoryHeadingAs={heading === null ? 'h2' : 'h3'}
           heading={aside ? headingNode : undefined}
           aside={aside}
+          navDeclared={skeletonNav}
         />
       </section>
       {schema && (
@@ -552,3 +652,82 @@ export function FaqSection({
     </>
   );
 }
+
+export interface FaqSectionSkeletonProps extends Pick<
+  FaqSectionProps,
+  'heading' | 'topic' | 'showTopic' | 'aside' | 'className' | 'id'
+> {
+  /** The groups drawn, in order. Default one group with no heading, of one screen of rows. */
+  shape?: FaqSkeletonShape;
+  /** Draw the category nav's row (one line of pills) whatever `sections` is: the host's FAQs are categorised. */
+  navRow?: boolean;
+}
+
+/**
+ * The FAQ block while its questions are read: the heading (the host's node, or "Frequently Asked Questions") and the
+ * topic line real, the aside (the ask card, which draws its own loading state) in its place, then the `shape`'s groups:
+ * a named one with its heading bar (two or more named ones draw the nav's pills), each its question rows, as bars.
+ */
+const DEFAULT_SKELETON_SHAPE: FaqSkeletonShape = [{}];
+
+export function FaqSectionSkeleton({
+  heading,
+  topic,
+  showTopic = false,
+  aside,
+  shape = DEFAULT_SKELETON_SHAPE,
+  navRow = false,
+  className,
+  id,
+}: FaqSectionSkeletonProps) {
+  const headingNode = faqHeadingNode(heading, showTopic, topic);
+  const CategoryHeading = heading === null ? 'h2' : 'h3';
+  const groups = shape.length > 0 ? shape : DEFAULT_SKELETON_SHAPE;
+  const named = groups.filter(group => group.heading).length;
+  const pill = (i: number) => (
+    // biome-ignore lint/suspicious/noArrayIndexKey: skeleton pills never reorder
+    <span key={i} className={cn(CATEGORY_PILL_CLASS, 'shrink-0 border-ods-border bg-ods-card')}>
+      <TextLineSkeleton type="inherit" as="span" className="w-24" />
+    </span>
+  );
+  const nav = navRow ? (
+    <div className={CATEGORY_NAV_SKELETON_LINE_CLASS} aria-hidden>
+      {Array.from({ length: FAQ_NAV_SKELETON_PILLS }, (_, i) => pill(i))}
+    </div>
+  ) : named > 1 ? (
+    <div className={CATEGORY_NAV_CLASS} aria-hidden>
+      {Array.from({ length: named }, (_, i) => pill(i))}
+    </div>
+  ) : undefined;
+  const questions = (
+    <div className={QUESTIONS_STACK_CLASS}>
+      {groups.map((group, index) => {
+        return (
+          // biome-ignore lint/suspicious/noArrayIndexKey: skeleton groups never reorder
+          <section key={index} className={CATEGORY_SECTION_CLASS} data-loading-item>
+            {group.heading && (
+              <CategoryHeading className={CATEGORY_HEADING_CLASS} data-loading-optional={navRow ? undefined : true}>
+                <TextLineSkeleton type="inherit" as="span" className="w-1/3" />
+              </CategoryHeading>
+            )}
+            <FaqAccordionSkeleton count={Math.max(1, group.rows ?? FAQ_SECTION_SKELETON_QUESTIONS)} />
+          </section>
+        );
+      })}
+    </div>
+  );
+  return (
+    <LoadingRegion label="Loading questions">
+      <section id={id} data-faq-topic={topic} className={className ?? SECTION_DEFAULT_CLASS}>
+        {!aside && headingNode}
+        <FaqLayout
+          heading={aside ? headingNode : undefined}
+          nav={nav}
+          navDeclared={navRow}
+          questions={questions}
+          aside={aside}
+        />
+      </section>
+    </LoadingRegion>
+  );
+}

package/src/components/faq/index.ts

@@ -9,6 +9,17 @@
 //
 // (Server-safe subpath is wired in tsup.config.ts under the server/universal
 // block and exposed via "./components/faq/json-ld" in package.json#exports.)
-export { FaqSection, PAGE_FAQ_SECTION_ID, pageFaqProps, type FaqSectionProps, type PageFaqSlot } from './faq-section';
+export {
+  FaqSection,
+  FaqSectionSkeleton,
+  FAQ_SECTION_SKELETON_QUESTIONS,
+  PAGE_FAQ_SECTION_ID,
+  pageFaqProps,
+  type FaqSectionProps,
+  type FaqSectionSkeletonProps,
+  type FaqSkeletonGroup,
+  type FaqSkeletonShape,
+  type PageFaqSlot,
+} from './faq-section';
 export { FaqDocumentPage, type FaqDocumentPageProps } from './faq-document-page';
 export { FaqAskCard, type FaqAskOptions } from './faq-ask-card';

package/src/components/faq-accordion.tsx

@@ -4,6 +4,8 @@ import { useState } from 'react';
 import { cn } from '../utils/cn';
 import { faqItemAnchor } from '../utils/faq-anchor';
 import { Chevron02DownIcon } from './icons-v2-generated/arrows/chevron-02-down-icon';
+import { TextLineSkeleton } from './loading/unified-skeleton';
+import { useLoadingScope } from './ui/loading-scope';
 
 export interface FaqItem {
   id: number | string;
@@ -16,8 +18,30 @@ interface FaqAccordionProps {
   defaultOpenIds?: (number | string)[];
 }
 
+/** The accordion's layout, read by the accordion and by its skeleton, so the skeleton is the accordion's size. */
+const ACCORDION_FRAME_CLASS =
+  'divide-y divide-ods-border overflow-hidden rounded-md border border-ods-border bg-transparent';
+const ROW_HEADER_CLASS = 'flex w-full items-center gap-6 px-6 py-4 text-left content-md:gap-10';
+const QUESTION_CLASS = 'min-w-0 flex-1 break-words';
+const CHEVRON_CLASS = 'shrink-0 text-ods-text-primary';
+/**
+ * Rows the accordion's skeleton draws when not told how many: one screen of closed rows, from the row's layout. A
+ * closed row is `py-4` around one `text-h3` line from `content-md` (57px with its divider: 13 under a 900px desktop
+ * viewport once the block's heading sits above them) and about one and a half lines on a phone (about 62px: 12 under
+ * an 844px one). 12 fills the first screen at both widths without drawing a second.
+ */
+export const FAQ_ACCORDION_SKELETON_ROWS = 12;
+/**
+ * Whether a skeleton row's question takes two lines on a phone (one from `content-md`, where a question fits a line).
+ * Typically about every other question wraps on a phone: the skeleton alternates, starting with a wrapping row.
+ */
+const wrapsOnPhone = (index: number) => index % 2 === 0;
+
 export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps) {
   const [openSet, setOpenSet] = useState<Set<string | number>>(new Set(defaultOpenIds));
+  // In a loading scope the items are the empty record: the accordion is its skeleton.
+  const loading = useLoadingScope();
+  if (loading) return <FaqAccordionSkeleton count={items.length || undefined} />;
 
   const toggle = (id: string | number) => {
     setOpenSet(prev => {
@@ -29,7 +53,7 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
   };
 
   return (
-    <div className="divide-y divide-ods-border overflow-hidden rounded-md border border-ods-border bg-transparent">
+    <div className={ACCORDION_FRAME_CLASS}>
       {items.map(item => {
         const isOpen = openSet.has(item.id);
 
@@ -43,6 +67,8 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
             // category anchors).
             id={faqItemAnchor(item.id)}
             className="scroll-mt-24 transition-colors hover:bg-ods-bg-hover"
+            // A question is a read list's row: how many there are is the data's.
+            data-loading-item
           >
             {/* Header */}
             <div
@@ -56,16 +82,16 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
                 }
               }}
               aria-expanded={isOpen}
-              className="flex w-full cursor-pointer items-center gap-6 px-6 py-4 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-focus content-md:gap-10"
+              className={cn(
+                ROW_HEADER_CLASS,
+                'cursor-pointer transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-focus',
+              )}
             >
-              <h3 className="min-w-0 flex-1 break-words">{item.question}</h3>
+              <h3 className={QUESTION_CLASS}>{item.question}</h3>
               <Chevron02DownIcon
                 aria-hidden="true"
                 size={24}
-                className={cn(
-                  'shrink-0 text-ods-text-primary transition-transform duration-300',
-                  isOpen && 'rotate-180',
-                )}
+                className={cn(CHEVRON_CLASS, 'transition-transform duration-300', isOpen && 'rotate-180')}
               />
             </div>
             {/* Content wrapper. Collapses with the grid 1fr->0fr transition the
@@ -93,3 +119,37 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
     </div>
   );
 }
+
+/**
+ * The accordion while its questions are read: the bordered list of `count` closed rows, each question a bar (two
+ * lines on a phone, one from `content-md`) inside the row's own `h3`, the chevron real.
+ */
+export function FaqAccordionSkeleton({
+  count = FAQ_ACCORDION_SKELETON_ROWS,
+  className,
+}: {
+  count?: number;
+  className?: string;
+}) {
+  return (
+    <div className={cn(ACCORDION_FRAME_CLASS, className)} aria-hidden>
+      {Array.from({ length: count }, (_, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: skeleton rows never reorder
+        <div key={i} className={ROW_HEADER_CLASS} data-loading-item>
+          <h3 className={QUESTION_CLASS}>
+            {/* A typical question's lines: `wrapsOnPhone` on a phone, one from `content-md`. */}
+            {wrapsOnPhone(i) ? (
+              <>
+                <TextLineSkeleton type="inherit" as="span" lines={2} className="w-5/6 content-md:hidden" />
+                <TextLineSkeleton type="inherit" as="span" className="hidden w-5/6 content-md:block" />
+              </>
+            ) : (
+              <TextLineSkeleton type="inherit" as="span" className="w-5/6" />
+            )}
+          </h3>
+          <Chevron02DownIcon aria-hidden="true" size={24} className={CHEVRON_CLASS} />
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/features/ai-enrich/AIStatusIndicator.tsx

@@ -8,6 +8,7 @@ import {
   getConfidenceLabel,
 } from '../../../utils/confidence-helpers';
 import { SparklesIcon } from '../../icons-v2-generated/interface/sparkles-icon';
+import { LIVE_PULSE_CLASS } from '../../ui/skeleton-surface';
 
 export type AIStatus = 'idle' | 'loading' | 'success' | 'error';
 
@@ -60,7 +61,7 @@ export const AIStatusIndicator: React.FC<AIStatusIndicatorProps> = ({
       <SparklesIcon
         size={16}
         className={cn(
-          status === 'loading' && 'animate-pulse',
+          status === 'loading' && LIVE_PULSE_CLASS,
           confidence !== undefined && status === 'success' ? getConfidenceTextClass(confidence) : config.color,
         )}
       />