Guide for Naming Assets in iOS Projects

This guide outlines best practices and naming conventions to help graphic designers and developers manage a large number of icons prepared for an iOS project.

Your input is welcome: issues, pull requests, or Twitter 😄

Table Of Contents

• Namespace
• Asset Folder
• Asset Type
• Naming
  • Uniqueness
  • Prefixing
  • Conventions
  • Special cases
  • Collisions
  • Spelling
  • Abbreviations
• Acknowledgment

Namespace

Naming an asset starts with breaking up the user interface of each screen into namespaces (or sections). Each namespace represents a logical grouping for the assets and can be used to create asset names.

• Shorter is better (one word if possible).
• Meaningful namespace name.
• Use lower case.
• No spaces or special characters (use dashes).

Namespaces can correspond to view controllers, typical namespaces are top, bottom, content although more specific names are better.

Examples

Twitter profile

• top or top-bar (shorter than navigation-bar)
• actions
• tweet
• tab

Tumblr home

• card or post
• tab

Instagram explore

• top
• photo
• tab

Asset Folder

• Asset Catalogs is the preferred way to manage assets in Xcode. It eliminates keeping track of files in a project. However naming assets (image sets) is still important especially when collaborating with a designer.
• If you choose to manage assets directly, use a main folder to store all assets for the app (usually named assets or images). This may seem radical but it works in conjunction with prefixing.
  • An alternative is to use subfolders for each namespace, be aware that subfolders can create problems with asset name uniqueness.
  • For extra credit, check out Structuring an iOS Project by Sebastian Rehnby and the Synx project.

Asset Type

• Use the PNG format (the JPG format is better for photos)
  • PNG is good for small assets
  • PNG is non-lossy
  • PNG supports transparency
• Create 1x, 2x and 3x assets in the same folder
• Add @2x or @3x at the end of the appropriate asset name

asset.png
asset@2x.png
asset@3x.png

To save disk space or time, one can omit the 1x, 2x or 3x asset: the system automatically scales up or down for the appropriate resolution (in particular, you could provide only 2x/3x assets when targeting retina devices).

Naming

Uniqueness

An important attribute of an asset name is uniqueness.

• This prevents confusion: for example having two different share assets (say one for iPhone and one for iPad, or one in a main view and one in a detail view).
• More importantly, while it is possible in Xcode to have two files of the same names in different folders, you can only reference one of them using + (UIImage *)imageNamed:(NSString *)name.

Prefixing

Prefixing is optional but it ensures that asset names are unique across the project.

• Prefix the asset with the app name so you can tell which project it belongs to (use a 2 or 3 letter prefix for long app names).
• Add a device prefix (especially for universal apps with device-specific assets).
• Add a namespace prefix so you can quickly organize your assets.
• Format: project-device-namespace-asset-name.png

ss-ipad-intro-arrow-right.png 
bpc-iphone-intro-arrow-right.png 

twitter-iphone-top-user.png
twitter-iphone-top-search.png
twitter-iphone-top-write.png

tumblr-iphone-card-action.png
tumblr-iphone-card-comment.png
tumblr-iphone-card-reblog.png
tumblr-iphone-card-heart.png

Conventions

• The asset name describes the icon, not the function of the icon (when possible, see special cases).
• Use lower case.
• No spaces or special characters (use dashes).

Examples

ss-rack-minus.png 
ss-top-bars.png 
ss-tree-check.png

Not

delete.png 
menu.png
selected.png

While CamelCase is the convention in Objective-C, it does not necessarily mean it needs to be applied to asset names (by all means feel free to use it if you prefer SSRackMinus.png).

Notable

• chevron for >
• caret for ►

Special cases

Sometimes the name is well represented by its function (refer to Charbase for Unicode).

• refresh for open circle arrow (⟳ U+21BB)
• edit for pencil (✎ U+270E)
• search for magnifying glass (🔍 U+1F50D)
• user for bust in silhouette (👤 U+1F464)
• comment for speech balloon (💬 U+1F4AC)

Collisions

Should two assets have the same name, add a qualifier at the end.

Color qualifer

ss-top-plus-pink.png
ss-top-plus-gray.png

Shape qualifer

• *-square
• *-circle
• *-o for outline

ss-top-arrow-right-circle.png
ss-top-arrow-right-square.png

Combine shapes

• *-square-o for square outline

Direction qualifer

• *-right
• *-left
• *-up, etc

ss-top-arrow-right.png
ss-top-arrow-square-right.png

Buttons (control states)

• *-normal
• *-selected
• *-highlighted, etc

ss-profile-gear-normal.png
ss-profile-gear-highlighted.png

Orientation

This is adapated from Apple's launch images guidelines.

• *-portrait
• *-landscape
• *-landscape-right, etc

Spelling

In the US, we would favor American over British spelling (sorry M'lady).

Examples

ss-top-hanger-gray.png  
ss-tree-color-swatch.png 

Not

hanger-grey.png  
colour-swatch.png 

Abbreviations

Do not abbreviate.

Examples

ss-share-facebook.png 
ss-share-twitter.png  

Not

fb.png
tw.png

Acknowledgment

This guide was inspired by the NYTimes Objective-C Style Guide and Font Awesome.

Special thanks to the following individuals for their feedback: Ash Furrow, Sergio Campama, Matteo Crippa, Marco Sousa, Dave McKinney.

Contact

• github.com/dkhamsing
• twitter.com/dkhamsing