docs: show a real application in the get-started animation - #169
Merged
Conversation
The showcase animation on both get-started pages was a mock clinical application. Public material shows real applications running synthetic data; the in-house stand-in is for internal testing only. A reader who lands on the first page of the docs and sees a fake EMR has no way to tell which parts of the product are real. Rebuild it from the openIMIS eligibility reference pack that openadapt-web already publishes, rather than shooting something new. That pack is already reviewed: it pins the openIMIS 25.10 container images by digest, declares its data synthetic, and records the outcome of every trial. Its three media files carry a recorded demonstration, a replay an independent read-only SQL query verified, and a replay the same query contradicted, which halted. That is the record, compile, replay loop both pages describe, and the halt is the part the old animation never showed. scripts/build_showcase_animation.py composes the frames. It reads the pack manifest for every label, outcome, and count it draws, refuses a pack that is not classified synthetic, and takes its colours from the vendored design tokens. docs/assets/showcase/PROVENANCE.txt records the source media hashes and the upstream commit. Both embeds become figures with captions, because the animation now shows a specific application and the caption has to say so. The get-started caption also says the tutorial below uses a browser page instead, so nobody expects to install openIMIS. The palette ledger is regenerated. The dominant colour moves from #0d0b1e to #0b1220, which is --inset-bg from the canonical tokens. measure_asset_palette.py samples an animation's first frame only, so that reading describes the opening card; the openIMIS screens behind it measure #fafafc and #dbeef0 and satisfy the cool-ground rule on their own. PROVENANCE.txt says this beside the number so the measurement is not mistaken for a claim about the footage. The file grows from 241,291 to 365,669 bytes. A light application UI costs more GIF than a dark terminal did. Frame count, palette size, and dither are tuned against that: 48 colours and no dithering are indistinguishable from 256 on flat UI chrome and cost roughly half the bytes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
The showcase animation on
get-started/index.mdandget-started/first-workflow.mdshowed a mock clinical application. Public material shows real applications running synthetic data; the in-house stand-in is for internal testing. A reader landing on the first page of the docs and seeing a fake EMR has no way to tell which parts of the product are real.What replaced it
The openIMIS eligibility reference pack that
openadapt-webalready publishes atpublic/reference/openimis-eligibility-standard-synthetic-v1. Nothing was shot for this PR. That pack was already reviewed: it pins the openIMIS 25.10 container images by digest, declaresdata_classification: synthetic, names theopenadapt-flowcommit that produced it, and records the outcome of every trial.Its three media files supply every screen:
recording/openimis-source-recording.unbound.mp4verified-replay/eligible-replay.mp4fail-safe-halt/expired-halt.mp4That is the record, compile, replay loop both pages describe. The halt is the part the old animation never showed, and it is the interesting frame: the two replays land on visually near-identical screens, and only the policy status differs. The read-only SQL oracle is what separates them.
scripts/build_showcase_animation.pycomposes the frames. It reads the pack manifest for every label, outcome, and count it draws, exits if the pack is not classified synthetic, and reads its colours fromdocs/stylesheets/vendor/openadapt-web/tokens.json. Frames are sampled and scaled but not otherwise altered; the animation adds a caption panel, a header, a footer, and an opening card.Palette guard
Regenerated with
scripts/measure_asset_palette.py --write. The dominant colour moves from#0d0b1eto#0b1220, which is--inset-bgfrom the canonical tokens, so blue >= red still holds. The guard is untouched.One thing worth knowing before you read that number:
measure_asset_palette.pysamples an animation's first frame only, and the first frame here is the opening card. So#0b1220describes the card, not the openIMIS footage. The footage is cool on its own measurement as well, at#fafafcfor the recording ground and#dbeef0for the eligibility panel.docs/assets/showcase/PROVENANCE.txtsays this beside the measurement so it is not mistaken for a claim about the frames.Provenance
New file
docs/assets/showcase/PROVENANCE.txt, following the house style of theui/andscreenshots/records. It names the source pack, theopenadapt-webcommit, the SHA-256 of each of the three source media files, the pinned openIMIS images, and the rebuild command. It also states plainly that this file is composed rather than byte-identical to any one upstream file, which is the one way it differs from theui/assets.docs/assets/screenshots/PROVENANCE.txtis not touched.Copy
Both embeds become
<figure markdown="span">with a<figcaption>, matching the existing figures indesktop/install.md. The alt text and captions now name openIMIS, because a replacement animation under caption text describing the old one would be worse than the original problem.The
get-started/index.mdcaption also says the tutorial below runs against a browser page. The animation sits directly under a paragraph about the tutorial, and without that line a reader would reasonably think the tutorial installs openIMIS.Size
A light application UI costs more GIF than a dark terminal did. Frame count, palette size, and dither are tuned against that: 48 colours with no dithering are indistinguishable from 256 on flat UI chrome and cost roughly half the bytes. Staying with GIF keeps the embed working everywhere;
ffmpeghere has nolibwebpencoder, and animated WebP would drop first-frame-only on older Safari.Verification
pytest289 passed, including all 13 intests/test_design_tokens.pymkdocs build --strictclean; both figures render, and the emitted HTML matches the existing figures byte for byte in structure🤖 Generated with Claude Code