Note: This is still in the workings. If you have anything you want to see added into this document please leave some feedback in the comment section below; or mail me at kuroir at gmail dot com
In the recent years, we’ve been seeing a lot of improvements on the organization procedures for web applications. More specifically, the MVC Pattern; which greatly improved development speeds by imposing a well structured architecture. This allowed developers to feel at home with any application that uses the pattern.
The Model-View-Controller (MVC) Pattern is oriented to the back-end. There’s a specification about where to store your interface related code, the View, but there’s no real specification regarding how and where you should store your assets. This is where the Arrangement for View Assets (AVA) Pattern shines.
The AVA Pattern works side by side with the MVC Pattern. Both are framework and language agnostic, and independent of each other, but together you can achieve a better organization which will improve productivity, especially during advanced stages of the application.
Take these with a grain of salt and remember that you should always use what your team is accustomed to; these conventions may be modified to fit your project, however, try to follow the general idea about the structure.
For instance, you may want use snake_case over the dash-case naming pattern; these types of modifications are a matter of preference.
You may think that there's a steep learning curve involved with the AVA Pattern; however this is not true. The main objective of the AVA Pattern is to provide a written docuentation for you and your team to consult when in doubt about how to store your assets.
The main plus you'll get from the AVA Pattern is consitency. And that alone is something that is worth your time. Consistency is not something you should only want to achieve when you're working on a team with other Developers working on the Front-End but it's something you should aim for for your own sake.
Think of the following use cases:
The odds are that you're going to work alone on the project. You complete the project and months later you need to give maintenance to the project; and you completely forgot about the file structure and file names of the project.
You'll spend some time trying to figure out your own code. Wasting your precious time.
Members of the team will be looking into your code and you'll be looking into theirs. If you add up the time asking questions or figuring out how stuff is organized; you'll end up with a lot of wasted time.
As a Team Leader you know that efficiency is the key. Time is valuable for you, and you know that changes to your team is something you need to expect. Think of ho wmuch time it will take your team to figure out the work a team member left; or explain the basics to a new member.
Need to write some stuff here..
/css/ # Documented? Soon.
style.css
handheld.css
/img/ # Documented? ✓
/js/ # Documented? Soon.
tests/
qunit/
index.html
tests.js
libs/
jquery-1.5.1.min.js
jquery-1.5.1.js
modernizr-1.7.min.js
dd-belatedpng.js
plugins.js
script.js
Depending how you structure your project you may end with several files inside your img directory; having a naming onvention will save you from having to figure out how the project is structured.
The following conventions are the result of testing and polishing rules on production environment over the years.
Please keep in mind, that we don't advise to have many images in your directory; you should always<> use sprites when aplicable.
Grouping is important; especially when you're working with projects that have many assets. The following rule proposes a way to organize these files into an easy to navigate way.
RULE
IF images FROM same GROUP > 5
store in new directory
repeat RULE
else
store in root
This rule may loop a max of 3 times. Having too many levels is not advised since it may make everything more complex to mantain in the long run and will make your css file bigger.
Names for individual files should always be singular, even if they're sprites that contain several elements (sp-interface.png).
Sub-Directories a.k.a. Groups should be named in their plural form when possible. Remember, this only applies to directories. For files, use the singular variant.
This singular vs plural convention is taken from web-related paradigms (mvc, databases, etc).
background files:
bg(-group)?(-name)
sprites:
sp(-group)?(-name)
buttons:
bt(-group)?(-name)
icons:
ic(-group)?(-name)
other:
(group-)?(name)
When the file is going to have several variants, it's a good practice to append the change in type or dimension using the following pattern.
(name)(-variant)
Example:
logo-big.jpg
logo-small.jpg
ad-skyscraper.jpg
ad-midsquare.jpg
Using names as variants will allow you to change the proportions of the file without having to change any reference.
Need to document this further.
/bg-content.jpg
/bg-content-light.jpg
/sp-main.jpg
/sp-interface.png
/ic-form-submit.jpg
/placeholders/
content-big.jpg
content-small.jpg
content-medium.jpg
user-mid.jpg
user-small.jpg
- Armando Canals for his feedback.
- Cesar Salazar for his feedback.
- Chris Eppstein for his feedback.
+1 to everything here.
images are tricky because... well. i normally end up with two sprites... one is a big spritesheet, the other is a vertically very long sprite.. aside from that i rarely have other backgrounds or icon img files.