How to use this
The page itself is built and tested. Layout, typography, colour, scroll behaviour, interaction and delivery are finished. This document describes what goes into it.
Use the filter above to show only your section. Every constraint here exists for a measured reason, and where the reason is not obvious it is stated. If a constraint blocks something you want to do, raise it before producing — several are browser or accessibility limits that cannot be worked around after the fact.
What we are not asking for
- Page mockups or layout proposals
- Typeface selection or colour direction
- UI components, buttons, icons, navigation
- Text baked into any image or video
Editorial rules
These govern every asset and every line of copy, regardless of who produces it.
Attribution travels with the claim
Figures, counts, percentages, assessments of extent and attributions of responsibility belong to named sources with their titles and affiliations. They appear in the story only with that apparatus intact. They never appear in a caption, a heading, a card, a map popup or alt text, where the apparatus cannot follow.
Documented history is permitted and encouraged
Architectural periods, construction features, ornament, plan and historical names are stable and sourceable. Mamluk period, 1250–1517 is a fact about a building. Destroyed in 2023 is a claim about an event and needs a source.
Captions
Place, date, credit. Nothing else. No cause, no consequence, no extent, no responsibility.
Conservators at work · Gaza · 10 July 2023 · Ali Jadallah
The archive record is authoritative. Where EXIF disagrees with the wire stamp, the archive record wins and the EXIF value goes in the manifest notes. Captions carry the shoot date, not the distribution date.
Register
This is a subject about loss. Motion stays restrained — no bounce, no playful easing, no decorative flourish. Nothing that turns the material into spectacle. Dignity is a design constraint, not a preference.
No simulation
The page does not reconstruct, animate or dramatise events. What is shown is what was photographed, filmed or documented. Diagrams may show documented architecture; they do not show damage, before-and-after states, or anything that was not observed.
Copy
Every limit below is set by the layout. Exceeding one does not produce a scroll bar — it produces a headline in four lines on a phone, or a label clipped out of the wire rail.
| Field | Limit | Why |
|---|---|---|
| Kicker | 32 characters, 2–4 words | Single line above the headline |
| Headline | 6–10 words, max 65 characters | Breaks to four lines beyond this on a phone |
| Standfirst | 40–60 words | Fixed block above the fold |
| Chapter slug | Max 20 characters | Appears in the wire rail, which truncates |
| Chapter title | Max 55 characters | Two lines at display size |
| Body paragraph | 60–90 words | Reading column is fixed at 33rem |
| Pull quote | Max 160 characters | Set at display size |
| Scrollmation step | 40–70 words | Read while looking at the image |
| Annotation label | Max 32 characters | Measured; beyond this it wraps into the artwork |
| Caption | 15–30 words | Mono, over a gradient |
| Card blurb | 40–60 words | Fixed card height |
| Meta description | 150–160 characters | Search and social preview |
Arabic runs roughly 1.8× longer than English for the same content. An annotation label at the 32-character English limit will not fit when translated. For anything destined for both editions, aim at 20 characters in English.
Structure
- 3–6 paragraphs per chapter
- 3–5 steps per scrollmation sequence — never more
- 4, 6 or 9 cards in a grid. No other count works
- Placeholder copy stays visibly placeholder, written as instructions to an editor, never as plausible journalism
Photography
Deliver originals at full resolution. We handle all compression, format conversion and responsive variants — do not export for web, do not pre-compress, do not send watermarked preview copies.
| Slot | Size | Notes |
|---|---|---|
| Cover | 2560 × 1440 | Bottom 45% and top ~17% both carry text — see below |
| Reveal | 2560 × 1440 | Bottom 25% carries a caption |
| Scrollmation frame | 1600 × 1600 · 1:1 | 3–5 per sequence, pixel-registered |
| Portrait | 800 × 800 | Head and shoulders, eyes on upper third |
| Before / after pair | 2560 × 1440 each | Same camera position |
| Share card | 1200 × 630 | The only asset where text may be baked in |
The cover no longer darkens only at the foot. A scrim band was added across the top ~17% so the masthead row stays legible over a bright frame — measured, because it failed at 3.4:1 against a 4.5:1 requirement without it. So the image is darkened at both ends: the bottom 45% for the headline and standfirst, the top 17% for the masthead.
The clear zone is the middle band only — roughly 17% to 55% of frame height. That is where the subject has to live. It is a real constraint on composition and it is not obvious from a contact sheet: a frame whose subject sits high or low will be half-buried in scrim.
Full-bleed images fill the viewport, so a 16:9 frame becomes roughly 9:16 on a phone — cut from the left and right, never top and bottom. Anything essential must sit within the centre 45% of the width. Mark that column and check the subject survives.
Scrollmation frames — the rule that makes them work
The frames are the same image with one thing changed. Same camera, same crop, same lighting, pixel-registered. What changes is one state: a position, an extent, a highlight, a layer appearing. Different photographs turn the sequence into a slideshow and waste the technique. Build them as layers on one master.
Portraits
Displayed desaturated and returning to colour on hover, so they must read as monochrome. Consistent lighting and background value across the set matters more than any individual frame. If no cleared portrait exists, deliver nothing — the page shows an empty block. No stock, no silhouette.
Before and after
Two photographs of the same site from the same camera position, one before and one after. If no matched pair exists in the archive, the block is dropped rather than faked. This is the strongest single element available and it depends entirely on what was shot years ago — check early.
Illustration and the flyover
The flagship element: one tall illustration in a single consistent perspective that the reader scrolls down through. Bespoke per story and the largest commission in the set.
Two artboards, both drawn
| Artboard | Size | For |
|---|---|---|
| Desktop | 2400 × 9000 | Tablet and up |
| Mobile | 1200 × 9000 | Phones — art-directed, not resampled |
The mobile artboard is redrawn for a narrow column: fewer elements, larger subjects, tighter framing, simplified background. A desktop artboard scaled to phone width renders its subjects too small to read.
Perspective
- One camera position for the whole artboard. Oblique aerial works best
- Horizon at a constant height where visible
- Scale consistent top to bottom
- Vertical position is narrative order — scrolling down reads as moving forward
There is no camera, no 3D and no animation behind this. The entire illusion of movement comes from the drawing being in perspective, which places the whole effect in design's hands.
Seams
Deliver each artboard as one file; we slice it into six horizontal tiles. But plan where the seams fall — at y = 1500, 3000, 4500, 6000 and 7500. A band ±60 px either side of each must contain no critical subject, no sharp horizontal edge and no fine repeating texture. Put seams in sky, open ground, water or haze. Decide while composing, not after.
Six tiles load progressively as the reader descends rather than making them wait on one 9000px file. Secondarily, a single tall image can exceed the per-image decode memory mobile Safari allows — 2400 × 9000 is 21.6 megapixels; each tile is 3.6.
Test slice first
Draw one tile, not the artboard. A single 2400 × 1500 slice loads into the live page on a real phone and settles perspective, palette, seam behaviour and decode speed in one pass. One day of work, and nothing is drawn at volume before it clears.
Annotations — ai2html
Labels stay live HTML text over the artwork: selectable, translatable, searchable, screen-reader readable, and correctable after publication without redrawing. Design does not hand over a coordinate list — ai2html generates it. It is an open-source Illustrator script from the New York Times graphics department that exports artwork as an image and overlays every text element as positioned HTML.
| Requirement | Why |
|---|---|
| Document colour mode RGB | The script requires it |
| Document saved before running | Output is written beside the .ai file |
| Labels as point text | Area text reflows unpredictably on export |
| Artboards named by width | Becomes the breakpoint key |
| Label font Space Mono 11pt | Matches the page; keeps the layout honest |
Download the script from github.com/newsdev/ai2html, not from the documentation site — that site is served over plain HTTP and the certificate warning is expected. Test compatibility with your Illustrator version before committing to this workflow.
Leader lines are ours. Supply the label at its resting position and mark the anchor point; we draw the hairline in AA red so it matches the interface.
Drifting elements
Anything intended to move continuously — atmosphere, dust, haze. Animated in CSS, not delivered as animation.
- Transparent PNG or SVG, max 600 × 600, under 60 KB each, max 3 per scene
- Cut out and isolated, nothing else in frame
- No shadow, glow or motion blur baked in — added in CSS so they respond to the movement
- Must read at 40px, which is its size on a phone
Palette
| Token | Hex | Role |
|---|---|---|
| Ink | #131110 | Page background |
| Paper | #F5F1EA | Headlines, key text |
| Newsprint | #B9B1A6 | Body text |
| AA red | #ED1C24 | Interface only |
AA red is not available as a scene colour. It marks chapter slugs, the progress bar, annotation leaders and links. If it appears as a major element inside artwork, the reader loses the ability to tell interface from content.
Video
Deliver masters. We build every web rendition — the encode ladder, posters, captions and responsive delivery are already built and tested. Nothing should be exported "for web".
Deliver at 48 kHz / 24-bit uncompressed as stated. We normalise at build time to −16 LUFS integrated with true peak at or below −1 dBTP, so nothing needs to arrive at a target. But the state it arrives in decides whether that is achievable.
Unmixed rushes are effectively silent. Measured across the material supplied so far: integrated loudness between −19 and −40 LUFS. Lifting a −40 LUFS file by 24 dB raises its noise floor by 24 dB too, and no normaliser can undo that.
And some arrive already clipped — two of ours peak at +0.1 and −0.1 dBTP on delivery. A signal already at the ceiling cannot be lifted at all without breaching it, which limits what normalisation can do from either direction.
So: a mixed deliverable is best, and a consistently levelled one is the minimum worth asking for. Consistency matters more than the absolute figure — a set of clips at a steady −24 LUFS is far more useful than a set ranging from −19 to −40.
Archive distribution proxies arrive at 640 × 360. Missing pixels cannot be recovered and upscaling produces softness, not detail. AI super-resolution invents texture that was never photographed, which is unacceptable on a heritage site. Send the master.
| Property | Specification |
|---|---|
| Codec | ProRes 422 HQ or DNxHR HQ. Failing that, H.264 at 50 Mbps or higher |
| Resolution | 1920 × 1080 minimum · 3840 × 2160 preferred |
| Frame rate | Native and constant. Conform any variable-rate source |
| Scan | Progressive only |
| Colour | Rec.709, legal range, no baked LUT |
| Audio | 48 kHz, 24-bit, uncompressed — levelled if at all possible, see below |
What must not be in the file
- Burned-in subtitles — captions ship as WebVTT so they stay live text, searchable, screen-reader readable, and reusable for the Arabic edition by swapping one file
- Logos, bugs, straps, lower thirds — branding is applied in the page
- Music beds — natural sound only
- Transitions, dissolves, wipes — deliver raw shots
- Graded look or baked LUT
- Vertical or square reframes — we crop
- Watermarks or timecode burn-in
Cover loop
- 8–12 seconds, one continuous shot, no cuts
- No audio track at all — stripped, not muted
- Slow drift, slow push or locked off. No pans — a pan will always snap back visibly at the loop
- Bottom 45% and top ~17% quiet; subject inside the centre 45% of width
Location footage — the gap
Packaged reports are built around pieces to camera and contain no usable silent windows. What the page needs, and what is currently missing:
- 20–40 seconds per shot, one continuous take
- Camera settled on a tripod — no whip pan, no zoom mid-shot, no refocus
- Nobody addressing the lens or an off-camera interviewer
- Architecture, stone detail, hands at work, general views
- Stable frames at both ends that hold as a poster
- 1 second of head and tail handles
Filmed interviews
The page has an interview block whose transcript scrolls with playback and lets the reader click any line to jump to that moment. That feature depends entirely on what arrives with the video.
- Locked-off tripod shot. Medium close-up, look room, eyes on the upper third
- Shot 16:9 but keep the subject centre-safe — the block may crop to square on phones
- Lavalier or shotgun microphone. Never the camera mic
- 30 seconds of room tone, recorded separately — routinely forgotten, and it is what makes edits inaudible
- No music under the interview at any level
Send the full interview, not a pre-cut selection,
plus a note marking the strongest passages. And a verbatim
timecoded transcript in the original language, format
00:01:23.500, timed per sentence. Without it the transcript
feature cannot be built at all. Translation is a separate editorial job.
Location sound
Audio only. WAV, 48 kHz, 24-bit, 60 seconds or more per location, uninterrupted. Two or three good recordings do more for the page than a dozen clips of footage.
Motion
Pan, never zoom. A continuous scale costs 3–5× what a translation costs in file size, and it is not proportional — a 0.5% zoom already costs 3.1× a held frame, while a full 7.5% zoom costs 5.1×.
A continuous scale resamples every macroblock by a different fraction each frame, so no block can be copied and the residual is nonzero everywhere. An integer-pixel translation at output scale compresses almost as cheaply as a still. There is no "smaller push" that avoids this.
Practically: any Ken Burns sequence is art-directed as a horizontal or vertical move across the frame, not a push in or out. Compose so the move has somewhere to go — a subject at one edge and a related subject at the other.
Playback
- Silent video autoplays as it enters view and pauses as it leaves
- Sounded video autoplays muted with a prominent unmute control
- Audio and interviews are always reader-initiated — testimony must not ambush the reader
- Nothing autoplays under reduced-motion, Save-Data or a slow connection; the poster shows instead
- Only one piece of media plays at a time across the page
Maps
Markers carry the site name, its type and its quarter or city. Every coordinate is cross-verified against OpenStreetMap and Wikidata. A site that cannot be verified is left off rather than approximated.
What a map does not carry
- Status, condition or damage of any site
- Dates, figures or counts
- Colour coding by condition — a legend keyed to site type is fine
- Boundary lines, shading or fills by area — drawing administrative boundaries is a cartographic claim
- Eastern Arabic numerals anywhere, in any language edition
How a place is verified
Follow OpenStreetMap's own wikidata= tag on the
feature. Read the OSM object, take the Wikidata ID it carries, then
confirm on the Wikidata side that P31 (instance of) and
P131 (located in) describe the right kind of thing in the right
place. That is OSM asserting the identity, which is a source.
Searching by English name is guessing at a romanisation, and it produces
false negatives. It did so on three of five
Gaza neighbourhoods here: "Daraj" returned a village in South Khorasan,
Iran, and Zaytun, Tuffah and Rimal returned nothing at all. Following the
wikidata= tag found all four that exist, immediately.
Why neighbourhood labels are not on the map
They were specified, verified and then not shipped, and the reason is a property of areas rather than a shortcoming of the sources.
Published centroids for the same neighbourhood disagree by 534 to 1042 m — Wikidata's point against the true centroid of OSM's boundary polygon. Neither is wrong; an area has no single centre. But the map's phone frame is 709 m wide, so the uncertainty in where a label goes exceeds the entire viewport. Placing one would assert a precision the sources do not support.
Point features are fine. Hammam al-Sammara's two sources agree to ~30 m, and it is on the map. The rule is not "neighbourhoods are unreliable" — it is polygons carry an anchor ambiguity that points do not, and it only matters at close zoom.
Orientation is carried in the popups instead: every marker names its quarter, attached to a point verified to metres. If a future story needs neighbourhood labels, it needs a second, wider locator map — around zoom 13, where roughly 5 km is on screen — not a change to this one.
Should they ever ship, they remain context, not content: small, muted, letter-spaced, no marker, not clickable, hidden from screen readers.
Every marker type needs a legend letter
A site type with no letter renders as a bare unlabelled pin, and nothing catches it — the popup still carries its name, type and place, so every content assertion passes. One shipped to the live site that way. Adding a type means adding it in three places: the marker letter map, the legend, and the manifest.
Delivery and manifest
Naming
site_category_NN.ext — lowercase, hyphens, zero-padded.
Example: qasr-al-basha_interview_01.mov
This is a hard rule, not a convention. The publishing host
is case-sensitive; macOS, where the work is done, is not. So
one wrong letter — Qasr for qasr, .JPG
for .jpg — works perfectly on the machine that made it and
breaks in production.
And it does not fail as a missing file. The host answers an unknown path with HTTP 200 and the page's own HTML, so a case error surfaces as a silently broken image — never a 404, never an error in any log. Nothing local can catch it; only a check against the live origin can.
Manifest
One CSV accompanying every delivery:
filename · site · category · photographer · date · location ·
duration · has_audio · language · status · notes
Photographer, date and location are rendered on the page directly from this file. An asset arriving without them cannot be used, because an uncredited image on a page carrying the AA logo is indefensible.
Status
| Value | Meaning |
|---|---|
| FINAL | Cleared AA material. Carries no testing mark |
| TEST | Placeholder. Carries a burned-in testing badge |
The build enforces both directions: a TEST asset without its badge fails, and a FINAL asset still carrying one fails too. The second catches the more dangerous mistake — a placeholder promoted without being replaced.
Colour and format
- sRGB with the profile embedded. No CMYK
- Stills as PNG or TIFF, lossless. Never pre-compressed, never JPEG-exported
- Layered masters stay with the originating team — they will be needed again for the Arabic edition
Weight
| Budget | Limit | Covers |
|---|---|---|
| First paint | 600 KB — enforced | Cover, fonts, page code. Build fails above it |
| ↳ measured | 0.42 MB — 72% | 12 requests, no video |
| Full page | Reported, not enforced | Everything a reader downloads at 1440px |
| ↳ measured | 7.41 MB | 60 requests, ~72% of it video |
Producers do not need to hit these — compression and every responsive variant are handled downstream. But three decisions at production time move the number more than any encoder can:
- Flat and graphic compresses; photographic noise does not. A clean illustration at 2400px can land under 100 KB. The same size under heavy grain lands at 400 KB
- Gradients across large areas band badly. Skies are the usual casualty. Slight texture compresses better than perfect smoothness
- Detail density costs decode time, separately from file size. A tile that downloads instantly can still stall for 80–150 ms on a mid-range phone — and that stall lands exactly at a seam. Passages of quiet between areas of detail help both the compressor and the decoder
The Reuters piece this engine was benchmarked against ships 49 MB on desktop and 33 MB on a phone, with no responsive images at all.
This page, measured, ships 7.41 MB across 60 requests — and it carries five video clips where that one carries none. First paint is 0.42 MB, which is 72% of the enforced ceiling and about 1.2% of the 33 MB a phone pays for the comparison piece. Readers on constrained networks are a large share of this audience.
Hosting requirements
These are properties of wherever the story is finally published, not of the page. Nothing in the build can compensate for them, and none of them is anyone's production job — but one of them changes what a reader experiences.
| Requirement | Why | Status |
|---|---|---|
| HTTP Range | Without it, seeking in audio and video degrades to downloading the whole file. A reader dragging a scrubber waits for the entire clip before it moves | Not met on the prototype host. A 100-byte range
request for a 2.8 MB clip returns all 2,860,338 bytes, and no
Accept-Ranges header is sent at all |
| Brotli or gzip on text | The document is 210 KB raw and 63 KB compressed — a 0.30× ratio. Uncompressed, first paint roughly quadruples | Met — brotli, verified on the live origin |
| No CDN image transformation | The FOR TESTING markings are pixels. A host that re-encodes or re-crops images can remove them, and the interlock that enforces them runs at build time, not at the edge | Met — no transformation configured |
Accepted for the prototype rather than worked around: the long clip is placeholder-captioned and nobody scrubs it in a demonstration. It becomes a real problem the moment a reader is expected to navigate inside a piece of testimony. Confirm Range on the production host before the first real interview ships.
Sequence of work
- Test slice. One flyover tile, one pair of scrollmation frames, one drifting element, one ai2html export with two or three labels. One silent location clip. Loaded into the live page on a real phone
- Review. Perspective, palette, seams, legibility, decode timing. Half a day
- Commission. The full set, only after the slice passes
Nothing is produced at volume before step 2 clears.
Open dependencies
| Needed | From | Blocks |
|---|---|---|
| Logo as SVG (or ≥512px raster) | Corporate identity | Brand mark capped at 21px; favicon |
| Video masters | Video desk | All video above 360p |
| Silent location footage | Video desk | Acts two and three |
| Timecoded transcripts | Video desk | Interview block entirely |
| Matched before/after pair | Archive | Comparison block — dropped if none exists |
| Test slice | Design | Flyover commission |
| ai2html compatibility check | Design | Annotation workflow |
| Domain decision | Management / technical | Publication |