Naming & Alt Text

Every diagram in Accessible Notes has two pieces of metadata that matter a lot: its name, which is how you reference the diagram in your note, and its alt text, which describes the diagram for people who can't see it. Both are set in the Diagrams tab alongside the TikZ code editor.

Diagram names

A diagram's name is its identifier — it determines the placeholder you use to embed the diagram in your note body.

Name rules:

• Lowercase letters, numbers, and underscores only
• No spaces, hyphens, or special characters
• Must be unique within your note

Valid names: circuit_diagram, flow_chart_1, figure_3, process_overview

Invalid names: Circuit Diagram, flow-chart, figure #3

The placeholder

Once you've named a diagram, embed it in your note by placing its placeholder at the desired location in the editor:

{{diagram:circuit_diagram}}

You can copy this placeholder from the panel below the code editor — no need to type it manually.

Renaming a diagram

You can rename a diagram at any time. When you do, Accessible Notes automatically updates every {{diagram:old_name}} placeholder in your note body to use the new name. You won't need to hunt through your note to fix references.

Alt text

Alt text is a written description of your diagram for people who use screen readers or other assistive technology. It is required for accessibility — every diagram should have meaningful alt text before you export.

What makes good alt text

Good alt text communicates what the diagram shows and why it matters. Think about what a sighted person gets from looking at the diagram, and convey that in words.

Good alt text:

• "A flowchart showing the three-step order processing pipeline: customer submits order, warehouse picks items, shipping dispatches package. Steps are connected by arrows showing the sequence."
• "A circuit diagram with a 9V battery connected in series with a 100-ohm resistor and an LED."

Poor alt text:

• "diagram"
• "figure 1"
• "see above"

If a diagram is purely decorative and conveys no information, you can leave a note to that effect, but most diagrams in technical documents are informational and deserve a real description.

Where alt text appears

Your alt text travels with the diagram into every export format:

• PDF — embedded in the document's accessibility tags, readable by screen readers
• Word (DOCX) — set as the image's alt text property
• HTML — becomes the aria-label on the SVG element
• Markdown — written into the <figure> element wrapping the embedded SVG

This means you only have to write the alt text once, and every format your readers receive will include it.