Medical Companions: two diseases, animated and cited

Most writing about a disease explains a process with a paragraph and a static diagram: a protein misfolds, a cell reacts, a drug steps in. Medical Companions shows the process instead. Each companion covers one disease, and each mechanism is an SVG drawing on a timeline you can scrub or play. Every claim links to a numbered source. There are two so far: Alzheimer's disease, in English and Hebrew, and Familial Mediterranean Fever (FMF), the most common inherited autoinflammatory disease.

The companions are written for health-science students, nursing included, and for people living with the disease and the families who care for them. They are a self-initiated studio project. The FMF companion came first and the Alzheimer's companion two days later; the next day, the two separate repositories were merged into one site with a shared hub.

Sources cited, Alzheimer's

497

Sources cited, FMF

259

Modules across the two

41

Evidence labels

3

A timeline under every mechanism

Each companion is one self-contained page: a rail of modules on the left and one module on stage at a time, grouped into five parts that run from the disease itself through diagnosis and treatment to living with it, with flashcards, a quiz, a glossary and the sources at the end. Inside a module, a drawing is a function of time. A shared player wires a range input and a Play button to the module's draw(t), so dragging the slider and pressing Play run the same code. Step buttons jump to the moments that matter, such as the cut that releases amyloid beta.

That one pattern covers very different timescales. In the Alzheimer's companion, amyloid goes from a single protein cut to a plaque, and the biomarker cascade runs across the twenty years before the first symptom. Lecanemab and donanemab play out over their 18-month trials, side effects included. In the FMF companion, an attack plays hour by hour over 72 hours, site by site, and the colchicine module follows a pill into a neutrophil and then follows a patient over months, to show why the benefit builds slowly.

Calculators that teach a point

A few modules are interactive in a different way. The Alzheimer's diagnosis module has a blood-test calculator. You set the test's sensitivity and specificity and the share of people tested who have the disease, and a grid of people shows who is caught, who is missed and who is falsely flagged. The lesson is that a test's predictive value depends on who is being tested, so a published figure holds only for people like the ones studied. The FMF companion has the equivalent for diagnosis: a criteria calculator for the Tel Hashomer, Livneh and Eurofever/PRINTO sets, each shown with the sensitivity and specificity reported in the study it was measured in.

Every claim has a number

The writing began as research, not prose. The Alzheimer's companion went through nine research passes, from epidemiology and pathology to nursing care and the search for a cure; FMF went through seven. Each pass returned cited facts, their reference lists were merged into one sources.json per companion, and the modules were written against that file.

In the source, a citation is a key in double brackets. The build turns each key into a numbered link to the Sources module, fails on any key it doesn't know, and warns about sources that are never cited. The counts on the hub come from the same pass, so they include only the sources a page actually cites: 497 for Alzheimer's and 259 for FMF. Corrections to individual sources sit in a separate file that is applied after every regeneration, so a fix can't be lost when the list is rebuilt.

Each research claim is labelled Established, Early evidence or Hypothesis. Where experts disagree, the page presents both sides.

The Alzheimer's companion sets the 2024 Alzheimer's Association diagnostic criteria next to the IWG's from the same year, and it presents the argument over whether the new antibodies' benefit is clinically meaningful as an argument. Both companions open with a notice at the top of the page: they are educational summaries of published research, cannot diagnose anyone, and should not change a treatment without your own clinician. Doses and guideline statements are quoted as published, not as instructions.

A phone gets its own drawing

The drawings are laid out on a 720-unit-wide stage, which is far too wide for a phone held upright. Rather than shrink them, each animation has a second layout. draw() asks whether the screen is narrow and reads its coordinates from the matching table, so on a phone the panels stack in a tall column. A module that crosses the threshold, from a rotation or a resized window, is redrawn at the same moment on its timeline.

• Every timeline is a real range input, so arrow keys scrub it; in the FMF companion, Enter or Space plays and pauses.
• Each drawing has a written description for screen readers, and the step buttons give the slider a spoken value like “Step 2 of 5” with the step's name, not a bare number.
• Captions that change with the animation sit in polite live regions, so a screen reader hears them without losing its place.
• With reduced motion on, Play jumps straight to the end state instead of animating.
• Colours come from theme tokens, so the drawings follow light and dark mode.

Hebrew, kept in step with the English

The Alzheimer's companion also exists in Hebrew. The Hebrew parts mirror the English ones file for file, and the build uses the English part for anything not yet translated. The page reads right to left, but the drawings keep a left-to-right frame, so a time axis runs the same way in both languages. A checker fails if a Hebrew part's code, element structure, citations or numbers differ from the English, so a translation can't quietly drop a source or change a figure.

Plain files, one site

There is no framework. Each companion is assembled by a short Python build from its parts (a head with the styles, a shell, one HTML and one JavaScript file per module, and the sources) into a single page that is committed, so the repository is the site and GitHub Pages serves it as is. The only outside resource is Google Fonts. Each companion keeps its own palette, fonts and icon; everything that turns parts into a page is shared.

A smoke test loads every module in headless Chrome. It drags every slider through four points on its timeline, clicks every toggle, and reports any JavaScript error or drawing that came out empty.

The merge kept both repositories' git histories. The old addresses now send visitors on, including links to a specific module. GitHub Pages can't send a real permanent redirect, so each old page carries a canonical link and an immediate refresh, which search engines treat as a permanent move. The site's address lives in one config file, so moving it to its own domain is a one-line change and a rebuild. Adding a third disease takes three steps: its parts, an entry in that file, and a card on the hub.