@sarimarcus/content-sites-ui 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 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,34 @@ 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.
+
 ## Document shell
 
 ```astro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-ui",
-  "version": "0.18.0",
+  "version": "0.19.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.19.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>
+)}

package/src/editorial/AuthorCard.astro

@@ -0,0 +1,174 @@
+---
+/**
+ * AuthorCard — an author's portrait, role line, name, bio and expertise badges. Three shapes: a whole-card link
+ * (`href`), a centred polaroid portrait (`polaroid`), or a plain card with a profile link. `roleLabel` is free text
+ * whose meaning is the caller's: a job title on one page, "Curated by" on another.
+ */
+import Badge from '../primitives/Badge.astro';
+import LinkArrow from '../primitives/LinkArrow.astro';
+import ArrowLabel from '../primitives/ArrowLabel.astro';
+
+interface Props {
+  name: string;
+  /** Portrait URL, base path already applied. */
+  photoSrc: string;
+  portraitAlt: string;
+  bio: string;
+  credentials?: string;
+  expertise: string[];
+  /** Profile URL used by the plain and polaroid shapes. */
+  profileHref: string;
+  /** When set, the whole card is this link. */
+  href?: string;
+  roleLabel: string;
+  viewLabel: string;
+  /** Link-card footer text, e.g. "12 articles". */
+  countLabel?: string;
+  /** Clamp the bio to two lines (link-card shape). */
+  compact?: boolean;
+  headingLevel?: 2 | 3;
+  polaroid?: boolean;
+  /** Caption under the polaroid portrait. */
+  caption?: string;
+  class?: string;
+}
+
+const {
+  name,
+  photoSrc,
+  portraitAlt,
+  bio,
+  credentials,
+  expertise,
+  profileHref,
+  href,
+  roleLabel,
+  viewLabel,
+  countLabel,
+  compact = false,
+  headingLevel = 2,
+  polaroid = false,
+  caption,
+  class: className,
+} = Astro.props;
+
+const cardBase = 'rounded-2xl border border-border bg-card p-6 shadow-sm';
+const linkExtra = 'group transition-all duration-200 hover:shadow-md hover:border-primary/40 block';
+const Heading = `h${headingLevel}` as 'h2' | 'h3';
+---
+
+{href ? (
+  <a href={href} class:list={[cardBase, linkExtra, className]}>
+    <article>
+      <div class="flex items-start gap-4">
+        <img
+          src={photoSrc}
+          alt={portraitAlt}
+          width="96"
+          height="96"
+          class="h-24 w-24 rounded-xl object-cover bg-muted shrink-0"
+          loading="lazy"
+          decoding="async"
+        />
+        <div class="min-w-0">
+          <p class="text-xs font-semibold uppercase tracking-[0.16em] text-primary">{roleLabel}</p>
+          <Heading class="mt-2 text-xl font-display font-semibold text-foreground">{name}</Heading>
+          <p class:list={["mt-3 text-sm text-muted-foreground leading-relaxed", compact && "line-clamp-2"]}>{bio}</p>
+        </div>
+      </div>
+
+      <div class="mt-5 flex flex-wrap gap-2">
+        {expertise.map((topic) => (
+          <Badge tone="custom" toneClass="border bg-muted/50 text-foreground" size="md" lines={0} class="border-border">
+            {topic}
+          </Badge>
+        ))}
+      </div>
+
+      <div class="mt-5 flex items-center justify-between gap-4">
+        {countLabel !== undefined && (
+          <p class="text-sm text-muted-foreground">
+            {countLabel}
+          </p>
+        )}
+        <ArrowLabel class="text-sm font-medium text-primary ml-auto">
+          {viewLabel}
+        </ArrowLabel>
+      </div>
+    </article>
+  </a>
+) : polaroid ? (
+  <article class:list={[cardBase, 'sm:p-8', className]}>
+    <div class="flex flex-col items-center gap-6 text-center lg:flex-row lg:items-start lg:gap-10 lg:text-left">
+      <div class="shrink-0 rotate-[-2deg] rounded-sm bg-white p-3 pb-8 shadow-xl ring-1 ring-black/5">
+        <img
+          src={photoSrc}
+          alt={portraitAlt}
+          width="256"
+          height="256"
+          class="h-48 w-48 sm:h-64 sm:w-64 rounded-sm object-cover bg-muted"
+          loading="lazy"
+          decoding="async"
+        />
+        {caption && (
+          <p class="mt-3 font-display italic text-sm text-neutral-600">{caption}</p>
+        )}
+      </div>
+
+      <div class="flex w-full flex-col items-center lg:items-start">
+        <p class="text-xs font-semibold uppercase tracking-[0.16em] text-primary">{roleLabel}</p>
+        <Heading class="mt-1 text-xl font-display font-semibold text-foreground">{name}</Heading>
+        <p class="mt-4 max-w-xl text-sm text-muted-foreground leading-relaxed text-pretty">{bio}</p>
+        {credentials && <p class="mt-2 max-w-xl text-sm text-foreground leading-relaxed text-pretty">{credentials}</p>}
+
+        <div class="mt-5 flex flex-wrap justify-center gap-2 lg:justify-start">
+          {expertise.map((topic) => (
+            <Badge tone="custom" toneClass="border bg-muted/50 text-foreground" size="md" lines={0} class="border-border">
+              {topic}
+            </Badge>
+          ))}
+        </div>
+
+        <div class="mt-5">
+          <LinkArrow href={profileHref} size="sm" color="primary">
+            {viewLabel}
+          </LinkArrow>
+        </div>
+      </div>
+    </div>
+  </article>
+) : (
+  <article class:list={[cardBase, className]}>
+    <div class="flex items-start gap-4">
+      <img
+        src={photoSrc}
+        alt={portraitAlt}
+        width="96"
+        height="96"
+        class="h-24 w-24 rounded-xl object-cover bg-muted shrink-0"
+        loading="lazy"
+        decoding="async"
+      />
+      <div class="min-w-0">
+        <p class="text-xs font-semibold uppercase tracking-[0.16em] text-primary">{roleLabel}</p>
+        <Heading class="mt-2 text-xl font-display font-semibold text-foreground">{name}</Heading>
+        <p class="mt-3 text-sm text-muted-foreground leading-relaxed">{bio}</p>
+        {credentials && <p class="mt-3 text-sm text-foreground leading-relaxed">{credentials}</p>}
+      </div>
+    </div>
+
+    <div class="mt-5 flex flex-wrap gap-2">
+      {expertise.map((topic) => (
+        <Badge tone="custom" toneClass="border bg-muted/50 text-foreground" size="md" lines={0} class="border-border">
+          {topic}
+        </Badge>
+      ))}
+    </div>
+
+    <div class="mt-5">
+      <LinkArrow href={profileHref} size="sm" color="primary">
+        {viewLabel}
+      </LinkArrow>
+    </div>
+  </article>
+)}

package/src/editorial/AuthorStrip.astro

@@ -0,0 +1,52 @@
+---
+/** AuthorStrip — a centred row of author portraits linking to their profiles, with a link to the team page. */
+import { Image } from 'astro:assets';
+import type { ImageMetadata } from 'astro';
+import type { AuthorSummary } from './types';
+
+interface StripAuthor extends AuthorSummary {
+  displayName: string;
+  specialty: string;
+  image: ImageMetadata | string;
+}
+
+interface Props {
+  authors: readonly StripAuthor[];
+  ariaLabel: string;
+  heading: string;
+  teamHref: string;
+  teamLabel: string;
+  /** Portrait ring colour, e.g. "ring-background". */
+  ringClass?: string;
+  class?: string;
+}
+
+const { authors, ariaLabel, heading, teamHref, teamLabel, ringClass = 'ring-background', class: className = '' } = Astro.props;
+const imgClass = `w-16 h-16 rounded-full object-cover ring-2 ${ringClass} group-hover:ring-primary/60 transition-shadow duration-200`;
+---
+<section id="authors" aria-label={ariaLabel} class:list={["bg-muted/50 py-10", className]}>
+  <div class="mx-auto max-w-shell px-4 sm:px-6 lg:px-8">
+    <p class="text-center text-sm font-medium text-muted-foreground mb-6">{heading}</p>
+    <div class="flex flex-wrap justify-center gap-6 sm:gap-8">
+      {authors.map((author) => (
+        <a
+          href={author.href}
+          class="group flex flex-col items-center gap-2 transition-opacity hover:opacity-80"
+        >
+          {typeof author.image === 'string' ? (
+            <img src={author.image} alt={author.name} width="64" height="64" class={imgClass} loading="lazy" decoding="async" />
+          ) : (
+            <Image src={author.image} alt={author.name} width={64} height={64} class={imgClass} loading="lazy" />
+          )}
+          <span class="text-sm font-medium text-foreground">{author.displayName}</span>
+          <span class="text-xs text-muted-foreground">{author.specialty}</span>
+        </a>
+      ))}
+    </div>
+    <div class="mt-6 text-center">
+      <a href={teamHref} class="text-sm font-medium text-primary hover:underline">
+        {teamLabel}
+      </a>
+    </div>
+  </div>
+</section>

package/src/editorial/InsiderTips.astro

@@ -0,0 +1,102 @@
+---
+/**
+ * InsiderTips — the "reporter notebook" block: a header with an optional author byline, then one card per tip with a
+ * kind badge. Kinds are site-defined keys mapped to a label and a tone; tip bodies arrive as site-rendered HTML.
+ */
+import Badge from '../primitives/Badge.astro';
+import type { InsiderTip, InsiderTipAuthor, InsiderTipKinds, InsiderTipTone } from './types';
+
+interface Props {
+  items: InsiderTip[];
+  kinds: InsiderTipKinds;
+  title: string;
+  eyebrow: string;
+  /** Label above the author's name. */
+  filedByLabel: string;
+  author?: InsiderTipAuthor;
+  lede?: string;
+  /** Typography colour preset for the tip bodies, e.g. "prose-stone". */
+  proseClass?: string;
+  class?: string;
+}
+
+const { items, kinds, title, eyebrow, filedByLabel, author, lede, proseClass = 'prose-stone', class: className = '' } = Astro.props;
+
+const toneClasses: Record<InsiderTipTone, { card: string; badge: string }> = {
+  accent: { card: 'border-accent/40 bg-accent/5', badge: 'bg-accent/20 text-accent-strong font-bold' },
+  primary: { card: 'border-primary/40 bg-primary/5', badge: 'bg-primary/15 text-primary' },
+  secondary: { card: 'border-secondary/40 bg-secondary/5', badge: 'bg-secondary/15 text-secondary' },
+  muted: { card: 'border-border bg-muted/35', badge: 'bg-muted text-foreground' },
+};
+const kindOf = (kind: string) => {
+  const k = kinds[kind];
+  if (!k) throw new Error(`InsiderTips: no label/tone for kind "${kind}"`);
+  return { label: k.label, ...toneClasses[k.tone] };
+};
+---
+
+{items.length > 0 && (
+  <section class:list={['rounded-2xl border border-primary/20 bg-muted/40 p-6 shadow-sm lg:p-8', className]}>
+    <div class="border-b border-primary/15 pb-5">
+      <div class="flex flex-col gap-4 lg:flex-row lg:items-center lg:justify-between">
+        <div class="max-w-deck">
+          <p class="text-xs font-semibold uppercase tracking-[0.22em] text-primary">{eyebrow}</p>
+          <h2 class="mt-2 text-xl font-semibold font-display">{title}</h2>
+          {lede && <p class="mt-2 text-sm leading-relaxed text-muted-foreground">{lede}</p>}
+        </div>
+
+        {author && (
+          <aside class="flex items-center gap-2 md:gap-3 lg:max-w-sm lg:justify-end">
+            {author.photoSrc ? (
+              <img
+                src={author.photoSrc}
+                alt={author.portraitAlt}
+                width="44"
+                height="44"
+                class="h-11 w-11 rounded-full object-cover bg-muted shrink-0"
+                loading="lazy"
+                decoding="async"
+              />
+            ) : (
+              <div class="h-11 w-11 rounded-full bg-primary/15 shrink-0" aria-hidden="true" />
+            )}
+            <div class="min-w-0">
+              <p class="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">{filedByLabel}</p>
+              {author.href ? (
+                <a href={author.href} class="font-semibold text-foreground hover:text-primary transition-colors">{author.name}</a>
+              ) : (
+                <p class="font-semibold text-foreground">{author.name}</p>
+              )}
+              {author.expertise && (
+                <p class="mt-0.5 text-xs uppercase tracking-wide text-muted-foreground">{author.expertise}</p>
+              )}
+              {author.credentials && (
+                <p class="mt-1 text-sm leading-relaxed text-muted-foreground line-clamp-2">{author.credentials}</p>
+              )}
+            </div>
+          </aside>
+        )}
+      </div>
+    </div>
+
+    <div class:list={['mt-6 grid gap-4', items.length > 1 && 'md:grid-cols-2']}>
+      {items.map((item) => {
+        const k = kindOf(item.kind);
+        return (
+          // min-w-0 + break-words: a grid item defaults to min-width:auto, so one unbreakable token (a bare URL) would
+          // size the whole track and scroll the page sideways on a phone.
+          <article class:list={['min-w-0 break-words rounded-2xl border px-5 py-4', k.card]}>
+            <Badge tone="custom" toneClass={k.badge} size="md" lines={0} class="uppercase tracking-wide !font-semibold">
+              {k.label}
+            </Badge>
+            <h3 class="mt-3 text-lg font-semibold font-display text-foreground">{item.title}</h3>
+            <div
+              class={`prose ${proseClass} prose-sm mt-3 max-w-none text-foreground/80 prose-p:my-0 prose-strong:text-foreground`}
+              set:html={item.bodyHtml}
+            />
+          </article>
+        );
+      })}
+    </div>
+  </section>
+)}

package/src/editorial/index.ts

@@ -8,3 +8,12 @@ export { default as NotFoundPage } from './NotFoundPage.astro';
 export { default as ArticlesListingPage } from './ArticlesListingPage.astro';
 export { default as ArticleFeatureCard } from './ArticleFeatureCard.astro';
 export type { EventInfoRow, EventInfoIcon } from './event';
+export { default as ArticleKeyFacts } from './ArticleKeyFacts.astro';
+export { default as AuthorCard } from './AuthorCard.astro';
+export { default as ArticleCard } from './ArticleCard.astro';
+export { default as ArticleGrid } from './ArticleGrid.astro';
+export { default as ArticleCategoryNav } from './ArticleCategoryNav.astro';
+export type { AuthorSummary, ArticleSummary, KeyFact, SourceItem, ArticleCategoryLink } from './types';
+export { default as InsiderTips } from './InsiderTips.astro';
+export type { InsiderTip, InsiderTipAuthor, InsiderTipKinds, InsiderTipTone } from './types';
+export { default as AuthorStrip } from './AuthorStrip.astro';

package/src/editorial/types.ts

@@ -0,0 +1,68 @@
+import type { ImageMetadata } from 'astro';
+import type { TrustedHtml } from '../types';
+import type { SourceInput } from '../seo/types';
+
+/** A person as listed on author strips and cards. The byline shape is ui/seo `ArticleAuthor`. */
+export interface AuthorSummary {
+  name: string;
+  /** Profile URL, base path already applied. */
+  href: string;
+  /** Optimised portrait, or a public URL with the base path applied. */
+  image?: ImageMetadata | string;
+}
+
+/** One article as a card or grid entry. Dates arrive formatted, so the package never picks a time zone. */
+export interface ArticleSummary {
+  href: string;
+  title: string;
+  description: string;
+  author?: string;
+  image?: ImageMetadata;
+  imageAlt?: string;
+  /** ISO value for `<time datetime>`: dateModified when `updated`, else datePublished. */
+  dateTime?: string;
+  dateLabel?: string;
+  updated?: boolean;
+  /** Pre-composed reading-time text, e.g. "6 min read". */
+  readingLabel?: string;
+}
+
+/** A key-fact tile. `detailHtml` is parsed by the site, so footnote markers resolve. */
+export interface KeyFact {
+  figure: string;
+  label: string;
+  detailHtml?: TrustedHtml;
+}
+
+export type SourceItem = SourceInput;
+
+/** One category chip in an article topic nav. */
+export interface ArticleCategoryLink {
+  href: string;
+  label: string;
+  icon?: string;
+  count: number;
+  active: boolean;
+}
+
+export type InsiderTipTone = 'primary' | 'accent' | 'secondary' | 'muted';
+
+/** Site-defined tip kinds: the key stored in content, its badge label and its tone. */
+export type InsiderTipKinds = Record<string, { label: string; tone: InsiderTipTone }>;
+
+export interface InsiderTip {
+  kind: string;
+  title: string;
+  bodyHtml: TrustedHtml;
+}
+
+export interface InsiderTipAuthor {
+  name: string;
+  href?: string;
+  /** Portrait URL, base path already applied. */
+  photoSrc?: string;
+  portraitAlt: string;
+  /** Pre-joined expertise line. */
+  expertise?: string;
+  credentials?: string;
+}