@sarimarcus/content-sites-ui 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.20.0 (2026-10-02)
+
+- `./editorial` article interludes: `Interlude` dispatcher (site `renderInline`, `labels`, `didYouKnowVariant`; entity interludes left to the site), `AnswerBox`, `ComparisonTable`, `EvidenceContext`, `FieldNote` (`authorHref`, `class`), `Quote`, `StatFact`, `Timeline`, `Tldr`, `DidYouKnow` (`ruled` / `inline`, `labelClass`) and `RelatedCard` (`inline` / `featured`, `eyebrowClass`). Every visible and aria string is a required prop; HTML props are `TrustedHtml`. Types `InterludeData`, `InterludeLabels`, `RenderInline` (SLA-2740).
+
+## 0.19.0 (2026-10-02)
+
+- `./editorial` editorial presentation: `ArticleKeyFacts`, `AuthorCard` (link, polaroid and plain shapes), `AuthorStrip`, `ArticleCard` and `ArticleGrid`, `ArticleCategoryNav`, `InsiderTips` (site-defined tip kinds). Every visible and aria string is a required prop. New view-model types `ArticleSummary`, `AuthorSummary`, `KeyFact`, `SourceItem`, `ArticleCategoryLink`, `InsiderTip`, `InsiderTipKinds`, `InsiderTipAuthor` (SLA-2740).
+- `./composed`: `RelatedContent` and `RelatedContentCard` (grid or carousel of `RelatedItem` cards, `tone` primary/accent/secondary; types `RelatedItem`, `RelatedTone`). In `./composed` because they render CardCarousel, whose `<style>` would otherwise reach every `./editorial` importer (SLA-2740).
+- `ArticleFeatureCard`: `label` optional; new `readingLabel`, `loading` (lazy drops the high fetch priority), `headingLevel`, `pagefindIgnore` and `class` (replaces the default `mb-12`) (SLA-2740).
+
 ## 0.18.0 (2026-10-02)
 
 - New page templates in `./editorial`: `StaticProsePage` (legal and site-information pages: heading, optional eyebrow, prose slot, `after` slot, closing CTA box; not Pagefind-indexed), `NotFoundPage` (the 404 body, every string a prop; its decoration ships as `./not-found.css` so a barrel import never carries it to other pages), `ArticlesListingPage` (article index and topic hub shell: breadcrumb band, header, `<main>`, Pagefind body optional) and `ArticleFeatureCard` (SLA-2744).

package/README.md

@@ -100,6 +100,56 @@ prose stay in the route so the site's link and outbound-domain scanners still se
 A component exported from a barrel must not carry a `<style>` block: Astro ships it to every page that imports the
 barrel. Put such rules in a stylesheet entry the one route imports.
 
