Colour and ink / What the output device does to it
How the paper changes the colour that was in the file
The stock the document is printed on, which is the white in every light area and therefore part of every colour on the page.
What actually happens
Nothing in a printed document is white. What looks white is the paper, and papers differ: a coated sheet is bright and slightly blue, an uncoated one is warmer and duller, a recycled one is greyer still, and each of those is the background against which every other colour is judged. The same file produces visibly different results on three stocks, and the differences are largest exactly where documents put their light tones. Absorbency compounds it: an uncoated sheet takes more ink and spreads it more, so tints darken and fine detail thickens, while a coated sheet holds detail and keeps tints close to specification. Opacity is the third property and the one people forget, because a light sheet lets the next page show through.
Where this API stands on colour
This API renders HTML to PDF, and the colour in the output is the colour in your CSS, which is RGB. There is no colour-space option, no CMYK mode, no ICC embedding, no ink-limit control and no greyscale conversion. Two options touch colour at all and neither changes a colour value: print_background, which is on by default here and off by default in most renderers, decides whether backgrounds and background images are painted at all, and media decides whether your print stylesheet applies. Anything that converts this document into inks happens after the render, in a tool you choose, and that is where the decisions on this page are enforced.
The decisions that avoid it
Reasons rather than a description of the code. Each of these is a choice with a wrong answer, and the wrong answer usually looks correct on a screen.
- Know the stock before finalising light tones. A tint chosen against a bright coated white looks muddy on a warm uncoated sheet.
- Expect more gain and less detail on uncoated stock, and design the tints and rules with that headroom rather than tuning them afterwards.
- Check opacity for anything printed double sided. A heavy dark panel on one side shows through a light sheet and interferes with the text on the other.
- Do not try to correct for paper colour by tinting the background of the page. Printing a white or off-white background wastes ink, defeats the paper, and is dropped by print settings anyway.
- Where a document is issued on more than one stock, pick the least forgiving one as the design target.
- The file has no notion of paper. Nothing in the markup or in a render option expresses it, so this is a decision made outside the document and then designed around inside it.
In the stylesheet
Where the decision is expressible in CSS, this is what it looks like. Where it is not, the snippet says so rather than inventing a property.
/* The page background is the paper. Leave it alone: printing a
white or near-white background wastes ink, is dropped by print
settings, and cannot make the paper a different colour anyway. */
@media print {
body { background: transparent; } /* not #fff, not an off-white tint */
}
/* Design the light tones with headroom for a warmer, more absorbent
stock rather than tuning them to a bright coated proof. */
:root {
--tint-soft: #f2f0ea; /* reads as a tint on coated and uncoated both */
}
/* Double sided: keep heavy dark areas off the reverse of pages that
carry small text, because a light stock shows through. */
.dense-text-page { --panel-allowed: none; }What people do instead
Painting the page background white or a pale tint to control the look. On a screen it sets the tone; on paper it either does nothing, because print backgrounds are off, or it lays a flat wash of ink over the whole sheet, which costs money and makes the paper look worse rather than better.
How to find out rather than assume
Print the same file on every stock the document might be issued on and lay them side by side. The differences in the light areas will be larger than you expect. Then hold a double-sided sheet up to the light and see how much of the reverse is visible through it.
Frequently asked
Can I ask the API for CMYK output?
No. There is no colour-space option on the render, and the document comes out in RGB. Converting to CMYK is a downstream step: a preflight tool or a converter rewrites the colour against a profile you choose, and that is also where an output intent and an ink-coverage check belong. Convert after rendering rather than trying to reach the conversion from a stylesheet.
Will my backgrounds and tints print?
From this API they are painted into the document by default, because print_background defaults to true here rather than to false. What happens afterwards is the reader's print settings, and a viewer told not to print backgrounds will still drop them. That is why every page in this cluster treats a background as an enhancement rather than as the thing carrying the meaning.
Does any of this apply to a document that is only ever read on screen?
Very little of it. Dot gain, ink coverage, registration and paper are properties of a physical process. If the document is genuinely never printed, photocopied or faxed, most of this cluster is not your problem. The reason it is worth reading anyway is that people are consistently wrong about which of their documents get printed.
Related colour and ink topics
The topics that cause each other, then the rest of the same group.
Why a 10% tint prints darker than it looks on screen
A percentage screen of a colour, which is printed as a pattern of dots rather than a lighter ink, and comes out darker than specified.
The same PDF on an office laser and on a commercial press
Two output devices with different resolutions, different colour behaviour and different physical limits, producing two different objects from one file.
Greyscale conversion, and the two colours that become one grey
What happens when a colour document is printed on a monochrome device, which is most of the time for most documents.
Designing a document that survives being photocopied and faxed
What a document has to be like to still work after it has been through a copier, a scanner or a fax, which is where most operational documents end up.
Every colour and ink topic
The full list, grouped by whether it happens in the ink, in a conversion, or at the device.
Everything on this page is decided in your stylesheet or at the printer. Render the document, then put it on the paper it will actually be printed on.