template-studio/docs/template-pack.md

AI Template Pack ZIP format

Template Studio accepts authenticated ZIP uploads containing a manifest and raster assets.

Layout

my-pack.zip
├── template-pack.json
└── assets/
    ├── hero.webp
    ├── paper-bg.webp
    └── page-border.png

Manifest

{
  "format": "template-studio-pack",
  "version": 1,
  "template": {
    "name": "AI generated customer report",
    "type": "report",
    "document": {
      "theme": {
        "backgroundColor": "#f6f1e8",
        "surfaceColor": "#ffffff",
        "textColor": "#172033",
        "mutedColor": "#64748b",
        "accentColor": "#8b5e34",
        "borderColor": "#d8c7b3",
        "borderRadius": 14,
        "pageMarginTop": 12,
        "pageMarginRight": 12,
        "pageMarginBottom": 12,
        "pageMarginLeft": 12,
        "pagePadding": 18,
        "reportDensity": "auto",
        "pageBackgroundImage": "asset://paper-bg",
        "pageBackgroundMode": "none",
        "pageBackgroundOpacity": 0.08,
        "decorativeBorder": false,
        "borderImage": "asset://page-border"
      },
      "blocks": [
        {
          "id": "hero-heading",
          "type": "heading",
          "props": {
            "text": "Report for {{customer.name}}"
          },
          "style": {
            "backgroundColor": "#fffaf2",
            "borderColor": "#d8c7b3",
            "borderWidth": 1,
            "borderRadius": 12,
            "padding": 18
          }
        },
        {
          "id": "hero-image",
          "type": "image",
          "props": {
            "url": "asset://hero",
            "alt": "Report hero"
          }
        }
      ]
    },
    "sampleData": {
      "customer": {
        "name": "Example Customer"
      }
    }
  },
  "assets": [
    {
      "key": "hero",
      "file": "assets/hero.webp"
    },
    {
      "key": "paper-bg",
      "file": "assets/paper-bg.webp"
    },
    {
      "key": "page-border",
      "file": "assets/page-border.png"
    }
  ]
}

Use asset://KEY anywhere in the document or sample data. Import replaces it with an opaque Template Studio media URL.

Image layout

Image blocks support explicit report layout controls:

{
  "id": "brand-logo",
  "type": "image",
  "props": {
    "url": "asset://logo",
    "alt": "Company logo",
    "variant": "logo",
    "maxWidth": 110,
    "maxHeight": 72,
    "fit": "contain"
  }
}

Use variant: "logo" for compact brand marks and variant: "hero" for banners/feature imagery. Hero images default to a 260px maximum height with cover; normal images default to 340px with contain. The renderer also recognises IDs/alt text containing logo, mark, hero, or banner for older packs that do not specify a variant.

For report pagination, blocks avoid splitting across pages by default. Optional block style flags are keepWithNext, pageBreakBefore, pageBreakAfter, and allowPageBreak.

Page setup

Report themes can set A4 print margins independently in millimetres with pageMarginTop, pageMarginRight, pageMarginBottom, and pageMarginLeft. Each accepts 0–40 mm and defaults to 12 mm.

pagePadding is separate: it controls the internal spacing inside the rendered document/frame in pixels and defaults to 18 px.

Report density

Set reportDensity to "auto", "comfortable", or "compact". Auto is the default. Reports with at least 20 blocks or 4 table blocks automatically use compact density.

Compact density:

• groups consecutive KPI blocks into a three-column grid;
• tightens heading, block, KPI and table spacing;
• treats normal pageBreakBefore hints as soft so sections can flow into unused page space;
• still honours forcePageBreak: true;
• keeps headings with the following content where possible.

For long tables set style.allowPageBreak: true. The renderer then permits rows to continue onto the next page and repeats the table header. Use style.compact: true to request tight table spacing even in comfortable mode.

Page artwork

