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

package/src/components/ui/analyzing-state.tsx

@@ -1,6 +1,7 @@
+import { DOT_SIZE } from '../../styles/component-sizes';
 import { cn } from '../../utils/cn';
 import { ChatTypingIndicator } from '../chat/chat-typing-indicator';
-import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { LIVE_PULSE_CLASS } from './skeleton-surface';
 
 export interface AnalyzingStateProps {
   /** What is being worked on, as a sentence with no closing mark ("Mingo is analyzing your logs"). */
@@ -12,6 +13,9 @@ export interface AnalyzingStateProps {
 const ROW_OPACITY = ['opacity-100', 'opacity-60', 'opacity-30'] as const;
 /** Each row pulses a beat after the one above it, so the eye reads them as a scan. */
 const ROW_STAGGER_MS = 200;
+/** A row's marks: a live dot and two bars of the row's own words, on ODS tokens. Live, not a loading state. */
+const ROW_DOT_CLASS = cn(DOT_SIZE.sm, 'shrink-0 rounded-full bg-ods-flamingo-cyan', LIVE_PULSE_CLASS);
+const ROW_BAR_CLASS = cn('h-2.5 rounded-md bg-ods-border', LIVE_PULSE_CLASS);
 
 /**
  * THE "it is working, nothing to show yet" state of a feed or a window: three
@@ -19,8 +23,9 @@ const ROW_STAGGER_MS = 200;
  * and the chat's own typing dots. It says an agent is at work, where a bare
  * sentence in an empty box reads as idle.
  *
- * Built from the shared pieces only: `UnifiedSkeleton` for the rows and
- * `ChatTypingIndicator` for the dots. Still under reduced motion. It is
+ * It is a live state, never a loading one: the rows pulse on the library's live pulse (`LIVE_PULSE_CLASS`), so no
+ * skeleton surface is left on a loaded page, and the dots are the chat's `ChatTypingIndicator`. Still under
+ * reduced motion. It is
  * announced as a status; the rows and dots are decoration.
  */
 export function AnalyzingState({ label, className }: AnalyzingStateProps) {
@@ -37,9 +42,9 @@ export function AnalyzingState({ label, className }: AnalyzingStateProps) {
                 opacity,
               )}
             >
-              <UnifiedSkeleton className="h-2 w-2 shrink-0 rounded-full bg-ods-flamingo-cyan" style={delay} />
-              <UnifiedSkeleton className="h-2.5 min-w-0 flex-1" style={delay} />
-              <UnifiedSkeleton className="h-2.5 w-12 shrink-0" style={delay} />
+              <span className={ROW_DOT_CLASS} style={delay} />
+              <span className={cn(ROW_BAR_CLASS, 'min-w-0 flex-1')} style={delay} />
+              <span className={cn(ROW_BAR_CLASS, 'w-12 shrink-0')} style={delay} />
             </div>
           );
         })}

package/src/components/ui/announcement-bar-view.tsx

@@ -4,6 +4,12 @@ import type { CSSProperties, ReactElement, ReactNode } from 'react';
 import { breakpoints } from '../../hooks/ui/use-media-query';
 import { cn } from '../../utils/cn';
 
+/**
+ * The bar's height (the 44px one-line strip, see the design note on `AnnouncementBarView`): read by the bar and by
+ * every shape that stands for it (a preview's loading state).
+ */
+export const ANNOUNCEMENT_BAR_HEIGHT_CLASS = 'min-h-11';
+
 export interface AnnouncementBarViewProps {
   /**
    * Leading slot — typically an icon, at content width before the title. Size
@@ -89,7 +95,7 @@ export function AnnouncementBarView({
     : undefined;
 
   return (
-    <div className={cn('flex min-h-11 w-full max-w-full items-center', className)} style={style}>
+    <div className={cn('flex w-full max-w-full items-center', ANNOUNCEMENT_BAR_HEIGHT_CLASS, className)} style={style}>
       {/* Content row — the tap target below `md`, where the CTA is hidden.
           Its vertical padding never drives the height; the 44px strip does. */}
       <div

package/src/components/ui/autocomplete.tsx

