Figma Handoff: Using Placeholder URLs in Design Specs

Problem

Why embedded Figma image fills slow down handoff

When a designer drags a stock photo into a card component, Figma encodes the image as a base64 blob. In the Inspect panel a developer sees no URL, only width and height in the properties. They must manually note the dimensions, open the image, export it, or look up the asset in a separate tool.

The embedded image also carries no semantic meaning about what the production image should look like. A developer implementing a 320×180 video thumbnail has no signal from the design file about whether the production image should be 16:9, whether there is a colored overlay, or what fallback state looks like.

Placeholder URLs fix both problems. A URL like `https://fallback.pics/api/v1/320x180/1E293B/94A3B8?text=Thumbnail` is self-documenting, carries exact dimensions, shows the intended color palette, and is immediately usable in a `<img>` tag during development.

Annotation technique

Adding figma placeholder image URLs to the Inspect panel

In Figma Dev Mode, select an image layer and use the component description field or a sticky annotation to record the placeholder URL. Teams that use Figma's annotation toolkit can add a custom annotation type called 'Placeholder URL' that appears inline next to dimension properties.

For component libraries, define a variant called 'Placeholder' that sets the image fill to a solid color matching the placeholder's background hex. Export it as an SVG with the URL recorded in the SVG title element. Developers reading the SVG source will find the URL without needing to open Figma.

<!-- Developer can read this directly from Figma Inspect -->
<!-- Placeholder URL: https://fallback.pics/api/v1/320x180/1E293B/94A3B8?text=Video+Thumbnail -->

<img
  src="https://fallback.pics/api/v1/320x180/1E293B/94A3B8?text=Video+Thumbnail"
  width="320"
  height="180"
  alt="Video thumbnail placeholder"
/>

Design tokens

Encoding brand colors into placeholder URLs for consistency

Placeholder URLs accept background and foreground hex values directly in the path. Pair these with your design token values to keep placeholders on-brand during development. If your card background token is `surface-muted` = `#F1F5F9` and your muted text token is `text-muted` = `#64748B`, encode them directly: `/F1F5F9/64748B`.

Document the mapping in your design system handbook so developers do not invent colors. A token-to-placeholder URL mapping table helps teams maintain visual consistency from design to staging.

// design-tokens.ts (excerpt)
export const placeholders = {
  cardSmall:   'https://fallback.pics/api/v1/280x160/F1F5F9/64748B?text=Image',
  cardLarge:   'https://fallback.pics/api/v1/560x320/F1F5F9/64748B?text=Image',
  avatar48:    'https://fallback.pics/api/v1/avatar/48?text=AB',
  heroBanner:  'https://fallback.pics/api/v1/1200x400/7C3AED/FFFFFF?text=Hero',
  thumbnail:   'https://fallback.pics/api/v1/1200x630?text=Title&style=soft&theme=purple&label=fallback.pics',
};

Responsive variants

Sizing placeholder URLs to match Figma breakpoint frames

Figma frames for mobile (375px wide), tablet (768px), and desktop (1440px) typically use different image dimensions. Define one placeholder URL per breakpoint frame and record all three in the annotation. Developers then map them to the correct responsive `srcset` or CSS media query.

For fluid images that use `width: 100%`, record the placeholder at the max intrinsic size the image should reach. Passing `width` and `height` attributes matching that maximum prevents CLS even when the actual render size is smaller.

Storybook bridge

Sharing placeholder URLs between Figma and Storybook

Storybook default args and Figma component specs can share the same placeholder URLs. Define the URLs in a shared `constants/placeholders.ts` file that both the component `defaultArgs` and the design token documentation import. When a designer updates a card dimension in Figma, one file change propagates to both Storybook and production fallback behavior.

Teams using Storybook Connect or Chromatic for Figma integration can use this shared token file to validate that the Storybook render dimensions match the Figma frame dimensions automatically in CI.

Handoff checklist

What to include in every Figma component spec for images

Every image surface in a Figma component should document: the placeholder URL at the primary render size, the aspect ratio or fixed dimensions, the alt text pattern (is it descriptive or decorative?), and the failure state if the production image is missing. Most teams skip the failure state; it is the most important one.

# Figma component annotation template

## Image surface: Product thumbnail
- Placeholder URL: https://fallback.pics/api/v1/240x240/F8FAFC/CBD5E1?text=Product
- Dimensions: 240×240 (1:1 aspect ratio)
- Alt text pattern: product.name + " product photo"
- Fallback state: show placeholder URL if src returns 404

## Related resources
https://fallback.pics/docs/
https://fallback.pics/placeholder-image-api/
https://fallback.pics/blog/storybook-default-placeholder-urls/