@breathe-ds/ui 0.3.0 → 0.5.1

package/README.md

@@ -57,6 +57,21 @@ For a site without a ready-made token file, define the roles on `:root` itself:
 and `scroll-padding` (6rem top, 7rem bottom) so keyboard focus never lands
 hidden behind the sticky Header or the BottomNav (WCAG 2.4.11).
 
+## Using it in a site (Tailwind v4)
+
+```css
+@import "tailwindcss";
+@import "@breathe-ds/ui/theme.css";        /* the roles */
+@import "@breathe-ds/ui/tokens/ttcab.css"; /* this brand's hex (or creeta.css, neutral.css) */
+/* Tailwind only generates the classes it finds written: scan the components */
+@source "../../node_modules/@breathe-ds/ui/components";
+```
+
+The components are TSX sources, not a build: in Next.js add
+`transpilePackages: ["@breathe-ds/ui"]` to `next.config`. The CSS entries of
+the package are exported with the `style` condition, which Tailwind's resolver
+requires (a plain string export fails with "Can't resolve").
+
 ## Token roles
 
 | Token (Tailwind) | Role | `--cg-*` |
@@ -69,7 +84,17 @@ hidden behind the sticky Header or the BottomNav (WCAG 2.4.11).
 | `ink-body` | reading body text | `--cg-ink-body` |
 | `action` | CTA / highlight — **never plain text** | `--cg-action` |
 | `action-text` | text in the action color (AA) | `--cg-action-text` |
+| `on-action` | text ON the action color (the accent button) | `--cg-on-action` |
+| `action-tint` | highlighted panel or card: a 6% wash of the action color over the surface | `--cg-action-tint` |
+| `action-line` | border of a highlighted card (closed tone, 3:1 on the surface; pure ttcab orange is 1.91:1) | `--cg-action-line` |
 | `line` | hairlines / borders | `--cg-line` |
+
+**Dose of the action color** (what brands with a hot accent do, Cloudflare orange,
+Airbnb red): the action color is the fill of ONE element per block, with
+`on-action` text on it; links stay in `ink`/`ink-soft` with an underline; a
+highlighted card is `action-tint` + `action-line`, not the full color; the
+color as text only as `action-text`. The "Action dose" section of the playground
+shows the disciplined and the loud version side by side.
 | `font-heading` / `font-body` | typography | `--cg-font-*` |
 | `radius-xl/2xl/pill` · `ease-cg` | radius and motion curve | fixed |
 
@@ -82,10 +107,11 @@ Values from the standard WCAG formula (the same ones `preview/` computes live):
 | surface `#fbf5e9` / ink `#144753` | 9.41:1 | AAA |
 | surface `#fbf5e9` / ink-soft `#54707a` | 4.86:1 | AA |
 | surface `#fbf5e9` / ink-body `#1e4f5b` | 8.32:1 | AAA |
-| surface `#fbf5e9` / action-text `#9a5d07` | 4.90:1 | AA |
+| surface `#fbf5e9` / action-text `#bd3f0c` | 4.98:1 | AA |
+| action `#e8541e` / on-action `#ffffff` (accent button) | 3.67:1 | 3:1 UI component; below AA text, conscious exception |
 | surface-panel `#144753` / cream text | 9.41:1 | AAA |
 
-`action` `#f6a22a` is decorative/CTA only — do not use it as text on cream.
+`action` `#e8541e` is a vivid red-orange with white text, the Cloudflare/Airbnb route: 3.67:1 passes the 3:1 of UI components, not the 4.5:1 of normal text. A conscious exception, limited to the accent Button (one per block, same type scale as the other buttons so they never look mismatched); small controls (chips, tabs, segments) use `ink` or `action-tint` + `action-text` instead. The UI orange does not match the logo's `#f6a22a` on purpose. As text, use `action-text`.
 
 ## Family typography
 
