Emit an accessible Figure with a Caption over Connect

Emit an accessible Figure with a Caption over Connect

At a glance

Send an HTML <figure> with an <img> and a <figcaption> over the Connect transports. The pipeline emits a standard Figure structure element, nests the caption as a Caption child, and uses the alt attribute to populate /Alt. Verify the result with the Pro-tier accessibility tool. NextPDF discovers that tool through class_exists() and registers it only when nextpdf/premium is installed alongside the server. Core tools handle document creation and HTML ingestion.

A passing accessibility-tool result is an accessibility check, not an independent conformance certification.

Install

composer require nextpdf/server

Confirm that the Pro accessibility tool is present with a tools/list call. See /connect/tool-catalog/.

Conceptual overview

An alternate description provides text for non-text content, such as a figure (ISO 32000-2 §14.8). The structure element stores that description in its /Alt entry (ISO 32000-2 §14.8). The HTML alt attribute populates /Alt on the emitted Figure. The pipeline emits the <figcaption> as a nested Caption child, rather than as a sibling paragraph, so the caption stays reachable as part of the figure (PDF/UA-2 §8.2.4).

API surface

Verify tool names against the running registry with tools/list. The catalog of record is /connect/tool-catalog/. This recipe uses the core document and HTML tools, plus the Pro accessibility check. It does not restate a tool count.

Code sample — Quick start

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "Architecture Reference", "language": "en" }
  }
}

Code sample — Production

Add the figure markup. The alt is required for the figure to be accessible:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<figure><img src=\"diagrams/architecture.png\" alt=\"Three-tier deployment: web frontend, REST API, datastore\" /><figcaption>Figure 1 — Deployment topology.</figcaption></figure>"
    }
  }
}

Run the accessibility check, then inspect the reported structure tree. It shows a single Figure with /Alt and exactly one Caption child.

Edge cases & gotchas

• <img> with no alt. The check reports a figure-alternate-text failure. Provide a descriptive alt, or mark a purely decorative image as an artifact (see /cookbook/connect/page-artifacts/).
• Empty <figcaption>. The pipeline warns. Provide caption text or remove the element.
• <figcaption> outside any <figure>. The pipeline emits it as an orphan caption. Wrap it in a <figure>.
• Tool absent. Without nextpdf/premium, the Pro accessibility tool is not registered, and verification fails with an unknown-tool error.

Performance

The front-matter budget is a documentation cap. Figure handling runs as part of the normal layout pass.

Security notes

No extra guidance applies beyond the general Connect transport guidance.

Conformance

PDF/UA-2 mapping

Claim	Clause	reference_id
Alternate description for non-text content	ISO 32000-2 §14.8
Alternate description held in /Alt	ISO 32000-2 §14.8
Caption reachable through the structure tree	PDF/UA-2 §8.2.4

Tag → ISO 32000-2 §14.9 cross-ref

Figure and Caption are standard structure types. Nesting the <figcaption> as Caption defines the accessible-figure contract.

WCAG 2.2 mapping

A figure with alt text and an associated caption supports Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.1.1 (Non-text Content) and SC 1.3.1 (Info and Relationships) at the content level.

A passing accessibility-tool result is an accessibility check, not a conformance certification. An independent checker makes that determination.

Commercial context

The accessibility check tool is Pro-tier and registers only when nextpdf/premium is installed alongside the server.

Connect specifics

Transport availability (MCP / REST / gRPC)

Invoke create_pdf, add_html, and the accessibility check the same way over Model Context Protocol (MCP), REST, and gRPC through the shared tool executor.

HITL risk tier

Document creation and HTML ingestion are caution-level. The accessibility check is read-only. None of them is approval_required by default. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

These tools do not trigger the gate unless an operator override raises one to approval_required. The envelope and single-use token contract are in /connect/hitl-risk-tiers/.

See also

• /cookbook/connect/aria-tagged-pdf/ — landmark role mapping.
• /cookbook/connect/aria-noteref-pattern/ — footnote reference and body roles.
• /cookbook/connect/page-artifacts/ — mark decorative images as artifacts.
• /connect/tool-catalog/ — per-tier tool set computation.