Skip to content
Beta Multi-model support (OpenAI, Gemini, and more) launching soon.
RBA RBA Skills

alt-text-writer

Standalone Web-only skill. Copy it into Claude, or drop it into your project.
Open Claude.ai

Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V.

ExperimentalNo security review

Alt Text Writer

Generate WCAG 2.2 SC 1.1.1-conformant alternative text for a single image. This is the atomic per-image task content authors, designers, and engineers hit constantly — distinct from a full-page accessibility audit. Output is ready to paste into markup, a CMS alt field, or a design spec.

Usage

/alt-text-writer <image-path|URL|description> [options]

Options:

Flag Values Default
--type auto, informative, decorative, functional, complex, text-image auto
--context Surrounding text, link label, caption, or page section (none)
--platform sitecore, optimizely, umbraco, headless (none)

Examples:

/alt-text-writer /assets/hero-banner.jpg --context "Homepage hero above the fold"
/alt-text-writer https://cdn.example.com/bar-chart.png --type complex --context "Q1 revenue by region"
/alt-text-writer "A blue 'Submit' button" --type functional
/alt-text-writer /images/decorative-swoosh.svg --type decorative
/alt-text-writer /uploads/pricing-table-screenshot.png --type text-image
/alt-text-writer /charts/funnel.png --type complex --platform sitecore

Step 1 — Classify the Image

If --type auto (default), apply the W3C decision tree from reference.md to determine the image type before writing alt text. Work through these questions in order:

  1. Does the image contain embedded text that is not present elsewhere on the page? → text-image

  2. Is the image inside a link or button, and is there no other accessible label (visible text, aria-label) on that control? → functional

  3. Does the image convey information that a sighted user would miss without it?

    • Simple photograph or graphic → informative
    • Chart, graph, map, or diagram with quantitative/relational data → complex
    • Purely decorative (visual flourish, spacer, stock photo that adds no meaning) → decorative

  4. Is the image redundant — the same meaning already in adjacent text? → decorative (use alt="")

If classification remains ambiguous after these checks, ask the user one targeted question rather than guessing. Document the chosen type in the output.

Step 2 — Write Alt Text by Type

Apply the rules in reference.md for the chosen type. Summaries:

Informative

  • Describe what the image communicates, not what it looks like.
  • Use natural language; no "Image of…" or "Photo of…" prefix.
  • Target 8–15 words; hard cap ~125 characters (screen reader truncation risk beyond this).
  • Convey the essential meaning — omit decorative detail that adds nothing.
  • Use present tense for diagrams ("A flowchart showing…"); past for photos only when tense matters.

Decorative

  • Output: alt=""
  • Do NOT omit the attribute — a missing alt causes the filename or URL to be announced.
  • Confirm that role="presentation" or aria-hidden="true" is not also needed (e.g., SVG inline).
  • If the image is inside a link, a decorative image alone is never acceptable — the link needs an accessible label.

Functional

  • Describe the action or destination, not the image's appearance.
  • Examples: alt="Search" not alt="Magnifying glass"; alt="Open main menu" not alt="Hamburger icon".
  • If adjacent visible text already labels the control, use alt="" to avoid duplication.
  • For icon-only buttons: the alt text is the button's accessible name — make it imperative and action-oriented.

Complex (Charts, Graphs, Diagrams, Maps, Infographics)

Follow the two-part pattern from reference.md:

  1. Short alt (≤125 chars): type of visual + its main takeaway.

    • Format: "[Chart/Graph/Diagram/Map] showing [key insight or subject]"
    • Example: "Bar chart showing Q1 revenue by region, with APAC leading at 42%"

  2. Long description in the page body (preferred: <figcaption> or a collapsed <details> element linked via aria-describedby). See reference.md for HTML patterns. The long description must contain:

    • Axis labels and units (for charts)
    • All data points or a summary sufficient for equivalence
    • Trend or conclusion the image is making

Note: longdesc is obsolete in HTML5 and unsupported in Safari and mobile browsers — do not use it. Use aria-describedby pointing to an on-page element instead.

