Agents

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 }
      }
    }
  }
}
  • theme is the base for type and colour: default (the brand itself) or one of its themes (list_themes, braaand themes list).

  • paper is the document paper, #rrggbb. ink optionally overrides the theme's text colour.

  • light optionally overrides any other light colour role of the theme, for documents only: inkMuted, rule, accent, accentInk, link, highlight, tableHeader, tableHeaderInk, quote and calloutBg. 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" }. dark takes the same roles for a follow-viewer kit.

  • darkMode is light-only (the default: the document is light paper everywhere, inside a dark app too) or follow-viewer (the paper follows the viewer's app). See below.

  • header and each footer have left, centre and right slots. A slot shows logo, pageNumber, title, date, confidentiality, contact, or a fixed line of text, { "text": "…" }. A document picks one of its kit's footers; defaultFooter is the one it starts with.

  • logos.library lists the brand's marks a document may use (ids from the logo system). cover, header and footer say which goes where; a document may swap a logo only for another mark in the library.

  • pages are declarative templates, not HTML: covers per purpose (report, quote, brief, proposal, generic), plus contents, divider and back. 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 logo has a placement (top-left, top-center, top-right, center, bottom-left, bottom-center, bottom-right or none), an optional logoId from 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 and max(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: true puts a top-* logo against the page's top edge and a bottom-* 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, and center and none ignore it.

    Both are left out of the document theme when the kit does not set them.

  • terms lists the ids of the quote terms a quote made with this kit may use (standard terms, blk_…).

  • parts styles 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.dark and ink.dark;
  • dark.accent, dark.link and dark.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-viewer without 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 default nor one of the brand's themes.
  • Footers and pages: no footer, repeated ids, a defaultFooter that 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, a fullBleedImage page with no image.
  • defaultKit that 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 example kits.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.paper is the kit's paper, and the blockquote fill and the chart background follow it. The kit's light roles 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.dark and chart.dark are present only for a follow-viewer kit, and come from the kit.
  • page takes the kit's margins, and its header and default footer.
  • New fields: kit { id, name }, darkMode, header, footers and defaultFooter, logos.library (each mark with its URL, SHA-256, size, tone and default placements), pages, and terms: 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.ruleColor is --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.