Brand asset handoff checklist for developers: a practical guide

Brand asset handoff checklist for developers

A broken logo is rarely a design problem. It usually surfaces at the moment a developer tries to pull a transparent PNG from a folder, opens a color value that does not match the marketing site, or asks which version of the wordmark is the official one. The brand asset handoff checklist for developers in this guide treats that moment as the real test of a brand system, not the Figma file or the brand book PDF.

Developers do not need a 60 page guidelines document. They need a small, predictable set of files, tokens, and decisions that let them ship a button, a hero, or a checkout page without asking three rounds of questions. The goal of this checklist is to make brand assets as easy to consume as a package on a registry. Open the folder, read the README, build the page.

What follows is a working checklist for designers, brand managers, and engineering leads who actually want the handoff to go smoothly. It focuses on the items that get missed in real projects, not on the items that look good in a style guide.

What a brand asset handoff actually contains

Before a checklist is useful, the team has to agree on what counts as a brand asset. In most product work, the handoff package includes the logo, color, typography, iconography, imagery, and motion. Each of those has its own file formats, naming rules, and decision points. The handoff document explains those rules in writing, not in tribal knowledge.

Think of a brand asset handoff as a contract. The design side promises a specific output, and the engineering side promises to use that output in a specific way. The checklist is the page where the two promises meet.

For a developer, the package needs to answer four questions for every asset class. Where do I get the file. Which version do I use. What name do I use in code. What do I do if the file is wrong. The rest of this article walks through the asset classes that most often fail those four questions.

Logo files: the part everyone underestimates

Logo files cause the most recurring bugs in a brand implementation. The PNG is too small, the SVG has stray transforms, the dark mode logo was never exported, and the favicon is a screenshot of the wordmark. A clean logo handoff removes those failures before code review.

For practical purposes, a logo package should ship in a small set of formats, each with a clear role. Treat the formats as roles, not as interchangeable files.

Role	Format	Use case	Notes for developers
Primary mark, full color	SVG	Default use on light backgrounds	Inline when possible, reference by id, do not rasterize
Primary mark, monochrome dark	SVG	Dark backgrounds, overlays, video	Recolor with currentColor, not a separate black file
Primary mark, monochrome light	SVG	Print and high contrast contexts	Use only when the surface is dark
Raster fallback	PNG, 2x and 3x	Email, legacy CMS, social cards	Export at the exact pixel size, do not upscale in CSS
Favicon	ICO, SVG, PNG 32 and 180	Browser tabs, iOS home screen	Ship the SVG and the ICO; avoid one giant PNG
App icon	PNG, platform sizes	iOS, Android, web app manifest	Use platform safe area, no transparency on iOS

File naming should describe the asset, the variant, and the format in that order. A name like logo-primary-dark.svg is easier to scan than logo_final_v3_OK.svg. The README in the logo folder should state the clear space rules, the minimum size in pixels, and which variant wins when in doubt.

Two decisions save a lot of bugs. First, decide whether the SVG uses currentColor for the fill or has the color baked in. Most modern implementations should use currentColor so the developer can recolor with one CSS property. Second, decide whether the wordmark and the mark are a single SVG or two separate components. A combined mark is simpler to drop in. A split mark is easier to animate or reorder on small screens.

Color tokens: from hex strings to design tokens

Color is the part of a brand that gets reinvented on every project unless the team ships a single source of truth. Hard coded hex values inside React components are a common symptom. So is a marketing site that uses #1A1A1A while the product uses #1B1B1B. A token based color system prevents both.

Design tokens are named values, usually defined in JSON, YAML, or CSS custom properties, that represent a design decision. The token name describes the role, not the value. --color-text-primary is a role. --color-gray-900 is a scale. Most mature systems use both, with role tokens pointing to scale tokens.

Token layer	Example name	Example value	Used by
Primitive	color.blue.500	#2563EB	Designers only
Semantic alias	color.action.primary	color.blue.500	Designers and developers
Component	color.button.bg.primary	color.action.primary	Developers only
Mode override	color.text.primary.dark	#F5F5F5	Dark mode layer