+## Editorial presentation
+
+```ts
+import { ArticleKeyFacts, AuthorCard, AuthorStrip, ArticleCard, ArticleGrid, ArticleCategoryNav, InsiderTips } from '@sarimarcus/content-sites-ui/editorial';
+import { RelatedContent, RelatedContentCard } from '@sarimarcus/content-sites-ui/composed';
+import type { ArticleSummary, AuthorSummary, KeyFact, SourceItem } from '@sarimarcus/content-sites-ui/editorial';
+import type { RelatedItem } from '@sarimarcus/content-sites-ui/composed';
+```
+
+Every visible and aria string is a required prop with no default, so the copy stays in the site. The site keeps a thin
+adapter of the same name that reads its collections, globs, routes, markdown renderer and author profiles, then passes
+view models: dates already formatted (the package never picks a time zone), hrefs with the base path applied, HTML that
+crosses the boundary only through `trustedHtml()` (key-fact details and tip bodies keep their `#fn-N` anchors because
+the site parses them with its source count). Palette props (`figureClass`, `surfaceClass`, `ringClass`, `proseClass`)
+let a site keep its own roles.
+
+- `ArticleKeyFacts`: figure-first `<dl>`, rendered only with three or more facts.
+- `AuthorCard`: whole-card link, polaroid, or plain card with a profile link. `AuthorStrip`: portraits row.
+- `ArticleCard` / `ArticleGrid`: listing cards; `pagefindIgnore` for a listing that is itself indexed.
+  `ArticleFeatureCard` is the wide lead card.
+- `ArticleCategoryNav`: "All" plus one chip per topic; the site supplies the links and counts.
+- `RelatedContent` / `RelatedContentCard` (in `./composed`, beside the CardCarousel they render): grid or carousel of `RelatedItem` cards, `tone` primary/accent/secondary.
+  Resolving which items to show (collections, scoring, backfill) stays a site adapter.
+- `InsiderTips`: tip kinds are site keys mapped to a label and a tone.
+
+These render inside the site's article styles (`.article-body` link rules, typography plugin presets); outside them
+they look different.
+
+### Article interludes
+
+```astro
+---
+import { Interlude, RelatedCard } from '@sarimarcus/content-sites-ui/editorial';
+import { trustedHtml } from '@sarimarcus/content-sites-ui/types';
+const renderInline = (s: string) => trustedHtml(parseMarkdownInline(s, basePath, sourcesLength));
+---
+{interlude.type === 'related-card' && <RelatedCard href={href} eyebrow={`Read next · ${label}`} title={name} />}
+<Interlude interlude={interlude} renderInline={renderInline} labels={labels} author={author} />
+```
+
+`Interlude` renders the eleven content interludes (quote, stat-fact, evidence-context, tldr, answer-box, field-note,
+caution, checklist, did-you-know, timeline, comparison-table) and nothing for the entity ones (`related-card`,
+`monument-feature`, `article-feature`): their target, route and image are site data, so the site's adapter renders
+`RelatedCard` (`inline` row or `featured` card) for them. Every string field passes through the site's `renderInline`
+except the stat figure. `labels` carries all the copy; `didYouKnowVariant` picks `ruled` or `inline`.
+
+The pieces are exported too, for pages that place an interlude by hand: `AnswerBox`, `ComparisonTable`,
+`EvidenceContext`, `FieldNote` (`authorHref` links the signature), `Quote`, `StatFact`, `Timeline`, `Tldr`,
+`DidYouKnow`. The content schema is core's `createInterludeSchema` (`@sarimarcus/content-sites-core/interludes`).
+
 ## Document shell
 
 ```astro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-ui",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Universal Astro UI components, layout shell and design tokens shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,6 @@
     "@lucide/astro": "^1.23.0",
     "astro": "^7.0.6",
     "tailwindcss": "^4.1.18",
-    "@sarimarcus/content-sites-core": "0.18.0"
+    "@sarimarcus/content-sites-core": "0.20.0"
   }
 }

package/src/composed/RelatedContent.astro

@@ -0,0 +1,135 @@
+---
+/**
+ * RelatedContent — related link cards as a grid (default) or a swipable carousel. Under `carousel`, `columns` sets
+ * the card width (how many fit a desktop viewport) rather than grid columns.
+ */
+import ArrowLabel from '../primitives/ArrowLabel.astro';
+import SectionDivider from '../primitives/SectionDivider.astro';
+import CardCarousel from './CardCarousel.astro';
+import RelatedContentCard from './RelatedContentCard.astro';
+import type { RelatedItem } from './related';
+
+interface Props {
+  /** Omit only when the caller renders its own heading (see `plain`). */
+  title?: string;
+  items: RelatedItem[];
+  /**
+   * `bordered`: hairline divider above, no surface. `card`: tinted, bordered panel. `plain`: no surface and no
+   * divider, for a caller that owns its heading and separation.
+   */
+  variant?: 'bordered' | 'card' | 'plain';
+  layout?: 'grid' | 'carousel';
+  columns?: 2 | 3;
+  headingLevel?: 2 | 3;
+  viewAllHref?: string;
+  /** Required with `viewAllHref`. */
+  viewAllLabel?: string;
+  trackingBlock?: string;
+  /** Carousel track label; defaults to the title. */
+  carouselAriaLabel?: string;
+  /** Image `sizes` override; the defaults assume a ~700px prose column. */
+  pictureSizes?: string;
+  class?: string;
+}
+
+const {
+  title,
+  items,
+  variant = 'bordered',
+  layout = 'grid',
+  columns = 2,
+  headingLevel = 2,
+  viewAllHref,
+  viewAllLabel,
+  trackingBlock,
+  carouselAriaLabel,
+  pictureSizes: pictureSizesProp,
+  class: className = '',
+} = Astro.props;
+
+if (viewAllHref && !viewAllLabel) throw new Error('RelatedContent: viewAllHref needs a viewAllLabel');
+
+const HeadingTag = `h${headingLevel}` as 'h2' | 'h3';
+
+// A titled block is tangential content (aside); an untitled one is the caller's own payload, and an unnamed aside
+// would add a second, unlabelled landmark inside it.
+const Wrapper = title ? 'aside' : 'div';
+
+const wrapperClass = variant === 'bordered'
+  ? 'mt-8'
+  : variant === 'plain'
+    ? ''
+    : 'p-6 bg-muted/50 rounded-xl border border-border';
+
+const gridClass = columns === 3
+  ? 'grid gap-4 sm:grid-cols-2 lg:grid-cols-3'
+  : 'grid gap-4 sm:grid-cols-2';
+
+// At `lg` a card fits `columns` per view, so the track stops overflowing and the controls hide. Percentages, not
+// fixed widths: the block usually sits inside a ~700px prose column. Below `lg` cards are wider than a column share
+// so the next one peeks in.
+const cardWidthClass = columns === 3
+  ? 'w-[80vw] sm:w-64 lg:w-[calc((100%-2rem)/3)]'
+  : 'w-[85vw] sm:w-80 lg:w-[calc((100%-1rem)/2)]';
+
+const pictureSizes = pictureSizesProp ?? (layout === 'carousel'
+  ? (columns === 3
+      ? '(min-width: 1024px) 240px, (min-width: 640px) 256px, 80vw'
+      : '(min-width: 640px) 320px, 85vw')
+  : (columns === 3
+      ? '(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw'
+      : '(min-width: 640px) 50vw, 100vw'));
+
+// CardCarousel's contract: every direct child of the track is one card with `snap-start shrink-0` and a width.
+const carouselShell = `shrink-0 snap-start ${cardWidthClass}`;
+---
+
+{items.length > 0 && (
+  <Wrapper class:list={[wrapperClass, className]} aria-label={title || undefined}>
+    {variant === 'bordered' && <SectionDivider />}
+
+    {layout === 'carousel' ? (
+      <CardCarousel
+        heading={title}
+        headingTag={HeadingTag}
+        headingClass="text-2xl font-display font-semibold text-foreground"
+        viewAllHref={viewAllHref}
+        viewAllLabel={viewAllLabel}
+        ariaLabel={carouselAriaLabel ?? title}
+      >
+        {items.map((item) => (
+          <RelatedContentCard
+            item={item}
+            shellClass={carouselShell}
+            pictureSizes={pictureSizes}
+            trackingBlock={trackingBlock}
+          />
+        ))}
+      </CardCarousel>
+    ) : null}
+
+    {/* Gated on `title || viewAllHref`: this row is the only consumer of viewAllHref in grid layout. */}
+    {layout !== 'carousel' && (title || viewAllHref) && (
+      <div class:list={['mb-6', viewAllHref && 'flex flex-wrap items-baseline justify-between gap-x-6 gap-y-2 mb-8']}>
+        {title && <HeadingTag class="text-2xl font-display font-semibold text-foreground">{title}</HeadingTag>}
+        {viewAllHref && (
+          <a href={viewAllHref} class="group text-sm font-medium text-primary hover:text-primary-strong transition-colors">
+            <ArrowLabel>{viewAllLabel}</ArrowLabel>
+          </a>
+        )}
+      </div>
+    )}
+
+    {layout !== 'carousel' && (
+      <div class={gridClass}>
+        {items.map((item) => (
+          <RelatedContentCard
+            item={item}
+            pictureSizes={pictureSizes}
+            trackingBlock={trackingBlock}
+          />
+        ))}
+      </div>
+    )}
+  </Wrapper>
+)}

package/src/composed/RelatedContentCard.astro

@@ -0,0 +1,99 @@
+---
+/**
+ * RelatedContentCard — one card inside RelatedContent. The grid and the carousel render this same card; only the
+ * shell classes and the responsive image hints differ. Three shapes, by precedence: image-led, icon-led, plain text.
+ */
+import { Picture } from 'astro:assets';
+import Icon from '../primitives/Icon.astro';
+import type { RelatedItem, RelatedTone } from './related';
+
+interface Props {
+  item: RelatedItem;
+  /** Layout-specific classes appended to the shared shell. */
+  shellClass?: string;
+  pictureSizes: string;
+  trackingBlock?: string;
+}
+
+const { item, shellClass = '', pictureSizes, trackingBlock } = Astro.props;
+
+const toneMap: Record<RelatedTone, { border: string; text: string; iconBg: string; iconText: string }> = {
+  primary: {
+    border: 'hover:border-primary/40',
+    text: 'group-hover:text-primary',
+    iconBg: 'bg-primary/20 group-hover:bg-primary/30',
+    iconText: 'text-primary',
+  },
+  accent: {
+    border: 'hover:border-accent',
+    text: 'group-hover:text-accent-strong',
+    iconBg: 'bg-accent/20 group-hover:bg-accent/30',
+    iconText: 'text-accent-strong',
+  },
+  secondary: {
+    border: 'hover:border-secondary',
+    text: 'group-hover:text-secondary',
+    iconBg: 'bg-secondary/20 group-hover:bg-secondary/30',
+    iconText: 'text-secondary',
+  },
+};
+
+const c = toneMap[item.tone ?? 'primary'];
+const hasIcon = !!item.icon;
+const hasImage = !!item.image;
+---
+
+<a
+  href={item.href}
+  aria-label={item.title}
+  {...(trackingBlock ? {
+    'data-track-event': 'internal_link_click',
+    'data-track-link-block': trackingBlock,
+  } : {})}
+  class:list={[
+    'group rounded-2xl border border-border bg-card transition-colors hover:bg-muted/50 overflow-hidden',
+    c.border,
+    hasImage ? 'flex flex-col' : (hasIcon ? 'flex flex-col gap-3 p-5' : 'flex flex-col gap-2 p-5'),
+    shellClass,
+  ]}
+>
+  {hasImage && (
+    <div class="relative aspect-video overflow-hidden">
+      <Picture
+        src={item.image!}
+        alt={item.imageAlt || item.title}
+        widths={[320, 480, 640]}
+        formats={['avif', 'webp']}
+        fallbackFormat="webp"
+        sizes={pictureSizes}
+        class="w-full h-full object-cover transition-transform duration-500 group-hover:scale-105"
+      />
+    </div>
+  )}
+  {!hasImage && hasIcon && (
+    <div class:list={['w-10 h-10 rounded-lg flex items-center justify-center shrink-0 transition-colors', c.iconBg]}>
+      <Icon name={item.icon!} class:list={['w-5 h-5', c.iconText]} />
+    </div>
+  )}
+  <div class:list={[
+    hasImage ? 'flex flex-col gap-2 p-5' : 'flex flex-col gap-1.5',
+  ]}>
+    {item.eyebrow && (
+      <span class="text-xs font-medium uppercase tracking-wider text-muted-foreground" aria-hidden="true">
+        {item.eyebrow}
+      </span>
+    )}
+    <span class:list={[
+      'font-display font-semibold text-foreground transition-colors flex items-center gap-1.5',
+      c.text,
+    ]}>
+      {item.title}
+      <Icon name="arrow-right" class="w-3.5 h-3.5 shrink-0 transition-transform group-hover:translate-x-0.5" />
+    </span>
+    {item.description && (
+      <span class="text-sm leading-relaxed text-muted-foreground" aria-hidden="true">
+        {item.description}
+      </span>
+    )}
+  </div>
+</a>

package/src/composed/index.ts

@@ -7,3 +7,7 @@ export { default as InlineImage } from './InlineImage.astro';
 export { default as Pagination } from './Pagination.astro';
 export { default as EntityCard } from './EntityCard.astro';
 export { default as ArrowLinkGrid } from './ArrowLinkGrid.astro';
+// RelatedContent sits here, not in ./editorial: it renders CardCarousel, whose <style> ships to every importer of the barrel.
+export { default as RelatedContent } from './RelatedContent.astro';
+export { default as RelatedContentCard } from './RelatedContentCard.astro';
+export type { RelatedItem, RelatedTone } from './related';

package/src/composed/related.ts

@@ -0,0 +1,16 @@
+import type { ImageMetadata } from 'astro';
+
+export type RelatedTone = 'primary' | 'accent' | 'secondary';
+
+/** A related-content card. Images are optimised imports, never public path strings. */
+export interface RelatedItem {
+  href: string;
+  title: string;
+  description?: string;
+  eyebrow?: string;
+  /** A ui Icon name. */
+  icon?: string;
+  tone?: RelatedTone;
+  image?: ImageMetadata;
+  imageAlt?: string;
+}

package/src/editorial/ArticleByline.astro

@@ -0,0 +1,34 @@
+---
+/** Internal: an article card's byline — author, the published date or an "Updated" Badge, then the reading time. */
+import Badge from '../primitives/Badge.astro';
+
+interface Props {
+  author?: string;
+  dateTime?: string;
+  dateLabel?: string;
+  updated?: boolean;
+  updatedLabel: string;
+  readingLabel?: string;
+  class: string;
+}
+
+const { author, dateTime, dateLabel, updated = false, updatedLabel, readingLabel, class: className } = Astro.props;
+---
+
+<p class={className}>
+  {author && <span>{author}</span>}
+  {author && dateTime && <span aria-hidden="true">·</span>}
+  {dateTime && (updated ? (
+    <Badge tone="custom" toneClass="bg-muted" size="sm" lines={0} class="![font-size:inherit] ![line-height:inherit] ![font-weight:inherit] !gap-1">
+      <svg class="w-3 h-3 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+        <polyline points="23 4 23 10 17 10" />
+        <path d="M20.49 15a9 9 0 1 1-2.12-9.36L23 10" />
+      </svg>
+      {updatedLabel}{' '}<time datetime={dateTime}>{dateLabel}</time>
+    </Badge>
+  ) : (
+    <time datetime={dateTime}>{dateLabel}</time>
+  ))}
+  {readingLabel && <span aria-hidden="true">·</span>}
+  {readingLabel && <span>{readingLabel}</span>}
+</p>

package/src/editorial/ArticleCard.astro

@@ -0,0 +1,56 @@
+---
+/**
+ * ArticleCard — one article in a grid: image, title, byline with the published or "Updated" date, description and
+ * a read link. Dates arrive formatted; the image is the route's import.
+ */
+import { Picture } from 'astro:assets';
+import ArticleByline from './ArticleByline.astro';
+import Icon from '../primitives/Icon.astro';
+import type { ArticleSummary } from './types';
+
+interface Props {
+  article: ArticleSummary;
+  readLabel: string;
+  updatedLabel: string;
+  loading?: 'eager' | 'lazy';
+  /** Keep the card out of the search index (listings that are themselves indexed). */
+  pagefindIgnore?: boolean;
+  class?: string;
+}
+
+const { article: a, readLabel, updatedLabel, loading = 'lazy', pagefindIgnore = false, class: className } = Astro.props;
+---
+
+<a
+  href={a.href}
+  data-pagefind-ignore={pagefindIgnore ? '' : undefined}
+  class:list={['group flex flex-col rounded-xl border border-border bg-card overflow-hidden hover:border-primary transition-colors focus:outline-none focus:ring-2 focus:ring-primary/50', className]}
+>
+  {a.image ? (
+    <div class="aspect-[4/3] overflow-hidden">
+      <Picture
+        src={a.image}
+        alt={a.imageAlt ?? ''}
+        widths={[320, 480, 640]}
+        sizes="(max-width: 640px) 100vw, 33vw"
+        formats={['avif', 'webp']}
+        fallbackFormat="webp"
+        class="w-full h-full object-cover motion-safe:transition-transform motion-safe:duration-500 motion-safe:group-hover:scale-105"
+        loading={loading}
+      />
+    </div>
+  ) : (
+    <div class="aspect-[4/3] bg-muted/40"></div>
+  )}
+  <div class="p-5 flex-1 flex flex-col">
+    <h3 class="text-base sm:text-lg font-semibold font-display leading-snug group-hover:text-primary transition-colors text-balance">
+      {a.title}
+    </h3>
+    <ArticleByline class="mt-1.5 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground" author={a.author} dateTime={a.dateTime} dateLabel={a.dateLabel} updated={a.updated} updatedLabel={updatedLabel} readingLabel={a.readingLabel} />
+    <p class="mt-2 text-sm text-muted-foreground leading-relaxed line-clamp-2">{a.description}</p>
+    <span class="inline-flex items-center gap-1 mt-auto pt-3 text-sm font-medium text-primary">
+      {readLabel}
+      <Icon name="arrow-right" class="w-3.5 h-3.5 motion-safe:transition-transform motion-safe:group-hover:translate-x-0.5" />
+    </span>
+  </div>
+</a>

package/src/editorial/ArticleCategoryNav.astro

@@ -0,0 +1,50 @@
+---
+/** ArticleCategoryNav — "All" plus one chip per populated topic, each with a count badge. The site resolves the links. */
+import Chip from '../primitives/Chip.astro';
+import Badge from '../primitives/Badge.astro';
+import type { ArticleCategoryLink } from './types';
+
+interface Props {
+  categories: ArticleCategoryLink[];
+  all: Omit<ArticleCategoryLink, 'icon'>;
+  ariaLabel: string;
+  class?: string;
+}
+
+const { categories, all, ariaLabel, class: className } = Astro.props;
+const countClass = (active: boolean) => (active ? 'bg-overlay-foreground/20' : 'bg-muted');
+---
+
+{categories.length > 0 && (
+  <nav aria-label={ariaLabel} class={className}>
+    <div class="flex gap-2.5 overflow-x-auto flex-nowrap pb-2 scrollbar-hide md:flex-wrap md:overflow-visible md:pb-0">
+      <Chip
+        href={all.href}
+        size="md"
+        tone="outline"
+        accent="primary"
+        active={all.active}
+        aria-current={all.active ? 'page' : undefined}
+        class="shrink-0"
+      >
+        {all.label}
+        <Badge tone="custom" toneClass={countClass(all.active)} size="sm" lines={0} class="!px-1.5 ![font-weight:inherit]">{all.count}</Badge>
+      </Chip>
+      {categories.map((c) => (
+        <Chip
+          href={c.href}
+          size="md"
+          tone="outline"
+          accent="primary"
+          active={c.active}
+          aria-current={c.active ? 'page' : undefined}
+          icon={c.icon}
+          class="shrink-0"
+        >
+          {c.label}
+          <Badge tone="custom" toneClass={countClass(c.active)} size="sm" lines={0} class="!px-1.5 ![font-weight:inherit]">{c.count}</Badge>
+        </Chip>
+      ))}
+    </div>
+  </nav>
+)}

package/src/editorial/ArticleFeatureCard.astro

@@ -5,7 +5,7 @@
  */
 import { Picture } from 'astro:assets';
 import type { ImageMetadata } from 'astro';
-import Badge from '../primitives/Badge.astro';
+import ArticleByline from './ArticleByline.astro';
 import Icon from '../primitives/Icon.astro';
 
 interface Props {
@@ -14,7 +14,7 @@ interface Props {
   description: string;
   author: string;
   /** "Featured" or "Latest". */
-  label: string;
+  label?: string;
   image?: ImageMetadata;
   imageAlt?: string;
   /** The date shown: the modified one when `updated`, else the published one. */
@@ -23,12 +23,20 @@ interface Props {
   updated?: boolean;
   readLabel?: string;
   updatedLabel?: string;
+  /** Pre-composed reading-time text, e.g. "6 min read". */
+  readingLabel?: string;
+  /** Lazy for a card below the fold; eager (with high fetch priority) by default. */
+  loading?: 'eager' | 'lazy';
+  headingLevel?: 2 | 3;
+  pagefindIgnore?: boolean;
+  class?: string;
 }
 
-const { href, title, description, author, label, image, imageAlt = '', dateTime, dateLabel, updated = false, readLabel = 'Read article', updatedLabel = 'Updated' } = Astro.props;
+const { href, title, description, author, label, image, imageAlt = '', dateTime, dateLabel, updated = false, readLabel = 'Read article', updatedLabel = 'Updated', readingLabel, loading = 'eager', headingLevel = 2, pagefindIgnore = false, class: className = 'mb-12' } = Astro.props;
+const Heading = `h${headingLevel}` as 'h2' | 'h3';
 ---
 
-<a href={href} class="group block mb-12 rounded-xl border border-border bg-card overflow-hidden hover:border-primary transition-colors focus:outline-none focus:ring-2 focus:ring-primary/50">
+<a href={href} data-pagefind-ignore={pagefindIgnore ? '' : undefined} class:list={['group block', className, 'rounded-xl border border-border bg-card overflow-hidden hover:border-primary transition-colors focus:outline-none focus:ring-2 focus:ring-primary/50']}>
   <div class="grid sm:grid-cols-[1.2fr_1fr] gap-0">
     {image ? (
       <div class="aspect-[4/3] sm:aspect-auto overflow-hidden">
@@ -40,33 +48,19 @@ const { href, title, description, author, label, image, imageAlt = '', dateTime,
           formats={['avif', 'webp']}
           fallbackFormat="webp"
           class="w-full h-full object-cover motion-safe:transition-transform motion-safe:duration-500 motion-safe:group-hover:scale-105"
-          loading="eager"
-          fetchpriority="high"
+          loading={loading}
+          fetchpriority={loading === 'eager' ? 'high' : undefined}
         />
       </div>
     ) : (
       <div class="aspect-[4/3] sm:aspect-auto bg-muted/40"></div>
     )}
     <div class="p-6 sm:p-8 flex flex-col justify-center">
-      <p class="text-xs font-semibold uppercase tracking-[0.18em] text-primary mb-2">{label}</p>
-      <h2 class="text-xl sm:text-2xl font-semibold font-display text-foreground leading-snug group-hover:text-primary transition-colors text-balance">
+      {label && <p class="text-xs font-semibold uppercase tracking-[0.18em] text-primary mb-2">{label}</p>}
+      <Heading class="text-xl sm:text-2xl font-semibold font-display text-foreground leading-snug group-hover:text-primary transition-colors text-balance">
         {title}
-      </h2>
-      <p class="mt-2 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground">
-        <span>{author}</span>
-        <span aria-hidden="true">·</span>
-        {updated ? (
-          <Badge tone="custom" toneClass="bg-muted" size="sm" lines={0} class="![font-size:inherit] ![line-height:inherit] ![font-weight:inherit] !gap-1">
-            <svg class="w-3 h-3 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
-              <polyline points="23 4 23 10 17 10" />
-              <path d="M20.49 15a9 9 0 1 1-2.12-9.36L23 10" />
-            </svg>
-            {updatedLabel}{' '}<time datetime={dateTime}>{dateLabel}</time>
-          </Badge>
-        ) : (
-          <time datetime={dateTime}>{dateLabel}</time>
-        )}
-      </p>
+      </Heading>
+      <ArticleByline class="mt-2 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-muted-foreground" author={author} dateTime={dateTime} dateLabel={dateLabel} updated={updated} updatedLabel={updatedLabel} readingLabel={readingLabel} />
       <p class="mt-3 text-sm text-muted-foreground leading-relaxed line-clamp-3">{description}</p>
       <span class="inline-flex items-center gap-1 mt-5 text-sm font-medium text-primary">
         {readLabel}

package/src/editorial/ArticleGrid.astro

@@ -0,0 +1,23 @@
+---
+/** ArticleGrid — a grid of ArticleCards; renders nothing for an empty list. */
+import ArticleCard from './ArticleCard.astro';
+import type { ArticleSummary } from './types';
+
+interface Props {
+  articles: ArticleSummary[];
+  readLabel: string;
+  updatedLabel: string;
+  pagefindIgnore?: boolean;
+  class?: string;
+}
+
+const { articles, readLabel, updatedLabel, pagefindIgnore = false, class: className = 'grid gap-6 sm:grid-cols-2' } = Astro.props;
+---
+
+{articles.length > 0 && (
+  <div class={className}>
+    {articles.map((article) => (
+      <ArticleCard article={article} readLabel={readLabel} updatedLabel={updatedLabel} pagefindIgnore={pagefindIgnore} />
+    ))}
+  </div>
+)}

package/src/editorial/ArticleKeyFacts.astro

@@ -0,0 +1,54 @@
+---
+/**
+ * ArticleKeyFacts — the above-the-fold "3 quick facts" strip: figure-first tiles in a semantic <dl>, rendered only
+ * with 3+ items. Not composed/QuickFacts: that one is label-above-value, needs a title and a per-item icon.
+ * Palette classes are props so a site keeps its own figure and surface roles.
+ */
+import type { KeyFact } from './types';
+
+interface Props {
+  items: KeyFact[];
+  ariaLabel: string;
+  borderClass?: string;
+  surfaceClass?: string;
+  labelClass?: string;
+  figureClass?: string;
+  class?: string;
+}
+
+const {
+  items,
+  ariaLabel,
+  borderClass = 'border-accent/25',
+  surfaceClass = 'bg-card',
+  labelClass = 'tracking-[0.14em] text-foreground/70',
+  figureClass = 'text-primary',
+  class: className = '',
+} = Astro.props;
+---
+
+{items.length >= 3 && (
+  <dl
+    class:list={[
+      // gap-px over a bg-border grid draws the dividers as cell edges, never a side-stripe border.
+      `grid grid-cols-1 gap-px overflow-hidden rounded-xl border ${borderClass} bg-border sm:grid-cols-3`,
+      className,
+    ]}
+    aria-label={ariaLabel}
+  >
+    {items.map((fact) => (
+      <div class={`flex min-w-0 flex-col ${surfaceClass} px-5 py-5 sm:px-6`}>
+        {/* dt precedes dd in the DOM; order-* puts the figure first visually. */}
+        <dt class={`order-2 mt-2 text-[0.8125rem] font-semibold uppercase leading-none ${labelClass}`}>
+          {fact.label}
+        </dt>
+        <dd class={`order-1 m-0 font-display text-[2rem] leading-none tracking-[-0.02em] tabular-nums ${figureClass} sm:text-[2.25rem]`}>
+          {fact.figure}
+        </dd>
+        {fact.detailHtml && (
+          <dd class="order-3 m-0 mt-2 text-sm leading-snug text-muted-foreground" set:html={fact.detailHtml} />
+        )}
+      </div>
+    ))}
+  </dl>
+)}