K2Fv0.3Gallery
Playground

Images

An image is a node with content.type: "image" and role: "image". The engine does not read width or height from the file — you declare them in content.value as millipt (1 pt = 1000).

Copy ex_image.json into content/root.json children (keep id: "root" on the document; the catalog file is a small section, not a full root). Put the bytes at value.src under assets/images/ before k2f pack.

Asset files

RuleDetail
PathPackage-relative under assets/images/ only (not the assets/ root)
srcField name is src, not path; not an http:// URL
FormatsPNG, JPEG, WebP, SVG — not GIF
SVG textRasterized without system fonts. <text>, <tspan>, <textPath>, and <foreignObject> fail at pack — use <path> or a sibling K2F text node

Node shape

  • content.value.src, width, and height are required
  • width / height are the declared paint size (millipt), not CSS pixels
  • role is usually image; starter theme already defines that role

Fit and alignment

In a vertical stack, default align_items is stretch: the image box spans the content width; the bitmap is painted inside it.

  • Contain (default): letterbox, centered — role image_fit omitted or contain
  • Cover: center-crop into the box — node variant: "cover" on role image in the starter theme
  • Left / right: set self_align to start or end on the role in styles/theme.json, not on the node

Do not put image_fit or self_align on the image node. See Theme and fonts.

See also (catalog)

NeedFile
Fixed-width figure + flowing copyex_media_row.json (grid)
Title + logo / trailing imageex_split_bar.json
Full-bleed background imageex_overlay.json (layout)

Allowed keys

Allowed keys (image row) and nodes.schema.json.

Common mistakes

  • Omitting the file under assets/images/ before pack
  • Using CSS px or raw pixel numbers instead of millipt
  • Putting declared width / height on layout instead of content.value
  • Putting image_fit or self_align on the node instead of the theme role
  • GIF assets or external URLs in src
  • SVG that still contains live text tags

Catalog sources

ex_image.json
{
  "id": "ex.image",
  "role": "section",
  "content": {
    "type": "container",
    "value": {
      "children": [
        {
          "id": "ex.image.pic",
          "role": "image",
          "content": {
            "type": "image",
            "value": {
              "src": "assets/images/dot.png",
              "width": 24000,
              "height": 24000
            }
          }
        },
        {
          "id": "ex.image.caption",
          "role": "body",
          "content": {
            "type": "text",
            "value": "PNG under assets/images/ with declared millipt size."
          }
        }
      ]
    }
  },
  "layout": {
    "type": "stack",
    "direction": "vertical",
    "gap": 8000,
    "align_items": "start"
  }
}