A developer friendly handoff includes the token file in the format the codebase already uses. If the project is in CSS, ship CSS custom properties. If it uses a JS framework with a tokens package, ship the JSON or JS module. A tokens file that lives in the design tool but not in the repo is, for engineering, the same as no tokens at all.

The README should also list the contrast pairs that have been tested. WCAG contrast is a common requirement, and a handoff that lists the approved text on background pairs saves the developer from running contrast checks on every screen. If the brand uses a color combination that fails contrast, document that decision and pair it with a fallback.

Typography: more than font files

Typography handoff has three parts: the font files, the size and weight scale, and the usage rules. The font files are the easy part. The scale and the rules are where most implementations drift away from the brand.

For web work, ship variable font files where possible and document the axis ranges. A single variable font for the primary family is usually lighter than a folder of static cuts. If a static cut is needed for a specific platform, explain why. A common rule of thumb: variable fonts for web, static cuts for email and some native apps, system font fallbacks documented in the token file.

The type scale should be expressed in tokens, not in freeform values. A scale like 12, 14, 16, 18, 20, 24, 30, 36, 48 covers most product UI. Brand headlines can step outside the scale, but the scale should be the default. Developers should not have to pick between 17px and 18px on a button label.

• Ship the font files in WOFF2, with WOFF as a legacy fallback if the browser support matrix requires it.
• Document the allowed weights, the line height rules, and the letter spacing values for display text.
• List which weights are safe to load. A page that requests 12 weights will visibly delay first paint.
• Provide the system font stack used when the web font fails to load, so the layout does not shift.
• Specify whether the brand allows tracking on uppercase display text, and by how much.

If the brand uses a custom or licensed font, the license terms belong in the handoff. Developers do not want to discover mid build that the font cannot be self hosted or that the license is per seat.

Iconography: the asset that multiplies fast

Icons look small and harmless until the project ships 200 of them across a product. At that scale, a clear icon handoff matters more than the choice of library. The handoff should decide three things: the source, the stroke, and the export.

The source is the library or the original file set. The stroke is the visual style, usually a consistent pixel grid such as 24 by 24 with a 1.5 or 2 pixel stroke. The export is the format, almost always SVG, with or without currentColor support.

Two practical rules keep an icon set usable. First, ship the icons as a single sprite or as individual files with consistent naming. A sprite keeps the developer from importing 30 modules. Individual files make tree shaking simpler. The choice depends on the framework, and the README should state it. Second, ship a set of test icons at the extremes: a single dot, a complex shape, a stroked icon, and a filled icon. These four expose most alignment bugs in the rest of the set.

Icon naming should describe the function, not the shape. icon.check is more stable than icon.tick-mark. The first name survives a redesign. The second has to change when the icon shape changes.

Imagery, illustration, and motion

Photography, illustration, and motion each have their own handoff patterns. The common mistake is to treat them as a single bucket called “assets”. They have different storage, different rights, and different update cycles.

Photography should be shipped in a structured folder with a small set of approved crops and a written rule for color treatment. A developer who needs a hero image should not have to open the original PSD. The handoff should include hero crops, square crops for social, and small crops for product cards. Each crop should be at 1x, 2x, and 3x.

Illustration files are usually SVG. The handoff should state whether the illustration is a single color, uses brand colors as variables, or has baked gradients. A developer cannot recolor a baked gradient without a design tool. The README should also list the illustrations that are allowed to be cropped versus those that have a fixed safe area.

Motion is the trickiest asset class. A handoff that ships a video file with no specifications forces the developer to guess at compression, loop point, and file size. A reasonable motion handoff includes the Lottie JSON or Rive file, a poster image as a fallback, the loop behavior, and the maximum payload size in kilobytes. It also states whether the animation is decorative or functional, since the latter needs a reduced motion fallback.

When the project uses a lot of motion, the team should agree on a reduced motion strategy. The W3C draft on reduced motion accessibility is a good orientation point for what that strategy needs to cover.

Naming, file structure, and the README that ties it together

Most handoff problems come from naming, not from the assets themselves. Two teams can use the exact same color value and still disagree on what to call it. The README is the place where that disagreement is settled.

A good README for a brand asset package is short. It should list the contents of each folder, the naming convention, the version number, the last updated date, and the contact for questions. It should also point to the design system page for the project, if one exists. The README is not the place for a full guidelines document. It is the table of contents.

