April 2
Naming
Conventions 2009
Documentation of naming conventions regarding structure, folders and Structure and
names of files, folders, classes and identifiers throughout the web.
consistency
Naming Conventions
Structure and consistency
ola.sundqvist
Why?
The use of strict naming conventions and knowledge of them will aid any designer, developer or tester
on a day to day basis. By knowing the conventions file naming and structural work will be hastened and
more effective throughout any development process.
Who?
Just about anyone working with the web in any way including designers, interaction designers,
developers, interaction developers, programmers, testers, translators.
How?
By helping out and deciding together, the patterns will be designed and followed. Most patterns will be
based on learning’s gathered through experience and previous projects such as the old Rebtel website.
When?
Starting with the new external web for Rebtel.com these patterns will be followed. Whenever a new
element is added to the website or whenever a new resource is added to a project that resource should
be introduced to the patterns.
About?
Each pattern must be described, explained with a concrete example where purpose and reason to exist
must be questioned and defended.
Page 2
Naming Conventions
Structure and consistency
ola.sundqvist
CSS
Introduction
CSS, Cascading Style Sheets are used for presentational purposes to enhance readability, usability and
presentation of marked up content. As the name applies any rule set in CSS will cascade throughout the
children of its parent. This makes this language hard to make modular as any top level rule can affect the
whole project for the better or worse.
Structure:
All CSS should be placed within a folder called /css/ in the root level of the website. This way any styling
related issue can be found in a single place. Rather than having all types of definitions in one place it has
proven more efficient to divide different types into different, shorter documents. This makes them more
modular, lightweight and problems easier to find. Below is a prioritized example of stylesheet types.
They should be loaded in that order, from the most important to the least.
Example:
1. reset.css
2. element.css
3. type.css
4. grid.css
6. layout.css
7. skin.css
Reset
This stylesheet resets all the fundamental differences between all kinds of platforms, browsers and
medias on an element level. This way, everything will look the same and no more reseting will be
required in any other stylesheet.
Element
In this document core definitions regarding layout on an element will be set and only if they apply
globally for the entire website. A selected few standalone classes can also be placed in this document to
avoid any inline styling on any page such as .clear-both, .float-right, .image-right etc.
Page 3
Naming Conventions
Structure and consistency
ola.sundqvist
Type
The core element of design is content and the core element in content is text. Any layout or design is
just a shell surrounding text and this makes the Type stylesheet the most important stone in creating
the design itself. Font, font size and font style and line heights are all set in this document. If possible,
these rules should apply to any page throughout the entire website with no overrides.
Grid
“The Grid” contains a whole bunch of classes with layout definitions for widths and margins based on a
pattern dividing up 960 or 975 pixels into 12 or 16 columns. These classes can then be used globally to
create a consistent design. These columns can then be merged into wider columns and create just about
any design where they act pretty much like cells in a table by merging columns together.
Example:
Left
Main
Right
Layout
The grid will handle most of the core layout work but it’s in this document most of the real layout work
will be done. Some layout will be put on a global level but most of the layout will be on a page level. It is
also here that we will find the most browser inconsistencies that will need fixing. Whenever there’s a
styling bug, this is where to look. Typical definitions include margin, padding, width, height, min-width,
min-height, float, position, background-position, border-width etc.
Skin
Finally, we come to what most people see, notice and care about. Colors and pictures. Once everything
has been positioned properly it’s time to add color, background color and background images. Keeping
this part separate from everything else has many uses. The rendering will look better when positioning
first and loading the heavy background images last. The skin can easily change to increase contrast or
simply co-brand the site without having to bother with the difficult layout issues.
Page 4
Naming Conventions
Structure and consistency
ola.sundqvist
Platforms, devices, browsers and media
There are multiple devices, platforms and browsers out there that all interpret markup and CSS
differently where the differences should minimized and each targeted platform should be optimized.
On top of this there are multiple mediums and resolutions in which content can be presented such as
screen, mobile and print.
Example:
/css/
/css/all/
/css/web/
/css/mobile/
/css/iphone/
/css/:
The container for all styling for the entire web including external and internal parts.
/css/all/:
Place stylings that apply to any device, platform or medium.
/css/web/:
All is web based, but folder is used to handle anything shown on a screen from 640x480 up to extreme
resolutions. 90% of all CSS will probably be placed here.
/css/mobile/:
The container for the generic website. The design is minimal and simple as is the content and structure.
/css/iphone/:
Container for the iPhone applications web based stylesheets.
Naming convention:
The CSS file structure is based on short, lowercase lettering with no prefixes or suffixes. No language
dependent content is allowed in this hierarchy structure as styling is only for presentation.
Page 5
Naming Conventions
Structure and consistency
ola.sundqvist
Examples:
The example below shows what stylesheets file would be required to render the start page.
The idea is to merge the global files for a single roundtrip to use globally. Then have a similar sub-
structure on a page level that are also merged for a second roundtrip. A similar idea could be used for
JavaScript. By loading the page specific styles later adds possibility to override global definitions without
resorting to use important flags if needed. Note that it’s always the layout and skin that differs on a page
level. PS. By using special commenting techniques, any unconventional definitions required to fix the
numerous bugs in the notorious IE6 they should all be put into a single file and loaded only by that
browser. This goes for other browsers with issues with standards as well to keep it clean for the working
ones.
/css/reset.css
/css/web/element.css
/css/web/type.css
/css/web/grid.css
/css/web/layout.css
/css/web/ie6.css
/css/web/skin.css
= Merged into a globally cached, minified and compressed file.
/css/web/home/layout.css
/css/web/home/skin.css
= Merged into a single cached, minified and compressed file on a page basis.
Reason:
Icons, Modals and advanced interactive elements are no longer used on a selected few pages but are
expected to work on any page. This is why it’s important to find a more modular approach to reduce
weight globally. If possible, it’d be great if styling could be more consolidated into a single folder, no
matter what project or platform, just like the database and business layers.
Page 6
Naming Conventions
Structure and consistency
ola.sundqvist
CSS file content
CSS definitions can be set in multiple ways.
Element level (Example):
HTML: Hi
CSS: h1 { font-size: 18px; }
NOTE: This is the most fundamental and global level that can easily be overridden.
Identifier level (Example):
HTML: Hi
CSS: h1#news { color: #666; }
NOTE: An ID has to be unique in a document. It is more important than a class and is good for JS-hooking
and as switches in the markup to apply layout and skinning.
RULES: The dash (-) character is not allowed for ID’s. Neither is it allowed to start the name with a
number.
Class level (Example):
HTML: Hi
CSS: h1.weight-1 { color: #666; }
NOTE: The by far most common and useful level. A class can be used over and over again and can be
applied to any element at any time. By adding it directly to an element the element can act as a switch.
RULES: The class name can have the (-) character but can’t start with a number.
Inline level (Example):
HTML: Hi
NOTE: We will do anything we can to avoid inline level styling as it adds clutter to the source code, slows
down rendering times, mixes up the structural and presentational layers, adds weight to database cells
and is bad for onsite SEO.
Page 7
Naming Conventions
Structure and consistency
ola.sundqvist
CSS Classes naming conventions
Casing:
lowercase
Separator:
(-), the dash character.
Pattern:
prefix-variant-name-suffix
Prefix rule:
3 descriptive characters.
Variant:
Optional. Use numbers from 0-999 to indicate generic number, size or resolution. A lower values
indicates less weight and prominence.
Name:
As long and descriptive as needed to explain the purpose of the class. Name should not describe the use
rather than describing the presentation. Words like “green” or “large” are not allowed.
Example 1:
We want to show an icon. The requirement for an icon is that it could show up anywhere and so the
inline element is both generic and allowed anywhere due to its nature. The element is
way to generic to style on an element level and we want to use several icons on a single page so the
Identifier is not good either which leaves us with the class level. In order to keep it as modular as
possible it’s a good practice to use multiple classes so as many definitions as possible can be re-used.
HTML:
CSS:
.ico { display: block; }
.ico-16 { width: 16px; height: 16px; background-image: url("/image/icon/16.gif") }
.ico-16-phone { background-position: 0 -16px; }
Page 8
Naming Conventions
Structure and consistency
ola.sundqvist
Explanation:
The .ico class only has the most generic definition. In order to set width and height on an inline element,
the display need to change type into block.
The .ico-16 class defines the width and height of this block element. As we use a sprite in this case we
can also load the background image for all 16x16 pixel icons. For sprites to work a width and height need
to be set. Icons are special as standard is 16x16, 32x32, 48x48, 64x64. Only one digit is required stating
the size. Background image for sprite is also pointed out in this class.
This leaves us with ico-16-phone that describes how the icon looks like without being too descriptive
regarding shape and color.
This means that all we need for each new icon is another background position in the grid. Note that
these classes could be used on an , or just about any other element that doesn’t already have
definitions that doesn’t suit the icon format.
Example 2:
HTML
CSS:
.btn {}
Defines cursor behaviour for all buttons. Eg, Showing a hand when hovering etc. There might be other
values to use globally for buttons.
.btn-1 {}
A simple version counter to keep any button design as generic as possibl. When we decide we want
more types and sizes of buttons it simple adds to the counter. Any definition regarding width, height,
padding etc. goes into this class and applies to any weight regarding coloring.
.btn-1-secondary {}
Another variant of the same button. For instance a more subtle, less prominent version with the same
size and shape as .btn-1-primary {}
Page 9
Naming Conventions
Structure and consistency
ola.sundqvist
Example 3:
HTML
I’m a little less prominent than another paragraph.
CSS:
P
.weight-0
.weight-1
.weight-2
.weight-3
Explanation:
The is a global element. Setting font and font-size for the paragraph globally actually controls most
of any design as this is by far the most used tag for typography. By setting a class defining weight, the
text could be set to different font-sizes, colors etc. to reduce or gain prominence of a paragraph.
My suggestion is that weight-2 should default size and color so that any definition can be overridden if
required. The values 0 is barely visible, while 1 is 50% as visible as 2. 3 and higher adds prominence using
larger font-size and strong colors and can be up to as prominent as any heading which can be useful to
keep the semantics intact.
Page
10
Naming Conventions
Structure and consistency
ola.sundqvist
CSS Identifiers
Identifiers differ in purpose, rules and conventions from classes.
Casing:
lowercase
Separator:
(_), the underscore character.
Rules:
(-), the dash is not allowed. An identifier can’t start with a number.
Pattern:
unique_name
Name:
The names should in opposite of the class names be as descriptive and semantically correct as possible.
They can have prefixes with separators as switches for larger blocks of markup.
Examples:
#header, #footer, #navigation_primary, #navigation_secondary
When to use:
Identifiers are ideal for hooking unobtrusive JS to a unique element rather than a class name. It’s faster
to parse a document for ID’s as they are unique by nature and as we can use more descriptive names,
it’s easier to read the JS code. They are also useful for switches to other classes as an identifier adds
weight to the selector and the CSS code is easy to ready where the overrides apply.
Page
11
Naming Conventions
Structure and consistency
ola.sundqvist
Folders and image names:
Naming conventions:
Don’t use trailing s
Do not use (s) in names as it is obvious a folder contains more than one file. This usually applies to table
names in databases and should apply here for the same reason.
NO: /images/
YES: /image/
Don’t use prefixes when the path does the job well
There is no need for prefixes on file names as the folder name should be descriptive enough.
NO: /image/splash/spl-try-now.gif
YES: /image/splash/try-now.gif
Use the element name on and element specific graphic
If an element can use an image globally the image should be named the same as the element.
NO: /image/bg/swirlybackground.gif
YES: /image/element/body.gif
Use resolution sizes for banners and grid sizes on sprites
If a sprite contains several images of similar shape the width x height should be used as file name.
Leading zeroes should be used if value is a leading zero shorter than the other.
NO: /image/banner/rebtel_468x60.gif
YES: /image/banner/rebtel/468x060.gif
NO: /image/icon/phone.gif
YES:/image/icon/16x16.gif (The phone icon is presented with CSS background positioning)
NO:/image/flag/IN.gif
YES: /image/flag/48x32.gif (The india flag is presented with CSS background positioning)
There’s no use having a layout specific folder as almost all graphics are layout related
If the background image is used for sliding doors it should be put accordingly with a descriptive name.
If the sliding doors are used on navigation elements it should be as generic as possible to give room for
various kinds of navigation sliding door looks.
NO: /image/layout/slidingtabs.gif
YES: /image/slide/navigation-1.gif
Page
12
Naming Conventions
Structure and consistency
ola.sundqvist
Place sliding and scaling graphics in specific subfolders with trailing number
If the background image is used in a scale-9 pattern it should be put according to descriptive name and
variant for it’s look. It is important to know in what context the image is used and what is required to
display it properly and that’s why the different contexts get their own container. It’s still important to
keep the filename generic in case color scheme will change or a new type of box will be added.
NO: /image/bg/graybox.png
YES: /image/scale/box-1.png
Use highly descriptive names on photographic or illustrated content
If a photo is uploaded it should be put in a folder defining it's size according to the grid so you know
where you can use it. Use descriptive dash separated names here rather than generic names. This way
the image will be easier to find for the editor and he’ll know how big it is and where to find them. Even
though an illustration is used in a specific context or in a wizard step, it’s better to describe the
illustration with words so that it becomes more generic and re-usable throughout the website.
NO: /image/photo/girl-8.jpg
YES: /image/photo/col-12/blond-girl-with-iphone-and-indian-boyfriend.jpg
NO: /image/illustration/hiw-1.gif
YES: /image/illustration/user-computer-laptop.gif
Page
13
Naming Conventions
Structure and consistency
ola.sundqvist
Types of images
Different types of graphic elements should be placed in a suiting container to make it easier finding
them for the editor and content provider.
Type: Buttons
Path: /button/
Description: A button is a graphic element shaped as a button. Typical buttons look inviting, eager and
stand out from the rest of the page. Usually Photoshop filters are used to achieve this design including
bevel, emboss, border, rounded corners gradients and text filtering on the label if the graphic has
textual content merged into it. When the button graphic does not contain textual content and only acts
as a background image they should be placed under slide or scale depending on how the graphic is used
by the CSS. For naming conventions a language dependant button should have a descriptive name that
states the same label as the graphic itself and then placed in a strict language dependant structure. If
there are more variants of the same button such as primary and secondary they are to be placed in a
sprite graphic where the variants are selected using background positioning.
Examples:
/language/en/image/button/try-now.png
/image/slide/button-1.png
/image/scale/button-1.png
Type: Banner
Path: /banner/
Description: A banner is a square clickable surface and is always presented as an inline image or object.
The file formats can be GIF, JPEG or SWF (Flash). Banners have previously been used internally on the
website but will now only be used for external affiliate programs and partners to promote the service
and drive traffic. Banner campaigns are often launched in multiple languages and should therefore live
under that structural tree.
Naming convention: A root folder for this type called ‘banner’ is placed directly under the image folder.
From now on the formats .gif, .jpeg, .png and .swf are all considered images and are to be placed
images. If a widget or application is created using flash it will live somewhere else as it will likely not be
language specific. A banner campaign usually contains several sizes containing the same message. This
message is written as short, snappy and descriptive as possible. This folder then holds all the files where
the names are represented by their width, height and file extension. Note that a trailing zero should be
added to keep the X and Y values similar in length. Preferably we have manual and scheduled
distribution of banner content throughout some kind of Content Delivery Network (CDN)
Example:
/language/en/image/banner/cheap-calls-to-india/468x060.gif
Page
14
Naming Conventions
Structure and consistency
ola.sundqvist
Type: Splash
Path: /splash/
Description: A splash can be shaped as a pricetag, a star or a pointy sale price shape. The splash displays
bonus values rather than a USP or call to action. It’s there to sort of tip the user over the edge by adding
that little extra carrot to convert. Commonly the splashes aren’t shaped to be clickable but it’s proven
that some users still believe they have to click the splash in order to get the bonus. It never hurts to
present the splash within a link element. It can be an image or background image of the link element
itself and is usually language dependent. Place the file in the same structural way as buttons but within
its own container.
Overall note:
We’ll strive towards using background images for everything. Including the logotype, photos and graphic
buttons. Super-small amounts of text replacement is still allowed and the advantages of a background
image is superior. It gives control of scalability using background positioning. Text can be placed in front
of a background image without having to resort to absolute positioning etc.
Page
15
Naming Conventions
Structure and consistency
ola.sundqvist
HTML – Make good use the elements at your disposal
The use of the correct element is vital to a semantic, readable and optimized markup. It is vital that all
developers are familiar with the most common elements. Used properly and developer can build stuff
without need for new markup or styling assistance.
The element is a divider of content and should only be used as such.
No text is ever to be placed out of context and should always be put inside a semantic element
such as or . In some special cases or etc. can be valid containers, but placing
the text in text or text would be preferable.
should not be used to divide or wrap content as this is an inline element. It is ideal to use
as a switch key inside a block element or to present graphic elements inside other elements, like
icons or arrows in a link where the structural value is zero.
All links should use the element no matter what. In order to make a website work without
JavaScript, it’s crucial to follow this rule. If this causes issue with page scrolling, then prevent the
default behavior which is to go to an anchor link with JS.
The element should only be used to present tabular data. Sometimes not even then.
Use and not . It's more modern and generic for styling.
Use and not . It's more modern and generic for styling.
is stronger than . Use them to highlight parts of text with various styling.
Example:
Markup showing the Rebtel logo followed by the fairly important byline.
Rebtel - Cheap international calls
Page
16
Naming Conventions
Structure and consistency
ola.sundqvist
JavaScript
The language JavaScript has evolved and become very powerful with the latest generation of browsers
and libraries. It’s easy to build really cool stuff for hours and forgetting about SEO, handicap usability,
performance and device compatibility that has little or no support for this language. The scripts can also
be large and cumbersome to maintain.
This is why it is vital to build a website that works without it. This is the way the search robot will view
our website. The JavaScript should be seen as just another layer for the vast majority of web visitors to
enhance their user experience.
In order to achieve the best of both worlds, it is important that all JS is written separately from the
structural and presentational layers (HTML and CSS).
Library:
The library of choice is JQuery for several reasons. Microsoft has built in support for it that helps us. The
library is supported by Google which makes it maintained and well documented on a daily basis. It is so
widely used that we get access to a vast library of free plugin scripts to use.
Structure
The structure for JS differs from CSS as it should not cascade in the same way. The library and plugins
are are part of a top hierarcy structure but the page specific functions are connected on a pagetype
basis.
Global:
/js/jquery/jquery-1.3.0.js
/js/jquery/jquery-1.3.1.js
/js/jquery/plugin/modal-2.0.1.js
Pagetype
/home/default.aspx
/home/default.aspx.cs
/home/default.js
Rules:
Absolutely NO HACKING of core library allowed.
All plugins for JQuery should remain as untouched as possible so they can be updated at any time.
Page
17
Naming Conventions
Structure and consistency
ola.sundqvist
Language dependant content
Content is king and just about all content based on text. This text is stored in a database. In order to get
content translated the text is exported from the database into specially formed XML-files and then
manually emailed to external translation agencies. Rebtel currently has the resources to handle
languages Swedish, English, Spanish, French and Polish. The goal is to expand the website into a total of
a dozen different languages. This is why it is vital that a language can easily be exported, translated and
imported without causing havoc in the overall layout or brings other high costs.
Give the text some space
The new website will provide for larger and more scalable content containers that should allow for
lengthier text and labels that will in no circumstances put the core layout at risk. A good policy is to
make sure that at least 30-50% extra space is left when creating an English copy based design.
Put some responsibility on the translators
If the word “mobile” becomes 4 times as long in another language, it’s time to ask if there’s a shorter
word for it. A design can handle up to a limited amount of abuse.
Structure
In order to keep track of language dependant content it’s best to somehow put it all in one place.
Preferably with some sort of validation tool that helps reducing human mistakes regarding updating,
translating and publishing.
Naming conventions
The system uses a 2 letter ISO abbreviation for all languages. All CSS-classes used for flag sprites use the
same convention and so should the file structure. The English language uses /en/. For each language
there are different types of content that can be language dependant. Any graphic content should be
placed in an image folder. In order to make import and export as simple as possible it’d be great if it
could be done in a structured way as well.
Example:
/language/
/language/en/
/language/en/image/
/language/en/content/page/home.xml (Contains all text unique to the start page)
/language/en/content/common.xml (Contains global labels such as “name”, “mobile” etc.)
/language/en/content/control/rate.xml (Contains all text used in the rate calculation application)
/language/en/content/control/signin.xml (Contains unique labels used only in the sign in application)
Page
18
Naming Conventions
Structure and consistency
ola.sundqvist
Som i CSS får en högre hierarki en lägre vikt som kan overridas längre ner.
Högst upp har vi här generella labels och länkar som ska kunna användas över hela siten.
Då jag är webnisse tänker jag i taggar och föklarar lättast så.
Varje element, oavssett om det är en länk som skapats eller uppdateras stämplas den med ett datum
och kopplas till den user som gjort uppdateringen.
Varje resurs är unik med sitt ID som kan efterfrågas och overridas längre ner med nya värden.
Attributen ”min” och ”max” talar med en siffra om hur kort eller lång en textmassa får vara i tecken.
Stämmer inte detta varnar systemet.
Attributet ”translate” är true/false och avgör om något ska översättas. Man kanske inte vill att
översättarna skall översätta visa saker. Hur vi hanterar det är en annan sak.
Common/Global
Name
Phone
Email
WebSMS
Page
19
Naming Conventions
Structure and consistency
ola.sundqvist
Sign up
Sign up with Rebtel
Tell
friends
Add
credit
Page level
Labels kan defineras på sidnivå för enkla korta texter.
Ett block kan vara vad som helst. Ofta en box med en mängd text och innehåll. Den kan innehålla vissa
HTML-taggar. Här visas exempel på hur sign up-länken hämtas ut i texten där labeln overridas på plats.
Kul vore även om viss dynamisk information kunde defineras och skrivas ut på liknande sätt för att vara
konsekvent.
Your
name
Welcome
to Rebtel!
Page
20
Naming Conventions
Structure and consistency
ola.sundqvist
We
provide Cheap International calls
So you found us?
Why dont't you try and .
is
Page
21