Placeholder Images for Design System Documentation

Published March 11, 2026

Design system documentation needs to show components in every possible state: different sizes, color themes, content types, and edge cases. Real images distract from the component's structure and introduce visual noise that makes it harder to evaluate spacing, alignment, and typography. Deterministic placeholder images isolate the component itself by providing consistent, labeled content for every documentation example.

The problem with real images in component docs

Using real photographs in design system documentation creates several issues. First, the photo's subject draws attention away from the component's structure — reviewers comment on the image instead of the padding. Second, real images vary in tone and contrast, making it hard to evaluate consistent styling across variants.

Placeholder images solve both problems. They are visually neutral (solid color with a label), so the component's structure is the focal point. And they are generated from a known specification, so every variant uses an image with the exact same visual weight.

Documenting component variants

A typical design system image component has variants for aspect ratio, size, and theme. For example, a Card component might support:

- **16:9 thumbnail**: 320×180, 480×270, 640×360 - **Square**: 200×200, 300×300 - **Portrait**: 300×400, 450×600 - **With overlay**: same sizes, darker background

Generate all variants in one PlacePack session. Use per-item color overrides to distinguish themes — for example, a dark background for the dark theme variant and a light background for the default.

Labeling images for self-documenting examples

The PlacePack text template system makes each placeholder self-documenting. Use a template like `{label} / {w}×{h}` to embed the component name and dimensions directly in the image.

When someone browses the design system docs and sees a placeholder labeled `Card / Hero / 640×360`, they immediately understand the image's role, dimensions, and component context. This is far more informative than a random stock photo or a blank grey rectangle.

Integrating with Storybook and documentation sites

Most design systems use Storybook for component development and a documentation site (Docusaurus, Notion, or a custom build) for the public-facing docs. The same PlacePack fixture set serves both environments.

Commit the fixture images to the repository. Import them in Storybook stories and reference them in documentation Markdown. When the design system evolves — new variants, new breakpoints — regenerate from the saved PlacePack share URL and commit the updated files.

import cardHero from "../../fixtures/images/card_hero_640x360.png";

export const Hero = {
  args: {
    image: cardHero,
    title: "Card Title",
    aspect: "16:9",
  },
};

Maintaining consistency across the system

Use a single PlacePack session to generate all placeholder images for the design system. This ensures consistent colors, label formatting, and file naming across every component's documentation. Store the PlacePack share URL in the design system's CONTRIBUTING.md or internal wiki so anyone extending the system uses the same configuration.

FAQ — Frequently asked questions

How many placeholder variants do I need?

Generate one image per unique width×height combination across all component variants. A typical design system needs 15-30 placeholder images covering all aspect ratios and sizes.

Should I use the same colors as my design tokens?

Using a neutral color (like slate or grey) keeps placeholders unobtrusive. For theme-specific variants, match the background to the theme's surface color to show how the component looks in context.

Can I automate placeholder generation in CI?

Yes. Use the PlacePack REST API's /pack endpoint in a CI step to generate or verify the fixture set. Compare the downloaded ZIP hash against the committed fixtures to detect drift.

Related guides

• Placeholder Images for Storybook Stories →