---
title: "Metadata and alt text"
description: "What each asset should carry, why alt text is not optional, and how metadata affects automatic placement."
updated: "2026-08-18"
verifiedAgainst:
  - packages/shared/src/assets.ts
---

An asset with no description is an asset a drafting run cannot choose correctly.

## What to fill in

<PropertyList>
  <Property name="Alt text">
    What the image shows, for a reader who cannot see it. It is also what a
    search engine reads. Describe the content, not the file.
  </Property>
  <Property name="Kind">
    Product screenshot, brand visual, diagram, logo, or other. This is the
    strongest signal for automatic selection.
  </Property>
  <Property name="Description">
    What is happening in the image and where it belongs. This is what makes the
    difference between an image placed in the right section and one placed in the
    first section.
  </Property>
  <Property name="Credit">
    Attribution, where the source requires it.
  </Property>
</PropertyList>

## Alt text and publication

Alt text travels with the image into published articles. A post published with
images that have no alt text is a post that is harder to read for some of your
audience and thinner to a crawler.

## Logos

A logo is a special case: it is the one asset where being approximately right is
worse than being absent. Blogged holds the exact logo rather than regenerating
something similar, so brand marks stay correct wherever they appear.