Screenshots, design tokens, and written briefs for coding agents

Give a coding agent screenshots to show composition, design tokens to preserve shared values, and a written brief to explain the task and behavior. Combine them when building a new screen inside an existing product. State which source controls each decision, especially when a borrowed reference conflicts with your design system.

The useful choice depends on what is missing. A button color change may need only the existing token and a precise instruction. A new page with an unfamiliar layout needs visual evidence. An account-recovery flow needs explicit behavior even if its screenshots already look finished.

Each context type answers a different question

The boundaries can overlap. A detailed design system may document layouts beside its tokens. A screenshot annotation can specify behavior. Judge the information supplied rather than the file extension. A token export with no component guidance and a complete design-system manual offer different levels of help.

Use screenshots to discuss relationships

A screenshot shows how a designer placed content in a particular state and viewport. You can discuss the width of a reading column, the distance between a heading and its action, or the balance between product imagery and text. Those relationships are cumbersome to communicate through adjectives alone.

Treat exact measurements as estimates unless you have the source design or implementation. A screenshot does not identify the font license, reveal semantic HTML, or explain a loading state outside the capture. A visually similar result can still use the wrong controls. Record the source page, capture date, viewport, and known state beside the image.

Ask the agent to separate observations from proposals. "The heading occupies a narrow column" describes visible evidence. "The column should become full width on mobile" is a proposed behavior if no mobile reference exists. Keep that distinction in the review. The design reference guide covers getting the selected image into the agent's context.

Use design tokens for values you already own

The Design Tokens Community Group defines a token as information associated with a human-readable name, including a name and value. Its 2025.10 format specification describes a format for exchanging those decisions between tools. It is a Community Group report, not a W3C Standard.

In a codebase, point the agent to the actual token source and the components that consume it. A semantic name such as text-muted has a purpose that an isolated gray hex value lacks. Show an established component usage so the agent can preserve that purpose across themes and states.

Tokens help keep a new screen consistent with the surrounding product. They do not decide whether a page needs a sidebar or whether the primary action belongs beside the title. Copying a reference's colors into new local variables can also create a second, conflicting palette. Prefer existing values unless a reviewed design change requires new ones.

Use the brief for decisions a picture cannot settle

Write who uses the screen, what they need to accomplish, and which content must remain. Specify empty, loading, error, and success behavior where those states apply. Include the awkward cases. A long project name, a failed request, or an unavailable action can change the layout more than the preferred corner radius.

A useful brief also defines completion. "Make the page polished" provides little direction during review. "Keep the plan comparison readable on mobile, preserve the existing purchase action, and expose billing details before checkout" gives the agent concrete decisions to implement and you concrete behavior to inspect.

Text is sufficient for many small changes inside an established system. Keep that path short. For a substantial visual change, replace vague style words with a selected image and a note about the relationship you want to borrow. Why agents build the same landing page explains the limits of naming familiar page sections.

Combine them with an explicit order of authority

For an existing product, use the brief to define required behavior, preserve the repository's established components and tokens, and use external screenshots for the named visual relationships. Accessibility requirements apply throughout. If those inputs conflict, ask the agent to identify the conflict before introducing a new design-system exception.

Build a project settings screen in this repository.
Read the existing settings components and token definitions first.
Use the attached screenshot for the narrow form column and grouped field spacing.
Keep our typography, colors, control components, and navigation.
Required behavior: save changes, show field errors, and preserve input after a failed save.
Include loading and empty states where relevant.
Before coding, list observed reference details, proposed behavior, and conflicting requirements.
After coding, render desktop and mobile views and verify the save and failure paths.

For a new product without an established system, decide which repeated values to adopt after choosing a visual direction. Record those decisions once the first screen works. Extracting a large token catalog before settling the composition adds maintenance for choices you may discard. The right amount of context changes as the product develops.

Review behavior and appearance separately

Compare rendered screenshots to inspect composition. Read the implementation to check token use. Drive the interface to verify the brief. A screenshot comparison alone cannot establish keyboard behavior or show whether a failed save preserves the user's work. Mark each check as verified or still pending.

Measure text contrast using the implementation's foreground and background values. W3C's contrast guidance explains why evaluation uses those values rather than antialiased pixels in a screenshot. A borrowed reference's apparent readability is insufficient evidence that your own text meets the requirement.

• Does the rendered page preserve the specific relationship selected from the reference?
• Does the code reuse the product's components and token names?
• Can a user complete the task and recover from an error?
• Have you checked the widths and states missing from the reference?
• Are observed source details distinguishable from new design decisions?

If the missing input is visual, start with the gallery. swaggin's search, metadata, and low-resolution fold previews are free. Crisp folds, overviews, and segments require a license. The setup guide connects retrieval to your agent. Bring the product's own tokens and task brief alongside the references you select.