Introduction
These guidelines are intended to help make Songbird’s CSS
consistent, efficient, maintainable, and accessible to feathers
developers. The rules represent a tradeoff between readability,
efficiency, and existing Mozilla/Songbird conventions.
Use this document when reviewing CSS changes and working on
the existing code base. If you see rules that could be improved, create
a patch.
Conventions
Formatting
- Two-space indenting
- At least two lines between sections
- Braces on their own lines
- One selector or declaration per line
Example:
.faceplate-intro-image
{
list-style-image: url(chrome://songbird-branding/skin/faceplate.png);
}
- Prefer shorthand declarations.
Example:
margin: 0px;
instead of
margin-left: 0px;
margin-right: 0px;
margin-top: 0px;
margin-bottom: 0px;
Comments
Start each file with a header that explains what the file contains,
why it exists, and briefly how it fits into the rest of the CSS
architecture.
Example:
/**
*******************************************************************************
WEB TOOLBAR IMAGES
Applies images to the toolbar buttons in browserToolbarOverlay.xul.
Imported by bindings.css or directly into feathers.
*******************************************************************************
*/
Within files, clearly label each section with what it controls and
why. Use whitespace to separate your sections for easy scanning.
Example:
/** The home button **/
Naming
General
- Make class names self documenting. Avoid short cryptic names and abbreviations.
- Name classes based on what they represent, not what they (currently) look like. For example, use .error-box instead of .red-box
- Always use lower case characters. Classes and IDs are case sensitive, so please keep this consistent.
- Use “sb-” only when matching tag names or if needed to avoid confusion. Avoid arbitrarily adding “sb” and “songbird” prefixes.
- Use words that are consistent with other parts of the application, Mozilla, and CSS in general. For example, use “top” instead of “north”, since that is the language used in XUL and CSS
- Use underscores as separators in IDs and hyphens in class names. The Mozilla standard is to avoid underscores, but this is the scheme Songbird has used since day one, and there is no point in changing it now.
XBL Classes
Within XBL widgets, use the format .[widget name]-[description or purpose]-[target element].
Example:
.button-menu-dropmarker
A selector such as "button dropmarker" would be preferable from a
maintenance and readability standpoint, but is prohibitively expensive.
Usage Considerations
Efficiency
CSS rules have a significant impact on Songbird’s performance.
Before contributing CSS patches you should make sure you understand how
Mozilla’s style system works.
Key points:
- Avoid the descendant (space) selector whenever possible
- Prefer single classes or IDs above all other selectors
Sandboxing
- Prefer rules that are either very specific or intentionally very general. For example, make sure you are applying your background image to the button box only, not the box, the label, and the image
- Prefer sandboxing with single or multiple classes only. Use the child selector as a last resort
Example:
.sb-player-volume-slider.miniplayer { }
XBL
In general we emulate Mozilla’s approach to styling XBL. The largest
difference is that our widgets do not directly include their own CSS.
We leave the loading of all CSS up to feathers developers.
Key points:
- Use classes, not IDs, when styling widgets. IDs should be used
for things that occur once. XBL widgets may appear many times per
window, so styles should by applied using classes.
- If possible, we’d like ONLY single class selectors. Child selectors are needed in some cases though, and are forgivable.
- Split CSS into per widget or per widget family style sheets in app/skin/bindings.
Images
- Avoid hardcoding image URLs into XUL or Javascript
- Prefer list-style-image over background-image, since
list-style-image can automatically define the dimensions of the
element, and is generally inherited down to the correct anonymous
element within XBL widgets
- Be especially aware of the scope of your image rules. For
example, if you assign a list-style-image to a clickhold button, the
image will show up in both the button icon AND the drop down menu items
- Reduce load time and prevent flickering by placing multiple
button states into a single image. Use –moz-image-region and
background-position to change the viewable area for :active and :hover
states
- Image files should be placed in the feathers unless they are somehow common to all skins
!Important
The !important keyword overrides normal cascading and specificity
rules. This is a useful feature, but can cause severe maintenance
problems if used indiscriminately.
When you’re not sure why your rules aren’t applying it can be
very tempting to use the !important keyword. This may be satisfying in
the short term, but creates an escalating arms race and dependency
nightmare. Take your time, use DOMInspector, and make sure you
understand the problem.
You should only use !important when, for example, you need a
class rule to win out over an ID rule, or are battling an
existing !important rule. If you use !important you should justify why
you think it is necessary.
Organization
- Use nested @import statements to aggregate CSS from multiple
files. Modularizing the CSS makes development easier, and allows
feathers developers to selectively include existing rules without
copying and pasting
- Group rules by window, widget, and context, not by appearance or rule similarity
- Make sure all color rules are located in the feathers
packages. Color rules can exist in other packages, but should always be
overridden by the feathers
- Separate window layout rules, widget rules, and feathers specific rules.
Preprocessing
- Do not use the preprocessor for feathers CSS, or any other CSS
that will be used by external developers (e.g.
chrome://songbird-bindings/skin/). Assume most feathers developers will
not be using our build system
- Using the preprocessor in the Songbird global skin is
acceptable, as it is a set of base rules for all platforms, and should
not be copied by feathers developers
Tools
DOM Inspector
Always, always, always use the DOM Inspector
when making CSS changes. Make sure you understand the problem you are
trying to solve, and that your rules are applying as you expect.
Error Console
Look at the error console (Tools > Error Console on the main
menu) before checking in CSS changes. The style system will ignore
rules that contain syntax errors, creating headaches for developers who
try to maintain the CSS.
