Document kits
Paper, dark mode, header, footers, logos and page templates for the brand's documents in Polyther and Nitti, edited as a draft and published.
A document kit is everything a brand curates for its documents: the paper, the dark-mode policy, the margins, a header, a set of footers to choose from, the logos a document may use, and the cover, contents, divider and back pages. Polyther Docs and Nitti notes render kits through the document theme (profile=document).
A brand can have several kits ("Reports", "Quotes"), and one of them is the default.
Why a kit, and not the brand's colours
Without a kit, the document paper is the brand's light ad panel colour, and the document dark mode is its dark ad panel. That is why Reform Society's documents were beige, and why almost every brand had a dark document mode it never designed. A kit gives the document its own paper, so a white document does not change the ads or the website, and dark mode becomes a decision.
The Documents page
In the app, kits live under Documents (under Build in the brand sidebar,
/brands/{id}/documents). The page lists the draft's kits (new, duplicate,
rename, delete, make default) and edits one at a time: the base theme, paper,
ink and colour roles with their live contrast, dark mode, margins, the
header, footers, the logo library and placements, and a page template per
cover purpose plus contents, divider and back. A page's logo has a size
(presets or an exact height in millimetres) and, for top and bottom
placements, Flush with the page edge.
The Parts section styles the body of a document part by part (the title, each heading level, the quote, the table and so on; see Parts). Each property shows the system's look as its placeholder and has a Reset; a part with values has Reset part.
Beside the editor is a live A4 preview of a sample document: the cover
(switch the purpose), contents, body pages with every block a document can
hold (the title and lead, headings at every level, bold, italic and links,
lists and a check list, a quote, code, a table, a divider, an image with its
caption and source, key figures, a chart, a citation and a file) under the
running header and footer, a section divider and the back page. The body is set
in the design system's document style, so it looks as a shared document does. It is drawn with @nitti-ai/doc-theme, the same renderer
Polyther and Nitti use, from the theme braaand's export would build for the
draft kit, so what you see is what publishing puts in documents. The Dark
toggle is available only when the kit follows the viewer.
Edits save to the draft as you go. A banner says when the draft differs from what documents use; Publish first lists what changes in live documents, kit by kit, and errors land on the fields they name. Contrast notes are listed there too, but never stop you: Publish anyway stays available. In the editor each failing pair sits under the colour role that fixes it (a role inside the collapsed "Colour roles" opens it), with a one-click Use #xxxxxx that sets the nearest shade of the same hue that passes. The kit list counts them as "contrast notes". Discard goes back to the published kits.
Draft, then publish
Editing a kit never changes a live document. Kits are edited as a draft,
stored apart from the brand: saving a draft does not bump the brand version
and reaches no document. Publishing validates the draft, makes it the
brand's live kits, bumps the brand version and sends brand.changed, so
documents pick it up the next time they open. Discard drops the draft.
| REST | MCP | CLI | |
|---|---|---|---|
| Published kits | GET /api/brands/{id}/documents |
get_document_kits |
braaand documents kits <id> |
| Read the draft | GET /api/brands/{id}/documents/draft |
get_document_kit_draft |
braaand documents draft <id> |
| Replace the draft | PUT /api/brands/{id}/documents/draft |
update_document_kit_draft |
braaand documents set-draft <id> --file kits.json |
| Publish | POST /api/brands/{id}/documents/publish |
publish_document_kits |
braaand documents publish <id> |
| Discard the draft | DELETE /api/brands/{id}/documents/draft |
discard_document_kit_draft |
braaand documents discard <id> |
| Draft a kit from the brand | POST /api/brands/{id}/documents/draft/kits |
draft_document_kit |
braaand documents draft-kit <id> --name Reports --purposes report,quote |
Reading the published kits needs read access to the brand, and accepts the brand-supply OAuth grant that Polyther and Nitti use. Everything about the draft, and publishing, needs editor access.
Drafting a kit from the brand adds a complete kit to the draft (started
from the published kits when there is none): white paper (or paper), the
theme's type and colours with neutral rule, table-header and callout fills
when the theme was tinted for another paper, light-only, the logo system's
marks placed by form (the wordmark on the cover and in the header, the emblem
in the footer), a header, two footers, a cover per purpose (purposes,
default report and generic) and contents, divider and back pages. Its body is
{ name?, id?, purposes?, theme?, paper?, description?, parts?, makeDefault? };
parts starts the kit with per-part styling. A
taken id gets a suffix, so no kit is overwritten, and it never publishes: an
agent drafts, refines with update_document_kit_draft, and asks before
publishing.
A draft is { kits, defaultKit }. Saving checks only its shape (unknown
keys and wrong types are refused, field by field), so a half-made kit saves.
Publishing a draft with no kits removes the published kits.
What a kit holds
{
"id": "reports",
"name": "Reports",
"theme": "default",
"paper": { "light": "#ffffff" },
"darkMode": "light-only",
"margins": { "top": 22, "right": 20, "bottom": 22, "left": 20 },
"header": { "left": "logo", "right": "title" },
"footers": [
{ "id": "standard", "name": "Standard", "left": "confidentiality", "right": "pageNumber" },
{ "id": "contact", "name": "With contact", "left": "contact", "centre": { "text": "reformsociety.se" }, "right": "pageNumber" }
],
"defaultFooter": "standard",
"logos": { "library": ["asset_wordmark", "asset_emblem"], "cover": "asset_wordmark", "header": "asset_wordmark", "footer": "asset_emblem" },
"pages": {
"covers": {
"report": {
"preset": "left",
"slots": [{ "slot": "purposeLabel", "role": "label" }, { "slot": "title", "role": "display" }, { "slot": "date", "role": "small" }],
"background": { "colorRole": "paper" },
"logo": { "placement": "top-left", "heightMm": 28, "flush": true }
}
}
}
}themeis the base for type and colour:default(the brand itself) or one of its themes (list_themes,braaand themes list).paperis the document paper,#rrggbb.inkoptionally overrides the theme's text colour.lightoptionally overrides any other light colour role of the theme, for documents only:inkMuted,rule,accent,accentInk,link,highlight,tableHeader,tableHeaderInk,quoteandcalloutBg. A theme tinted for its ads (Reform Society's beige) keeps tinted rules and fills on a white paper unless the kit sets them, for example"light": { "rule": "#e3e3e3", "tableHeader": "#f2f2f2", "calloutBg": "#f6f6f6" }.darktakes the same roles for a follow-viewer kit.darkModeislight-only(the default: the document is light paper everywhere, inside a dark app too) orfollow-viewer(the paper follows the viewer's app). See below.headerand each footer haveleft,centreandrightslots. A slot showslogo,pageNumber,title,date,confidentiality,contact, or a fixed line of text,{ "text": "…" }. A document picks one of its kit's footers;defaultFooteris the one it starts with.logos.librarylists the brand's marks a document may use (ids from the logo system).cover,headerandfootersay which goes where; a document may swap a logo only for another mark in the library.pagesare declarative templates, not HTML:coversper purpose (report,quote,brief,proposal,generic), pluscontents,dividerandback. A template is a preset (centered,left,fullBleedImage,minimal), named slots (title,subtitle,purposeLabel,clientName,clientLogo,date,author,version,coverImage,brandLogo,confidentiality), each text slot with a typography role and optional colour role, a background (a document colour role, or one of the brand's images by asset id) and a logo placement.A page's
logohas aplacement(top-left,top-center,top-right,center,bottom-left,bottom-center,bottom-rightornone), an optionallogoIdfrom the library (the kit's cover logo otherwise), and two optional fields:heightMm(6 to 80, default 12) sizes the logo: it is fitted into a box that many millimetres high andmax(60, heightMm × 4)mm wide, keeping its shape. A tall or vertical mark, like WWF's panda, needs more than the default. The editor offers Small 10, Medium 16, Large 28 and X-large 44 mm, or an exact value.flush: trueputs atop-*logo against the page's top edge and abottom-*logo against the bottom edge instead of inside the margin, for a logo that hangs from the edge like a flag. The side margins still apply, andcenterandnoneignore it.
Both are left out of the document theme when the kit does not set them.
termslists the ids of the quote terms a quote made with this kit may use (standard terms,blk_…).partsstyles the document's body part by part. See below.
Parts
parts lets a brand style any part of a document, in the editor or by an
agent. The parts and their properties are the design system's document parts
(documentParts in @nitti-ai/design-system/lib/document-parts), the same
list @nitti-ai/doc-theme reads. A part or property left out keeps the
system's look.
"parts": {
"title": { "font": "display", "weight": 700, "case": "uppercase", "color": "accent" },
"h2": { "size": 1.5, "space": 2.4 },
"quote": { "fill": "none", "rule": 3, "ruleColor": "accent", "style": "italic" },
"table": { "headFill": "tableHeader", "headColor": "tableHeaderInk", "rule": 1 },
"divider": { "points": "none", "rule": 1 }
}| Part | Properties |
|---|---|
title (the document's name) |
font, size, weight, case, tracking, color |
lead (the paragraph under the title) |
size, color |
h2, h3, h4 (h4 covers h5 and h6) |
font, size, weight, case, tracking, color, space |
body |
font, color |
strong |
weight |
link |
color, line |
list |
marker (bullet and number colour), check (a ticked box's fill) |
quote |
fill, color, font, size, style, rule, ruleColor |
code |
font, fill |
table |
headFill, headColor, headWeight, stripe, rule |
divider |
points, rule, color |
figure (a chart's or key figures' frame) |
fill, radius, titleFont, titleWeight |
caption |
color, size |
stat (a key figure's number) |
font, weight, color |
citation (the source pill) |
fill, color |
file |
fill |
image |
radius |
Values are names or bounded numbers, never CSS:
| Kind | Value |
|---|---|
| font | display, heading, body or mono (the kit's font roles) |
| weight | a whole number from 400 to 800 |
| case | none, uppercase, lowercase or capitalize |
| color | a document colour role: ink, inkMuted, link, accent, accentInk, rule, highlight, tableHeader, tableHeaderInk, quote, calloutBg or paper |
| fill | a colour role, or none |
| size | 0.6 to 3, in em of the body size |
| space | 0 to 4, the space above in em |
| tracking | -0.1 to 0.3, letter-spacing in em |
| radius | 0 to 3, in em |
| style | normal or italic |
| line | underline or none |
| rule | 0 to 4, a line's thickness in px (0 is no line) |
| points | points (the divider's three points) or none |
A misspelt part or property, or a value out of range, is refused when the
draft is saved. A text colour is measured on what it sits on: the paper, or the
part's own fill for the quote's color, the table's headColor and the
citation's color. One that misses AA is drawn in ink by Polyther and Nitti,
and publishing warns about it (see below). Heading case still follows the
theme's heading style wherever case is left out.
Dark mode
A kit is light-only unless it says otherwise, and a light-only kit's document theme carries no dark colours at all. The brand's dark ad panel is not a document palette.
To give documents a dark mode, set darkMode: "follow-viewer" and supply all
of it:
paper.darkandink.dark;dark.accent,dark.linkanddark.chart.series(the other dark roles are derived from these unless you set them);- an on-dark logo for every placement, in
logos.onDark.
What publishing checks
Publishing refuses a draft with any of these, and answers 422 with the field
at fault and why, for example
{ "path": "kits.0.paper.light", "message": "\"white\" is not a #rrggbb colour" }:
- Colours: a value that is not
#rrggbb. - Dark mode:
follow-viewerwithout the dark paper, ink, accent, link, chart series or an on-dark logo for each placement. - Logos: a library id that is not in the brand's logo system, or a placement that is not in the library.
- Theme: an id that is neither
defaultnor one of the brand's themes. - Footers and pages: no footer, repeated ids, a
defaultFooterthat is not one of them, a text slot with angle brackets or control characters, a slot used twice on a page, a text role on an image slot, a background asset that is not an image of the brand's, afullBleedImagepage with no image. defaultKitthat is not one of the kits.
Contrast informs, it never blocks
Contrast (WCAG AA) is measured on every publish but never refuses one. Each
failing pair comes back in warnings, beside a successful publish
({ documents, version, warnings }) and beside a 422's errors alike, in the
same { path, message } shape. The pairs:
- on the light paper: the ink and the link at 4.5:1, the accent at 3:1, and
text on the accent at 4.5:1; the same for the dark palette with
follow-viewer; - for a colour-role override, every pair it takes part in: muted text on the paper, table-header text on its fill, and ink on the callout, quote and highlight fills, each at 4.5:1. The theme's own fills are shown as hints in the editor but are not reported against a kit that leaves them alone;
- for
parts, every colour role a part uses for text, at 4.5:1 on the paper or on the part's own fill. The path is the part's property, for examplekits.0.parts.title.color, and the message names the roles that do pass there. Readers see a failing one in ink.
A warning's path is the role that fixes it, not the paper: the accent on
the paper points at light.accent (or dark.accent) even when the kit does
not override the accent yet, the link at light.link, text on the accent at
light.accentInk, ink at ink.light, and ink on a fill at that fill. The
message says what readers will see, and names the nearest shade of the same
hue that passes, for example:
{ "path": "kits.0.light.accent", "message": "The accent on the light paper (#1fc34d on #ffffff) reads 2.34:1; WCAG AA asks 3:1. It is drawn as chosen; decorative rules and highlights may be hard to see. #00ab3e passes (3.04:1)." }
What readers see when a pair fails:
- Ink, link, text on the accent, table-header text: Polyther and Nitti replace the failing colour with a readable one (their system colour, the ink, the paper, black or white).
- The quote fill: mixed toward the paper until the ink reads on it.
- The accent, muted text, the callout and highlight fills: drawn as chosen. A pale accent's rules and highlights may be hard to see.
In the document theme
GET /api/brands/{id}/design-system?profile=document&kit=<id> builds
document-theme.json from a published kit; without kit it uses the default
kit. The kit's theme becomes the export's theme unless you ask for another.
Then:
colors.light.paperis the kit's paper, and the blockquote fill and the chart background follow it. The kit'slightroles replace the theme's; the chart's grid, axis and accent follow an overridden rule, muted ink and accent. The ads, the UI kit and the website are not touched.colors.darkandchart.darkare present only for afollow-viewerkit, and come from the kit.pagetakes the kit's margins, and its header and default footer.- New fields:
kit { id, name },darkMode,header,footersanddefaultFooter,logos.library(each mark with its URL, SHA-256, size, tone and default placements),pages, andterms: the kit's quote terms that are published, as{ id, name }only. Their text is never in the theme; a document resolves it per client. parts, when the kit sets any: the kit's parts as they are, each value checked against its bounds. Each property becomes one CSS variable,--doc-<part>-<prop>(quote.ruleColoris--doc-quote-rule-color), that the design system's document style reads in the read view and the editor.
A brand with no published kit exports exactly the same document theme as before kits existed.