# Scribe Illustrations Specification **Conformance target:** Hand-drawn-feel line illustrations that a non-reading user can name correctly, on a printed card and on a low-end phone screen **Audience:** Designers, researchers, and engineers producing illustrations that carry meaning for low-literacy users, in survey instruments, choice experiments, POS screens, and printed material **Scope:** Single-subject line illustrations built from one heavy rounded stroke, white interiors, and a warm spot-fill accent. Delivered as square raster for survey and print pipelines, with vector source where the asset was authored as vector. **Companion specs:** `equity/design-for-low-literacy-spec.mdx`, `research/discreet-choice-experiment-spec.md`, `research/field-research-synthesis-spec.mdx`, `regions/Haiti-spec.mdx`, `accessibility/WCAG-AAA-spec.md`, `equity/financial-concept-framing-spec.mdx`, `equity/bias-audit-spec.mdx`, `illustrations/flat-art-illustrations-spec.md`, `illustrations/corporate-illustrations-spec.md` **Implementation home:** `lls-dce/` holds the working library, the per-concept metaphor decisions, and the build and export pipeline (`design-notes.md`, `docs/ROADMAP.md`, `manifest.csv`, `icons/`, `features/`, `PNG/`, `build/`, `export/`). This spec states the rules and how to check them; the concept-by-concept metaphor choices live there. Terms **MUST**, **SHOULD**, and **MAY** follow [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). **The core claim:** in this style the illustration *is* the label. There is no caption to fall back on, because the user cannot read one, so an ambiguous drawing is not a rough edge, it is a wrong answer recorded in a dataset or a wrong choice made at a counter. Comprehension is therefore measured with real users in the target market and stated as a number, and every style rule below exists to protect that number. **Out of scope:** Multi-element scene illustrations (see `illustrations/corporate-illustrations-spec.md`), isometric monochrome icon-family art (see `illustrations/flat-art-illustrations-spec.md`), animation, and interface iconography that sits next to readable text. --- ## 1. Purpose and conventions | Field | Content | |---|---| | **Rule** | Every illustration MUST have a stated target concept in English and in the user's language, and MUST NOT ship as final until it reaches the project's comprehension threshold with users from the target population, unaided by any text. | | **Why** | These assets stand in for words for people who cannot read them, and the metaphors available to a designer are mostly borrowed from another market. A money sack reading as "winnings" instead of "savings" is not a style flaw, it is a confound that corrupts every response collected against that card. | | **How to verify** | Show the illustration alone, no label and no context, to users from the target population and record what they say it is in their own words. Compare against the target concept and against the wrong reads named in the record. Below threshold means the asset is a draft, whatever it looks like. | Each section below uses the same Field/Content table format and lists **MUST / SHOULD / MAY** rules. The unit of work is one **illustration**: one subject, one canvas, one concept. --- ## 2. Line, fill, and stroke system | Field | Content | |---|---| | **Rule** | Build the subject from a single heavy dark stroke with round caps and joins, at one weight per illustration, over white or very light interiors. Color appears only as flat warm spot fills inside those closed shapes. | | **Why** | The dark stroke is the only element that survives every degradation this style has to pass through: greyscale printing, a cheap screen in daylight, a photocopied card deck, a small ODK image slot. Making the stroke carry the drawing means the asset degrades gracefully instead of disappearing. | | **How to verify** | Convert the asset to pure black and white with color removed. The subject must remain fully identifiable. Then enumerate stroke widths: one weight for the subject, with secondary marks no lighter than the documented ratio. | **MUST** - Scale stroke weight with the canvas so weight stays visually constant across the library. The authored ratio is roughly 1:12 between stroke and viewBox edge, which is stroke-width 2 at a 24 unit icon and stroke-width 5 at a 96 unit illustration. - Use round caps and round joins throughout. Mitred corners read as a different library. - Keep interiors white or a single very light tint, so the asset works on white, on the beige page background, and on transparent. - Hold one corner-radius and one line-weight family per illustration. **SHOULD** - Keep the drawing to the smallest number of strokes that still names the subject. Hatching, shading lines, and interior texture cost legibility at card size and buy nothing. **MUST NOT** - Use gradients, bevels, gloss, or simulated lighting. - Outline every element at a different weight to create emphasis. Emphasis comes from size and position. --- ## 3. Color carries connotation, never information | Field | Content | |---|---| | **Rule** | Assign each hue one fixed meaning across the whole library, take the meanings from the applicable region spec rather than from Western convention, and never let a hue be the only thing distinguishing two concepts. | | **Why** | Warm yellow on white is around 1.7:1 against the background: far below any contrast floor, invisible in daylight on a cheap screen, and gone entirely in a greyscale print. It is usable as connotation precisely because it is not carrying the information. Colors also mean specific things in the target culture, and inheriting the wrong meaning is a comprehension failure, not a taste question. | | **How to verify** | Compute the contrast ratio of every fill against white from resolved colors. Any fill below 3:1 MUST be enclosed by the dark stroke, and removing all color must leave the concept intact per section 2. Then confirm every hue in the asset appears in the library's documented meaning map. | **MUST** - Reserve red for errors and warnings only. - Enclose every low-contrast fill inside a dark stroke, so the shape is defined by the stroke and merely tinted by the fill. - Keep two concepts that could be confused distinguishable by shape, not by hue. - Document the meaning map once (which hue means prosperity, which means growth, which is reserved) and cite the region spec it came from. **SHOULD** - Keep the accent fill to a small share of the artwork. A subject filled edge to edge in the accent loses the white interiors that make the line read. **MUST NOT** - Introduce a hue outside the documented map to make one asset more appealing. - Use color alone to signal a state, a magnitude, or a difference between variants. --- ## 4. No text, no digits, and no borrowed currency glyphs | Field | Content | |---|---| | **Rule** | Illustrations MUST contain no words and no digits. Magnitude is shown by repeating the subject or a token, never numerically. Currency is shown with a locally recognized coin or note motif, not with a foreign currency glyph. | | **Why** | Digits are literacy, so a number is a barrier dressed as information. And the `$` glyph is specifically American: for the target population it is either meaningless or it means a different currency than the one the product uses, which changes the amount the user thinks they are being offered. | | **How to verify** | Inspect the artwork for glyphs. Any letter, digit, or foreign currency sign is a blocking defect. Where quantity matters, count the repeated elements and confirm they match the intended magnitude. Existing library assets carrying a `$` are non-conformant and must be reworked, not grandfathered. | **MUST** - Express amounts, tiers, and counts by repetition at counts a user can subitize, typically up to five. - Use the generic coin motif documented for the library where a currency mark is needed. - Keep the same token meaning the same thing everywhere it appears in a study or a product surface. **MUST NOT** - Render a threshold, price, or reward value inside the illustration. Values belong on the card or in the surface copy where they can be set in the user's language and changed without redrawing. --- ## 5. Composition and canvas | Field | Content | |---|---| | **Rule** | One subject, centered, complete, on a square canvas with generous margin, optionally sitting on a soft light contact shadow. Secondary marks are limited to a small number of motion or emphasis strokes. | | **Why** | These assets land in fixed square slots: a survey image field, a printed card, a grid on a review sheet. A subject that fills the canvas unevenly or gets cropped reads as a different size than its neighbors in a deck, and in a choice experiment inconsistent visual weight is itself a treatment effect. | | **How to verify** | Measure the artwork bounding box as a fraction of canvas width across the library. Every asset must sit within a narrow band of the target fill, with no pixels in the outer margin and none touching an edge. | **MUST** - Keep the subject uncropped and centered. - Keep the export square at the documented dimensions, padded rather than stretched. - Keep visual weight comparable across any set of assets that will be compared against each other. **SHOULD** - Keep the contact shadow soft, light, and grounded directly under the subject. - Limit sparkle, motion, and emphasis marks to a few strokes. They read as liveliness at full size and as noise at card size. **MUST NOT** - Add a background scene, a frame, a border, or a second subject. - Render any note, annotation, condition, or explanation inside the illustration. That belongs in the manifest or the research plan. --- ## 6. Metaphor selection is a research decision | Field | Content | |---|---| | **Rule** | Every metaphor MUST be recorded with the connotation it carries, the alternatives considered, and the reason the chosen one was preferred. A metaphor MUST NOT be adopted on the designer's intuition alone when a plausible alternative exists. | | **Why** | The failure is not that a drawing is unclear, it is that it is clear and means the wrong thing. A cinched sack of money reads as a lump of winnings, which is exactly the connotation a savings concept must avoid, and the difference is invisible to whoever drew it. Naming the alternatives is what makes the choice reviewable. | | **How to verify** | Pick any three library assets at random. Each must resolve to a record naming the target concept in both languages, the metaphor, the alternatives, the verdict, and the comprehension result that closed it. If the record says nothing about alternatives, the choice was not made, it was assumed. | **MUST** - Carry weak or contested metaphors into comprehension testing as explicit contrasts rather than discarding or shipping them silently. - Keep concepts that must stay distinct visually distinct, especially where two rewards could be confused with each other. - Check the metaphor against local practice and vocabulary from field research, not against the source-language product vocabulary. - Apply the framing rules in `equity/financial-concept-framing-spec.mdx`. An illustration frames a money concept whether or not it intends to. **SHOULD** - Prefer a metaphor drawn from something the user already does over one that must be taught. **MUST NOT** - Treat a Western financial trope as a neutral default. A piggy bank is a hypothesis, not a given. --- ## 7. Variant discipline for comparison and testing | Field | Content | |---|---| | **Rule** | Where two illustrations of the same concept are compared, they MUST differ in exactly the property under test, and every other property in this spec MUST be held constant between them. | | **Why** | The point of an A/B pair is to attribute a difference in comprehension or in choice to one change. A pair that also differs in stroke weight, fill share, subject scale, or number of accent marks cannot support that attribution, and the resulting number is worse than no number because it will be believed. | | **How to verify** | Diff the two variants property by property against sections 2 through 5: stroke weight, fill palette and share, bounding-box fill, mark count, canvas. Everything except the stated variable must match. Then confirm the manifest names the variable. | **MUST** - Name the variable in the manifest entry for the pair. - Swap only one variant at a time in a live instrument, holding the rest of the deck constant, and record when the swap happened. - Keep variant naming consistent and mechanical across the library so pairs cannot be mismatched during assembly. **MUST NOT** - Introduce a redrawn-from-scratch variant as an A/B pair. A full redraw changes every property at once. --- ## 8. Output, print, and delivery | Field | Content | |---|---| | **Rule** | Vector is the source of truth wherever the asset was authored as vector, and exports MUST be generated from it by the build pipeline rather than hand-produced. Every shipped asset MUST be verified in each medium it ships in: on screen, printed at final card size, and in greyscale. | | **Why** | These illustrations are printed on physical cards handled outdoors and mirrored into a survey app on low-end Android hardware. An asset verified only on a design-tool canvas has not been verified in either place it actually lives. | | **How to verify** | Print the deck at final size and read it at arm's length in daylight, then open the same assets in the target app on the target device. Any asset that fails in either medium fails, regardless of how it looks at full resolution. | **MUST** - Record every asset in the library manifest with its filename, target concept in both languages, group, metaphor notes, and variant variable. - Keep filenames matching across every export format, and keep drafts out of the shipped directories. - Regenerate exports from source after any edit, and verify the shipped file rather than the source. **SHOULD** - Provide an accessible name where the asset appears in a digital surface, and mark it decorative where it is decorative. An illustration carrying the meaning of a choice is never decorative. - Keep the pipeline reproducible from a clean checkout, so the deck can be rebuilt when a value or a label changes. **MUST NOT** - Hand-edit an exported raster. The edit will be lost on the next build and the two will silently diverge. - Ship an asset whose comprehension result is unknown into an instrument that will produce data.