How to Keep Alt Text With Designs During Handoff

Alt text is metadata. It describes an image for users who cannot see it — screen reader users, users on low-bandwidth connections where images do not load, users of search engines that index by alt text. The moment alt text is separated from the image it describes, the pair breaks. The image ships without a description, the description ships without an image, and somewhere down the line an accessibility audit finds the gap and the team files a ticket that should never have existed.

This guide is about the small but persistent mistake of copying alt text out of a design file and into a clipboard note, a chat message, or a spreadsheet cell, then handing the image off separately. It is written for designers, content designers, and developers who care about accessibility in production handoff. For neighbouring topics, see how to brief a videographer with staged references, seasonal campaign kits: pin, ship, unpin, best clipboard setup for Photoshop users, and the Figma desktop vs Figma web paste behavior note for cases where the same asset lands in multiple tools.

Why alt text is metadata, not content

Treat alt text the way you treat a file name or a colour profile. It is a property of the image, attached to the image, and it travels with the image. When the image moves from design file to ticket to repo to CMS, the alt text moves with it. If the alt text does not move with the image, the image arrives in production without a description, and somebody has to write one later — usually from a screenshot, badly, under deadline pressure.

The W3C's Web Content Accessibility Guidelines (WCAG) make this implicit. Success Criterion 1.1.1 (Non-text Content) requires that all non-text content has a text alternative that serves the equivalent purpose. The guideline does not say "the alt text exists somewhere in the project". It says the alternative is served with the content. That means at the img element, in the document, attached to the asset — not in a spreadsheet the developer has to cross-reference.

The mistake pattern

The mistake is small and looks helpful:

1. Designer writes good alt text in a Figma text frame next to the image.
2. Designer selects the alt text, copies it to the clipboard, and pastes it into a Jira ticket description (or a Slack message, or a Notion page, or a comment on the design file).
3. Developer receives the image export (a PNG, an SVG) without the alt text nearby.
4. Six weeks later, the alt text in the ticket is stale because the image was updated, the ticket was closed, and nobody updated the alt text to match.

The fundamental problem is that copying alt text out of a design file makes it a free-floating string. It has no link back to the asset it describes. When the asset changes, the alt text does not change with it.

What to do instead

The rule is: alt text lives with the asset, in every layer of the handoff.

The principle at every layer is the same: alt text is a property of the image. It is not a separate piece of content. It does not get its own ticket. It does not live in a spreadsheet.

Practical handoff format

For a single image going from design to code, the handoff should include the asset file and the alt text in the same message or ticket. A reasonable template:

### Image: product-hero.png

- File: product-hero.png (SVG, 12 KB)
- Alt text: A barista pours milk into a cup of espresso, with steam rising from the cup.
- Decorative? No
- Caption (visible): Our morning ritual, in three pours.

If the image is decorative (a background flourish, a divider), the alt text should be empty (alt="") and the ticket should say so explicitly. Decorative is not the absence of a decision; it is a decision, and it needs to be communicated.

If the image is a chart or diagram, the alt text should describe the conclusion of the chart ("Bar chart showing sales rising 40% from Q1 to Q3"), and a longer description or a data table should be provided in the surrounding text or as an aria-describedby link. Charts are the case where one-line alt text is not enough, and that extra detail also needs to travel with the asset.

Tools that help

• Figma Dev Mode — exposes alt text and other accessibility annotations directly in the inspector, so a developer reading the spec sees the alt text next to the image rather than in a separate annotation.
• Storybook — for component libraries, an alt prop on an Image component makes the alt text a required input, which means a missing alt text fails the component contract rather than slipping through review.
• axe DevTools and WAVE — browser-based accessibility checkers that flag missing or empty alt text on non-decorative images. Run these on a staging build before launch, not after.
• CMS alt text fields — most modern CMSes (WordPress, Contentful, Sanity, Strapi) have a dedicated alt text field on media library items. Use it. The alt text then travels with the image across every page that uses it.

A local clipboard shelf can hold the working set of alt text strings being moved between design and code, but it is a staging area, not the destination. The destination is the design file's annotation, the ticket's alt-text field, the code's alt attribute, and the CMS's media library. If the alt text lives only on the clipboard, it is already lost.

What does not count

• "We'll write alt text at the end." No, you won't. You'll write it badly, in a rush, two days before launch, from screenshots. Write it when the image is chosen.
• "The image is obvious from context." It is not. Context is invisible to a screen reader reading the alt attribute in isolation.
• "Alt text is the same as the caption." It is not. A caption is visible content for sighted users. Alt text is hidden content for non-sighted users. They can overlap, but they serve different purposes.
• "The CMS will handle it." Only if you fill in the field. An empty alt-text field in the CMS is the same as no alt text.
• "AI can generate it later." AI-generated alt text is better than nothing, but worse than designer-written alt text that knows what the image is supposed to communicate. Use AI as a draft, not as the final.

The rule, restated

Alt text is metadata. It belongs with the image. Copy the image, the alt text comes with it. Move the image to a new file, the alt text moves with it. Hand the image to a developer, the alt text is in the handoff. Ship the image to the CMS, the alt text is in the media library. Never let alt text exist as a clipboard string detached from its image. If you find yourself with alt text on the clipboard and the image somewhere else, you are one paste away from an accessibility gap.

A worked example: the hero image swap

Consider a typical sequence of events. A designer picks a hero image for a landing page, writes alt text in the Figma file's annotation panel, and exports the image. The developer implements the page, copies the alt text from Figma Dev Mode into the alt attribute, and ships. Two weeks later, marketing swaps the hero image for a different one. The new image asset overwrites the old one in the CMS media library. The CMS, if it has a per-image alt text field, now has new alt text associated with the new image — assuming the marketer filled it in. If the marketer did not, the old alt text is gone (it was a property of the old image) and the new alt text is empty. The page now serves an image without a description.

The fix is straightforward but boring: every image in the CMS media library has an alt text field, and that field is required for non-decorative images. The CMS enforces this at upload time. The designer's alt text in Figma is the source for that field, transferred through the ticket and the PR. Nobody copies alt text into a chat message, because the chat message is not where the alt text lives. The alt text lives with the image, in every layer, from design to production.

This is the discipline. It is unglamorous, it adds 30 seconds to every image upload, and it is the difference between an accessible site and a site that fails its next audit.

Related reading

• Seasonal Campaign Kits: Pin, Ship, Unpin
• Best Clipboard Setup for Photoshop Users
• Best Clipboard Habits for Developers in 2026
• How to Enable Clipboard History in Windows 11

Sources

• W3C — WCAG 2.2 Success Criterion 1.1.1 Non-text Content — the formal requirement that non-text content have a text alternative serving the equivalent purpose
• W3C — WAI tutorial on Images — the Web Accessibility Initiative's guidance on alt text for functional, decorative, and complex images including charts
• Figma — Dev Mode overview — documentation for Dev Mode's inspector, which exposes alt text annotations alongside image assets
• MDN Web Docs — img element: the alt attribute — the canonical developer reference for the alt attribute, including the empty alt for decorative images
• Deque — axe DevTools accessibility testing — widely used accessibility testing tool that flags missing or empty alt text on non-decorative images

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