This style guide should help two types of readers
- It should help developers who are making new pages. They should find a description of the recommended styles.
- It should help users who are modifying the style sheet for a space by pasting modified styles into the Admin/Appearances page.
Where to put style sheets
We package our style sheets into a single file on the production server, using a plugin called asset_packager. This makes pages load faster. If you want to add a style sheet that will be used on more than one page, please add it to a list of style sheets in config/asset_packages.yml. Then, it will be included in the layout if you use stylesheet_link_merged with the package name, like
<%= stylesheet_link_merged :base_app_and_alerts %>
Naming conventions
We use lowercase letters to name page elements and use hyphens to separate words. E.g.: panel-info, add-team-members, etc.
Fonts, units and colors
A base font 12px Verdana with a line-height of 18px is used throughly the interface. This gives us a nice 18/12 = 1.5 ratio. This is a sort of "magic mumber" with appears often in the stylesheet. Where applicable we set margin, padding and widths to be multiple or submultiple of 1.5. That's why you see odd numbers like .375em and .75em all over the place.
Verdana does not look good at bigger sizes, hence Arial font (Helvetica as a fallback) is used for heading and subheading (h1, h2, and so on). The h1 element is reserved to specify space and user names on the header, while h2 is used to markup the current page title and other important items on the page.
Apart from setting the base font wherever feasible we use em units instead of pixels in the stylesheet to make the entire UI zoomable. Since ems are proportional to the used font, this means that in modern browsers (Firefox, Opera, Safari, IE7+, etc.) changing the text zoom will expand dimensions of layout elements accordingly.
Colors
Most of the UI elements use black (hex 000000) on white (hex ffffff). We use some additional colors to grab user attention.
hex 2E4B73 Dark blue::
Used in the header.
hex 5375A6 Blue::
Used in the header, to create contrast with dark blue.
hex 15478C Deep blue::
All of the links in the #content div use this color.
hex E7FABB Light green::
Used for boxes, and background color of tabs and action links (edit, add, etc.)
hex FFF8A6 Yellow::
Used for boxes.
hex EEEEEE - Light gray::
xxx
Column layout
First of all, let's see how layout divs made up the page. This layout is repeated in all pages, and it is contained in the views/layout/application.rthml file.
+------------------------------------+ | #header-w | | +--------------------------------+ | | | #header | | | +--------------------------------+ | +------------------------------------+ +------------------------------------+ | #main-menu-w | | +--------------------------------+ | | | #main-menu | | | +--------------------------------+ | +------------------------------------+ +--------------------------------+ | #content | | | | ...view markup here... | +--------------------------------+ +------------------------------------+ | #footer-w | | +--------------------------------+ | | | #footer | | | +--------------------------------+ | +------------------------------------+
the *-w variants are container wrappers which let us to stretch contents up to browser full page width.
Typically each view customizes #content markup.
Let's see how one can easily build a multicolumn layout using a couple of built-in styles.
Main content plus sidebar (flexible)
+----------------------+ | .main-col-w | |+--------------------+| +---------+ || .main-col || |.side-col| || || | | || || | | |+--------------------+| +---------+ +----------------------+ <!-- don't forget to clear float! --> <div class="cut"> </div>
We need two boxes called main-col-w and main-col to build a main-content-and-sidebar configuration since users may want to apply some custom styles in spaces. We are using the ''negative margin'' technique to maintain the column source order (first the content, then the sidebar) and to add some flexibility to the styling process.
Default style applied to styles does not stretch #content width, but we have a stock custom styles called flexible which does exactly that (see below).
Main content plus sidebar (fixed)
We just mentioned the importance of the main-col-w div, however in views not called by the space and the various tool controllers you can simplify the configuration described above and just build something like this:
+--------------------+ +---------+ | .main-col | |.side-col| | | | | | | | | +--------------------+ +---------+ <!-- don't forget to clear float! --> <div class="cut"> </div>
Two equal-width columns
+--------------+ +--------------+ | .col | | .col .last | | | | | | | | | +--------------+ +--------------+ <!-- don't forget to clear float! --> <div class="cut"> </div>
Note that, since col class applies a right margin, we need to apply a last class to the second column (use the HTML class="col last" syntax to do that), so the right margin will be set to zero and the second column will not wrap.
Using full #content width
You may want to stretch #content children elements to the full width of the parent. To do that do not declare any columns and put elements directly on the view.
All together now
You can stack different column configurations on a single view, just remember to clear the float after each group, like shown in the diagram below.
+----------------------+ | .main-col-w | |+--------------------+| +---------+ || .main-col || |.side-col| || || | | || || | | |+--------------------+| +---------+ +----------------------+ <!-- don't forget to clear float! --> <div class="cut"> </div> +---------------+ +---------------+ | .col | | .col .last | | | | | | | | | +---------------+ +---------------+ <!-- don't forget to clear float! --> <div class="cut"> </div>
Styles used in all parts of the application
Main
Header
Content
Right column
Prompts displaying data
Informational and warning panels
We have a couple of panels defined: panel-info (yellow) and panel-critical (pink). They are put on top on the #content div, and they may contain other markup. As an example here's some markup taken from the wiki:
<div class="panel-info"> Viewing version <%= @page_version.version %> created <%= time_ago_in_words(@page_version.updated_at) %> ago by <%= page_version_user(@page_version.user_id) %>. </div>
Do not confuse these panels with the ones (also pink) which appear when form validation errors are raised by the system. Those are wrapped by and .errorExplanation div (see blue_form.css) and generated automatically by helpers methods.
Forms
Please see the StyleGuideForms page.
Top Tabs
Styles used in a space page
Flexible
#content {
width:auto;
margin: 3em 3em;
}
.main-col {
margin-right: 16em;
width: auto;
float: none;
}
.main-col-w {
width: 100%;
float: left;
margin-right: -14em;
}
.side-col {
float: right;
width: 14em;
}
Flexible (sidebar on the left)
Same as above with sidebar on the left, not on the right (the default).
#content {
width:auto;
margin: 3em 3em;
}
.main-col {
margin-left: 16em;
width: auto;
float: none;
}
.main-col-w {
width: 100%;
float: right;
margin-left: -14em;
}
.side-col {
float: left;
width: 14em;
}
