@breathe-ds/ui 0.2.0 → 0.4.0

package/components/Rail.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { useEffect, useRef, useState, type ComponentPropsWithoutRef, type ReactNode } from "react";
+
+type RailProps = {
+  /** Name of the list for screen readers: "Treatments", "Team". */
+  label: string;
+  /** Grid classes from md up, written in full (Tailwind only generates whole
+   *  classes). Default: three columns. */
+  grid?: string;
+  /** <li> children, usually RailItem. */
+  children: ReactNode;
+  className?: string;
+};
+
+/**
+ * Rail — novo.creeta's `Trilho` (components/trilho.tsx) with the Breathe
+ * tokens. On a phone it is a horizontal rail with snap, and the next card
+ * shows by half to say there is more. From md it becomes a grid.
+ *
+ * Under the rail, a small bar follows the finger: it starts the size of what
+ * is already in view and fills to the end — it says how much is left. Shown
+ * only when the rail really scrolls, decoration for screen readers. The fill
+ * is written straight to the style, without re-rendering on every scroll frame.
+ */
+export function Rail({ label, grid = "md:grid-cols-3", children, className = "" }: RailProps) {
+  const list = useRef<HTMLUListElement>(null);
+  const bar = useRef<HTMLSpanElement>(null);
+  const [scrolls, setScrolls] = useState(false);
+
+  useEffect(() => {
+    const ul = list.current;
+    if (!ul) return;
+    let frame = 0;
+    const measure = () => {
+      frame = 0;
+      const overflow = ul.scrollWidth - ul.clientWidth;
+      setScrolls(overflow > 8);
+      if (bar.current && ul.scrollWidth > 0) {
+        const seen = Math.min(1, (ul.scrollLeft + ul.clientWidth) / ul.scrollWidth);
+        bar.current.style.transform = `scaleX(${seen})`;
+      }
+    };
+    const ask = () => {
+      if (!frame) frame = requestAnimationFrame(measure);
+    };
+    measure();
+    ul.addEventListener("scroll", ask, { passive: true });
+    window.addEventListener("resize", ask);
+    return () => {
+      ul.removeEventListener("scroll", ask);
+      window.removeEventListener("resize", ask);
+      if (frame) cancelAnimationFrame(frame);
+    };
+  }, []);
+
+  return (
+    <>
+      <ul
+        ref={list}
+        aria-label={label}
+        className={`cg-no-scrollbar -mx-4 flex snap-x snap-mandatory scroll-px-4 gap-3 overflow-x-auto px-4 pb-1 md:mx-0 md:grid md:snap-none md:gap-5 md:overflow-visible md:px-0 ${grid} ${className}`}
+      >
+        {children}
+      </ul>
+      <div
+        aria-hidden="true"
+        data-cg-rail-progress=""
+        className={`mx-auto mt-4 h-1 w-14 overflow-hidden rounded-full bg-ink/15 md:hidden ${scrolls ? "" : "hidden"}`}
+      >
+        <span ref={bar} className="block h-full w-full origin-left rounded-full bg-ink-soft" />
+      </div>
+    </>
+  );
+}
+
+/** Widths of one item on the rail (phone / sm); from md the grid decides.
+ *  The next card shows by half: that is what says "there is more". */
+export const RAIL_ITEM = {
+  /** Treatments, videos: one card almost full width. */
+  wide: "w-[78%] shrink-0 snap-start sm:w-[46%] md:w-auto",
+  /** Team (medium ProfessionalCard): two cards and a bit. */
+  narrow: "w-[46%] shrink-0 snap-start sm:w-[30%] md:w-auto",
+} as const;
+
+type RailItemProps = ComponentPropsWithoutRef<"li"> & {
+  /** `wide` (default) or `narrow`. */
+  width?: keyof typeof RAIL_ITEM;
+};
+
+/** One <li> of the Rail, with the phone width preset. */
+export function RailItem({ width = "wide", className = "", ...rest }: RailItemProps) {
+  return <li className={`${RAIL_ITEM[width]} ${className}`} {...rest} />;
+}