@@ -200,9 +226,17 @@ from color, not from extra markup.
   replace the arrow). The ProfessionalCard is built on them.
 - **ProfessionalCard** / **ProfessionalModal** / **CaptionBand**: the team card of
   novo.creeta — portrait (plain, living clip on hover, or with the "Presentation"
-  chip), name, role, registration (**always**: COFFITO 414/2012), trajectory /
-  guidance / Instagram rows; the modal plays the presentation with sound, the
-  live caption band (active WebVTT cue) above the name, and the full bio.
+  chip), name, role, registration (**always**: COFFITO 414/2012) and generic
+  `rows` (collapse with text or links, link with arrow or icon — on creeta:
+  trajectory, guidance, Instagram); the modal plays the presentation with sound,
+  the live caption band (active WebVTT cue) above the name, and the full `bio`.
+  Three sizes (`size`): `full` (team page), `medium` (the home's tile — 3:4
+  portrait, name, "Meet" badge on hover, a link to the full card; `shortName`,
+  `href`) and `micro` (the "who treats" row — 72px photo, name, role, link).
+- **Rail** / **RailItem**: novo.creeta's `Trilho` — on the phone a snapping
+  horizontal rail with a progress bar underneath (shown only when it scrolls),
+  a grid from md (`grid` classes written in full). RailItem presets the phone
+  width: `wide` (treatments, videos) or `narrow` (team).
 - **Byline** / **PersonChip** / **Avatar**: who signs or explains content
   (novo.creeta) — stacked portraits + eyebrow + linked names, or portrait + name
   + "Watch the video ↗"; the person chip (portrait, name, role · registration,
@@ -234,9 +268,56 @@ from color, not from extra markup.
 - **CtaCard** / **VideoInviteCard**: the final call of a novo.creeta page — white
   card (title, lead, CTA slot) beside a video card: muted loop with the speaker's
   name over it, pause control, play button that plays the full video with sound.
+- **CareSteps**: "how the care works" of novo.creeta — a bento mosaic of
+  numbered steps (drawing above, text below; the first takes two columns) with
+  the invite on the dark panel closing the sequence. The drawings are slots:
+  **ChatPreview** (a sample chat, bubble by bubble, the clinic "types"; loops
+  while on screen, pause button), **PlanTimeline** (three stages, the line comes
+  down and each dot lights up; 6s loop, pause button), **PhotoSequence** (photos
+  with fade and a slow zoom, CSS only, paused by a hidden checkbox), or a still
+  image. All stand still and whole with reduced motion. `useOnAppear` (animate
+  when half on screen, only while on screen) and `PauseButton` (44px, 32px
+  circle) are exported for your own drawings.
+- **Blog**: creeta's "guidance" area — **PostCard** (the card of the list:
+  cover, category, title as the link stretched over the card, excerpt in three
+  lines, author · date), **FeaturedPosts** ("in the words of who treats you":
+  bento, the first post wide with the cover beside the text, a Byline with the
+  speaker and "Watch the video ↗" at the foot) and **PostArticle** (the page:
+  trail, title, PersonChip and date, the text with its notice, the video beside
+  it sticky from md, the transcript open; children for "other posts" and the
+  final call).
+- **SidePanel**: Luma's drawer — a native `<dialog>` that slides in from the
+  right, full height, up to 32rem wide (full width on the phone), with a top
+  bar (close on the left, actions such as "Copy link" and "Course page ↗" on
+  the right) and a scrolling body. Esc, the backdrop and the button close it;
+  focus goes back to what opened it. The playground opens one from a
+  CourseCard (`onSelect`) with the whole class inside: cover, facts,
+  RegistrationBox with the button straight to the school's cart, programme,
+  discounts, rules.
+- **CourseCard**: the class card (ttcab's "Formação", the school's class list)
+  in the family's own vocabulary: course name as the category line, the city as
+  the title with the seats pill, the facts as EventFacts tiles (DateBadge for
+  the start, pin for the venue with its map link, clock for the workload), who
+  teaches as a Byline, a cover photo at the top, and at the foot the price with
+  its note beside the Button `accent`; `soldOut` puts the pill in the button's
+  place; `onSelect` makes the card a button stretched over it (the links inside
+  keep working) to open its details. By tone: no border, no shadow, no lift.
+- **Events** (after Luma and Meetup, for the school's classes): **EventList**
+  (days down a dotted rail, each with its rows), **EventRow** (time with an
+  accented end, title as the stretched link, organizers, location, who is going
+  with "+N", square cover, an optional badge), **EventFacts** (date on a
+  calendar tile, venue on a pin tile with its link), **DateBadge** and
+  **RegistrationBox** (a strip title, ticket options as a radio group with the
+  remaining pill and the price, the one button at the foot).
+- **StoryPanel**: creeta's "origin" block — one dark panel (surface-panel)
+  grouping a story: media at the top with a film that fades into the panel, the
+  logo at its base, title, lead, three pillars in columns with a hairline above
+  each, and the outbound links. For "who we are" and "why us" blocks.
 - **Footer**: the site-footer of novo.creeta, by tokens — full width like the
   Header, with the signed brand + sentence, "Pages" (title on the first line, links in two
-  columns), "Where we are" (address, hours, "Directions ↗ · Waze ↗"), an optional
+  columns; with many pages, `pages.groups` — titled columns, up to four side by
+  side, so the list gets wider instead of taller), "Where we are" (address, hours,
+  "Directions ↗ · Waze ↗"), an optional
   notice band on `surface`, the legal line with the **CNPJ (always required in
   the family)** plus the contact chips, and the languages as plain links.
   `navHiddenFrom` keeps room at the bottom for the BottomNav.
