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

package/src/components/ui/page-actions.tsx

@@ -3,7 +3,7 @@
 import React from 'react';
 import { cn } from '../../utils/cn';
 import { Chevron02DownIcon } from '../icons-v2-generated';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { InteractiveSkeleton, UnifiedSkeleton } from '../loading/unified-skeleton';
 import { ActionsMenuDropdown, type ActionsMenuGroup, type ActionsMenuItem } from './actions-menu';
 import type { ButtonProps, SplitButtonIconAction } from './button';
 import { Button, SplitButton } from './button';
@@ -32,7 +32,8 @@ export type PageActionButton = {
   /**
    * Render the desktop button as icon-only (label hidden, icon centered). The full
    * label still appears in the mobile "..." dropdown. The desktop icon is forced to
-   * `text-ods-text-primary`; the mobile row keeps the caller-provided icon color.
+   * `text-ods-text-primary`; the mobile row keeps the caller-provided icon color
+   * (re-tinted only when it was picked for a filled variant, see `menuRowIcon`).
    */
   iconOnlyOnDesktop?: boolean;
   /** Render as a link (next/link). Mutually exclusive with `submenu`. */
@@ -61,6 +62,29 @@ function actionKey(action: PageActionButton, idx: number) {
   return `${action.label ?? action.ariaLabel ?? 'action'}-${idx}`;
 }
 
+/** Variants that paint the button: the caller tints its icon for that fill (`text-ods-text-on-accent`). */
+const FILLED_VARIANTS: ReadonlySet<NonNullable<PageActionButton['variant']>> = new Set([
+  'accent',
+  'destructive',
+  'warning',
+]);
+
+/**
+ * The action's icon as a "..." menu row shows it. An icon tinted for a filled
+ * button (an empty list's accent "Add ...") is dark on the menu's dark row, so it
+ * is re-tinted to the row's secondary icon color. Outline and transparent buttons
+ * sit on the page background like the row does, so their icon is kept as is. No
+ * variant renders as accent, the Button default.
+ *
+ * `&&` doubles the class (specificity 0,2,1): a caller that tints the fill with its
+ * own `[&_svg]:!text-...` wrapper ties with a single class, and the tie would go to
+ * whichever rule the consumer's stylesheet happens to emit last.
+ */
+function menuRowIcon(action: PageActionButton): React.ReactNode {
+  if (!action.icon || !FILLED_VARIANTS.has(action.variant ?? 'accent')) return action.icon;
+  return <span className="inline-flex [&&_svg]:!text-ods-text-secondary">{action.icon}</span>;
+}
+
 function actionToMenuItems(action: PageActionButton, idx: number): ActionsMenuItem[] {
   if (action.submenu && action.submenu.length > 0) {
     // When a split-button action collapses into the merged mobile "..." menu,
@@ -78,7 +102,7 @@ function actionToMenuItems(action: PageActionButton, idx: number): ActionsMenuIt
     {
       id: `action-${idx}`,
       label: action.label,
-      icon: action.icon,
+      icon: menuRowIcon(action),
       onClick: action.onClick,
       disabled: action.disabled,
       href: action.href,
@@ -223,15 +247,6 @@ export interface PageActionsProps {
 
 const ACTIONS_GAP = 'gap-[var(--spacing-system-xs)]';
 
-/** Matches `Button` size="icon" / size="default" exactly, so a placeholder and the
- *  button that replaces it occupy the same box at both breakpoints. `rounded-md`
- *  is the same token `Button` itself uses — a raw `6px` would agree today and
- *  drift the moment a platform overrides `--radius`. */
-const SKELETON_HEIGHT = 'h-11 md:h-12';
-const SKELETON_ICON_WIDTH = 'w-11 md:w-12';
-const SKELETON_LABEL_WIDTH = 'w-[120px] md:w-[140px]';
-const SKELETON_RADIUS = 'rounded-md';
-
 /**
  * Placeholders for actions whose SHAPE isn't known yet — the page is still
  * loading the record that decides which actions exist (e.g. an archived entity
@@ -273,24 +288,33 @@ function ActionSkeletons({
         // stretches only labelled buttons (`fullWidth: !!action.label`), so an
         // icon action keeps its square box there too.
         const isIconOnly = action ? !action.label || !!action.iconOnlyOnDesktop : emptyFallback === 'icon';
-        return (
-          <UnifiedSkeleton
-            // Static placeholder list — index IS the identity here.
-            key={`action-skeleton-${idx}`}
-            className={cn(
-              SKELETON_HEIGHT,
-              SKELETON_RADIUS,
-              isIconOnly ? SKELETON_ICON_WIDTH : fullWidth ? 'flex-1' : SKELETON_LABEL_WIDTH,
-            )}
-          />
-        );
+        // Static placeholder list — index IS the identity here.
+        const key = `action-skeleton-${idx}`;
+        // The square button's own size (`Button size="icon"`).
+        if (isIconOnly) return <InteractiveSkeleton.Button key={key} size="icon" />;
+        // A labelled action is the button it will render (its label is the caller's copy), drawn invisible under one
+        // bar, so the placeholder is that button's box at every breakpoint. Not a control while it loads.
+        if (action) {
+          return (
+            <span key={key} inert aria-hidden className={cn('relative inline-flex', fullWidth && 'flex-1')}>
+              <span className={cn('invisible inline-flex', fullWidth && 'flex-1')}>
+                {renderRawActionButton(action, { fullWidth })}
+              </span>
+              <UnifiedSkeleton className="absolute inset-0 h-full" />
+            </span>
+          );
+        }
+        // An unknown set that settles into a labelled button: the default button's size.
+        return <InteractiveSkeleton.Button key={key} size="default" className={fullWidth ? 'flex-1' : undefined} />;
       })}
     </>
   );
 }
 
 /** Mobile placeholder for the variants that collapse to ONE trigger (icon button or "…"). */
-const MOBILE_TRIGGER_SKELETON_CLASS = cn(SKELETON_HEIGHT, SKELETON_ICON_WIDTH, SKELETON_RADIUS);
+function MobileTriggerSkeleton() {
+  return <InteractiveSkeleton.Button size="icon" />;
+}
 
 export function PageActions({
   variant = 'icon-buttons',
@@ -370,7 +394,7 @@ function IconButtonsVariant({
       {/* Mobile: single icon button OR all actions merged into one "..." menu */}
       <div className={cn('flex content-md:hidden', className)}>
         {loading ? (
-          <UnifiedSkeleton className={MOBILE_TRIGGER_SKELETON_CLASS} />
+          <MobileTriggerSkeleton />
         ) : useSingleActionMobile && singleAction ? (
           renderActionButton(singleAction, { iconOnly: true })
         ) : hasMobileMenuItems ? (
@@ -424,11 +448,7 @@ function PrimaryButtonsVariant({
       </div>
 
       <div className={cn('hidden items-center md:content-max-md:flex', ACTIONS_GAP, className)}>
-        {loading ? (
-          <UnifiedSkeleton className={MOBILE_TRIGGER_SKELETON_CLASS} />
-        ) : (
-          <CompactPrimaryActions actions={desktopActions} />
-        )}
+        {loading ? <MobileTriggerSkeleton /> : <CompactPrimaryActions actions={desktopActions} />}
       </div>
 
       <MobileBottomActions actions={sortedActions} loading={loading} />
@@ -479,7 +499,7 @@ function MenuPrimaryVariant({
 
       <div className={cn('flex content-md:hidden', className)}>
         {loading ? (
-          <UnifiedSkeleton className={MOBILE_TRIGGER_SKELETON_CLASS} />
+          <MobileTriggerSkeleton />
         ) : hasMobileMenuItems || selector ? (
           // The selector rides into the menu as its header row: on mobile the
           // title row has no room for it, and hiding it entirely (what

package/src/components/ui/page-loader.tsx

@@ -2,6 +2,7 @@
 
 import { cn } from '../../utils/cn';
 import { OpenframeLogoIcon } from '../icons-v2-generated/logos/openframe-logo-icon';
+import { LIVE_PULSE_CLASS } from './skeleton-surface';
 
 export interface PageLoaderProps {
   /**
@@ -28,7 +29,7 @@ function LoaderMark() {
     <div className="relative h-6 w-6">
       <OpenframeLogoIcon
         secondaryColor="var(--color-text-tertiary)"
-        className="h-6 w-6 animate-pulse text-ods-accent"
+        className={cn('h-6 w-6 text-ods-accent', LIVE_PULSE_CLASS)}
         color="currentColor"
       />
     </div>

package/src/components/ui/people-cell.tsx

@@ -1,10 +1,12 @@
 'use client';
 
 import { personFirstName } from '../../utils/format';
+import { TextLineSkeleton } from '../loading/unified-skeleton';
 import { AvatarStack } from './avatar-stack';
 import { Button } from './button';
 import { FloatingTooltip } from './floating-tooltip';
-import { SquareAvatar } from './square-avatar';
+import { useLoadingScope } from './loading-scope';
+import { SquareAvatar, SquareAvatarSkeleton } from './square-avatar';
 import { TruncateText } from './truncate-text';
 
 /**
@@ -51,6 +53,9 @@ const PERSON_CELL_SIZE = {
   lg: { avatar: 'lg', gap: 'gap-[var(--spacing-system-sf)]', primary: 'h3' },
 } as const;
 
+/** The cell's row: avatar, then its two lines. Read by the cell and by its skeleton. */
+const PERSON_ROW_CLASS = 'flex min-w-0 items-center';
+
 export function PersonCell({
   name,
   avatarUrl,
@@ -60,10 +65,12 @@ export function PersonCell({
   actionTitle,
   size = 'sm',
 }: PersonCellProps) {
+  // In a page's loading state the person is read: the cell is its skeleton.
+  if (useLoadingScope()) return <PersonCellSkeleton size={size} />;
   const displayName = name || fallbackName;
   const scale = PERSON_CELL_SIZE[size];
   const row = (
-    <div className={`group/person-cell flex min-w-0 items-center ${scale.gap}`}>
+    <div className={`group/person-cell ${PERSON_ROW_CLASS} ${scale.gap}`}>
       <SquareAvatar size={scale.avatar} src={avatarUrl ?? undefined} alt={displayName} fallback={displayName} />
       <div className="min-w-0 flex-1">
         <TruncateText
@@ -93,6 +100,20 @@ export function PersonCell({
   );
 }
 
+/** The cell while it loads: the SAME avatar box, gap and two lines (the name's type step, then the caption's). */
+export function PersonCellSkeleton({ size = 'sm' }: { size?: PersonCellProps['size'] }) {
+  const scale = PERSON_CELL_SIZE[size];
+  return (
+    <div className={`${PERSON_ROW_CLASS} ${scale.gap}`} aria-hidden>
+      <SquareAvatarSkeleton size={scale.avatar} />
+      <div className="flex min-w-0 flex-1 flex-col">
+        <TextLineSkeleton type={scale.primary} className="w-3/4" />
+        <TextLineSkeleton type="h6" className="w-1/2" />
+      </div>
+    </div>
+  );
+}
+
 export interface PeopleCellPerson {
   /** Stable render key (a profile id) — names can collide or be blank. */
   key?: string | number;
@@ -112,6 +133,8 @@ export interface PeopleCellProps {
 const PEOPLE_CELL_STACK_SLOTS = 2;
 
 export function PeopleCell({ people, fallbackName = 'Unassigned' }: PeopleCellProps) {
+  // In a page's loading state the people are read: the cell is a person cell's skeleton.
+  if (useLoadingScope()) return <PersonCellSkeleton />;
   if (people.length <= 1) {
     const [person] = people;
     return (

package/src/components/ui/photo-wall.tsx

@@ -20,6 +20,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import Image, { resizedImageUrl } from '../../embed-shims/next-image';
 import { cn } from '../../utils/cn';
 import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from './loading-scope';
 import { MarqueeWall } from './marquee-wall';
 
 export interface PhotoWallImage {
@@ -175,7 +176,17 @@ export interface PhotoWallProps {
   loading?: boolean;
 }
 
-export function PhotoWall({ images, columns = 2, speed = 24, fadeColor, className, loading = false }: PhotoWallProps) {
+export function PhotoWall({
+  images,
+  columns = 2,
+  speed = 24,
+  fadeColor,
+  className,
+  loading: loadingProp = false,
+}: PhotoWallProps) {
+  // In a page's loading state the pictures are read: the wall draws its placeholder frames and measures nothing.
+  const inScope = useLoadingScope();
+  const loading = loadingProp || inScope;
   const rootRef = useRef<HTMLDivElement | null>(null);
   const [box, setBox] = useState<{ width: number; height: number } | null>(null);
   useEffect(() => {
@@ -208,11 +219,11 @@ export function PhotoWall({ images, columns = 2, speed = 24, fadeColor, classNam
   // One frame per picture: a url listed twice is its first entry. Nothing is
   // asked for before the wall knows its width.
   const unique = useMemo(() => {
-    if (requestWidth === undefined) return [];
+    if (requestWidth === undefined || inScope) return [];
     const byUrl = new Map<string, PhotoWallImage>();
     for (const image of images) if (!byUrl.has(image.url)) byUrl.set(image.url, image);
     return Array.from(byUrl.values());
-  }, [images, requestWidth]);
+  }, [images, requestWidth, inScope]);
   // Each picture is measured at the url it is drawn from (the boxed `Image`'s
   // `optimizedWidth`: the host's resizer at the column's width), so it is downloaded once.
   const drawnWidth = requestWidth ?? undefined;

package/src/components/ui/product-screen-frame.tsx

@@ -4,6 +4,7 @@ import { type CSSProperties, type ReactNode, useLayoutEffect, useRef, useState }
 import { LAYOUT_STEPS } from '../../styles/layout-steps';
 import { cn } from '../../utils/cn';
 import { PagePicture } from '../layout/page-picture';
+import { LoadingScope } from './loading-scope';
 import { CollisionBoundaryContext, PortalContainerContext } from './portal-container';
 
 /** The widest content step: a product screen is drawn at this width and scaled to its frame. */
@@ -69,7 +70,8 @@ export function ProductScreenFrame({
   const [frame, setFrame] = useState<HTMLDivElement | null>(null);
   const [portalHost, setPortalHost] = useState<HTMLDivElement | null>(null);
   // Which layout the screen takes. `pending` until measured: the frame keeps its
-  // box and shows nothing, so the first paint is never the unscaled screen.
+  // box and the screen draws as its own loading state, so the first paint is
+  // never the unscaled real screen.
   // React holds only this (it changes at two widths); the scale itself changes
   // with every pixel of a resize, so it is written to a CSS variable on the
   // frame and never re-renders the screen.
@@ -118,11 +120,20 @@ export function ProductScreenFrame({
           <div
             inert
             aria-hidden
-            className={cn('ods-content-area', mode === 'pending' && 'invisible')}
+            className="ods-content-area"
             style={screenStyle}
           >
             <div className="ods-content-scope">
-              <PagePicture>{children}</PagePicture>
+              {/* Until measured (the server's HTML, a page without scripts) the screen is its own loading state: every
+                  component in it draws its skeleton, so the window shows the screen's shape instead of nothing, and
+                  the unscaled real screen is never painted. */}
+              {mode === 'pending' ? (
+                <LoadingScope bare>
+                  <PagePicture>{children}</PagePicture>
+                </LoadingScope>
+              ) : (
+                <PagePicture>{children}</PagePicture>
+              )}
             </div>
             <div ref={setPortalHost} style={{ display: 'contents' }} />
           </div>

package/src/components/ui/progress-bar.tsx

@@ -3,6 +3,18 @@
 import type React from 'react';
 import { useEffect, useRef, useState } from 'react';
 import { useContentMdUp } from '../../hooks/ui/use-content-breakpoint';
+import { cn } from '../../utils/cn';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
+
+/** The bar's height in px: below the content `md` step, and from it (the bar switches on the content's width). */
+export const PROGRESS_BAR_HEIGHT = { mobile: 8, desktop: 24 } as const;
+/** The same heights as a class (8px, 24px from `content-md`), read by the bar's box and by its skeleton. */
+const PROGRESS_BAR_HEIGHT_CLASS = 'h-2 content-md:h-6';
+
+/** The bar while its value is read: one box at the bar's own height, switched at the bar's own step. */
+export function ProgressBarSkeleton({ className }: { className?: string }) {
+  return <UnifiedSkeleton className={cn(PROGRESS_BAR_HEIGHT_CLASS, 'w-full rounded', className)} />;
+}
 
 type ProgressBarProps = {
   progress: number; // 0–100
@@ -23,8 +35,8 @@ export const ProgressBar: React.FC<ProgressBarProps> = ({
   segmentWidth = 3.43,
   mobileSegmentWidth = 5,
   segmentGap = 2,
-  height = 24,
-  mobileHeight = 8,
+  height = PROGRESS_BAR_HEIGHT.desktop,
+  mobileHeight = PROGRESS_BAR_HEIGHT.mobile,
   inverted = false,
 }) => {
   const isMdUp = useContentMdUp() ?? true;
@@ -70,7 +82,18 @@ export const ProgressBar: React.FC<ProgressBarProps> = ({
   };
 
   return (
-    <div ref={containerRef} className="flex w-full" style={{ gap: `${segmentGap}px` }}>
+    <div
+      ref={containerRef}
+      // The box holds the bar's height before its segments are counted: the default heights by the class the skeleton
+      // reads, a host's own by style.
+      className={cn(
+        'flex w-full',
+        height === PROGRESS_BAR_HEIGHT.desktop &&
+          mobileHeight === PROGRESS_BAR_HEIGHT.mobile &&
+          PROGRESS_BAR_HEIGHT_CLASS,
+      )}
+      style={{ gap: `${segmentGap}px` }}
+    >
       {Array.from({ length: segmentCount }).map((_, i) => (
         <div
           key={i}

package/src/components/ui/progress.tsx

@@ -5,19 +5,30 @@ import { type ComponentPropsWithoutRef, type ElementRef, forwardRef } from 'reac
 
 import { cn } from '../../utils/cn';
 
+/**
+ * `default`: the original bar. `step`: a thin ODS bar (border-coloured track, accent fill)
+ * for a step line ("Step 1 of 2").
+ */
+const PROGRESS_VARIANT = {
+  default: { root: 'h-2 bg-secondary', indicator: 'bg-primary' },
+  step: { root: 'h-1 bg-ods-border', indicator: 'bg-ods-accent' },
+} as const;
+
 const Progress = forwardRef<
   ElementRef<typeof ProgressPrimitive.Root>,
   ComponentPropsWithoutRef<typeof ProgressPrimitive.Root> & {
     indicatorClassName?: string;
+    variant?: keyof typeof PROGRESS_VARIANT;
   }
->(({ className, value, indicatorClassName, ...props }, ref) => (
+>(({ className, value, indicatorClassName, variant = 'default', ...props }, ref) => (
   <ProgressPrimitive.Root
     ref={ref}
-    className={cn('relative h-2 w-full overflow-hidden rounded-full bg-secondary', className)}
+    className={cn('relative w-full overflow-hidden rounded-full', PROGRESS_VARIANT[variant].root, className)}
+    value={value}
     {...props}
   >
     <ProgressPrimitive.Indicator
-      className={cn('h-full w-full flex-1 bg-primary transition-all', indicatorClassName)}
+      className={cn('h-full w-full flex-1 transition-all', PROGRESS_VARIANT[variant].indicator, indicatorClassName)}
       style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
     />
   </ProgressPrimitive.Root>

package/src/components/ui/release-changelog-section.tsx

@@ -4,8 +4,12 @@ import { ChevronDown } from 'lucide-react';
 import type React from 'react';
 import { useState } from 'react';
 import type { ChangelogEntry } from '../../types/product-release';
-import { Badge } from './badge';
+import { cn } from '../../utils/cn';
+import { TextLineSkeleton, UnifiedSkeleton } from '../loading/unified-skeleton';
+import { Badge, BadgeSkeleton } from './badge';
+import { Button } from './button';
 import { FadePreview } from './fade-preview';
+import { useLoadingScope } from './loading-scope';
 import { RichMarkdownRenderer } from './markdown';
 
 interface ReleaseChangelogSectionProps {
@@ -39,12 +43,43 @@ interface ReleaseChangelogSectionProps {
    *  (YouTube, OG cards, etc.) work out of the box. Hosts that already
    *  wrap with a Supabase-aware preset can keep passing their own. */
   MarkdownRenderer?: React.ComponentType<{ content: string }>;
+  /** Mark the loaded section `data-loading-optional`: a block its page's loading state does not draw. */
+  loadingOptional?: boolean;
 }
 
 // Collapsed height for the preview-first mode. ~120px shows the first
 // entry's title + the start of its description before the mask kicks in.
 const PREVIEW_COLLAPSED_HEIGHT = 120;
 
+/** The section's layout, read by the section and by its skeleton, so the skeleton is the section's size. */
+const SECTION_CLASS = 'space-y-4';
+const COLLAPSIBLE_TITLE_ROW_CLASS = 'flex w-full cursor-pointer items-center justify-between';
+/**
+ * The collapsible title row as a `glyph` `Button` (no surface, no box of its own: `size="wrap"`): it lets the
+ * heading wrap, and restates the heading icon's 24px, because a Button sizes every svg inside it.
+ */
+const COLLAPSIBLE_TITLE_BUTTON_CLASS = cn(
+  COLLAPSIBLE_TITLE_ROW_CLASS,
+  'whitespace-normal text-left [&_svg]:h-6 [&_svg]:w-6',
+);
+const TITLE_BASE_CLASS = 'flex items-center gap-2 text-h2';
+const titleClass = (isBreaking: boolean) =>
+  `${TITLE_BASE_CLASS} ${isBreaking ? 'text-ods-error' : 'text-ods-text-primary'}`;
+const COUNT_BADGE_CLASS = 'ml-2';
+/** 16px, kept against the title Button's svg size (`!`). */
+const CHEVRON_CLASS = '!h-4 !w-4 shrink-0 text-ods-text-secondary transition-transform duration-200';
+const ENTRY_LIST_CLASS = 'space-y-6';
+const ENTRY_CLASS = 'ml-0 border-l-2 border-ods-border pl-4';
+const ENTRY_TITLE_CLASS =
+  'mb-2 text-ods-text-primary text-h3 [&_p+p]:!mt-2 [&_p]:!my-0 [&_p]:!text-[length:var(--font-size-h3-body)] [&_p]:!font-bold [&_p]:!leading-[var(--font-line-space-h3-body)]';
+const ENTRY_DESCRIPTION_CLASS =
+  'text-ods-text-primary text-h4 [&_p]:!text-[length:var(--font-size-h4-body)] [&_p]:!font-medium [&_p]:!leading-[var(--font-line-space-h4-body)]';
+/** FadePreview's toggle row: a `size="compact"` link Button (h-6, at every width) under a `mf` gap. */
+const COMPACT_BUTTON_HEIGHT_CLASS = 'h-6';
+const PREVIEW_TOGGLE_SKELETON_CLASS = cn('mt-[var(--spacing-system-mf)] w-28', COMPACT_BUTTON_HEIGHT_CLASS);
+/** Entries a skeleton draws when it is not told how many (the first fold of a section). */
+const CHANGELOG_SKELETON_ENTRIES = 1;
+
 export function ReleaseChangelogSection({
   title,
   entries,
@@ -55,8 +90,23 @@ export function ReleaseChangelogSection({
   previewFirst = false,
   icon,
   MarkdownRenderer = RichMarkdownRenderer,
+  loadingOptional = false,
 }: ReleaseChangelogSectionProps) {
   const [collapsed, setCollapsed] = useState(collapsible ? defaultCollapsed : false);
+  const loading = useLoadingScope();
+
+  if (loading)
+    return (
+      <ReleaseChangelogSectionSkeleton
+        title={title}
+        isBreaking={isBreaking}
+        hideTitle={hideTitle}
+        collapsible={collapsible}
+        defaultCollapsed={defaultCollapsed}
+        previewFirst={previewFirst}
+        icon={icon}
+      />
+    );
 
   if (!entries || entries.length === 0) return null;
 
@@ -65,34 +115,31 @@ export function ReleaseChangelogSection({
   const showEntries = !collapsible || !collapsed;
 
   return (
-    <div className="space-y-4">
+    <div className={SECTION_CLASS} data-loading-optional={loadingOptional || undefined}>
       {!hideTitle &&
         (collapsible ? (
-          <button
+          <Button
             type="button"
+            variant="glyph"
+            size="wrap"
             onClick={() => setCollapsed(!collapsed)}
-            className="flex w-full cursor-pointer items-center justify-between"
+            aria-expanded={!collapsed}
+            className={COLLAPSIBLE_TITLE_BUTTON_CLASS}
           >
-            <h2
-              className={`flex items-center gap-2 text-h2 ${isBreaking ? 'text-ods-error' : 'text-ods-text-primary'}`}
-            >
+            <h2 className={titleClass(isBreaking)}>
               {icon}
               {title}
-              <Badge variant="secondary" className="ml-2">
+              <Badge variant="secondary" className={COUNT_BADGE_CLASS}>
                 {entries.length}
               </Badge>
             </h2>
-            <ChevronDown
-              className={`h-4 w-4 shrink-0 text-ods-text-secondary transition-transform duration-200 ${
-                !collapsed ? 'rotate-180' : ''
-              }`}
-            />
-          </button>
+            <ChevronDown className={`${CHEVRON_CLASS} ${!collapsed ? 'rotate-180' : ''}`} />
+          </Button>
         ) : (
-          <h2 className={`flex items-center gap-2 text-h2 ${isBreaking ? 'text-ods-error' : 'text-ods-text-primary'}`}>
+          <h2 className={titleClass(isBreaking)}>
             {icon}
             {title}
-            <Badge variant="secondary" className="ml-2">
+            <Badge variant="secondary" className={COUNT_BADGE_CLASS}>
               {entries.length}
             </Badge>
           </h2>
@@ -129,9 +176,9 @@ function ChangelogEntryList({
   MarkdownRenderer: React.ComponentType<{ content: string }>;
 }) {
   return (
-    <ul className="space-y-6">
+    <ul className={ENTRY_LIST_CLASS}>
       {entries.map((entry, index) => (
-        <li key={index} className="ml-0 border-l-2 border-ods-border pl-4">
+        <li key={index} className={ENTRY_CLASS}>
           {/* Entry title — run through the SAME markdown renderer as the
               description so inline markdown (links like `[label](url)`,
               emphasis) renders instead of showing as raw text, then pinned
@@ -140,7 +187,7 @@ function ChangelogEntryList({
               so plain-text titles look exactly as before. `[&_p]:!my-0`
               strips the renderer's paragraph margins; `mb-2` keeps the gap to
               the description. */}
-          <div className="mb-2 text-ods-text-primary text-h3 [&_p+p]:!mt-2 [&_p]:!my-0 [&_p]:!text-[length:var(--font-size-h3-body)] [&_p]:!font-bold [&_p]:!leading-[var(--font-line-space-h3-body)]">
+          <div className={ENTRY_TITLE_CLASS}>
             <MarkdownRenderer content={entry.title} />
           </div>
           {entry.description && (
@@ -151,7 +198,7 @@ function ChangelogEntryList({
                inflate the changelog body to 20px. The `[&_p]:!` overrides
                pin every descendant `<p>` back to the h4 responsive tokens
                so the breakpoints stay aligned with the rest of the page. */
-            <div className="text-ods-text-primary text-h4 [&_p]:!text-[length:var(--font-size-h4-body)] [&_p]:!font-medium [&_p]:!leading-[var(--font-line-space-h4-body)]">
+            <div className={ENTRY_DESCRIPTION_CLASS}>
               <MarkdownRenderer content={entry.description} />
             </div>
           )}
@@ -160,3 +207,89 @@ function ChangelogEntryList({
     </ul>
   );
 }
+
+export interface ReleaseChangelogSectionSkeletonProps {
+  /** The section's heading (static copy: drawn for real). */
+  title: string;
+  /** Entries drawn when not `previewFirst` (the first fold). Default 1. */
+  count?: number;
+  isBreaking?: boolean;
+  hideTitle?: boolean;
+  collapsible?: boolean;
+  defaultCollapsed?: boolean;
+  /** The preview-first mode: the first entry clamped to the preview height, then the toggle row. */
+  previewFirst?: boolean;
+  icon?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * A changelog section while it is read: the real icon and heading, the count badge as a chip, the first entry (title
+ * line and description lines) as bars, clamped to the preview height with FadePreview's toggle row in preview mode.
+ */
+export function ReleaseChangelogSectionSkeleton({
+  title,
+  count = CHANGELOG_SKELETON_ENTRIES,
+  isBreaking = false,
+  hideTitle = false,
+  collapsible = false,
+  defaultCollapsed = true,
+  previewFirst = false,
+  icon,
+  className,
+}: ReleaseChangelogSectionSkeletonProps) {
+  const heading = (
+    <h2 className={titleClass(isBreaking)}>
+      {icon}
+      {title}
+      {/* The count badge's own frame; its text is one or two digits. */}
+      <BadgeSkeleton className={cn(COUNT_BADGE_CLASS, 'w-[2ch]')} />
+    </h2>
+  );
+  const inPreviewMode = previewFirst && !collapsible;
+  const showEntries = !collapsible || !defaultCollapsed;
+  const list = <ChangelogEntryListSkeleton count={inPreviewMode ? 1 : count} />;
+  return (
+    <div className={cn(SECTION_CLASS, className)} aria-hidden>
+      {!hideTitle &&
+        (collapsible ? (
+          <div className={COLLAPSIBLE_TITLE_ROW_CLASS}>
+            {heading}
+            <ChevronDown className={cn(CHEVRON_CLASS, !defaultCollapsed && 'rotate-180')} />
+          </div>
+        ) : (
+          heading
+        ))}
+      {showEntries &&
+        (inPreviewMode ? (
+          <div className="relative">
+            <div className="overflow-hidden" style={{ maxHeight: PREVIEW_COLLAPSED_HEIGHT }}>
+              {list}
+            </div>
+            <UnifiedSkeleton className={PREVIEW_TOGGLE_SKELETON_CLASS} />
+          </div>
+        ) : (
+          list
+        ))}
+    </div>
+  );
+}
+
+function ChangelogEntryListSkeleton({ count }: { count: number }) {
+  return (
+    <ul className={ENTRY_LIST_CLASS}>
+      {Array.from({ length: count }, (_, index) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: skeleton entries never reorder
+        <li key={index} className={ENTRY_CLASS}>
+          <div className={ENTRY_TITLE_CLASS}>
+            <TextLineSkeleton type="h3" className="w-2/3" />
+          </div>
+          <div className={ENTRY_DESCRIPTION_CLASS}>
+            {/* Five lines: in preview mode the entry runs past the 120px clamp, as a real first entry does. */}
+            <TextLineSkeleton type="inherit" lines={5} className="w-full" />
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}