Alt Text in Design Handoff: Keep It With the Image

Write alt text when you choose the image, attach it to that image in the design file, and hand the two over together: same annotation, same ticket, same pull request, same CMS media item. Alt text that travels separately, in a chat message, a spreadsheet or a loose clipboard copy, falls out of step the first time the image changes. The developer's job is then to put it in the image's alt attribute, or alt="" if the design marks the image as decorative.

Why alt text gets lost in handoff

WCAG 2.2 Success Criterion 1.1.1 requires that non-text content presented to the user has "a text alternative that serves the equivalent purpose", and that purely decorative images are implemented so assistive technology can ignore them. Meeting it depends on a decision made for every image, but that decision is usually made by a designer and implemented by someone else.

The common failure looks like this:

1. The designer writes alt text in a text box next to the image in the design file.
2. They copy it into a chat message or a ticket comment.
3. The developer receives the exported image from somewhere else, such as a shared folder.
4. The image is later swapped or recropped. Nobody updates the text, because nothing links the two.

Copying the image itself doesn't help: an image on the Windows clipboard is pixel data with no field for a description, so whatever you paste it into receives no alt text. What the Windows clipboard can and cannot store explains the formats.

Where alt text should live at each stage

The rule at every stage is that alt text sits next to the specific image it describes, never in a separate list. Giving each image a descriptive file name helps too, because the name is what ties a ticket entry to the right file; naming and keeping a copied image as an asset covers that, and handing assets to a developer without Slack soup covers the rest of the handoff. For screenshots in a repository's docs, keeping README screenshots as files applies the same idea to Markdown.

How to attach alt text in Figma

Figma Design doesn't have a dedicated alt text field for images in a design file, so handoff relies on annotations:

1. Select the image layer.
2. Press Shift+T to add an annotation (or use the annotation tool in Dev Mode).
3. Choose the Accessibility category and write the alt text, or write "Decorative" if it should be alt="".

Annotations are visible in Dev Mode by default, so developers see the alt text while inspecting the image. According to Figma's help, annotations are available on paid plans and need a Full seat with edit access to add. On a free plan, put the alt text in a clearly labelled text layer grouped with the image, and name the image layer after its export file.

Figma Sites and FigJam do have their own alt text settings for images. In prototypes viewed with Adapt content for screen readers turned on, Figma uses an image-filled layer's name as its alt text, so descriptive layer names help there too.

Alt text handoff template

For each image in a ticket or spec, include the file and its text in one entry:

Image: product-hero-barista.webp
Alt text: A barista pours steamed milk into a cup of espresso.
Decorative: No
Visible caption: Our morning ritual, in three pours.
Long description: None needed

For a decorative image, such as a background texture or divider:

Image: divider-wave.svg
Alt text: (empty, use alt="")
Decorative: Yes

Say "decorative" explicitly. An empty field could mean "decorative" or "forgot", and developers can't tell which.

Charts, diagrams and other complex images

A one-line alt can't carry a chart's data. The W3C's images tutorial describes a two-part text alternative for complex images: a short alt that identifies the image, plus a long description elsewhere, such as text near the image, a linked section or a data table. In the handoff, attach both: the short alt and the long description, or the source data the long description should be built from.

Writing the alt text itself

• Describe what the image is there to communicate in context, not every visual detail.
• Don't start with "Image of" or "Picture of"; screen readers already announce it's an image.
• If the image contains text that matters, include that text.
• For a linked image or icon button, describe the action or destination, such as "Search".
• If the visible caption or nearby text already says everything the image shows, the image may be decorative.

The W3C's alt decision tree walks through these cases one question at a time.

How to check alt text before launch

1. In code review: check that every new img has an alt attribute and that decorative images have alt="". If your component library uses TypeScript, make alt a required prop so a missing value fails type checking.
2. With an automated checker: tools such as axe DevTools and WAVE flag images with no alt attribute. They can't judge whether the text is accurate.
3. With a screen reader: listen to the page with Narrator (Ctrl+Windows logo key+Enter turns it on) or NVDA and check that each image makes sense where it's read.
4. In the CMS: check that reused images have alt text that still fits each page they appear on.

FAQ

Is alt text the same as a caption?

No. A caption is visible to everyone. Alt text replaces the image for people who can't see it. They can overlap, but if the caption already describes the image fully, the alt can be shorter or empty.

Can AI write alt text for handoff?

It can produce a draft, but it doesn't know why the designer chose the image. Have someone who knows the intent review it.

Who is responsible for alt text, design or development?

Whoever knows the image's purpose should write it, usually the designer or content designer. The developer is responsible for implementing it exactly and flagging any image that arrives without a decision.

Related reading

• How to Hand Off Design Assets to Developers (Checklist)
• How to Save a Copied Image With Your Own File Name
• How to Add Screenshots to a GitHub README
• When to Turn Copied Elements Into Figma Components

Sources

• Understanding SC 1.1.1: Non-text Content (W3C) — text alternatives and decorative images.
• Images tutorial (W3C WAI) — alt text guidance by image type.
• An alt decision tree (W3C WAI) — deciding what alt text an image needs.
• Complex images (W3C WAI) — two-part text alternatives for charts and diagrams.
• Add measurements and annotate designs (Figma Help) — annotation categories, Shift+T, plan and seat requirements.
• Accessible prototypes in Figma (Figma Help) — layer names used as image alt text.
• img: The Image Embed element (MDN) — the alt attribute and empty alt for decorative images.
• axe DevTools (Deque) and WAVE (WebAIM) — automated accessibility checkers.

Copy. Stack. Drop.

Transform your clipboard into an interactive edge shelf. Stack, pin, and drag assets into any app with zero friction.

Download for Windows Get from Microsoft Store

How to Install Guide · First 10 Minutes Guide · Drag & Drop Guide · Edge Drop vs Win+V · Support