Asset names must map onto the code structure
Aliases: export naming · asset-path mapping · slice filenames · module-aligned names
What it is
Exported icons, illustrations, and bitmaps must carry names that map onto the code structure that consumes them — module, component, route — not onto how the layer looked on the artboard. icon-settings can resolve to settings/Icon.tsx; blue-btn-final-2 is unsearchable in the repo. The build resolves files by path and identifier, not by “looks like”.
The mapping is not prettier filenames. It is admission into the same address space as code. An unmapped file becomes an orphan: unfindable, undeletable, and replaceable only by dropping another copy beside it.
Why it happens
Design tools export from a layer tree named for visual grouping — color, state, a designer’s version slang. Code addresses a feature-module tree; the bundler only knows module paths. If the two trees do not share a concatenable name, import becomes human translation: someone remembers “that blue button is actually Primary inside Settings”. When memory breaks, the repo keeps final, final2, use-this.
Failed replacement is the visible consequence. The correct move is to open the component’s directory and swap a same-named file so every call site follows. If the name cannot point at a directory, the replacer hunts thumbnails in a flat dump, misses a path, and leaves dual references: the old file still eaten by a leftover import, the new file eaten only by new code. Deletion is equally unsafe — orphans have no reference count.
Where it stops holding
One-shot campaign art that never enters the app bundle may be named for the campaign. A bitmap shared across brands and swapped at runtime by a theme layer should map to a semantic role (icon.nav.home), not a brand folder; baking the brand name into the file shatters at the next theme. When a pipeline generates density variants from a source, humans name the source, not the generated files; a handmade @2x name that ignores the module fights the pipeline. Third-party icon sets can keep their short names behind a wrapper map; the source pack need not be renamed.
Applying it
- Write a naming table against code modules before export:
{domain}/{component}/{slot}-{state}. Banfinal, color words, and author names from filenames. - Land slices in the consuming module directory, or in a pipeline that moves them by the same rule. Do not stage them in a desktop “export” folder for a person to ferry.
- A new asset must be reachable by identifier from the component file; a call site named for appearance (
blueIcon) is unfinished. - How to check: search the repo for the exported filename; the hit must sit under the consuming module. Then run a replacement drill — find the file from the component name alone, swap it, and confirm every call site follows and the old file has no remaining reference. Multiple
finalhits, or no hit, means the name did not map.