package/components/Rows.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
+import { ArrowDown, ArrowUpRight, ChevronDown } from "lucide-react";
+
+/**
+ * Rows — the list of equal rows at the foot of a card (the Trajectory /
+ * Guidance / Instagram block of novo.creeta's ProfessionalCard), made generic.
+ *
+ * `RowList` draws the hairlines; each child is a `CollapseRow` (opens in place:
+ * a text, or a list of links with the count beside the label) or a `LinkRow`
+ * (goes somewhere). The arrow follows the family's Pill: ↗ another page, ↓ an
+ * anchor on this page; `external` only adds the new tab. Every row is 48px
+ * tall for the finger, label in `ink` on `card` (creeta's petrol on white: 10.2:1).
+ */
+
+/** One row: label left, glyph right, 48px tall. */
+export const ROW =
+  "flex min-h-12 cursor-pointer list-none items-center justify-between gap-3 text-sm font-semibold text-ink focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink [&::-webkit-details-marker]:hidden";
+
+/** Hover tells the two rows apart (2026-10-29): a link row underlines its label
+ *  (the family's sign for "goes somewhere", as the Footer and the Byline) and
+ *  its arrow takes the step; a collapse row never underlines — it goes nowhere —
+ *  its chevron dips 2px, "opens down here", and turns up when open. */
+const ROW_LINK = `${ROW} underline decoration-transparent underline-offset-4 transition-[text-decoration-color] duration-150 hover:decoration-ink motion-reduce:transition-none`;
+
+const OPEN_CHEVRON =
+  "shrink-0 text-ink-soft transition-[transform,translate] duration-200 group-hover/row:translate-y-0.5 group-open/row:rotate-180 group-open/row:group-hover/row:translate-y-0 motion-reduce:transition-none";
+
+/** What appears out of nowhere (the content of a <details>) fades in briefly
+ *  instead of jumping on screen: `@starting-style` via Tailwind's `starting:`
+ *  variant, no JavaScript. Browsers without support show it at once. */
+export const FADE_IN = "transition-[opacity,translate] duration-[220ms] ease-[var(--ease-cg)] starting:opacity-0 starting:-translate-y-1";
+
+const ROW_LINK_ITEM =
+  "flex min-h-11 items-center justify-between gap-3 py-1.5 text-sm leading-snug text-ink-soft underline decoration-transparent underline-offset-4 transition-[text-decoration-color] duration-150 hover:decoration-ink-soft focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink motion-reduce:transition-none";
+
+export type RowListProps = ComponentPropsWithoutRef<"div">;
+
+/** The hairlines: a line above the first row and between rows. */
+export function RowList({ className = "", ...rest }: RowListProps) {
+  return <div className={`divide-y divide-ink/10 border-t border-ink/10 ${className}`} {...rest} />;
+}
+
+export type RowLink = {
+  label: ReactNode;
+  href: string;
+  /** ↗ another page (default) or ↓ an anchor on this page. */
+  arrow?: "go" | "down";
+  /** Opens in a new tab (target=_blank). The arrow stays ↗. */
+  external?: boolean;
+};
+
+function Arrow({ arrow = "go", size }: { arrow?: "go" | "down"; size: number }) {
+  return arrow === "down" ? (
+    <ArrowDown aria-hidden="true" size={size} className="cg-arrow-down shrink-0" />
+  ) : (
+    <ArrowUpRight aria-hidden="true" size={size} className="cg-arrow-go shrink-0" />
+  );
+}
+
+export type CollapseRowProps = Omit<ComponentPropsWithoutRef<"details">, "children"> & {
+  label: ReactNode;
+  /** Read by screen readers right after the label (e.g. " of Person name"). */
+  srLabel?: ReactNode;
+  /** Number beside the label. With `links` it defaults to their count. */
+  count?: number;
+  /** A list of links as the content: one row per link, with the arrow. */
+  links?: RowLink[];
+  /** Link component of the app for `links` (e.g. next-intl Link). Default: <a>. */
+  linkComponent?: ElementType;
+  /** Free content (a string becomes one paragraph). Ignored with `links`. */
+  children?: ReactNode;
+};
+
+/** A row that opens in place: a native <details>, no JavaScript. */
+export function CollapseRow({ label, srLabel, count, links, linkComponent, children, className = "", ...rest }: CollapseRowProps) {
+  const L: ElementType = linkComponent ?? "a";
+  const n = count ?? links?.length;
+  return (
+    <details className={`group/row ${className}`} {...rest}>
+      <summary className={ROW}>
+        <span>
+          {label}
+          {srLabel && <span className="sr-only">{srLabel}</span>}
+          {n !== undefined && <span className="ml-2 font-normal text-ink/80">{n}</span>}
+        </span>
+        <ChevronDown aria-hidden="true" size={18} className={OPEN_CHEVRON} />
+      </summary>
+      {links ? (
+        <ul className={`${FADE_IN} pb-2`}>
+          {links.map((g, i) => (
+            <li key={`${i}-${g.href}`}>
+              <L href={g.href} className={ROW_LINK_ITEM} {...(g.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}>
+                {g.label}
+                <Arrow arrow={g.arrow} size={16} />
+              </L>
+            </li>
+          ))}
+        </ul>
+      ) : typeof children === "string" ? (
+        <p className={`${FADE_IN} pb-4 text-sm leading-relaxed text-ink/80`}>{children}</p>
+      ) : (
+        <div className={`${FADE_IN} space-y-3 pb-4 text-sm leading-relaxed text-ink/80`}>{children}</div>
+      )}
+    </details>
+  );
+}
+
+export type LinkRowProps = Omit<ComponentPropsWithoutRef<"a">, "children"> & {
+  label: ReactNode;
+  href: string;
+  /** Read by screen readers right after the label (e.g. " of Person name (opens in a new tab)"). */
+  srLabel?: ReactNode;
+  /** ↗ another page (default) or ↓ an anchor on this page. */
+  arrow?: "go" | "down";
+  /** Opens in a new tab (target=_blank). The arrow stays ↗. */
+  external?: boolean;
+  /** Replaces the arrow (an 18px glyph; the slot is `ink-soft`). */
+  icon?: ReactNode;
+  /** Link component of the app (e.g. next-intl Link). Default: <a>. */
+  linkComponent?: ElementType;
+};
+
+/** A row that goes somewhere: the label and, on the right, the arrow or an icon. */
+export function LinkRow({ label, href, srLabel, arrow, external = false, icon, linkComponent, className = "", ...rest }: LinkRowProps) {
+  const L: ElementType = linkComponent ?? "a";
+  return (
+    <L href={href} className={`${ROW_LINK} ${className}`} {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})} {...rest}>
+      <span>
+        {label}
+        {srLabel && <span className="sr-only">{srLabel}</span>}
+      </span>
+      <span className="flex shrink-0 text-ink-soft">{icon ?? <Arrow arrow={arrow} size={18} />}</span>
+    </L>
+  );
+}

