Designer documentation

Overview

Each designer SVG targets a specific combination of asset pack, page template, and paper size. When an AssetTemplate exists for the user's theme plus a page's template key and paper size, your artwork replaces the built-in code layout for that page.

Use bracket tokens for dynamic text, localized labels, and theme colors. The importer validates placeholders, strips unsafe markup, and registers packs from disk.

1. Canvas size

Author at the exact paper size in millimetres. Set the SVG width and height in mm (or a viewBox matching those dimensions).

2. Bracket tokens

Put tokens in <text>/<tspan> content or attribute values (fill, stroke, style). At render time each [token] is replaced. Unknown tokens are removed.

Dynamic & project fields

Localized text

These resolve using the planner language (Project.locale), not the site language.

Theme recoloring & fonts

Reference the active theme palette so artwork recolors when users switch themes:

• [color.primary], [color.accent], [color.background], [color.surface]
• [color.text], [color.muted], [color.line]
• [font.heading], [font.body] — theme font stacks

<rect fill="[color.primary]" .../>
<text style="fill:[color.text];font-family:[font.heading]">[title]</text>

For custom designer fonts, declare them in pack.json and reference the family name in your SVG.

3. Text styles

The importer scans <text> and <tspan> for font-family, font-size, font-weight, and fill. These are stored as metadata for font embedding and future editor controls.

4. Pack layout

Packs live under storage/assets/ (override with ASSETS_DIR). One folder per asset pack, named by slug (matching Asset.slug in the database).

storage/assets/
  winter/
    pack.json
    cover.A4.svg
    cover.A5.svg
    fonts/
      MyDisplay.woff2

SVG files are named <templateKey>.<paperSize>.svg — for example cover.A4.svg or month-calendar.A5.svg.

pack.json

Optional font declarations for @font-face embedding:

{
  "slug": "winter",
  "fonts": [
    {
      "family": "My Display",
      "weight": 700,
      "style": "normal",
      "file": "MyDisplay.woff2"
    }
  ]
}

5. Import & deploy

Run the importer to validate and register packs on the server:

• Strips <script>, event handlers, and javascript: URLs
• Extracts placeholders and text styles
• Upserts AssetTemplate rows per (asset, templateKey, paperSize)
• Serves fonts at /api/assets/<slug>/fonts/<file>

npm run assets:import

Available [label.*] tokens

Use these keys after label. in your SVG (e.g. [label.notes]).

Page template keys

Use these as the first segment of each SVG filename.