| name | kdp-cover-wrap |
| description | Build or edit a KDP full-wrap paperback cover in Typst — spine derived from the interior's measured extent, fold lines, safe zones, spine-text rules, and the layout traps that only show up in a printed proof. Use when building a cover, changing a cover design, diagnosing a spine that does not match the book, or preparing cover art for upload. |
The full-wrap cover
One page carrying back cover, spine and front cover, with bleed on all four
outside edges. That single sheet is what KDP wants uploaded.
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/build-cover.py
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/build-cover.py --pages 420 # what-if only
The rule the whole design hangs off
The cover is built last, and from the interior — never from a number.
Spine width is page count times caliper. A cover built before the interior was
finished, or carried over from a previous edition, has a spine that does not match
the book. At best the spine type sits off-centre; at worst the title wraps onto
the front face.
Nothing catches this on screen. Not a PDF viewer, not KDP's uploader. The proof
copy catches it, three weeks and one print charge later.
So build-cover.py will not take a page count. It runs pdfinfo over the
interior that was actually built. --pages exists only to answer "what would a
different extent cost", and refuses to write the file.
That is one of two independent checks. kdp-package.py then measures the
finished wrap, subtracts both faces and both bleeds, and compares what is left
against the spine this page count needs — the same fact reached from the opposite
direction. A stale cover has to defeat both.
Three layout rules that are not style preferences
Each of these is a proof copy someone lost. They are repeated at the top of
templates/cover.typ; read them before editing it.
1. Nothing on the front panel is anchored up from the bottom edge.
The whole panel is one fixed-height box with v(1fr) spacers in it, so leftover
space is distributed rather than assumed. Anchoring a block to the foot makes its
position a guess about how tall everything above it turned out — and that guess is
wrong the moment the title or subtitle wraps to another line.
With 1fr the collision is not tuned away, it cannot happen: a longer subtitle
squeezes the gaps instead of overprinting the byline.
2. Neither bottom corner of the back panel carries type.
KDP places the retailer barcode in one corner and other print channels use the
other, so neither is safe whichever channel the wrap is built for. Put back-cover
furniture at the head of the panel instead.
3. A literal /* opens a Typst block comment and eats the rest of the file.
The document still compiles — just shorter. If a cover rebuild loses its back
half for no apparent reason, this is why. Write any URL containing one as a
string concatenation.
Spine text
KDP prints no spine text at 79 pages or under; build-cover.py passes
spine_text=false and the template omits it. Above that, cap type to the band
left after 0.0625in clearance each side — the press trims with variance toward
either face.
Cover art
The wrap itself stays typeset. Folds, spine and safe zones are geometry, and an
image stretched across the whole wrap loses them.
To use raster art — AI-generated or otherwise — place it inside the front panel:
#place(top + left, dx: front-x, dy: bleed)[
#image("../assets/art/front.png", width: trim-w + bleed, height: wrap-h)
]
Supply it at 300 dpi at final size. kdp_geometry.py prints the wrap and
front-panel pixel dimensions at 300 dpi for exactly this.
The plugin does not generate cover art and does not call an image API. Source or
generate the image however you like, drop it in assets/art/, and place it.
Before upload
- Convert to CMYK. KDP asks for CMYK covers and strips embedded profiles.
Convert a copy, never the source.
- Confirm the print options selected in the KDP form match the file — a different
paper or trim there means a different spine.
When the geometry is wrong
build-cover.py measures the rendered wrap and fails if it does not match the
geometry it asked for. That failure means the template is overriding
page(width:) itself. Fix the template rather than the check.