• Use lowercase, kebab-case file names. Spaces and capitals break imports.
• Prefix component files with the system name, for example acme-logo-primary.svg, to avoid collisions when libraries are shared.
• Keep a single source of truth for version numbers. A VERSION file in the root of the package is a simple pattern.
• Do not commit generated or rasterized derivatives into the source. Let the build produce those.
• Mark deprecated assets clearly, and keep them in a _deprecated folder until the next major version.

If the project already has a design system page, the README should link to the page that explains the rationale. Design systems: a practical guide for product teams covers how to wire a design system page into the handoff so that the engineering team can find the rules without leaving the repo.

From Figma to repo: how the handoff lands in code

The handoff lives in two places. It lives in the design tool as the source of truth, and it lives in the repo as a set of files and tokens. The two places have to stay in sync, or the handoff decays. Decay is what produces the third round of questions about whether the new blue is the new blue or the old blue.

A useful pattern is to export tokens from the design tool into a tokens file in the repo, and to treat the export as a code generation step. The design tool changes a value, the export runs, the tokens file updates, and the build consumes the new file. This is not always possible on small projects, but the principle still applies. Whoever owns the tokens file also owns the brand values in code.

For larger projects, the team should also pick a delivery channel. Three common channels are:

• A versioned package, such as @acme/brand-assets, published to a private registry.
• A folder in the main repo, treated like a vendored dependency and updated through pull requests.
• A content delivery network that hosts the binary files and the tokens JSON.

Each channel has tradeoffs. A versioned package is the cleanest from an engineering point of view, but it requires a release process. A vendored folder is simple, but it is easy to forget to update. A CDN is fast, but it adds a runtime dependency that can fail. The handoff document should record which channel is in use, and the owner of that channel.

Roles and responsibilities during the handoff

The handoff is a process, not a file drop. A small team can run that process informally. A larger team needs to write down who owns what. The most common failure mode is that everyone assumes someone else is updating the tokens file. The second most common failure is that the design lead is the only person who can answer a question, and that person is on vacation.

A reasonable set of roles is:

• Brand owner, usually a brand or design lead, who approves token changes and the official asset set.
• Design system maintainer, who keeps the tokens file, the components, and the documentation in sync.
• Engineering lead for the consuming app, who decides how tokens are imported and which build flags gate the migration.
• Designers, who flag when an asset needs a new variant and write the brief for the brand owner.
• Developers, who raise clear, reproducible issues when an asset does not match the design.

The roles do not need to map one to one with people on a small team. A single person can hold two roles. The point is that each role has a name and a job, and that the handoff document says so.

Common handoff mistakes and how to prevent them

Patterns repeat across projects. The same set of mistakes shows up on the first product build, the marketing site rebuild, and the mobile app redesign. Listing the mistakes up front saves a lot of back and forth later.

Mistake	Symptom	Prevention
Hex values in components	Brand colors drift across the app	Ship a tokens file and lint for hard coded colors
Rasterized logos	Blurry marks on retina screens	Ship SVG as the primary, PNG only as a fallback
Mixed font weights	Random bold and regular text	Restrict the available weights in the tokens file
No dark mode plan	Inverted logos, broken contrast	Document dark mode tokens and dark mode logo variants
Icon naming chaos	Three icons named the same thing	Adopt a single naming scheme and review before export
Unversioned assets	No way to know which set is live	Use semantic versioning on the assets package
Hidden motion	Animations that ignore user preferences	Honor the reduced motion media query and ship a static fallback

Most of these mistakes are easy to catch in a pre launch review. A 30 minute review with a designer, a developer, and the latest build of the product catches more issues than a long documentation pass after the fact.

A pre launch handoff review you can run this week

The checklist below is a practical, one hour exercise that fits before a release. It is not exhaustive, and it is not a replacement for a full design system audit. It is meant to catch the most common failures before a customer does.