Reports default to a clean page even if the ZIP includes background or border assets. Set pageBackgroundMode to "watermark" or "full" to opt in to the background image. pageBackgroundOpacity controls artwork strength from 0 to 0.35.

Decorative border artwork is also opt-in with decorativeBorder: true. This prevents stationery-style page chrome from appearing automatically on operational reports.

Styling

The constrained theme supports colors, border radius, background imagery and report border imagery. Blocks may also include a style object with background/text/border colors, border width/radius, padding and alignment. Arbitrary CSS/HTML/JavaScript is intentionally not supported.

Limits

• ZIP upload: 20 MB compressed
• 100 files maximum
• 50 MB maximum expanded size
• 10 MB per image
• PNG, JPEG, WebP and GIF only
• template-pack.json must be at ZIP root

Reusable Theme Packs

Themes are independent from template content. Applying or removing a theme replaces only document.theme; blocks, bindings and sample data are unchanged.

A ZIP theme pack uses:

my-theme.zip
├── theme-pack.json
└── assets/
    ├── background.webp
    └── border.png

Minimal theme-pack.json:

{
  "format": "template-studio-theme",
  "version": 1,
  "name": "Clean Operations",
  "appliesTo": "report",
  "theme": {
    "backgroundColor": "#eef3f7",
    "surfaceColor": "#ffffff",
    "textColor": "#172b3a",
    "mutedColor": "#607282",
    "accentColor": "#123b5d",
    "borderColor": "#d8e1e8",
    "borderRadius": 8,
    "fontFamily": "Arial",
    "reportDensity": "auto",
    "pageMarginTop": 9,
    "pageMarginRight": 9,
    "pageMarginBottom": 9,
    "pageMarginLeft": 9,
    "pagePadding": 14,
    "pageBackgroundMode": "none",
    "pageBackgroundImage": "asset://background",
    "decorativeBorder": false,
    "borderImage": "asset://border"
  },
  "assets": [
    { "key": "background", "file": "assets/background.webp" },
    { "key": "border", "file": "assets/border.png" }
  ]
}

For themes with no image assets, the same manifest can be uploaded directly as a .json file. appliesTo may be "report", "email", or "all".

Theme tokens: typography, spacing and color

Reusable themes may also define these constrained tokens:

• Typography: fontFamily, baseFontSize, headingSize, lineHeight
• Spacing: blockGap, cardPadding, tableCellPadding, pagePadding
• Shape: borderRadius
• Palette: backgroundColor, surfaceColor, textColor, mutedColor, accentColor, buttonTextColor, borderColor

These tokens are editable from Preview and remain part of the draft/published theme.

Production email output

Email documents may define:

{
  "email": {
    "subject": "Welcome {{customer.name}}",
    "preheader": "Your account is ready"
  },
  "blocks": []
}

The email render API returns a provider-neutral payload:

{
  "subject": "Welcome Kauri",
  "preheader": "Your account is ready",
  "html": "<!doctype html>...",
  "text": "Welcome Kauri...",
  "warnings": [],
  "metadata": {
    "key": "customer-welcome",
    "version": 3,
    "html_bytes": 18420
  }
}

This payload is suitable for transport providers such as SendGrid, Amazon SES, Postmark and Mailgun. Template Studio remains the canonical template renderer; providers only deliver the rendered subject/HTML/plain-text parts.

Email-safe blocks

The email renderer supports heading, text, KPI, button, image, divider, spacer and table blocks. Tables are emitted through MJML's table component rather than browser CSS grid/flex layouts.

Plain text is generated automatically from the same blocks, including table rows and button URLs.

Compatibility checks

Each email render includes warnings for common risks including:

• missing subject or preheader;
• missing image alt text;
• insecure HTTP image URLs;
• image-only email content;
• tables wider than six columns;
• decorative background image dependence;
• compiled HTML approaching common clipping limits.

The editor exposes Mobile, Desktop, Plain text and Checks preview tabs. These checks are advisory and complement, rather than replace, real-client screenshot testing.