@flamingo-stack/openframe-frontend-core 0.0.765 → 0.0.767

package/src/ODS_TOKEN_RULES.md

@@ -154,8 +154,8 @@ out by **its own width** instead. `<main>` becomes an `.ods-content-area` contai
 - Convert hardcoded values to ODS tokens even when copying patterns from existing code.
 - Match Figma by choosing the typography class on **font family + weight + text-transform**, not just size.
 - If Figma uses a token that doesn't exist in ODS, flag it — don't silently hardcode a fallback.
-- **Z-index** — use the established hierarchy, don't invent numbers: in-layout sidebar overlay
-  `z-[40]`, footer `z-[44]` (page-chrome bottom, intentionally below the admin drawer so an open
+- **Z-index** — use the established hierarchy, don't invent numbers: a page's sticky section bar
+  (`PageSectionBar`, under the header) `z-30`, in-layout sidebar overlay `z-[40]`, footer `z-[44]` (page-chrome bottom, intentionally below the admin drawer so an open
   right-drawer covers it), admin `SlidingSidebar` drawer overlay `z-[45]` / panel `z-[46]` (a
   full-viewport `fixed` right-drawer that covers the footer but stays BEHIND the header — its panel
   has a header spacer), sticky header `z-[50]`, modals `z-[50]`/`z-[1300]` (Radix dialogs sit at

package/src/chat-protocol/decode.ts

@@ -54,11 +54,6 @@ export interface SseFrameDecoder {
   end(): ChatStreamEvent[];
 }
 
-// `escapeThinkingTags` moved to `./leading-frames` alongside the frame table,
-// and is re-exported here: consumers have imported it from this module since it
-// was written, and the `chat-protocol` barrel re-exports it from here.
-export { escapeThinkingTags } from './leading-frames';
-
 /** Narrow a parsed leading frame to something the frame table can read. */
 function isFrameObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;

package/src/chat-protocol/index.ts

@@ -28,3 +28,4 @@ export { isRecord, unwrapEnvelope } from './wire-narrow';
 // The `[card://<type>:<id>]` grammar — the renderer's and the server's one
 // definition, so a reference the hub emits is one the client expands.
 export * from './card-marker';
+export { escapeThinkingTags } from './leading-frames';

package/src/components/agent-identity.tsx

@@ -10,8 +10,6 @@ import {
 import { identityTint } from '../utils/identity-tint';
 import { HEX_PATTERN } from '../utils/ods-color-utils';
 
-export { AGENT_IDENTITIES_API_PATH, type AgentIdentityIcon, type AgentIdentityIcons };
-
 /**
  * The colour an agent's GLYPH is drawn in when its identity names none: the
  * theme's text colour, the same wherever the mark sits. An agent's mark is one

package/src/components/agent-mark.tsx

@@ -6,6 +6,7 @@ import Image from '../embed-shims/next-image';
 import { cn } from '../utils/cn';
 import { AGENT_GLYPH_COLOR, AGENT_PICTURE_CLASS, useAgentIdentityIcon } from './agent-identity';
 import { resolveIcon } from './chat/utils/icon-library';
+import { UnifiedSkeleton } from './loading/unified-skeleton';
 
 /** The agents the product ships. A mark is drawn for any agent slug the server has an identity for. */
 export type AgentName = 'fae' | 'mingo';
@@ -73,13 +74,21 @@ export interface AgentAvatarProps {
  * slug and never a picture, so an agent looks the same in a card, a log row, a
  * command bar and an example, and a new icon in its identity reaches all of them.
  */
+/** The avatar's round frame, read by the avatar and by its skeleton, so the two are one box. */
+const AGENT_AVATAR_FRAME_CLASS = 'inline-flex shrink-0 overflow-hidden rounded-full';
+
 export function AgentAvatar({ agent, size, className }: AgentAvatarProps) {
   return (
-    <span
-      className={cn('inline-flex shrink-0 overflow-hidden rounded-full', className)}
-      style={{ width: size, height: size }}
-    >
+    <span className={cn(AGENT_AVATAR_FRAME_CLASS, className)} style={{ width: size, height: size }}>
       <AgentMark agent={agent} className="h-full w-full" />
     </span>
   );
 }
+
+/**
+ * An agent's avatar while the agent is not known yet (the record that names it is read): the avatar's own round
+ * frame at the same `size`, so the picture takes its place without moving anything.
+ */
+export function AgentAvatarSkeleton({ size, className }: Pick<AgentAvatarProps, 'size' | 'className'>) {
+  return <UnifiedSkeleton as="span" className={cn(AGENT_AVATAR_FRAME_CLASS, className)} width={size} height={size} />;
+}

package/src/components/authors/author-detail-view.tsx

@@ -24,13 +24,16 @@
  */
 
 import type React from 'react';
-import { useChatRuntime } from '../../contexts/chat-runtime-context';
 import Image from '../../embed-shims/next-image';
+import { AVATAR_SIZE } from '../../styles/component-sizes';
 import type { AuthorProfile } from '../../types/entity-author';
 import { cn } from '../../utils/cn';
 import { formatBioText } from '../../utils/format';
-import { getProxiedImageUrl } from '../../utils/image-proxy';
-import { SocialIconRow } from '../social-icon-row';
+import { useProxiedImageUrl } from '../chat/hooks/use-proxied-image-url';
+import { InteractiveSkeleton, TextLineSkeleton } from '../loading/unified-skeleton';
+import { SocialIconRow, socialIconRowClass } from '../social-icon-row';
+import { useLoadingScope } from '../ui/loading-scope';
+import { SquareAvatar } from '../ui/square-avatar';
 import { StatusBadge } from '../ui/status-badge';
 
 export interface AuthorDetailViewProps {
@@ -42,61 +45,104 @@ export interface AuthorDetailViewProps {
   className?: string;
 }
 
-export function AuthorDetailView({ author, proxyImageUrl, children, className }: AuthorDetailViewProps) {
-  // Optional runtime — null-safe outside a provider (bare embeds render the
-  // raw avatar URL; the hub's app-wide HubRuntimeProvider supplies the proxy).
-  const runtime = useChatRuntime();
+/** The view's layout, read by the view and by its skeleton, so the skeleton is the view's size. */
+const VIEW_CLASS = 'flex flex-col gap-5 md:gap-6';
+const IDENTITY_ROW_CLASS = 'flex w-full items-start gap-6';
+const AVATAR_BOX_CLASS = `relative ${AVATAR_SIZE.profile} shrink-0`;
+const IDENTITY_TEXT_CLASS = 'flex min-w-0 flex-col justify-center gap-2';
+const NAME_CLASS = 'truncate leading-none text-ods-text-primary text-h2';
+const SUBTITLE_CLASS = 'truncate text-h4 leading-none text-ods-text-secondary';
+const BIO_CLASS = 'text-ods-text-secondary text-h6';
+const TOPICS_CLASS = 'flex flex-wrap gap-2';
+/** Social icons (compact, icon-sm 32px, gap-2) a skeleton draws: a profile's typical row (192px, five links). */
+const AUTHOR_SKELETON_SOCIALS = 5;
 
-  const proxiedAvatar = author.avatarUrl
-    ? proxyImageUrl
-      ? proxyImageUrl(author.avatarUrl)
-      : (getProxiedImageUrl(author.avatarUrl, {
-          proxyPrefix: runtime?.endpoints.imageProxyUrlPrefix,
-          skipDomains: runtime?.endpoints.imageProxySkipDomains,
-          directHttps: true,
-        }) ?? author.avatarUrl)
-    : null;
+export function AuthorDetailView({ author, proxyImageUrl, children, className }: AuthorDetailViewProps) {
+  // In a loading scope the host passes an empty profile and the view draws itself: each part holds its place with a
+  // skeleton of its own size, and `children` (the host's rail) draws its own.
+  const loading = useLoadingScope();
+  const proxiedAvatar = useProxiedImageUrl(loading ? null : author.avatarUrl, { proxyImageUrl }) || null;
 
   const subtitle = [author.jobTitle, author.company].filter(Boolean).join(' @ ');
   const bioText = formatBioText(author.about);
 
   return (
-    <div className={cn('flex flex-col gap-5 md:gap-6', className)}>
+    <div className={cn(VIEW_CLASS, className)}>
       {/* Identity header: avatar left; name → subtitle → socials stacked right. */}
-      <div className="flex w-full items-start gap-6">
-        <div className="relative h-24 w-24 shrink-0">
-          <div className="relative h-full w-full overflow-hidden rounded-full border border-ods-border bg-ods-bg-surface">
-            {proxiedAvatar ? (
-              <Image src={proxiedAvatar} alt={author.fullName} fill className="object-cover" unoptimized />
-            ) : (
-              <div className="flex h-full w-full items-center justify-center font-heading text-3xl text-ods-text-secondary">
-                {author.fullName.charAt(0).toUpperCase()}
-              </div>
-            )}
-          </div>
+      <div className={IDENTITY_ROW_CLASS} aria-hidden={loading || undefined}>
+        <div className={AVATAR_BOX_CLASS}>
+          {loading ? (
+            // The avatar in its scope draws its own skeleton, the round box of this frame.
+            <SquareAvatar variant="round" alt="" className="h-full w-full" />
+          ) : (
+            <div className="relative h-full w-full overflow-hidden rounded-full border border-ods-border bg-ods-bg-surface">
+              {proxiedAvatar ? (
+                <Image src={proxiedAvatar} alt={author.fullName} fill className="object-cover" unoptimized />
+              ) : (
+                <div className="flex h-full w-full items-center justify-center text-ods-text-secondary text-h2">
+                  {author.fullName.charAt(0).toUpperCase()}
+                </div>
+              )}
+            </div>
+          )}
         </div>
 
-        <div className="flex min-w-0 flex-col justify-center gap-2">
-          <p className="truncate leading-none text-ods-text-primary text-h2">{author.fullName}</p>
-          {subtitle && <p className="truncate font-body text-lg leading-none text-ods-text-secondary">{subtitle}</p>}
-          {author.socialLinks.length > 0 && (
-            // Ghost compact row (transparent 32px) — metadata, not CTAs.
-            <SocialIconRow
-              compact
-              links={author.socialLinks.map(link => ({
-                platform: link.platform,
-                href: link.url,
-                label: `${author.fullName}'s ${link.platform}`,
-              }))}
-            />
+        <div className={cn(IDENTITY_TEXT_CLASS, loading && 'w-full')}>
+          <p className={NAME_CLASS}>
+            {loading ? (
+              // A typical name's width (about 282px at the name's `text-h2`).
+              <TextLineSkeleton type="inherit" as="span" className="w-72 max-w-full" />
+            ) : (
+              author.fullName
+            )}
+          </p>
+          {(loading || subtitle) && (
+            <p className={SUBTITLE_CLASS}>
+              {loading ? <TextLineSkeleton type="inherit" as="span" className="w-48 max-w-full" /> : subtitle}
+            </p>
+          )}
+          {loading ? (
+            <div className={socialIconRowClass(true)}>
+              {Array.from({ length: AUTHOR_SKELETON_SOCIALS }, (_, i) => (
+                // biome-ignore lint/suspicious/noArrayIndexKey: skeleton icons never reorder
+                <InteractiveSkeleton.Button key={i} size="icon-sm" />
+              ))}
+            </div>
+          ) : (
+            author.socialLinks.length > 0 && (
+              // Ghost compact row (transparent 32px) — metadata, not CTAs.
+              <SocialIconRow
+                compact
+                links={author.socialLinks.map(link => ({
+                  platform: link.platform,
+                  href: link.url,
+                  label: `${author.fullName}'s ${link.platform}`,
+                }))}
+              />
+            )
           )}
         </div>
       </div>
 
-      {bioText && <p className="text-ods-text-secondary text-h6">{bioText}</p>}
+      {loading ? (
+        // A bio's usual length per width: five lines on a phone, three on a tablet, two from desktop.
+        <p className={BIO_CLASS} aria-hidden>
+          <TextLineSkeleton type="inherit" as="span" lines={5} className="w-full content-md:hidden" />
+          <TextLineSkeleton
+            type="inherit"
+            as="span"
+            lines={3}
+            className="hidden w-full content-md:flex content-lg:hidden"
+          />
+          <TextLineSkeleton type="inherit" as="span" lines={2} className="hidden w-full content-lg:flex" />
+        </p>
+      ) : (
+        bioText && <p className={BIO_CLASS}>{bioText}</p>
+      )}
 
-      {author.knowsAbout.length > 0 && (
-        <div className="flex flex-wrap gap-2">
+      {!loading && author.knowsAbout.length > 0 && (
+        // Optional per author (not drawn while loading): marked so for the loading-state check.
+        <div className={TOPICS_CLASS} data-loading-optional>
           {author.knowsAbout.map(topic => (
             <StatusBadge key={topic} text={topic} variant="button" colorScheme="cyan" singleLine />
           ))}

package/src/components/case-studies/entity-quotes-panel.tsx

@@ -2,7 +2,9 @@
 
 import type { EntityQuote } from '../../types/video-processing';
 import { ENTITY_QUOTES_TITLE } from '../../types/video-processing';
+import { TextLineSkeleton } from '../loading/unified-skeleton';
 import { StackedRowsPanel } from '../ui';
+import { useLoadingScope } from '../ui/loading-scope';
 
 export interface EntityQuotesPanelProps {
   /** A record's `quotes` column (case study, customer interview, prospect call). */
@@ -15,9 +17,22 @@ export interface EntityQuotesPanelProps {
  * with its speaker beneath, under a "Key Quotes · N" caption. Renders nothing
  * when there are none.
  */
+/** The quote's layout, read by the panel and by its skeleton. */
+const QUOTE_CLASS = 'flex flex-col gap-[var(--spacing-system-xxs)]';
+const QUOTE_TEXT_CLASS = 'text-ods-text-primary text-h4';
+const QUOTE_SPEAKER_CLASS = 'text-ods-text-secondary text-h4';
+/** Quote rows the skeleton draws: the panel shows every quote (no fold), so the panel's own default count. */
+const QUOTES_SKELETON_ROWS = 3;
+
 export function EntityQuotesPanel({ quotes, className }: EntityQuotesPanelProps) {
+  // Quotes are optional per record: a loading state cannot know a panel will be there, so it draws none (the
+  // panel's skeleton is for a host that knows it has quotes).
+  if (useLoadingScope()) return null;
   if (!quotes || quotes.length === 0) return null;
   return (
+    // Optional per record, so the loading state draws none: the gate leaves the loaded panel out of its comparison.
+    // A plain block around the one panel, so the parent's spacing applies to it as it did to the panel.
+    <div data-loading-optional>
     <StackedRowsPanel
       className={className}
       title={`${ENTITY_QUOTES_TITLE} · ${quotes.length}`}
@@ -27,14 +42,46 @@ export function EntityQuotesPanel({ quotes, className }: EntityQuotesPanelProps)
           {
             key: 'quote',
             content: (
-              <blockquote className="flex flex-col gap-[var(--spacing-system-xxs)]">
-                <p className="text-ods-text-primary text-h4">&ldquo;{q.text}&rdquo;</p>
-                {q.speaker && <p className="text-ods-text-secondary text-h4">{q.speaker}</p>}
+              <blockquote className={QUOTE_CLASS}>
+                <p className={QUOTE_TEXT_CLASS}>&ldquo;{q.text}&rdquo;</p>
+                {q.speaker && <p className={QUOTE_SPEAKER_CLASS}>{q.speaker}</p>}
               </blockquote>
             ),
           },
         ],
       }))}
     />
+    </div>
+  );
+}
+
+/**
+ * The quotes while they are read: the real "Key Quotes" caption (its count is read data, so it is left out) over
+ * the panel's rows, each a quote's two lines and its speaker line as bars in the quote's own elements.
+ */
+export function EntityQuotesPanelSkeleton({ className }: { className?: string }) {
+  return (
+    <StackedRowsPanel
+      className={className}
+      title={ENTITY_QUOTES_TITLE}
+      rows={Array.from({ length: QUOTES_SKELETON_ROWS }, (_, i) => ({
+        id: `skeleton-${i}`,
+        columns: [
+          {
+            key: 'quote',
+            content: (
+              <div className={QUOTE_CLASS} aria-hidden>
+                <p className={QUOTE_TEXT_CLASS}>
+                  <TextLineSkeleton type="inherit" as="span" lines={2} className="w-full" />
+                </p>
+                <p className={QUOTE_SPEAKER_CLASS}>
+                  <TextLineSkeleton type="inherit" as="span" className="w-40" />
+                </p>
+              </div>
+            ),
+          },
+        ],
+      }))}
+    />
   );
 }

package/src/components/case-studies/index.ts

@@ -1,3 +1,3 @@
 export { ShareExperienceSection, type ShareExperienceSectionProps } from './share-experience-section';
-export { EntityQuotesPanel, type EntityQuotesPanelProps } from './entity-quotes-panel';
-export { QuoteCardsStrip, type QuoteCard, type QuoteCardsStripProps } from './quote-cards-strip';
+export { EntityQuotesPanel, EntityQuotesPanelSkeleton, type EntityQuotesPanelProps } from './entity-quotes-panel';
+export { QuoteCardTile, QuoteCardTileSkeleton, QuoteCardsStrip, type QuoteCard, type QuoteCardTileProps, type QuoteCardsStripProps } from './quote-cards-strip';

package/src/components/case-studies/quote-cards-strip.tsx

@@ -1,9 +1,13 @@
 'use client';
 
+import type { HTMLAttributes } from 'react';
+import { cn } from '../../utils/cn';
 import { CardHitLayer } from '../features/card-hit-layer';
 import { CardsStrip } from '../features/cards-strip';
+import { LoadingRegion } from '../loading/loading-region';
 import { Card } from '../ui/card';
-import { PersonCell } from '../ui/people-cell';
+import { useLoadingScope } from '../ui/loading-scope';
+import { PersonCell, PersonCellSkeleton } from '../ui/people-cell';
 
 /** One customer quote chip: the line, who said it, their logo, and the case study it opens. */
 export interface QuoteCard {
@@ -17,18 +21,81 @@ export interface QuoteCard {
   href: string;
 }
 
+export interface QuoteCardTileProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  quote: QuoteCard;
+  /** The strip's loop clone: it keeps the click but stays out of the a11y tree. */
+  decorative?: boolean;
+}
+
+const QUOTE_CARD_CLASS = 'relative p-[var(--spacing-system-sf)]';
+
+/**
+ * ONE customer quote card: the line as the person's name, who said it beneath,
+ * their logo, and the whole card opening the case study it comes from. The
+ * strip draws one per quote; a page that shows a single story draws one alone.
+ */
+export function QuoteCardTile({ quote, decorative, className, ...props }: QuoteCardTileProps) {
+  return (
+    <Card
+      variant="panel"
+      aria-hidden={decorative || undefined}
+      className={cn(QUOTE_CARD_CLASS, 'hover:border-ods-border-hover', className)}
+      {...props}
+    >
+      <PersonCell size="lg" name={`"${quote.text}"`} secondary={quote.attribution} avatarUrl={quote.logoUrl} />
+      <CardHitLayer href={quote.href} label={`${quote.text}, ${quote.attribution}`} decorative={decorative} />
+    </Card>
+  );
+}
+
+/** One quote card while it loads: the same card and the person cell's own skeleton. */
+export function QuoteCardTileSkeleton({ className }: { className?: string }) {
+  return (
+    <Card variant="panel" className={cn(QUOTE_CARD_CLASS, className)}>
+      <LoadingRegion label="Loading a customer story">
+        <PersonCellSkeleton size="lg" />
+      </LoadingRegion>
+    </Card>
+  );
+}
+
 export interface QuoteCardsStripProps {
   quotes: readonly QuoteCard[];
+  /** The quotes are being read (the host's query runs): the strip draws its own skeleton. A page's loading scope does too. */
+  loading?: boolean;
+  /** The quote cards the skeleton draws: one screen of the host's strip. */
+  fold?: number;
   className?: string;
 }
 
+/** The quote cards a strip's skeleton draws when its host names none: a chip is about a third of a wide page's row. */
+const QUOTE_STRIP_FOLD = 4;
+
+/** The strip while its quotes are read: the same strip engine, still, with the quote card's own skeleton. */
+function QuoteCardsStripSkeleton({ fold, className }: { fold: number; className?: string }) {
+  return (
+    <CardsStrip
+      className={className}
+      showTitle={false}
+      showChevrons={false}
+      autoScroll={false}
+      items={Array.from({ length: fold }, (_, index) => ({ key: `quote-${index}` }))}
+      itemKey={item => item.key}
+      renderCard={(_item, ctx) => <QuoteCardTileSkeleton key={ctx.cardKey} className="shrink-0" />}
+    />
+  );
+}
+
 /**
  * A scrolling row of customer quote chips on THE strip engine every card rail
  * uses (`CardsStrip`, render-prop mode so each chip keeps its natural width).
  * The whole chip opens the case study the quote comes from; the loop clone
- * keeps the click but stays out of the a11y tree. Renders nothing when empty.
+ * keeps the click but stays out of the a11y tree. While its quotes are read (a page's loading scope with none handed
+ * over, or `loading`) it is its own skeleton; read and empty, it renders nothing.
  */
-export function QuoteCardsStrip({ quotes, className }: QuoteCardsStripProps) {
+export function QuoteCardsStrip({ quotes, loading = false, fold = QUOTE_STRIP_FOLD, className }: QuoteCardsStripProps) {
+  const scoped = useLoadingScope();
+  if ((scoped && quotes.length === 0) || loading) return <QuoteCardsStripSkeleton fold={fold} className={className} />;
   if (quotes.length === 0) return null;
   return (
     <CardsStrip
@@ -38,16 +105,14 @@ export function QuoteCardsStrip({ quotes, className }: QuoteCardsStripProps) {
       items={[...quotes]}
       itemKey={quote => quote.key}
       renderCard={(quote, ctx) => (
-        <Card
+        <QuoteCardTile
           key={ctx.cardKey}
-          aria-hidden={ctx.isClone || undefined}
+          quote={quote}
+          decorative={ctx.isClone}
           onPointerEnter={ctx.isTouch ? undefined : () => ctx.onActivate(ctx.cardKey)}
           onPointerLeave={ctx.isTouch ? undefined : () => ctx.onDeactivate(ctx.cardKey)}
-          className="relative shrink-0 rounded-md border-ods-border bg-ods-card p-[var(--spacing-system-sf)] shadow-none hover:border-ods-border-hover"
-        >
-          <PersonCell size="lg" name={`"${quote.text}"`} secondary={quote.attribution} avatarUrl={quote.logoUrl} />
-          <CardHitLayer href={quote.href} label={`${quote.text}, ${quote.attribution}`} decorative={ctx.isClone} />
-        </Card>
+          className="shrink-0"
+        />
       )}
     />
   );

package/src/components/categories-cart.tsx

@@ -2,9 +2,40 @@
 
 import { ChevronRight } from 'lucide-react';
 import Link from '../embed-shims/next-link';
+import { ICON_SIZE } from '../styles/component-sizes';
 import type { RealCategoryCardProps } from '../types/category';
-import { UnifiedSkeleton } from './loading/unified-skeleton';
-import { VendorIcon } from './vendor-icon';
+import { cn } from '../utils/cn';
+import { TextLineSkeleton } from './loading/unified-skeleton';
+import { useLoadingScope } from './ui/loading-scope';
+import { VendorIcon, VendorIconSkeleton } from './vendor-icon';
+
+/** The card's layout, read by the card and by its skeleton, so the skeleton is the card's size. */
+const CARD_SHELL_CLASS = 'group relative block rounded-lg border border-ods-border bg-ods-card p-3 pb-4 md:p-4 md:pb-6';
+const CARD_STACK_CLASS = 'flex flex-col gap-4 md:gap-6';
+const ICON_STRIP_CLASS = 'relative h-8 w-full overflow-hidden md:h-10';
+const ICON_ROW_CLASS = 'flex w-full gap-2 md:gap-3';
+/** The strip's vendor icons: one size and frame for the loaded icon and its skeleton. */
+const VENDOR_ICON_SIZE = 'md';
+const VENDOR_ICON_CLASS = 'overflow-hidden rounded opacity-60 grayscale filter';
+/** The inner stacks only stack: a one-column grid, not another column flexbox (WEBVIEW-001). */
+const INFO_STACK_CLASS = 'grid grid-cols-1 gap-2';
+const TITLE_STACK_CLASS = 'grid grid-cols-1 gap-1';
+const FOOT_ROW_CLASS = 'flex items-start justify-between gap-4 md:items-end md:gap-6';
+const ARROW_BOX_CLASS =
+  'flex h-10 w-10 flex-shrink-0 items-center justify-center rounded-md border border-ods-border bg-transparent transition-colors md:h-12 md:w-12';
+const ARROW_ICON_CLASS = `${ICON_SIZE.step} text-ods-text-primary transition-colors`;
+/** As many icon boxes as the widest strip shows (the strip clips the rest). */
+const ICON_STRIP_FOLD = 20;
+
+/** The strip's fades at both ends, into the card's own surface. */
+function StripFades() {
+  return (
+    <>
+      <div className="pointer-events-none absolute inset-y-0 left-0 w-4 bg-gradient-to-r from-ods-card to-transparent md:w-6" />
+      <div className="pointer-events-none absolute inset-y-0 right-0 w-4 bg-gradient-to-l from-ods-card to-transparent md:w-6" />
+    </>
+  );
+}
 
 // Component that receives vendor and subcategory data as props
 export function CategoriesCart({
@@ -15,48 +46,27 @@ export function CategoriesCart({
   isLoading = false,
   className = '',
 }: RealCategoryCardProps) {
+  if (useLoadingScope() || isLoading) return <CategoriesCartSkeleton className={className} />;
   return (
     <Link
       href={`/vendors?category=${category.slug}`}
-      className={`group relative block rounded-lg border border-ods-border bg-ods-card p-3 pb-4 transition-colors hover:border-ods-accent md:p-4 md:pb-6 ${className}`}
+      className={cn(CARD_SHELL_CLASS, 'transition-colors hover:border-ods-accent', className)}
     >
-      <div className="flex flex-col gap-4 md:gap-6">
+      <div className={CARD_STACK_CLASS}>
         {/* Vendor Icons Grid */}
-        <div className="relative h-8 w-full overflow-hidden md:h-10">
-          <div className="flex w-full gap-2 md:gap-3">
-            {isLoading
-              ? // Skeleton loading for vendor icons
-                Array.from({ length: 20 }).map((_, index) => (
-                  <UnifiedSkeleton key={index} className="h-8 w-8 flex-shrink-0 rounded md:h-10 md:w-10" />
-                ))
-              : vendors && vendors.length > 0
-                ? vendors.map(vendor => (
-                    <VendorIcon
-                      key={vendor.id}
-                      vendor={vendor}
-                      size="md"
-                      className="overflow-hidden rounded opacity-60 grayscale filter"
-                    />
-                  ))
-                : // No vendors found - show placeholder icons
-                  Array.from({ length: 6 }).map((_, index) => (
-                    <div
-                      key={index}
-                      className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded bg-ods-border opacity-30 md:h-10 md:w-10"
-                    >
-                      <div className="h-4 w-4 rounded-sm bg-ods-skeleton md:h-6 md:w-6" />
-                    </div>
-                  ))}
+        <div className={ICON_STRIP_CLASS}>
+          <div className={ICON_ROW_CLASS}>
+            {/* A category with no vendors leaves the strip empty: it keeps its height, and draws no stand-in icons. */}
+            {vendors.map(vendor => (
+              <VendorIcon key={vendor.id} vendor={vendor} size={VENDOR_ICON_SIZE} className={VENDOR_ICON_CLASS} />
+            ))}
           </div>
-
-          {/* Gradient overlays for fade effect */}
-          <div className="pointer-events-none absolute inset-y-0 left-0 w-4 bg-gradient-to-r from-[#212121] to-transparent md:w-6" />
-          <div className="pointer-events-none absolute inset-y-0 right-0 w-4 bg-gradient-to-l from-[#212121] to-transparent md:w-6" />
+          <StripFades />
         </div>
 
         {/* Category Information - Updated to use real data */}
-        <div className="flex flex-col gap-2">
-          <div className="flex flex-col gap-1">
+        <div className={INFO_STACK_CLASS}>
+          <div className={TITLE_STACK_CLASS}>
             <h3 className="text-ods-text-primary transition-colors text-h3 group-hover:text-ods-accent">
               {category.name}
             </h3>
@@ -65,15 +75,15 @@ export function CategoriesCart({
             </p>
           </div>
 
-          <div className="flex items-start justify-between gap-4 md:items-end md:gap-6">
+          <div className={FOOT_ROW_CLASS}>
             <p className="flex-1 text-ods-text-primary text-h4">{category.description}</p>
 
             {/* Arrow Button */}
             <div
-              className="flex h-10 w-10 flex-shrink-0 items-center justify-center rounded-md border border-ods-border bg-transparent transition-colors group-hover:bg-ods-accent md:h-12 md:w-12"
+              className={cn(ARROW_BOX_CLASS, 'group-hover:bg-ods-accent')}
               aria-label={`View ${category.name} category`}
             >
-              <ChevronRight className="h-5 w-5 text-ods-text-primary transition-colors group-hover:text-ods-text-on-accent md:h-6 md:w-6" />
+              <ChevronRight className={cn(ARROW_ICON_CLASS, 'group-hover:text-ods-text-on-accent')} />
             </div>
           </div>
         </div>
@@ -81,3 +91,37 @@ export function CategoriesCart({
     </Link>
   );
 }
+
+/**
+ * A category card while its category is read: the card's frame, the vendor strip as icon boxes, a bar for the name,
+ * the counts line and two description lines, and the arrow box as it is. Not a link: there is no category yet.
+ */
+export function CategoriesCartSkeleton({ className }: { className?: string }) {
+  return (
+    <div className={cn(CARD_SHELL_CLASS, className)} aria-hidden>
+      <div className={CARD_STACK_CLASS}>
+        <div className={ICON_STRIP_CLASS}>
+          <div className={ICON_ROW_CLASS}>
+            {Array.from({ length: ICON_STRIP_FOLD }, (_, index) => (
+              // biome-ignore lint/suspicious/noArrayIndexKey: skeleton icons never reorder
+              <VendorIconSkeleton key={index} size={VENDOR_ICON_SIZE} className="rounded" />
+            ))}
+          </div>
+          <StripFades />
+        </div>
+        <div className={INFO_STACK_CLASS}>
+          <div className={TITLE_STACK_CLASS}>
+            <TextLineSkeleton type="h3" className="w-40" />
+            <TextLineSkeleton type="h6" className="w-48" />
+          </div>
+          <div className={FOOT_ROW_CLASS}>
+            <TextLineSkeleton type="h4" lines={2} className="flex-1" />
+            <div className={ARROW_BOX_CLASS}>
+              <ChevronRight className={ARROW_ICON_CLASS} />
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/category-card.tsx

@@ -15,7 +15,7 @@ export function CategoryCard({ name, description, categoryCount, productCount, i
     <article className="box-border flex min-w-0 flex-col rounded-[12px] border border-ods-border bg-ods-card p-8">
       <div className="mb-8 flex items-center justify-center gap-6">
         {(icons.length > 0 ? icons : Array(10).fill(null)).map((icon, i) => (
-          <div key={i} className="flex h-10 w-10 items-center justify-center rounded bg-ods-skeleton">
+          <div key={i} className="flex h-10 w-10 items-center justify-center rounded bg-ods-border">
             {icon}
           </div>
         ))}

package/src/components/chat/chat-attachment-bar.tsx

@@ -288,7 +288,7 @@ function AttachmentChip({ attachment, onRemove, disabled, size = 'default' }: At
             chip to a single line; uploading/error states still surface. */}
         {(!compact || status !== 'ready') && (
           <div className="text-ods-text-muted text-h6">
-            {status === 'sniffing' && 'Checking…'}
+            {status === 'sniffing' && 'Checking the file'}
             {status === 'uploading' && `${progress}% · ${formatFileSize(file.size)}`}
             {status === 'ready' && formatFileSize(file.size)}
             {status === 'error' && (