@@ -264,7 +345,7 @@ from color, not from extra markup.
       **Data rule:** every professional MUST have a **CREFITO** attached (COFFITO requirement).
 - [x] **Pill / PillList** — the Atalho of novo.creeta (white 44px pill, arrow bubble: ↓ anchor, ↗ other page, optional meta); wrapping row + "See all"
 - [x] **AnchorNav** (floating capsule of anchors, scroll-spy + sliding indicator) — extracted from ttcab (10/29)
-- [x] **Footer** · **PageVideoHero** (loop and player) · **Header** (dropdown, house) · **BottomNav** · **Curtain** · **Lockup** (5 arrangements) · **BreatheMark**
+- [x] **Footer** · **PageVideoHero** (loop, and player from a YouTube id or the site's own mp4) · **Header** (dropdown, house) · **BottomNav** · **Curtain** · **Lockup** (5 arrangements) · **BreatheMark**
 - [x] **Site brand marks** (`components/marks/`): real symbol + wordmark for TTCAB and Creeta (10/29)
 - [ ] **ThreadRail** (side graphic device — a thread running down the left linking sections) — approved,
       **already exists in ttcab** → extract.

package/components/AnchorNav.tsx

@@ -36,7 +36,8 @@ type Props = {
  * The active signal = the indicator (ink/12 fill + outline), NOT text color:
  * the text is always `ink` on `surface`, with no low-contrast frame.
  * prefers-reduced-motion removes the slide. Target sections need a
- * `scroll-mt-*` compatible with the sticky offset (e.g. `scroll-mt-40`).
+ * `scroll-mt-*` that, added to the theme's `scroll-padding-top` (96px), clears
+ * the header plus the capsule (e.g. `scroll-mt-20` with an 80px header).
  */
 export function AnchorNav({ items, stickyTop = "top-20", linkComponent, className = "", labels }: Props) {
   const L: ElementType = linkComponent ?? "a";
@@ -45,6 +46,10 @@ export function AnchorNav({ items, stickyTop = "top-20", linkComponent, classNam
   const listRef = useRef<HTMLUListElement>(null);
   const linkRefs = useRef<Record<string, HTMLAnchorElement | null>>({});
   const [pill, setPill] = useState({ x: 0, y: 0, w: 0, h: 0, ready: false });
+  // Stable key of the items: sites pass the array inline, so a new reference
+  // on every render. Keyed by reference, the arrival effect below re-ran on
+  // every page scroll and kept dragging the page back to the hash.
+  const key = items.map((it) => it.id).join("|");
 
   // Scroll-spy
   useEffect(() => {
@@ -63,11 +68,13 @@ export function AnchorNav({ items, stickyTop = "top-20", linkComponent, classNam
     );
     sections.forEach((s) => io.observe(s));
     return () => io.disconnect();
-  }, [items]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
 
   // Arriving with a #hash via client-side navigation: scrolls to the anchor (on
   // a full load the browser already does it; here it's idempotent). Reapplies a
-  // few times to beat the router's late scroll reset.
+  // few times to beat the router's late scroll reset. Runs once, on arrival:
+  // the hash the person sets by clicking a pill is the browser's job.
   useEffect(() => {
     const hash = window.location.hash.slice(1);
     if (!hash || !items.some((it) => it.id === hash)) return;
@@ -80,7 +87,8 @@ export function AnchorNav({ items, stickyTop = "top-20", linkComponent, classNam
       if (++tries >= 4) window.clearInterval(id);
     }, 60);
     return () => window.clearInterval(id);
-  }, [items]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
 
   const measure = () => {
     const el = linkRefs.current[active];

package/components/Button.tsx

@@ -15,10 +15,17 @@ const linkBase =
   "group inline-flex items-center gap-1.5 font-body font-semibold underline decoration-[1.5px] decoration-current/50 underline-offset-4 transition-[text-decoration-color,text-underline-offset] duration-200 hover:decoration-current hover:underline-offset-[5px] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ink rounded-[2px] disabled:pointer-events-none disabled:opacity-50 motion-reduce:transition-none [&>svg]:transition-transform [&>svg]:duration-200 hover:[&>svg]:-translate-y-0.5 hover:[&>svg]:translate-x-0.5 motion-reduce:[&>svg]:transform-none";
 
 const variants: Record<Exclude<Variant, "link">, string> = {
-  // solid petrol, cream text (e.g. "Falar com a equipe")
-  solid: "bg-ink text-surface hover:-translate-y-0.5 shadow-[0_6px_18px_rgba(20,71,83,0.28)]",
-  // action color (orange/magenta) + on-action text (from the token, varies per site)
-  accent: "bg-action text-on-action hover:-translate-y-0.5 shadow-[0_6px_18px_rgba(20,71,83,0.22)]",
+  // Flat, as the pill buttons of novo.creeta: no drop shadow, no lift; the hover
+  // is a change of fill and the tap scales the pill (pillBase). A shadow under a
+  // hot action color read as a grey halo (2026-10-29).
+  // solid petrol, cream text (e.g. "Falar com a equipe"): hover goes to ink-soft (creeta's teal-escuro)
+  solid: "bg-ink text-surface hover:bg-ink-soft",
+  // action color (orange/magenta) + on-action text (from the token, varies per site).
+  // Same type scale as the other variants: buttons side by side must share a size.
+  // On ttcab (white on the vivid red-orange) that is 3.67:1, a conscious exception
+  // (Cloudflare and Airbnb ship the same): passes the 3:1 of UI components, not
+  // the 4.5:1 of normal text. Keep the accent for ONE large button per block.
+  accent: "bg-action text-on-action hover:brightness-[0.92]",
   outline: "border border-line text-ink hover:bg-ink/[0.05]",
   ghost: "text-ink hover:bg-ink/[0.06]",
 };

package/components/Byline.tsx

@@ -51,11 +51,13 @@ export function Byline({ people, eyebrow, action, joiners = { sep: ", ", last: "
       )}
     </span>
   ));
+  // min-h-11 keeps the 44px tap target; -my-3 takes those extra 12px out of the
+  // flow, so when the link wraps under the names the two lines read as one caption
   const actionEl = action ? (
     <L
       href={action.href}
       {...(action.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
-      className="inline-flex min-h-11 items-center gap-1 font-semibold text-ink underline underline-offset-4"
+      className="-my-3 inline-flex min-h-11 items-center gap-1 font-semibold text-ink underline underline-offset-4"
     >
       {action.label}
       <ArrowUpRight />

package/components/CareSteps.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from "react";
+
+export type CareStep = {
+  title: ReactNode;
+  /** What fits the phone card (two columns). */
+  summary: ReactNode;
+  /** The full text, from lg. */
+  text: ReactNode;
+  /** The drawing above the text: a ChatPreview, a photo, a PlanTimeline, a
+   *  PhotoSequence… It fills the frame (absolute inset-0). Decorative: it
+   *  repeats what the text says; only a pause button should reach the keyboard. */
+  visual: ReactNode;
+};
+
+type Labels = {
+  /** sr-only before the title: "Step 1: ". The number on screen is decoration. */
+  step: (n: number) => string;
+};
+const EN: Labels = { step: (n) => `Step ${n}: ` };
+
+type Props = {
+  steps: CareStep[];
+  /** The last tile, on the dark panel: the sentence and the action (a WhatsApp link, a Button). */
+  invite: { text: ReactNode; action: ReactNode };
+  /** Heading level of the step titles. */
+  headingLevel?: "h2" | "h3";
+  labels?: Partial<Labels>;
+  className?: string;
+};
+
+/** The frame of each drawing: surface colour, corner concentric with the
+ *  card's (28px minus the 12px of breathing room). */
+const FRAME = "relative h-32 overflow-hidden rounded-2xl bg-surface md:h-52";
+
+/**
+ * How the care works, from the first contact to the treatment — creeta's
+ * `Passos`, by tokens. A bento mosaic: each step has its drawing above and
+ * its text below; the first takes two columns and the invite closes the
+ * sequence:
+ *
+ *   [ 01, wide ]  02          phone:  [ 01, wide ]
+ *    03   04   invite                  02   03
+ *                                      04   invite
+ *
+ * The invite comes last: it is the conclusion of the steps.
+ */
+export function CareSteps({ steps, invite, headingLevel: Title = "h3", labels, className = "" }: Props) {
+  const t = { ...EN, ...labels };
+  return (
+    <div className={`grid grid-cols-2 gap-3 md:grid-cols-3 md:gap-5 ${className}`}>
+      {/* contents: the <li> become tiles of the mosaic and the list stays a list */}
+      <ol className="contents">
+        {steps.map((s, i) => (
+          <li key={i} className={`flex flex-col rounded-[28px] bg-card p-3 ${i === 0 ? "col-span-2 md:flex-row-reverse" : ""}`}>
+            {i === 0 ? (
+              <div className="relative overflow-hidden rounded-2xl bg-surface md:w-1/2">{s.visual}</div>
+            ) : (
+              <div className={FRAME}>{s.visual}</div>
+            )}
+
+            <div className="flex flex-1 flex-col px-2 pb-2 pt-4 md:px-3 md:pb-3 md:pt-5 lg:px-5 lg:pb-5 lg:pt-6">
+              {/* The number is visual reinforcement; the order goes as text for the screen reader. */}
+              <span aria-hidden="true" className="font-heading text-[1.75rem] font-normal leading-none tracking-[-0.04em] text-ink-soft md:text-[2.5rem]">
+                {String(i + 1).padStart(2, "0")}
+              </span>
+              {/* 16px on the phone: the column has 141px, and at 18px titles broke into three lines */}
+              <Title className={`mt-2 font-heading text-base font-medium leading-snug text-ink md:text-xl ${i === 0 ? "md:mt-auto md:pt-6" : "md:mt-3"}`}>
+                <span className="sr-only">{t.step(i + 1)}</span>
+                {s.title}
+              </Title>
+              {/* the full text only when the column fits it: up to lg it has less than 180px */}
+              <p className="mt-1.5 text-sm leading-relaxed text-ink-body lg:hidden">{s.summary}</p>
+              <p className="mt-2 hidden leading-relaxed text-ink-body lg:block">{s.text}</p>
+            </div>
+          </li>
+        ))}
+      </ol>
+
+      {/* The invite closes the mosaic: it is the last tile. */}
+      <div className="flex min-h-[200px] flex-col justify-between gap-6 rounded-[28px] bg-surface-panel p-5 text-surface md:p-6 lg:p-8">
+        <p className="font-heading text-[1.375rem] font-medium leading-[1.15] md:text-[2rem] md:leading-[1.12]">{invite.text}</p>
+        <div className="self-start">{invite.action}</div>
+      </div>
+    </div>
+  );
+}

package/components/ChatPreview.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties } from "react";
+import { Clock } from "lucide-react";
+import { reducedMotion, useOnAppear } from "./useOnAppear";
+import { PauseButton } from "./PauseButton";
+
+export type ChatMessage = { from: "person" | "clinic"; text: string };
+
+type Labels = {
+  /** Completes the pause button's name: "Pause the sample conversation". */
+  pause: string;
+};
+const EN: Labels = { pause: "the sample conversation" };
+
+type Props = {
+  messages: ChatMessage[];
+  /** Small line at the top, with a clock: the opening hours. */
+  hours?: string;
+  labels?: Partial<Labels>;
+  className?: string;
+};
+
+/** How long the clinic is "typing" before each reply, in ms. */
+const TYPING = 1100;
+/** At the end the conversation rests this long, fades out and restarts. */
+const REST = 3200;
+const EXIT = 350;
+/** Time to read the previous message before the next: grows with its length, 0.9s to 1.9s. */
+export const readingTime = (previous?: ChatMessage) =>
+  previous ? Math.min(1900, Math.max(900, 600 + previous.text.length * 28)) : 400;
+
+const BUBBLE = "cg-bubble max-w-[15rem] rounded-[20px] px-4 py-3 text-sm leading-snug lg:text-[0.9375rem]";
+const CURVE = "cubic-bezier(0.23, 1, 0.32, 1)";
+
+/**
+ * Step 1 of the care flow (creeta's `Conversa`): a sample conversation, bubble
+ * by bubble. The person writes, the clinic "types" and answers.
+ * - Starts when half of it is on screen and loops: at the end rests 3.2s,
+ *   fades and restarts. Only runs while on screen.
+ * - Works like a real chat: fixed height, new bubbles come in at the bottom,
+ *   old ones slide up and vanish at the top. Nothing pushes the page.
+ * - Moves by itself for more than 5s, so it has a pause button (WCAG 2.2.2).
+ * - Without JavaScript, IntersectionObserver or with reduced motion, the whole
+ *   conversation shows still, without the button.
+ * - The chat is decoration (aria-hidden): the step's text already says what
+ *   matters. The button stays outside it, for the keyboard and screen reader.
+ */
+export function ChatPreview({ messages, hours, labels, className = "" }: Props) {
+  const t = { ...EN, ...labels };
+  const { ref, state, onScreen } = useOnAppear<HTMLDivElement>();
+  const stack = useRef<HTMLDivElement>(null);
+  const height = useRef(0);
+  const [shown, setShown] = useState(0);
+  const [typing, setTyping] = useState(false);
+  const [paused, setPaused] = useState(false);
+  const [leaving, setLeaving] = useState(false);
+
+  const visible = state === "whole" ? messages : state === "waiting" ? [] : messages.slice(0, shown);
+
+  // The clock: one message at a time, and back to the start.
+  useEffect(() => {
+    if (state !== "playing" || paused || !onScreen) return;
+    const wait = readingTime(messages[shown - 1]);
+    const timer =
+      shown >= messages.length
+        ? leaving
+          ? setTimeout(() => {
+              setShown(0);
+              setLeaving(false);
+            }, EXIT)
+          : setTimeout(() => setLeaving(true), REST)
+        : messages[shown].from === "person"
+          ? setTimeout(() => setShown((v) => v + 1), wait + 300)
+          : typing
+            ? setTimeout(() => {
+                setTyping(false);
+                setShown((v) => v + 1);
+              }, TYPING)
+            : setTimeout(() => setTyping(true), wait);
+    return () => clearTimeout(timer);
+  }, [state, paused, onScreen, shown, typing, leaving, messages]);
+
+  // New bubble at the bottom: the stack grows upward at once. To slide the old
+  // ones up, it starts offset by the height it gained and returns (transform only).
+  useLayoutEffect(() => {
+    const el = stack.current;
+    if (!el) return;
+    const gained = el.offsetHeight - height.current;
+    height.current = el.offsetHeight;
+    if (state !== "playing" || gained <= 0 || reducedMotion() || !el.animate) return;
+    el.animate([{ transform: `translateY(${gained}px)` }, { transform: "translateY(0)" }], { duration: 320, easing: CURVE });
+  }, [state, shown, typing]);
+
+  return (
+    <div ref={ref} data-state={state} data-paused={paused ? "" : undefined} className={`cg-chat relative h-full min-h-[17.5rem] md:min-h-[20rem] ${className}`}>
+      <div aria-hidden="true">
+        {hours && (
+          <span className="absolute left-4 top-0 flex h-11 items-center gap-1.5 text-xs font-medium text-ink/80 lg:left-7">
+            <Clock size={13} strokeWidth={2} />
+            {hours}
+          </span>
+        )}
+        {/* the chat window: what goes past the top fades out */}
+        <div className="absolute inset-x-0 bottom-0 top-11 overflow-hidden [mask-image:linear-gradient(to_bottom,transparent,black_2rem)]">
+          <div
+            ref={stack}
+            className={`absolute inset-x-0 bottom-0 flex flex-col gap-2.5 px-4 pb-4 transition-opacity duration-300 ease-out motion-reduce:transition-none lg:px-7 lg:pb-7 ${leaving ? "opacity-0" : ""}`}
+          >
+            {visible.map((m, i) => (
+              <span
+                key={i}
+                className={
+                  m.from === "person"
+                    ? `${BUBBLE} origin-bottom-right self-end rounded-br-md bg-ink text-surface`
+                    : `${BUBBLE} origin-bottom-left self-start rounded-bl-md bg-card text-ink`
+                }
+              >
+                {m.text}
+              </span>
+            ))}
+            {typing && (
+              <span className="cg-bubble cg-typing flex origin-bottom-left gap-1 self-start rounded-[20px] rounded-bl-md bg-card px-4 py-3.5">
+                {[0, 1, 2].map((n) => (
+                  <i key={n} style={{ "--n": n } as CSSProperties} className="h-1.5 w-1.5 rounded-full bg-ink-soft" />
+                ))}
+              </span>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {state !== "whole" && (
+        <PauseButton paused={paused} onToggle={() => setPaused((p) => !p)} what={t.pause} className="right-0 top-0 lg:right-2" />
+      )}
+    </div>
+  );
+}

package/components/CourseCard.tsx

@@ -0,0 +1,139 @@
+import type { ElementType, ReactNode } from "react";
+import { Clock } from "lucide-react";
+import { Byline, type Person } from "./Byline";
+import { EventFacts, DateBadge, type EventFact } from "./EventFacts";
+
+type Labels = {
+  /** Prefix before the instructors' names ("With"). */
+  with: ReactNode;
+  /** The pill on the title line and the one in the button's place when sold out. */
+  soldOut: ReactNode;
+};
+const EN: Labels = { with: "With", soldOut: "Sold out" };
+
+type Props = {
+  /** Cover photo at the top (the school's pages always have one), 4:3,
+   *  focused near the top for the portrait photos the school uses. */
+  cover?: { src: string; alt?: string; position?: string };
+  /** The course ("Basic RTA course 2026"): the heading of the card. */
+  course?: ReactNode;
+  /** The class ("City · ST"): the line under the heading, with the seats pill.
+   *  Without `course`, it is the heading itself. */
+  title: ReactNode;
+  /** The start, for the calendar tile. */
+  start: { month: ReactNode; day: ReactNode };
+  /** The dates: "3 to 9 November 2026 · 08:30–17:30" and, below, the extra day. */
+  when: { title: ReactNode; subtitle?: ReactNode };
+  /** The venue (a link to the map when it has an href) and the address. */
+  where?: { title: ReactNode; subtitle?: ReactNode; href?: string; external?: boolean };
+  /** "69 class hours". */
+  workload?: ReactNode;
+  /** Seats, as a pill on the title line ("28 seats"). */
+  seats?: ReactNode;
+  /** Who teaches: portraits and names, each a link when it has an href. */
+  instructors?: Person[];
+  /** The price beside the button ("R$ 7.280") and a small note ("up to 12 instalments"). */
+  price?: { value: ReactNode; note?: ReactNode };
+  /** Small note at the foot ("Only physiotherapists can attend."). */
+  footnote?: ReactNode;
+  /** The call to action: a Button `accent`, the one full-colour element of the card. */
+  action?: ReactNode;
+  /** No seats left: the pill says so and takes the button's place. */
+  soldOut?: boolean;
+  /** Makes the card clickable (the title becomes a button stretched over the
+   *  card) to open its details, e.g. in a SidePanel. Links inside (the map,
+   *  the instructors, the action) keep working on their own. */
+  onSelect?: () => void;
+  headingLevel?: "h2" | "h3";
+  linkComponent?: ElementType;
+  labels?: Partial<Labels>;
+  className?: string;
+};
+
+const PILL = "inline-flex items-center rounded-pill bg-ink/[0.08] px-2.5 py-0.5 text-xs font-semibold text-ink";
+
+/**
+ * Course card of the Cuidado Global family — the class card (ttcab's
+ * "Formação", the school's class list), in the family's own vocabulary: the
+ * course name as the category line, the city as the title with the seats pill
+ * (as the EventRow), the facts as tiles (the DateBadge for the start, the pin
+ * for the venue, a clock for the workload, as the EventFacts), who teaches as
+ * a Byline, and the Button accent pinned at the foot. By tone: no border, no
+ * shadow, no lift.
+ */
+export function CourseCard({ cover, course, title, start, when, where, workload, seats, instructors, price, footnote, action, soldOut = false, onSelect, headingLevel: Title = "h3", linkComponent, labels, className = "" }: Props) {
+  const t = { ...EN, ...labels };
+  const facts: EventFact[] = [{ tile: <DateBadge month={start.month} day={start.day} />, title: when.title, subtitle: when.subtitle }];
+  if (where) facts.push({ tile: "pin", title: where.title, subtitle: where.subtitle, href: where.href, external: where.external });
+  if (workload)
+    facts.push({
+      tile: (
+        <span aria-hidden="true" className="flex h-12 w-12 shrink-0 items-center justify-center rounded-xl bg-ink/[0.06] text-ink">
+          <Clock size={20} strokeWidth={2} />
+        </span>
+      ),
+      title: workload,
+    });
+  const pill = soldOut ? t.soldOut : seats;
+
+  const foot = soldOut ? (
+    <span className="inline-flex min-h-11 items-center rounded-pill bg-ink/[0.08] px-5 font-heading font-semibold text-ink">{t.soldOut}</span>
+  ) : (
+    action
+  );
+
+  return (
+    <article className={`relative flex flex-col overflow-hidden rounded-[28px] bg-card ${onSelect ? "transition-transform duration-200 ease-out active:scale-[0.99] motion-reduce:transition-none motion-reduce:active:scale-100 [&_a]:relative [&_a]:z-10 [&_button]:relative [&_button]:z-10" : ""} ${className}`}>
+      {cover && (
+        <div className="relative aspect-[4/3] overflow-hidden">
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img src={cover.src} alt={cover.alt ?? ""} loading="lazy" decoding="async" className="absolute inset-0 h-full w-full object-cover" style={{ objectPosition: cover.position ?? "50% 25%" }} />
+        </div>
+      )}
+      <div className="flex flex-1 flex-col p-6 md:p-7">
+      {/* the course is what the person looks for: it is the heading; the city
+          is the variant, on the line below with the seats pill (2026-10-29) */}
+      <Title className="font-heading text-xl font-medium leading-snug text-ink md:text-[1.375rem]">
+        {onSelect ? (
+          // the stretched hit area of the card: this button is the exception to [&_button]:z-10 (static, after: covers the card)
+          <button type="button" onClick={onSelect} className="static! z-auto! text-left after:absolute after:inset-0 after:z-0 after:rounded-[28px] focus-visible:outline-none focus-visible:after:outline focus-visible:after:outline-2 focus-visible:after:-outline-offset-2 focus-visible:after:outline-ink">
+            {course ?? title}
+          </button>
+        ) : (
+          course ?? title
+        )}
+      </Title>
+      {(course || pill) && (
+        <p className="mt-2 flex flex-wrap items-center gap-2 text-base font-semibold text-ink">
+          {course && <span>{title}</span>}
+          {pill && <span className={PILL}>{pill}</span>}
+        </p>
+      )}
+
+      <EventFacts className="mt-5" facts={facts} linkComponent={linkComponent} />
+
+      {instructors && instructors.length > 0 && (
+        <div className="mt-5 flex items-center gap-3 text-sm text-ink-body">
+          <span className="shrink-0 text-ink-soft">{t.with}</span>
+          <Byline people={instructors} linkComponent={linkComponent} className="min-w-0" />
+        </div>
+      )}
+
+      {footnote && <p className="mt-5 text-sm text-ink-soft">{footnote}</p>}
+
+      {/* at the foot: the price on the left, the button on the right; cards side by side align here */}
+      {(foot || price) && (
+        <div className="mt-auto flex flex-wrap items-center justify-between gap-x-4 gap-y-3 pt-6">
+          {price && (
+            <p className="leading-tight">
+              <span className="block font-heading text-xl font-semibold text-ink">{price.value}</span>
+              {price.note && <span className="block text-sm text-ink-soft">{price.note}</span>}
+            </p>
+          )}
+          {foot}
+        </div>
+      )}
+      </div>
+    </article>
+  );
+}

package/components/DateBadge.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+
+type Props = {
+  /** Short month ("Nov"). */
+  month: ReactNode;
+  /** Day of the month. */
+  day: ReactNode;
+  /** 48px (default) or 56px. */
+  size?: "md" | "lg";
+  className?: string;
+};
+
+/** The date as a small calendar tile (Luma's "NOV / 6"): the month small on
+ *  top, the day large below, on a tinted bubble. Decorative beside the written
+ *  date; alone, give the parent an accessible text. */
+export function DateBadge({ month, day, size = "md", className = "" }: Props) {
+  const box = size === "lg" ? "h-14 w-14 rounded-2xl" : "h-12 w-12 rounded-xl";
+  return (
+    <span aria-hidden="true" className={`flex ${box} shrink-0 flex-col items-center justify-center bg-ink/[0.06] text-ink ${className}`}>
+      <span className="text-[0.6rem] font-bold uppercase leading-none tracking-[0.12em] text-ink-soft">{month}</span>
+      <span className={`mt-1 font-heading font-bold leading-none ${size === "lg" ? "text-2xl" : "text-lg"}`}>{day}</span>
+    </span>
+  );
+}