Design-to-Build Naming Conventions That Stop Handoff Rework

Handoff rework usually comes from three avoidable mismatches: semantic drift (design names mean something different to engineers), packaging drift (assets are exported with inconsistent sizes/formats), and version drift (branches and fixtures don’t track the same milestone). Naming conventions are the cheapest, highest-leverage defense against those gaps.

A practical rule: name for the consumer. Designers should name layers, tokens, and components the same way the code and backend expect them to be referenced. That means using the same token taxonomy in Figma variables as in your codebase and choosing filenames that map directly to asset keys the app reads at runtime.

bullets:[

Agree taxonomy first: primitives → aliases → components. Keep tokens at the primitive level (color, spacing, typography) and alias them for product variants.

Structure Figma tokens to mirror your runtime design system: start with primitives (tokens like color.semantic.primary.100), then create aliases for product-level meanings (color.brand.primary). Use a predictable separator (dot or slash) and keep names copy-paste-safe (no emojis, no slashes that conflict with export paths). Figma’s own guidance and the Variables/Styles model favor this hierarchy because it maps directly to automated token exports.

For layers and components, adopt verb-noun or role-based naming that matches component APIs (e.g., Button/Primary/Default or Card/Product/Compact). Include a small, enforced suffix for dev-ready frames such as —dev or /dev so developers can filter live files to the production-ready subset. Put the design-to-build-naming-conventions-filenames-tokens-branch-rules token taxonomy on the root Design System page so it’s discoverable inside Figma.

bullets:[

Token format example: color.palette.gray.50 → color.semantic.surface → color.brand.primary. Use dots for programmatic friendliness.

Mobile asset names should be explicit about scale and role. Use a pattern: <component>__<role>__<variant>__<scale>.<ext>. Examples: avatar__user__default__3x.png or icon__tab__settings__1x.svg. That maps cleanly to both iOS/Android asset catalogs and web build pipelines. Keep names lowercase, underscore or double-underscore as separators, and avoid spaces or special characters.

For API fixtures and mock JSON used by contractors, name files to match endpoints and variant states: GET_users_200_primary.json, GET_users_200_empty_profile.json. Store fixtures in a fixtures/ directory and include the API path and HTTP status in the filename so engineers immediately know which response the fixture represents. This small discipline prevents accidental mismatches between the design preview and the backend contract.

bullets:[

Asset filename pattern: <component>__<role>__<variant>__<scale>.<ext> (e.g., card__thumbnail__error__2x.png).

Adopt a concise branch prefix system that ties branches to tickets and handoff state. Use feature/<ticket>-<short> for new work, fix/<ticket>-<short> for bug fixes, and hotfix/<ticket> for urgent production patches. When a design is ready for development, create a dev-ready branch named devhand/<ticket>-<designerInitials>-vX and pin the Figma dev-ready frame and fixture commit to that branch.

Enforce two quick rules in pull requests: every PR must reference the Figma file ID and the design’s dev-ready frame (or include a link to the one-page acceptance checklist), and asset/fixture filenames in the diff must follow the naming patterns. This lets reviewers validate handoff compliance without opening Figma every time and reduces “it looked different on my machine” loops.

bullets:[

Branch naming: feature/1234-login-ui, fix/987-avatar-scaling, devhand/1234-JD-v1 for design-to-build ready branches.

Use a single-page checklist that must be satisfied before a ticket moves from Design → Dev. It’s small enough to keep in the ticket template and enforceable in code review. Include items that can be checked off by either the designer or the reviewer — not vague items like “look good” — but technical checks like token usage and asset filenames.

Below is a compact contractor-ready acceptance checklist you can paste into any ticket or PR (make it a required checklist in your issue template):

bullets:[

Design file: Figma file ID and frame link included.