@@ -24,8 +24,11 @@ import { Chevron02DownIcon } from '../icons-v2-generated/arrows/chevron-02-down-
 import { TrashIcon } from '../icons-v2-generated/interface/trash-icon';
 import { CheckIcon } from '../icons-v2-generated/signs-and-symbols/check-icon';
 import { XmarkCircleIcon } from '../icons-v2-generated/signs-and-symbols/xmark-circle-icon';
+import { LoadingRegion } from '../loading/loading-region';
+import { TextLineSkeleton, UnifiedSkeleton } from '../loading/unified-skeleton';
 import { FieldWrapper } from './field-wrapper';
 import { HiddenTagsPopup } from './hidden-tags-popup';
+import { useLoadingScope } from './loading-scope';
 import { Tag } from './tag';
 import { TruncateText } from './truncate-text';
 
@@ -99,6 +102,11 @@ interface AutocompleteBaseProps<T = string> {
   loading?: boolean;
   /** Loading text */
   loadingText?: string;
+  /**
+   * The field itself is read and has not arrived (its value and its options): it draws its skeleton, as in a
+   * loading scope. DISTINCT from `loading`, a search in flight under a field that stays up.
+   */
+  fieldLoading?: boolean;
   /** When true, shows a clickable "+ Create" option when no results match the input */
   creatable?: boolean;
   /** Callback fired after a new option is created via creatable. Use it to persist the new option server-side, etc. */
@@ -159,7 +167,34 @@ const innerInputStyles = cn(
   'disabled:cursor-not-allowed disabled:text-ods-text-disabled disabled:placeholder:text-ods-border',
 );
 
+/** The field's height, read by the field and by its skeleton. */
+const AUTOCOMPLETE_ANCHOR_HEIGHT_CLASS = 'min-h-11 md:min-h-12';
+/** An option row's frame, read by the rows and by the list's loading state. */
+const AUTOCOMPLETE_OPTION_ROW_CLASS =
+  'flex min-h-11 items-center border-b border-ods-border px-[var(--spacing-system-mf)] py-[var(--spacing-system-xsf)] last:border-b-0 md:min-h-12 text-h4';
+/** Option rows the list's loading state draws: the 240px scroller holds five 48px rows. */
+const AUTOCOMPLETE_OPTIONS_FOLD = 5;
+const AUTOCOMPLETE_ANCHOR_SHAPE_CLASS = 'rounded-[6px]';
+
+export interface AutocompleteSkeletonProps {
+  /** The field's label: the page's own words, drawn as they are. */
+  label?: string;
+  labelVariant?: 'default' | 'large';
+  className?: string;
+}
+
+/** A field while its options are read: its label for real, its control a box of the control's height. */
+export function AutocompleteSkeleton({ label, labelVariant, className }: AutocompleteSkeletonProps) {
+  return (
+    <FieldWrapper label={label} labelVariant={labelVariant} className={className}>
+      <UnifiedSkeleton className={cn('w-full', AUTOCOMPLETE_ANCHOR_SHAPE_CLASS, AUTOCOMPLETE_ANCHOR_HEIGHT_CLASS)} />
+    </FieldWrapper>
+  );
+}
+
 function AutocompleteInner<T = string>(props: AutocompleteProps<T>, ref: ForwardedRef<HTMLDivElement>) {
+  // In a loading scope the field is its skeleton (drawn at the end, after every hook has run).
+  const inScope = useLoadingScope();
   const {
     options,
     disabled = false,
@@ -178,7 +213,8 @@ function AutocompleteInner<T = string>(props: AutocompleteProps<T>, ref: Forward
     inputValue: inputValueProp,
     onInputChange,
     loading = false,
-    loadingText = 'Loading...',
+    loadingText = 'Loading options',
+    fieldLoading = false,
     creatable = false,
     onCreateOption,
     maxCreateLength,
@@ -470,7 +506,9 @@ function AutocompleteInner<T = string>(props: AutocompleteProps<T>, ref: Forward
           data-invalid={isInvalid || undefined}
           className={cn(
             // Layout — single line, no wrapping
-            'flex min-h-11 cursor-text items-center rounded-[6px] border md:min-h-12',
+            'flex cursor-text items-center border',
+            AUTOCOMPLETE_ANCHOR_SHAPE_CLASS,
+            AUTOCOMPLETE_ANCHOR_HEIGHT_CLASS,
             'focus-within:outline-none',
             'transition-colors duration-200',
             'border-ods-border bg-ods-card',
@@ -645,9 +683,20 @@ function AutocompleteInner<T = string>(props: AutocompleteProps<T>, ref: Forward
       >
         <ScrollAreaPrimitive.Root className="flex min-h-0 flex-col overflow-hidden">
           <ScrollAreaPrimitive.Viewport className="max-h-[240px] min-h-0 w-full [&>div]:!block">
-            <div role="listbox">
+            {/* A listbox owns options only: while they are read the box is the loading region's (a status and
+                hidden rows), with no listbox role around it. */}
+            <div role={loading ? undefined : 'listbox'}>
               {loading ? (
-                <div className="px-3 py-2 text-ods-text-secondary text-h6">{loadingText}</div>
+                // The options while they are read: the list's own rows, a label bar each (`loadingText` is what a
+                // screen reader hears).
+                <LoadingRegion label={loadingText}>
+                  {Array.from({ length: AUTOCOMPLETE_OPTIONS_FOLD }, (_, i) => (
+                    // biome-ignore lint/suspicious/noArrayIndexKey: skeleton rows never reorder
+                    <div key={i} className={AUTOCOMPLETE_OPTION_ROW_CLASS} aria-hidden>
+                      <TextLineSkeleton type="inherit" className="w-2/3" />
+                    </div>
+                  ))}
+                </LoadingRegion>
               ) : filteredOptions.length === 0 ? (
                 showCreateOption ? (
                   isCreateTooLong ? (
@@ -691,8 +740,8 @@ function AutocompleteInner<T = string>(props: AutocompleteProps<T>, ref: Forward
                       className={cn(
                         // `min-h` rather than a fixed height: an option may carry
                         // a second line, and a clipped one is worse than a taller row.
-                        'group/item flex min-h-11 cursor-pointer items-center border-b border-ods-border px-[var(--spacing-system-mf)] py-[var(--spacing-system-xsf)] transition-colors last:border-b-0 md:min-h-12',
-                        'text-h4',
+                        AUTOCOMPLETE_OPTION_ROW_CLASS,
+                        'group/item cursor-pointer transition-colors',
                         isHighlighted && 'bg-ods-bg-surface',
                         isSelected ? 'text-ods-accent' : 'text-ods-text-primary',
                         !isHighlighted && 'hover:bg-ods-bg-hover',
@@ -755,6 +804,9 @@ function AutocompleteInner<T = string>(props: AutocompleteProps<T>, ref: Forward
     </PopoverPrimitive.Root>
   );
 
+  if (inScope || fieldLoading)
+    return <AutocompleteSkeleton label={label} labelVariant={labelVariant} className={className} />;
+
   return (
     <FieldWrapper
       label={label}

package/src/components/ui/avatar-stack.tsx

@@ -1,6 +1,8 @@
 'use client';
 
 import { cn } from '../../utils/cn';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
+import { useLoadingScope } from './loading-scope';
 import { SquareAvatar } from './square-avatar';
 
 /**
@@ -63,6 +65,41 @@ const OVERFLOW_CIRCLE_SIZE: Record<AvatarStackSize, string> = {
   lg: 'h-12 min-w-12',
 };
 
+const STACK_ROW_CLASS = 'flex items-center';
+/** How far each later face tucks under the previous one, as the class both the stack and its skeleton use. */
+const overlapClass = (size: AvatarStackSize) => (size === 'xs' ? '-ml-2' : '-ml-3');
+/** A fixed-width stack's width (`slots`). */
+const slotsWidthStyle = (size: AvatarStackSize, slots?: number) =>
+  slots ? { width: SIZE_PX[size] + (slots - 1) * (SIZE_PX[size] - OVERLAP_PX[size]) } : undefined;
+
+/** A stack while its people are read: `count` overlapped circles of the faces' size. */
+export function AvatarStackSkeleton({
+  count = 3,
+  size = 'md',
+  slots,
+  className,
+}: {
+  count?: number;
+  size?: AvatarStackSize;
+  slots?: number;
+  className?: string;
+}) {
+  return (
+    <div aria-hidden className={cn(STACK_ROW_CLASS, slots && 'shrink-0', className)} style={slotsWidthStyle(size, slots)}>
+      {Array.from({ length: count }, (_, i) => (
+        <UnifiedSkeleton
+          // biome-ignore lint/suspicious/noArrayIndexKey: skeleton faces never reorder
+          key={i}
+          variant="circular"
+          className={cn('relative shrink-0 ring-2 ring-ods-card', i > 0 && overlapClass(size))}
+          width={SIZE_PX[size]}
+          height={SIZE_PX[size]}
+        />
+      ))}
+    </div>
+  );
+}
+
 export function AvatarStack({
   people,
   max = 3,
@@ -73,6 +110,8 @@ export function AvatarStack({
   label = 'Assignees',
   className,
 }: AvatarStackProps) {
+  const loading = useLoadingScope();
+  if (loading) return <AvatarStackSkeleton count={slots ?? max} size={size} slots={slots} className={className} />;
   if (people.length === 0) return null;
   const groupSize = Math.max(total ?? people.length, people.length);
   const faces = slots ? (groupSize > slots ? slots - 1 : slots) : max;
@@ -85,8 +124,8 @@ export function AvatarStack({
   const compact = size === 'xs';
   return (
     <div
-      className={cn('flex items-center', slots && 'shrink-0', className)}
-      style={slots ? { width: SIZE_PX[size] + (slots - 1) * (SIZE_PX[size] - OVERLAP_PX[size]) } : undefined}
+      className={cn(STACK_ROW_CLASS, slots && 'shrink-0', className)}
+      style={slotsWidthStyle(size, slots)}
       role="group"
       aria-label={`${label}: ${names}${unnamed > 0 ? ` and ${unnamed} more` : ''}`}
     >
@@ -99,7 +138,7 @@ export function AvatarStack({
           alt={person.name}
           fallback={person.name}
           title={person.name}
-          className={cn('relative ring-2', ringClassName, i > 0 && (compact ? '-ml-2' : '-ml-3'))}
+          className={cn('relative ring-2', ringClassName, i > 0 && overlapClass(size))}
           // Leftmost (primary assignee) on TOP — later avatars tuck
           // BEHIND, so the first face is always fully visible.
           style={{ zIndex: visible.length - i }}

package/src/components/ui/badge.tsx

@@ -4,6 +4,7 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import type { HTMLAttributes } from 'react';
 
 import { cn } from '../../utils/cn';
+import { UnifiedSkeleton } from '../loading/unified-skeleton';
 
 const badgeVariants = cva(
   // Weight from the ODS token. Scale stays at 12px rather than the `text-h6`
@@ -32,4 +33,18 @@ function Badge({ className, variant, ...props }: BadgeProps) {
   return <div className={cn(badgeVariants({ variant }), className)} {...props} />;
 }
 
-export { Badge, badgeVariants };
+/**
+ * A badge while its text is read: one skeleton box with the badge's own frame, padding and type step, its content
+ * one line of that step (`box-content`: the padding adds to the line, as it does around the badge's text). The
+ * width stands for the text (`className` overrides it).
+ */
+function BadgeSkeleton({ className }: { className?: string }) {
+  return (
+    <UnifiedSkeleton
+      as="span"
+      className={cn(badgeVariants({ variant: null }), 'box-content h-[1lh] w-10 border-transparent', className)}
+    />
+  );
+}
+
+export { Badge, BadgeSkeleton, badgeVariants };

package/src/components/ui/benefit-list.tsx

@@ -1,17 +1,48 @@
 import type { ReactNode } from 'react';
+import { ICON_SIZE } from '../../styles/component-sizes';
 import { cn } from '../../utils/cn';
 import { trialLabels } from '../../utils/trial';
 import { FileOffIcon } from '../icons-v2-generated/documents/file-off-icon';
 import { CreditCardXmarkIcon } from '../icons-v2-generated/finance/credit-card-xmark-icon';
 import { FlaskVialIcon } from '../icons-v2-generated/school/flask-vial-icon';
 import { XmarkAltIcon } from '../icons-v2-generated/signs-and-symbols/xmark-alt-icon';
+import { TextHold } from './layout-hold';
 
 export interface BenefitItem {
   /** Drawn at 16px in the quiet colour. */
   icon?: ReactNode;
   label: string;
+  /**
+   * The words carry read data that is not here yet ("Trusted by {count} MSPs" before the count): pass the copy with
+   * its slots unfilled. The mark and the page's own words are drawn real, and each `{slot}` is a bar as wide as
+   * `typical` (a typical value of the data, held unseen: `'000'` for a count).
+   */
+  loading?: boolean;
+  /** A typical value of a loading item's slots, whose width each slot's bar takes. */
+  typical?: string;
+}
+
+/** A loading benefit's words: the copy real, each `{slot}` a bar as wide as a typical value. */
+function LoadingLabel({ label, typical }: { label: string; typical: string }) {
+  return (
+    <>
+      {label.split(/(\{\w+\})/).map((part, index) =>
+        /^\{\w+\}$/.test(part) ? (
+          // biome-ignore lint/suspicious/noArrayIndexKey: the parts of one fixed string never reorder
+          <TextHold key={index}>{typical}</TextHold>
+        ) : (
+          part
+        ),
+      )}
+    </>
+  );
 }
 
+/** A benefit's layout, read by the benefit and by its loading form. */
+const BENEFIT_ITEM_CLASS = 'flex items-center gap-[var(--spacing-system-xs)]';
+const BENEFIT_ICON_CLASS = `flex ${ICON_SIZE.sm} shrink-0 items-center justify-center text-ods-text-secondary [&_svg]:size-4`;
+const BENEFIT_LABEL_CLASS = 'whitespace-nowrap text-ods-text-primary text-h4';
+
 /** The mark of each of the trial's terms, wherever a term is listed. */
 export const TRIAL_TERM_ICONS = {
   noCard: <CreditCardXmarkIcon />,
@@ -80,16 +111,20 @@ export function BenefitList({
       )}
     >
       {all.map(item => (
-        <li key={item.label} className="flex items-center gap-[var(--spacing-system-xs)]">
+        <li key={item.label} className={BENEFIT_ITEM_CLASS}>
           {item.icon && (
-            <span
-              className="flex size-4 shrink-0 items-center justify-center text-ods-text-secondary [&_svg]:size-4"
-              aria-hidden
-            >
+            <span className={BENEFIT_ICON_CLASS} aria-hidden>
               {item.icon}
             </span>
           )}
-          <span className="whitespace-nowrap text-ods-text-primary text-h4">{item.label}</span>
+          {item.loading ? (
+            // The page's own words, real, and a bar where each read value goes: the row keeps its box.
+            <span className={BENEFIT_LABEL_CLASS}>
+              <LoadingLabel label={item.label} typical={item.typical ?? '000'} />
+            </span>
+          ) : (
+            <span className={BENEFIT_LABEL_CLASS}>{item.label}</span>
+          )}
         </li>
       ))}
     </ul>

package/src/components/ui/button/button-styles.ts

@@ -78,3 +78,51 @@ export const splitDividerColorClasses = {
 } as const;
 
 export type ButtonSurfaceVariant = keyof typeof buttonSurfaceClasses;
+
+/**
+ * A button's box per size (height, padding, label type, glyph size): read by `buttonVariants` and by
+ * `InteractiveSkeleton.Button`'s `size`, so a button's skeleton is the button's box at every breakpoint.
+ */
+export const BUTTON_SIZE_CLASS = {
+  default: 'h-11 px-[var(--spacing-system-m)] py-[var(--spacing-system-sf)] text-h3 md:h-12',
+  small: 'h-6 p-[var(--spacing-system-xs)] text-h5 md:h-8',
+  // The CHILD is the affordance (a badge, a chip, a thumbnail): the button
+  // contributes the hit target, the focus ring and the keyboard/ARIA
+  // semantics, and NO box of its own. Without this, call sites reached for
+  // a `className="h-auto p-0"` override to cancel the default box.
+  wrap: 'h-auto p-0',
+  'small-legacy': 'h-10 px-[var(--spacing-system-m)] py-[var(--spacing-system-xs)] text-[14px] font-bold', // Temporary alias for "small" — deprecated; grep size="small-legacy" (lib + hub) and migrate the remaining consumers before removal
+  // 24px pill for slim strips (announcement/promo bars, inline banner
+  // actions — Primer banner / Polaris banner / Vercel-bar convention).
+  // The label matches the strip's MESSAGE type ramp exactly (DM Sans
+  // regular, 13px -> md:14px, snug leading — the announcement bar's
+  // subtitle styling): in-strip CTAs must never read louder than the
+  // message beside them, so this deliberately uses neither the
+  // mono-uppercase control style of "small" nor a heavier weight.
+  // Pinned h-6 across breakpoints (24px = the WCAG 2.5.8 target-size
+  // floor) with horizontal-dominant padding and a 14px glyph.
+  compact: 'h-6 px-[var(--spacing-system-sf)] py-0 font-normal text-h6 [&_svg]:h-3.5 [&_svg]:w-3.5',
+  icon: 'h-11 w-11 p-[var(--spacing-system-sf)] md:h-12 md:w-12 [&_svg]:h-4 [&_svg]:w-4 md:[&_svg]:h-6 md:[&_svg]:w-6',
+  // Quiet 32px icon target with a 16px glyph, fixed across breakpoints
+  // (Carbon ghost sm / Primer medium / shadcn icon-sm all pin 32px;
+  // ≥ the 24px WCAG 2.5.8 target floor). For icon actions that read as
+  // metadata rather than CTAs — author-page social rows, share rows.
+  // Pair with variant="transparent" for the ghost treatment.
+  // `BUTTON_ICON_SM_SIZE` states the same 32px for a layout that must clear one.
+  'icon-sm': 'h-8 w-8 p-[var(--spacing-system-xxs)] [&_svg]:h-4 [&_svg]:w-4',
+  // 20px inline glyph for affordances that sit INSIDE a line of text —
+  // an info hint beside a badge, a copy glyph after an id. `icon-sm`'s
+  // 32px target is correct for a metadata row but visually swamps a
+  // 10px badge or a 14px label, so hosts were reaching for className
+  // overrides to shrink it. Below the WCAG 2.5.8 target floor on purpose:
+  // this is only for glyphs whose information is ALSO available another
+  // way (tooltip content mirrored into an aria-describedby node), never
+  // for a sole means of performing an action.
+  'icon-inline': 'h-5 min-h-0 w-5 min-w-0 shrink-0 p-0 [&_svg]:h-3.5 [&_svg]:w-3.5',
+  // Bare 56px media glyph (play / unmute over video). A size variant so
+  // hosts stop re-implementing a <button> to escape the 20px svg cap.
+  'icon-glyph': 'h-14 w-14 p-0 [&_svg]:h-14 [&_svg]:w-14',
+} as const;
+
+export type ButtonSizeKey = keyof typeof BUTTON_SIZE_CLASS;
+

package/src/components/ui/button/button.tsx

@@ -6,6 +6,7 @@ import React from 'react';
 import Link from '../../../embed-shims/next-link';
 import { cn } from '../../../utils/cn';
 import {
+  BUTTON_SIZE_CLASS,
   buttonSurfaceClasses,
   outlineBorderClasses,
   splitDividerColorClasses,
@@ -13,6 +14,9 @@ import {
 } from './button-styles';
 
 // Default layout: centered single content area, padding/gap on the button itself.
+/** The `icon-sm` button's size (its `h-8 w-8`), for a layout that must leave room for one. */
+export const BUTTON_ICON_SM_SIZE = '2rem';
+
 const buttonVariants = cva(
   [
     'relative inline-flex items-center justify-center gap-[var(--spacing-system-xsf)]',
@@ -35,45 +39,7 @@ const buttonVariants = cva(
         overlay: buttonSurfaceClasses.overlay,
         link: buttonSurfaceClasses.link,
       },
-      size: {
-        default: 'h-11 px-[var(--spacing-system-m)] py-[var(--spacing-system-sf)] text-h3 md:h-12',
-        small: 'h-6 p-[var(--spacing-system-xs)] text-h5 md:h-8',
-        // The CHILD is the affordance (a badge, a chip, a thumbnail): the button
-        // contributes the hit target, the focus ring and the keyboard/ARIA
-        // semantics, and NO box of its own. Without this, call sites reached for
-        // a `className="h-auto p-0"` override to cancel the default box.
-        wrap: 'h-auto p-0',
-        'small-legacy': 'h-10 px-[var(--spacing-system-m)] py-[var(--spacing-system-xs)] text-[14px] font-bold', // Temporary alias for "small" — deprecated; grep size="small-legacy" (lib + hub) and migrate the remaining consumers before removal
-        // 24px pill for slim strips (announcement/promo bars, inline banner
-        // actions — Primer banner / Polaris banner / Vercel-bar convention).
-        // The label matches the strip's MESSAGE type ramp exactly (DM Sans
-        // regular, 13px -> md:14px, snug leading — the announcement bar's
-        // subtitle styling): in-strip CTAs must never read louder than the
-        // message beside them, so this deliberately uses neither the
-        // mono-uppercase control style of "small" nor a heavier weight.
-        // Pinned h-6 across breakpoints (24px = the WCAG 2.5.8 target-size
-        // floor) with horizontal-dominant padding and a 14px glyph.
-        compact: 'h-6 px-[var(--spacing-system-sf)] py-0 font-normal text-h6 [&_svg]:h-3.5 [&_svg]:w-3.5',
-        icon: 'h-11 w-11 p-[var(--spacing-system-sf)] md:h-12 md:w-12 [&_svg]:h-4 [&_svg]:w-4 md:[&_svg]:h-6 md:[&_svg]:w-6',
-        // Quiet 32px icon target with a 16px glyph, fixed across breakpoints
-        // (Carbon ghost sm / Primer medium / shadcn icon-sm all pin 32px;
-        // ≥ the 24px WCAG 2.5.8 target floor). For icon actions that read as
-        // metadata rather than CTAs — author-page social rows, share rows.
-        // Pair with variant="transparent" for the ghost treatment.
-        'icon-sm': 'h-8 w-8 p-[var(--spacing-system-xxs)] [&_svg]:h-4 [&_svg]:w-4',
-        // 20px inline glyph for affordances that sit INSIDE a line of text —
-        // an info hint beside a badge, a copy glyph after an id. `icon-sm`'s
-        // 32px target is correct for a metadata row but visually swamps a
-        // 10px badge or a 14px label, so hosts were reaching for className
-        // overrides to shrink it. Below the WCAG 2.5.8 target floor on purpose:
-        // this is only for glyphs whose information is ALSO available another
-        // way (tooltip content mirrored into an aria-describedby node), never
-        // for a sole means of performing an action.
-        'icon-inline': 'h-5 min-h-0 w-5 min-w-0 shrink-0 p-0 [&_svg]:h-3.5 [&_svg]:w-3.5',
-        // Bare 56px media glyph (play / unmute over video). A size variant so
-        // hosts stop re-implementing a <button> to escape the 20px svg cap.
-        'icon-glyph': 'h-14 w-14 p-0 [&_svg]:h-14 [&_svg]:w-14',
-      },
+      size: BUTTON_SIZE_CLASS,
       // Label typography axis (Figma 133-740). `bold` is the classic h3-bold
       // label; `regular` swaps the DEFAULT size's label to the h4 step
       // (DM Sans 500, neutral tracking) — added for navigation buttons.

package/src/components/ui/button/index.ts

@@ -1,2 +1,3 @@
 export * from './button';
 export * from './split-button';
+export { BUTTON_SIZE_CLASS, type ButtonSizeKey } from './button-styles';

package/src/components/ui/card.tsx

@@ -4,19 +4,34 @@ import { type HTMLAttributes, type ReactNode, forwardRef } from 'react';
 
 import { cn } from '../../utils/cn';
 
-const Card = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => (
-  <div
-    ref={ref}
-    className={cn(
-      // `border` with NO color token resolves to `currentColor` — on a dark card
-      // with light text that paints a WHITE outline. Every ODS surface borders
-      // on `--color-border`; say so.
-      'rounded-lg border border-ods-border bg-card text-card-foreground shadow-sm',
-      className,
-    )}
-    {...props}
-  />
-));
+/**
+ * `default`: the raised card (a shadow, the card colour). `panel`: a flat ODS card surface,
+ * the frame a page section draws around a block of its own (a call-to-action band, the
+ * booking fold, a quote tile): small radius, the card fill, no shadow.
+ */
+const CARD_VARIANT_CLASS = {
+  default: 'rounded-lg bg-card text-card-foreground shadow-sm',
+  panel: 'rounded-md bg-ods-card text-ods-text-primary',
+} as const;
+
+export type CardVariant = keyof typeof CARD_VARIANT_CLASS;
+
+const Card = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement> & { variant?: CardVariant }>(
+  ({ className, variant = 'default', ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        // `border` with NO color token resolves to `currentColor` — on a dark card
+        // with light text that paints a WHITE outline. Every ODS surface borders
+        // on `--color-border`; say so.
+        'border border-ods-border',
+        CARD_VARIANT_CLASS[variant],
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
 Card.displayName = 'Card';
 
 const CardHeader = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => (

package/src/components/ui/checkbox.tsx

@@ -3,6 +3,7 @@
 import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
 import { type ComponentPropsWithoutRef, type ElementRef, forwardRef } from 'react';
 
+import { CONTROL_SIZE } from '../../styles/component-sizes';
 import { cn } from '../../utils/cn';
 import { CheckboxCheckmarkIcon } from '../icons-v2-generated/signs-and-symbols/checkbox-checkmark-icon';
 
@@ -23,13 +24,17 @@ export interface CheckboxProps extends Omit<CheckboxPrimitiveProps, 'onCheckedCh
   onCheckedChange?: (checked: boolean) => void;
 }
 
+/** The checkbox's box (its size and corners): read by the checkbox and by every skeleton that stands for one. */
+export const CHECKBOX_BOX_CLASS = `${CONTROL_SIZE.checkbox} shrink-0 rounded-sm`;
+
 const Checkbox = forwardRef<ElementRef<typeof CheckboxPrimitive.Root>, CheckboxProps>(
   ({ className, onCheckedChange, ...props }, ref) => (
     <CheckboxPrimitive.Root
       ref={ref}
       onCheckedChange={booleanCheckedChange(onCheckedChange)}
       className={cn(
-        'peer h-4 w-4 shrink-0 rounded-sm border border-ods-border bg-ods-card focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-ods-accent data-[state=checked]:bg-ods-accent',
+        CHECKBOX_BOX_CLASS,
+        'peer border border-ods-border bg-ods-card focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-ods-accent data-[state=checked]:bg-ods-accent',
         className,
       )}
       {...props}

package/src/components/ui/compliance-badge.tsx

@@ -1,4 +1,5 @@
 import type { ComponentType, ReactNode } from 'react';
+import { TILE_SIZE } from '../../styles/component-sizes';
 import { cn } from '../../utils/cn';
 import {
   complianceStandardForName,
@@ -33,6 +34,9 @@ function markFontSize(mark: string): number {
   return 7;
 }
 
+/** A compliance logo's box (the official mark's frame and the drawn badge alike): read by its skeletons too. */
+export const COMPLIANCE_LOGO_SIZE_CLASS = TILE_SIZE.lg;
+
 /**
  * A compliance standard's badge, for a standard the icon set has no official
  * mark for: the standard's mark ("CMMC", "FedRAMP") in a plain ring, drawn in
@@ -45,7 +49,7 @@ export function ComplianceBadge({ standard, className }: { standard: ComplianceS
     <svg
       viewBox="0 0 40 40"
       xmlns="http://www.w3.org/2000/svg"
-      className={cn('size-10 shrink-0', className)}
+      className={cn(COMPLIANCE_LOGO_SIZE_CLASS, 'shrink-0', className)}
       role="img"
       aria-label={`${standard.body} ${standard.mark}`}
     >
@@ -96,7 +100,7 @@ export function ComplianceLogo({
     <span
       role="img"
       aria-label={`${standard.body} ${standard.mark}`}
-      className={cn('flex size-10 shrink-0 items-center justify-center', className)}
+      className={cn('flex shrink-0 items-center justify-center', COMPLIANCE_LOGO_SIZE_CLASS, className)}
     >
       {/* Fills the box, so a caller's size class sizes the mark too (not only its frame). */}
       <Official size={40} className="size-full" aria-hidden="true" />