Text-in-Image

  • Reproduce the exact text visible in the image.
  • Include punctuation and line breaks where semantically meaningful.
  • Flag to the author that text-in-image is a WCAG 1.4.5 (Level AA) concern — real text is always preferred. Note: logos and logotypes are exempt from 1.4.5.
  • If the same text already appears in adjacent markup, use alt="" (redundant).

Step 3 — Validate Against Common Failure Modes

Check the drafted alt text against the failure list in reference.md. At minimum verify:

  • Does NOT start with "Image of", "Photo of", "Picture of", "Graphic of"
  • Does NOT restate the filename or URL (e.g., alt="DSC_0421.jpg")
  • Does NOT duplicate adjacent visible text (caption, heading, link label)
  • Does NOT keyword-stuff for SEO
  • Is ≤125 characters for informative/functional; complex uses short+long pattern
  • Decorative alt="" is present (not missing attribute)
  • Functional alt describes the action, not the appearance

Step 4 — CMS-Specific Guidance (when --platform is set)

When a platform flag is provided, append a short implementation note after the alt text. Full patterns are in reference.md.

Sitecore XM Cloud / SXA

  • Alt text lives on the Media Library item's Alt field; rendering variants can override via a dedicated Alt Text rendering parameter. Never hard-code alt in JSS component markup — surface it as a Sitecore field so editors can update it without a code deploy.
  • For complex images, use a Rich Text or General Link field on the component for the long description; wire it to aria-describedby in the JSS template.

Optimizely CMS (Content Cloud)

  • Images managed in the Optimizely Asset Manager have an Alt Text property on ImageData; editors set it per-instance via the Properties panel in the block editor.
  • For decorative images, editors must explicitly clear the Alt field AND check "Decorative image" if that UI option is present — leaving the field empty without the flag may still render no alt attribute depending on the view template.

Umbraco

  • The built-in Image media type exposes an alternativeText property; use it in views as @Model.Image.AltText(). For complex images, add a Description property to the media type and wire it to aria-describedby.
  • Rich Text editor pasted images bypass the media library — remind authors to set alt directly in the editor's image properties dialog.

Headless / Composable (Next.js, Astro, React)

  • Pass alt text as a required prop; TypeScript: alt: string (never alt?: string for informative images — optional alt encourages omission). For decorative, use alt="".
  • Next.js <Image> requires alt; for SVG inline use aria-label + role="img" or <title> inside the SVG element.
  • For complex images, render the long description in a <details> sibling and link it: aria-describedby="chart-123-desc".

Step 5 — Output Format

Return the following block for every image processed:

## Alt Text — [image filename or identifier]

**Type:** [informative | decorative | functional | complex | text-image]
**WCAG SC:** 1.1.1 (Non-text Content, Level A)[, 1.4.5 (Images of Text, Level AA) if text-image]

**Alt text:**
[Ready-to-paste alt text, or `alt=""` for decorative]

**For complex images — long description:**
[Long description text, or "N/A"]

**Rationale:**
[1–2 sentences explaining why this alt text was chosen for this type]

**Flags / Warnings:**
[Any issues: text-in-image, missing context, ambiguous type, CMS field notes, character count warning]

If processing multiple images in one invocation, repeat the block for each.

Reference files

  • reference.md — W3C image decision tree, full type rules, character limit guidance, HTML markup patterns for complex images (aria-describedby, figcaption, <details>), WCAG SC 1.1.1 / 1.4.5 success criteria text, common failure modes table, CMS field-name reference (Sitecore / Optimizely / Umbraco / headless props)
  • examples.md — Before/after pairs for all five image types across real DX agency scenarios (hero banners, icon buttons, data charts, pricing screenshots, decorative SVGs)
Technical details
Source
Standalone skill
Author
Dakota Smith
Skill name
alt-text-writer
Maturity
experimental
Security review
No security review
Argument hint
<image-path|URL|description> [--type informative|decorative|functional|complex|text-image|auto] [--context <surrounding text or link label>] [--platform sitecore|optimizely|umbraco|headless]
Allowed tools
  • Read
  • Write
  • Edit
File
skills/alt-text-writer/SKILL.md

To use this skill in Claude Code, copy SKILL.md into your local .claude/skills/alt-text-writer/ directory. Standalone skills are not exposed via claude plugin install — that path is reserved for plugin bundles.

Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.