• Open the production app and a staging build side by side. Compare the logo, the primary color, and the body font.
• Run a contrast check on the most visited page, using the official color tokens.
• Search the codebase for hard coded hex values. Replace any that should be tokens with the token reference.
• Check the network panel for the number of font weights and icon requests. Trim anything above the budget.
• Toggle the system to dark mode and confirm the logo and the text contrast still meet the brand rules.
• Toggle the system to reduced motion and confirm the key animations have a static fallback.
• Verify that the assets package in the repo matches the version listed in the design tool.
• Ask a developer who was not on the handoff to add a new screen using only the README and the tokens file. Note every place they got stuck.

The last step is the most useful. If a developer who did not see the handoff can ship a screen without asking for help, the handoff is doing its job. If they cannot, the README is the file to fix, not the developer.

How this checklist fits into a broader design system

A brand asset handoff is one slice of a larger system. It sits between the brand book on one side and the component library on the other. When the slice is thin, the seams between the three are visible. When the slice is well built, the seams disappear.

The handoff is also the part of the system that is most often skipped on a small project. The team agrees on the logo, agrees on the colors, ships the site, and then discovers six months later that the new landing page uses three different shades of blue. A short handoff document, kept in the repo, prevents that drift. It is one of the cheapest pieces of documentation a team can maintain, and one of the highest leverage.

For teams that are formalizing their practice, the next step is usually a written design system. The design systems guide on this site is a reasonable starting point. It explains the relationship between the brand book, the handoff, and the component library, and it lists the artifacts a small team needs to maintain.

Frequently asked questions

What is the difference between a brand asset handoff and a design system?

A brand asset handoff is the act of moving approved brand assets from the design side to the engineering side, in a form engineers can use without further translation. A design system is the larger set of decisions, components, and documentation that those assets support. The handoff is one step in the lifecycle of a design system, and it usually shows up as the first concrete artifact when a team starts to formalize its practice.

Who should own the brand asset handoff package?

A single person should be listed as the owner, with a clear backup. On a small team, that is often the design lead. On a larger team, it is usually the design system maintainer, with the brand owner approving changes. The important part is not the title, but the fact that the handoff has a name on it and a way to reach that person.

How often should the handoff package be updated?

As often as the brand changes, and no more often than the team can review. A common pattern is a minor release every two to four weeks for small additions, and a major release when the brand itself changes, such as a logo refresh or a new color palette. Version numbers, in either semantic versioning or a simple dated folder, keep the team honest about what is live.

Should tokens live in the design tool or in the codebase?

Both, with the codebase as the source of truth for engineering and the design tool as the source of truth for design. The two should be generated from each other where possible, or kept in sync by an export step. A token that exists only in the design tool is, for a developer, the same as no token at all.

What file formats should a brand asset handoff include for logos?

At minimum, an SVG for the primary mark, a monochrome SVG that supports currentColor, PNG fallbacks at 1x and 2x, and a favicon set. The exact set depends on the surfaces the brand appears on. A handoff that also covers app icons, social cards, and email signatures is more complete, but only if each format has a clear role in the README.

How do we handle dark mode in a brand asset handoff?

Decide the dark mode values for each semantic token, and add a dark mode logo variant if the primary mark does not work on dark backgrounds. The visual identity page on this site covers how to think about dark mode as a brand decision rather than a purely technical one.

Do we need a Lottie or Rive file in every brand handoff?

No. A handoff should include motion only when the brand has motion. If the brand has a single animated logo and a small set of loaders, the handoff should include the source files and the reduced motion fallback. If the brand has no motion, a documented “no motion” decision is more useful than an empty folder.

What is the most common reason a brand asset handoff fails?

Naming and version drift. The assets exist, the tokens exist, but the names in the design tool do not match the names in the code, and the team is not sure which version is live. A short README with a single naming convention and a version number prevents most of those failures.

How do we measure whether the handoff is working?

Track the number of brand related questions and bugs raised by the engineering team per release. A working handoff shows a steady decline in those questions after the first release, and a flat line at a small number. A failing handoff shows repeated questions about the same assets, month after month.

What should we do when a developer needs an asset that is not in the package?

Document the request in a single place, usually the design system backlog, and treat it as a brand decision rather than a one off export. The brand owner either approves a new asset, redirects the developer to an existing asset, or marks the request as out of scope. This keeps the asset list from growing without a review.

Related reading

• Design systems: a practical guide for product teams
• Website typography: how to choose and use type online