---
title: "Illustration style"
description: "Where a drawing is the right medium, the constraints that keep an illustration honest, and why a friendly-tech-company house style is wrong for a health result."
url: "https://opsinjs.pensievelabs.org/foundations/imagery/illustration-style"
source: "https://opsinjs.pensievelabs.org/foundations/imagery/illustration-style.md"
section: "Foundations"
kind: "foundation"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["illustration", "drawing style", "spot illustration"]
---
> Elements written as `` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.
## Overview [#overview]
Illustration is the right medium in a health product for exactly one class of
thing: showing how something is done or where something is. How to position a
cuff. Which button on a meter. Where on the arm. Drawings do this better than
photographs because they can leave out everything irrelevant, and better than
words because spatial instructions in prose are hard to follow.
They are the wrong medium for everything else, and particularly for the thing they
are most often used for: making a screen feel friendly. Flat, bright, weightless
figures with simplified faces are the dominant illustration style in consumer
software, and they read as marketing. Marketing beside a blood test result reads
as someone trying to sell you something at a bad moment.
opsinjs ships no illustration set. A product that needs one is commissioning it,
and this page is what to put in the brief.
## How it works [#how-it-works]
**Instructional first, always.** An illustration in the system exists to be
followed. That has consequences for the style before any aesthetic question comes
up: it must be unambiguous about orientation and scale, it must show enough
context for the reader to locate themselves, and it must not simplify away the
part that distinguishes correct from incorrect.
**Depict people as people, not as symbols.** Faceless, uniformly coloured figures
are the standard solution to the representation problem and they do not solve it:
they avoid depicting anyone rather than depicting a range of people, and a reader
looking for somebody like themselves finds nobody. Where a figure is shown, it is
a specific person, and the set as a whole covers a genuine range of skin tones,
body sizes, ages and visible assistive equipment. See
[Skin-tone representation](./skin-tone-representation.mdx).
**No implied verdicts.** No expressions, no thumbs, no celebration, no
commiseration. An illustration that reacts to a reading is a verdict from an
unnamed source, and verdicts belong to
[clinical status](../../health/clinical-status-semantics.mdx) expressed in words.
**Sit inside the colour system, and outside the two axes.** Illustration uses
neutral roles and, where it needs more, the chart ramp. It never uses the status
palette and it never uses the category palette. An illustration drawn in the
urgent colour is an illustration making a clinical claim.
**No fabricated data.** A drawn chart with an invented line, a mock reading in a
device illustration, a screenshot-style image with plausible numbers in it: all
banned. A reader cannot reliably tell an illustrative number from a real one, and
in a health product the cost of getting that wrong is high. Where a device is
shown, its display is blank or shows an obviously non-numeric placeholder.
**Style constraints that follow from the above:** a limited palette so the
illustration does not compete with the status colour on the same screen; enough
line weight to survive at the size it is actually displayed; no fine detail that
disappears on a phone; and no drop shadows or gradients that will not survive a
greyscale print.
## Using it [#using-it]
**Write the brief around the question the reader is asking.** "Show where to place
the cuff on the upper arm, from the reader's own point of view, with the tube
downward" produces a usable drawing. "Illustrations for the onboarding flow" does
not.
A three-step sequence showing a cuff positioned on an upper arm, drawn from
the angle the reader will see their own arm from, with the same figure in all
three steps.
A single spot illustration of an abstract figure with a stylised heart,
captioned "your health". It answers no question, it takes vertical space above
the fold, and the heart is one glyph away from a
[banned medical symbol](../iconography/health-glyphs.mdx).
**Keep the point of view consistent.** An instructional set that switches between
first-person and third-person views makes the reader do a mental rotation at every
step. Pick the reader's own viewpoint and stay in it.
**Do not put text inside the drawing.** Labels in an illustration cannot be
translated, cannot be scaled with the reader's text size, and cannot be read
aloud. Put them beside it, in text, positioned by the layout.
**Do not animate an instruction.** A looping animation of a step means the reader
has to catch the right moment, and cannot go back. Steps are steps. See
[Steps](../../handbook/contributing/documentation-templates.mdx) for the
documentation form and [Motion](../motion/index.mdx) for the constraint.
**Budget the weight.** An illustration that delays a reading is worse than no
illustration, and instructional images are exactly the ones a reader is looking at
on a bad connection.
## Tokens [#tokens]
Illustration consumes the neutral colour roles and the chart ramp. It may not
consume `--opsin-status-*` or `--opsin-category-*`; both carry meaning that an
illustration would then be asserting.
## Accessibility impact [#accessibility-impact]
* **An instructional illustration needs a text equivalent that is genuinely
usable**, not a label. If the drawing shows how to position a cuff, the
alternative describes how to position a cuff. See
[Alt text and descriptions](../../content/alt-text-and-descriptions.mdx).
* **Line weight and contrast are legibility, not style.** A thin, low-contrast
drawing is a drawing a reader with low vision cannot follow. Meaningful marks
are measured under WCAG 2.2 SC 1.4.11 like any other non-text content.
* **No text inside images**, for the reasons above, and it is the rule most often
broken by an illustration set delivered from a design tool.
* **Illustrations must survive greyscale**, because they will be printed, screen-
shotted and read in high-contrast modes.
* **Faceless figures are not neutral.** Avoiding representation is a choice with
its own effect; the alternative is a set that represents a range, which is what
[Skin-tone representation](./skin-tone-representation.mdx) requires.
## Related [#related]
* [Skin-tone representation](./skin-tone-representation.mdx) is the requirement
any commissioned illustration set must satisfy.
* [Body diagrams](./body-diagrams.mdx) covers the specialised case where a drawing
of a body is doing diagnostic-adjacent work.
* [Health glyphs](../iconography/health-glyphs.mdx) covers the same authority
question, one scale down.