package/components/StoryPanel.tsx

@@ -0,0 +1,107 @@
+import type { ElementType, ReactNode } from "react";
+
+export type StoryPillar = { title: ReactNode; text: ReactNode };
+export type StoryLink = { label: ReactNode; href: string; external?: boolean };
+
+type Labels = {
+  /** sr-only after an external link. */
+  newTab: string;
+};
+const EN: Labels = { newTab: "(opens in a new tab)" };
+
+type Props = {
+  /** What fills the media box at the top: a BackgroundVideo, an <img>
+   *  (absolute inset-0, object-cover). The panel's film fades it into the panel. */
+  media: ReactNode;
+  /** Box of the media: 4:3 on the phone, 21:8 from md (creeta). */
+  mediaAspect?: string;
+  /** Logo for the dark background, at the base of the media where the film is already full. */
+  logo?: ReactNode;
+  title: ReactNode;
+  lead?: ReactNode;
+  /** Three columns with a hairline on top: a short title and a paragraph. */
+  pillars: StoryPillar[];
+  /** Outbound links at the end ("Learn about the method ↗"). */
+  links?: StoryLink[];
+  headingLevel?: "h2" | "h3";
+  /** Colour of the pillar titles. Default `text-surface`; creeta passes its light teal. */
+  pillarTitleClassName?: string;
+  linkComponent?: ElementType;
+  labels?: Partial<Labels>;
+  className?: string;
+};
+
+const ArrowUpRight = () => (
+  <svg aria-hidden="true" viewBox="0 0 24 24" width={18} height={18} className="cg-arrow-go" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M7 17 17 7M9 7h8v8" /></svg>
+);
+
+const link =
+  "inline-flex min-h-11 items-center gap-1.5 font-semibold underline underline-offset-4 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-surface";
+
+/**
+ * Story panel of the Cuidado Global family — creeta's `OrigemRta`, by tokens:
+ * a dark panel (surface-panel) that groups a story in one piece. Media at the
+ * top with a film that fades into the panel, the logo at its base, a title and
+ * a lead, three pillars in columns with a hairline above each, and the outbound
+ * links. Good for "who we are" blocks: one rounded card, everything inside.
+ */
+export function StoryPanel({
+  media,
+  mediaAspect = "aspect-[4/3] md:aspect-[21/8]",
+  logo,
+  title,
+  lead,
+  pillars,
+  links,
+  headingLevel: Title = "h2",
+  pillarTitleClassName = "text-surface",
+  linkComponent,
+  labels,
+  className = "",
+}: Props) {
+  const L: ElementType = linkComponent ?? "a";
+  const t = { ...EN, ...labels };
+  return (
+    <section className={`overflow-hidden rounded-[28px] bg-surface-panel text-surface ${className}`}>
+      <div className={`relative ${mediaAspect}`}>
+        {media}
+        {/* -bottom-px: the box's height is fractional and a light half pixel showed under the film */}
+        <span aria-hidden="true" className="pointer-events-none absolute inset-0 -bottom-px bg-gradient-to-t from-surface-panel from-10% via-surface-panel/70 via-40% to-surface-panel/10" />
+        {logo && <div className="absolute bottom-2 left-6 md:bottom-4 md:left-12">{logo}</div>}
+      </div>
+
+      <div className="px-6 pb-9 pt-7 md:px-12 md:pb-14 md:pt-9">
+        <Title className="max-w-3xl font-heading text-[1.75rem] font-medium leading-[1.12] tracking-[-0.01em] md:text-5xl">{title}</Title>
+        {lead && <p className="mt-4 max-w-2xl text-lg leading-relaxed text-surface/85">{lead}</p>}
+
+        <ul className="mt-8 grid list-none gap-6 md:mt-12 md:grid-cols-3 md:gap-10">
+          {pillars.map((p, i) => (
+            <li key={i} className="border-t border-surface/25 pt-5">
+              <p className={`font-heading text-2xl font-medium ${pillarTitleClassName}`}>{p.title}</p>
+              <p className="mt-2 leading-relaxed text-surface/85">{p.text}</p>
+            </li>
+          ))}
+        </ul>
+
+        {links && links.length > 0 && (
+          <div className="mt-8 flex flex-wrap gap-x-8 gap-y-1 md:mt-10">
+            {links.map((l, i) =>
+              l.external ? (
+                <a key={i} href={l.href} target="_blank" rel="noopener noreferrer" className={link}>
+                  {l.label}
+                  <ArrowUpRight />
+                  <span className="sr-only"> {t.newTab}</span>
+                </a>
+              ) : (
+                <L key={i} href={l.href} className={link}>
+                  {l.label}
+                  <ArrowUpRight />
+                </L>
+              ),
+            )}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}

package/components/TestimonialCard.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import { useState, type ElementType, type ReactNode } from "react";
+import { Play } from "lucide-react";
+import { Byline } from "./Byline";
+
+type Labels = {
+  /** sr-only text of the play button: "Watch: {description}". */
+  watch: (description: string) => string;
+  /** sr-only after the outbound link. */
+  newTab: string;
+};
+const EN: Labels = { watch: (description) => `Watch: ${description}`, newTab: " (opens in a new tab)" };
+
+export type TestimonialCaptions = {
+  /** WebVTT file in the page's language. Drawn by the browser over the video:
+   *  only for clips WITHOUT burned-in captions. */
+  src: string;
+  /** BCP 47 tag ("en", "pt-BR"). */
+  srcLang: string;
+  /** Name of the language, for the browser's captions menu. */
+  label?: string;
+};
+
+export type TestimonialVideo = {
+  /** The clip. Downloaded only on tap. */
+  src: string;
+  /** Still frame shown until the person taps. */
+  poster: string;
+  /** What the video shows, for screen readers ("Tereza's mother tells… (1 min 39 s)"). */
+  description: string;
+  /** Plays with audio (testimonials have speech). Default: true. The play is
+   *  a click by the person, so the browser allows the sound. */
+  withSound?: boolean;
+  captions?: TestimonialCaptions;
+  /** Replaces the default poster <img> (the site's own image component).
+   *  Must fill the box (h-full w-full object-cover). */
+  media?: ReactNode;
+};
+
+type Props = {
+  /** The family's words, with their own cuts, in a <blockquote>. */
+  quote: ReactNode;
+  /** Who speaks, as shown on the site ("Tereza's family"). Goes in <cite>, with
+   *  the portrait (or the initials) in front — the family's Byline. */
+  author?: string;
+  authorPhoto?: string;
+  authorAvatar?: ReactNode;
+  /** Two or more voices ("Ana and João"): stacked portraits, names joined. Replaces `author`. */
+  authors?: { name: string; photo?: string; avatar?: ReactNode }[];
+  /** The public source of the quote ("View on Instagram ↗"), opened in a new tab. */
+  link?: { href: string; label: ReactNode };
+  /** The family's video, on the left. */
+  video: TestimonialVideo;
+  /** Element rendered as the card root (default <div>); `li` inside a <ul>. */
+  as?: ElementType;
+  labels?: Partial<Labels>;
+  className?: string;
+};
+
+/** Short video that only downloads and plays on tap, with the family's round
+ *  play button (creeta's `VideoAoToque`). Before the tap it is just the poster:
+ *  the browser's controls (0:00, volume) over the image clashed. No aspect
+ *  ratio: the height comes from the grid row (the text beside it). */
+function TapVideo({ src, poster, description, withSound = true, captions, media, label }: TestimonialVideo & { label: string }) {
+  const [playing, setPlaying] = useState(false);
+  const frame = "relative min-h-[16rem] overflow-hidden bg-ink";
+
+  if (playing) {
+    return (
+      <div className={frame}>
+        <video
+          src={src}
+          poster={poster}
+          controls
+          autoPlay
+          muted={!withSound}
+          playsInline
+          aria-label={description}
+          className="absolute inset-0 h-full w-full object-cover"
+        >
+          {captions && <track kind="subtitles" src={captions.src} srcLang={captions.srcLang} label={captions.label} default />}
+        </video>
+      </div>
+    );
+  }
+
+  return (
+    <div className={frame}>
+      <button
+        type="button"
+        onClick={() => setPlaying(true)}
+        className="group absolute inset-0 h-full w-full focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-4 focus-visible:outline-white"
+      >
+        {media ?? (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img src={poster} alt="" loading="lazy" decoding="async" className="h-full w-full object-cover" />
+        )}
+        <span
+          aria-hidden="true"
+          className="absolute left-1/2 top-1/2 flex h-14 w-14 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full bg-card text-ink shadow-[0_8px_24px_-8px_rgba(0,0,0,0.6)] transition-transform duration-200 ease-out group-hover:scale-105 group-active:scale-95 motion-reduce:transition-none motion-reduce:group-hover:scale-100 motion-reduce:group-active:scale-100"
+        >
+          <Play size={22} strokeWidth={2} className="ml-0.5 fill-current" />
+        </span>
+        <span className="sr-only">{label}</span>
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Testimonial card of the Cuidado Global family — one item of novo.creeta's
+ * `Depoimentos`, by tokens. White card: the family's video on the left (only
+ * downloads on tap, plays with sound and the browser's controls, in place), the
+ * quote on the right, who speaks, and the link to the public post so anyone can
+ * check the source. The quote is a real <blockquote> with <cite>: it is someone
+ * else's words and the screen reader announces it as such.
+ */
+export function TestimonialCard({ quote, author, authorPhoto, authorAvatar, authors, link, video, as: Root = "div", labels, className = "" }: Props) {
+  const t = { ...EN, ...labels };
+  const people = authors ?? [{ name: author ?? "", photo: authorPhoto, avatar: authorAvatar }];
+  return (
+    <Root className={`grid grid-cols-[minmax(0,2fr)_minmax(0,3fr)] overflow-hidden rounded-[28px] bg-card ${className}`}>
+      <TapVideo {...video} label={t.watch(video.description)} />
+      <figure className="flex flex-col justify-between gap-5 p-5 md:p-7">
+        <blockquote className="font-heading text-[0.9375rem] font-medium leading-relaxed text-ink md:text-base">{quote}</blockquote>
+        <figcaption>
+          <Byline
+            cite
+            people={people}
+            action={link ? { label: link.label, href: link.href, external: true } : undefined}
+            newTabLabel={t.newTab.trim()}
+          />
+        </figcaption>
+      </figure>
+    </Root>
+  );
+}

package/components/Text.tsx

@@ -0,0 +1,31 @@
+import type { ElementType, ReactNode } from "react";
+
+export type TextVariant = "lead" | "body" | "small" | "eyebrow";
+
+export const TEXT: Record<TextVariant, string> = {
+  /** supporting paragraph under a title */
+  lead: "text-lg leading-relaxed text-ink-body",
+  /** reading text */
+  body: "leading-relaxed text-ink-body",
+  /** notes, captions */
+  small: "text-sm text-ink-soft",
+  /** small label one tone below, over a title or a date ("Década de 1980") */
+  eyebrow: "text-sm font-semibold text-ink-soft",
+};
+
+type Props = {
+  as?: ElementType;
+  variant?: TextVariant;
+  children: ReactNode;
+  className?: string;
+};
+
+/** Text — the family's paragraph styles (Figtree): lead, body, small, eyebrow. */
+export function Text({ as: Tag = "p", variant = "body", children, className = "" }: Props) {
+  return <Tag className={`m-0 ${TEXT[variant]} ${className}`}>{children}</Tag>;
+}
+
+/** Prose — a run of paragraphs at reading width: 1rem between them, relaxed leading, `ink-body`. */
+export function Prose({ children, className = "" }: { children: ReactNode; className?: string }) {
+  return <div className={`max-w-2xl space-y-4 leading-relaxed text-ink-body [&>p]:m-0 ${className}`}>{children}</div>;
+}

package/components/Timeline.tsx

@@ -0,0 +1,69 @@
+import type { ComponentType, ElementType, ReactNode } from "react";
+
+type IconType = ComponentType<{ size?: number; strokeWidth?: number; className?: string; "aria-hidden"?: boolean | "true" }>;
+
+export type TimelineStep = {
+  Icon: IconType;
+  title: ReactNode;
+  body: ReactNode;
+  /** Optional link under the body ("See the team ↗"): the family's strong
+   *  link, semibold, underlined, with the outbound arrow. `external` opens a new tab. */
+  link?: { label: ReactNode; href: string; external?: boolean };
+};
+
+type Props = {
+  steps: TimelineStep[];
+  /** Heading level of each step's title (h3 under an h2 section title). */
+  headingLevel?: "h3" | "h4";
+  /** Link component of the app (e.g. next-intl Link). Default: <a>. */
+  linkComponent?: ElementType;
+  /** sr-only after an external link. */
+  newTabLabel?: string;
+  className?: string;
+};
+
+const ArrowUpRight = () => (
+  <svg aria-hidden="true" viewBox="0 0 24 24" width={16} height={16} className="cg-arrow-go" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M7 17 17 7M9 7h8v8" /></svg>
+);
+
+/**
+ * Timeline — the "Como cuidamos" of novo.creeta, by tokens: an ordered
+ * sequence of steps, each with its own drawing (a 44px bubble with a lucide
+ * icon, decoration) and a title answered by a paragraph. A thin line links
+ * one drawing to the next: it is a path, from the first question to the last.
+ */
+export function Timeline({ steps, headingLevel = "h3", linkComponent, newTabLabel = "(opens in a new tab)", className = "" }: Props) {
+  const H = headingLevel;
+  const L: ElementType = linkComponent ?? "a";
+  return (
+    <ol className={`list-none ${className}`}>
+      {steps.map(({ Icon, title, body, link }, i) => {
+        const last = i === steps.length - 1;
+        return (
+          <li key={i} className={`relative grid grid-cols-[2.75rem_minmax(0,1fr)] gap-x-4 ${last ? "" : "pb-7"}`}>
+            {/* the line linking this drawing to the next */}
+            {!last && <span aria-hidden="true" className="absolute bottom-1 left-[1.375rem] top-12 w-px -translate-x-1/2 bg-ink/15" />}
+            <span aria-hidden="true" className="flex h-11 w-11 items-center justify-center rounded-full bg-ink/[0.12] text-ink">
+              <Icon size={20} strokeWidth={1.75} />
+            </span>
+            <div>
+              <H className="m-0 pt-2 font-heading text-lg font-medium leading-snug text-ink">{title}</H>
+              <p className="m-0 mt-1.5 leading-relaxed text-ink/80">{body}</p>
+              {link && (
+                <L
+                  href={link.href}
+                  {...(link.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+                  className="mt-2 inline-flex min-h-11 items-center gap-1.5 font-semibold text-ink underline underline-offset-4 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink"
+                >
+                  {link.label}
+                  <ArrowUpRight />
+                  {link.external && <span className="sr-only"> {newTabLabel}</span>}
+                </L>
+              )}
+            </div>
+          </li>
+        );
+      })}
+    </ol>
+  );
+}