Style Guide

Front end development & design guide

Getting Started

This style guide is intended to help new designers, developers and content managers understand the structure and patterns of Crossroads.net.

Back to top

Coding Style

Naming

  • Use hypens '-' instead of camelCase and/or underscores '_'
  • Use all lower case characters

Spacing

  • Use soft-tabs with a two space indent. Spaces are the only way to guarantee code renders the same in any person's environment.
  • Put spaces after : in property declarations.
  • Put spaces before { in rule declarations.
  • Put line breaks between rulesets.
  • When grouping selectors, keep individual selectors to a single line.
  • Place closing braces of declaration blocks on a new line.
  • Each declaration should appear on its own line for more accurate error reporting.

Formatting

  • Use hex color codes #000 unless using rgba().
  • Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;.

Misc

  • As a rule of thumb, avoid unnecessary nesting in SCSS. At most, aim for three levels. If you cannot help it, step back and rethink your overall strategy (either the specificity needed, or the layout of the nesting).
  • Document styles with KSS.

Examples

Here are some good examples that apply the above guidelines:

      // Example of good basic formatting practices
      .styleguide-format {
        color: #000;
        background-color: rgba(0, 0, 0, .5);
        border: 1px solid #0f0;
      }

      // Example of individual selectors getting their own lines (for error reporting)
      .multiple,
      .classes,
      .get-new-lines {
        display: block;
      }
      
Back to top

File Structure

Theme Specific Styles

In general, the Sass files for the project will live in /app/scss. Within that directory, there are subdirectories that we use to organize the code.

  • Base: The base/ folder holds what we might call the boilerplate stuff for your project.
  • Helpers: The helpers/ folder gathers all Sass tools and helpers we’ll use across the project, including variables and overrides to Bootstrap.
  • Layout: The layout/ directory contains files which set up styles for the main sections of the layout (header, footer, and so on).
  • Modules: For smaller components, there is the modules/ folder. While layout/ is kind of macro (defining the global wireframe), components/ is more micro. It can contain all kinds of specific modules like a slider, a loader, a widget, or anything along those lines.
  • Pages: If you have page-specific styles, put them in a pages/ folder and in a file named after the page.
      app/
      |
      └── scss/
        |
        ├── base/
        |   ├── brand.scss                 # Crossroads colors, etc
        |   ├── typography.scss            # Typography rules
        |   ...                            # Etc…
        |
        ├── helpers/
        |   ├── style-overrides.scss       # Override Bootstrap styles
        |   ├── variable-overrides.scss    # Override Bootstrap variables
        |   ...                            # Etc…
        |
        ├── layout/
        |   ├── footer.scss                # Footer styles
        |   ├── forms.scss                 # Form styles
        |   ...                            # Etc…
        |
        ├── modules/
        |   ├── billboard.scss             # Ad Boxes
        |   ├── brandbar.scss              # Brandbar
        |   ...                            # Etc…
        |
        ├── pages/
        |   ├── home.scss                  # Home specific styles
        |   ├── blog.scss                  # Blog specific styles
        |   ...                            # Etc…
        |
        |
        └──  main.scss                     # primary Sass file
      

Module Specific Styles

If a component of the site is turned into an Angular module, then the structural styling for the module will live outside of the app/scss directory. The styling that is required by the module to work on it's own should live in that's module directory. An example of this is the Profile module. If you have styling for the module that is just theming (colors, typeography, etc) and not structural, then it should live in the scss folder: app/scss/modules/profile.scss

      modules/
      └── profile/                        # Example using the Profile module
        └── app/
          └── css
            └── module.scss               # Non-theme module styles
                ...                       # Etc…
      
      app/
      └── scss/
        └── modules/
            └── profile.scss             # Theme styles for the Profile module
      
Back to top

Class Naming Conventions

  • Use (single) dashes in class names.
  • Keep things as short as possible without adding confusion.
  • For State rules, use is- as in is-hidden or is-collapsed.
  • To extend a module, use subclasses. With sub-classing the module, both the base module and the sub-module class names get applied to the HTML element. (eg. .pod, .pod-constrained, .pod-callout)
  • As a rule, it is unwise to bind your CSS and your JS onto the same class in your HTML. Please refer to our Javascript Style Guide for further explanation.
Back to top

Specificity (classes vs. ids)

Elements that occur exactly once inside a page can use IDs, otherwise, use classes. When in doubt, use a class name.

  • Good candidates for ids: header, footer, modal popups.
  • Bad candidates for ids: navigation, item listings, item view pages (ex: issue view).

CSS Specificity guidelines

  • If you must use an id selector (#selector) make sure that you have no more than one in your rule declaration. A rule like #header .search #quicksearch { ... } is considered harmful.
  • When modifying an existing element for a specific use, try to use specific class names. Instead of .listings-layout.bigger use rules like .listings-layout.listings-bigger. Think about ack/greping your code in the future.
  • The class names disabled, mousedown, danger, hover, selected, and active should always be namespaced by a class (button.selected is a good example).
Back to top

Prefixes

We use Autoprefixer to parse CSS and add vendor prefixes to CSS rules using values from Can I Use. For that reason, you do not need to include any vendor prefixes in your SCSS.

Back to top

Colors

$primary
$brand-secondary
$cr-dkblue
$cr-grey
$success
$info
$warning
$danger
$gray-darker
$gray-dark
$gray
$gray-light
$gray-lighter
Back to top

Icons

We use inline SVGs with the <use> element for icons. For more information as to why, read here.

  • Icons that are already being used in the system are all listed on the Icon Preview Page.
  • To use one of these icons, just click the "Show Snippet" button and copy the code.
  • We also have a library of approved icons that you can add to the project as well. To see these, view our Approved Icon Library.
  • To add any of these icons to the project:
    1. Clone the 'icon-library' repo.
    2. Find the icon you would like to use in the project. Make sure to double check that we haven't already included it.
    3. Copy the SVG file for the icon you want to use from the icon-library directory in to the "/app/icons/" directory in the crossroads.net repo.
    4. Run 'gulp' on the crossroads.net project. Your icon will now be included in the project.
Back to top

Preloader

Used to indicate the site is waiting for something to load. Use <preloader full-screen='false'> </preloader> to display in an element. When used for a whole page, you just have to make sure all of your data is being resolved in the route. This uses <preloader full-screen='true'> </preloader> .


Back to top

Layouts

We've created a hierarchy of layouts as follows:

NOTE: This does not work in current environment. Will be done in future.
      base: Basic structure, including head elements
        |
        ├── default: Adds a Header and Footer
        |   |
        |   └── container: Adds the container wrapper
        |    |
        |    ├── container_row: Adds the row wrapper
        |    |   |
        |    |   ├── one_column: Central content section only
        |    |   |   |
        |    |   |   └── post: Adds post meta data (title and date)
        |    |   |
        |    |   ├── left_column: Adds a left sidebar section
        |    |   |
        |    |   └── right_column: Adds a right sdiebar section
        |    |
        |    └── row: Adds the row wrapper, without a container wrapper
        |        |
        |        └── full_width: Spans the entire page width
        |
        └── full_page: No header or footer, complete flexibility within the body
      

Layout Examples

Click to view example:

  • No Side Bar
  • Screen Width
  • Left Sidebar
  • Right Sidebar
  • No Header or Footer
Back to top

Headings

Page Header

Page Header

With A Subheading

This is an h1 heading

This is an h2 heading

This is an h3 heading

This is an h4 heading

This is an h5 heading
This is an h6 heading
This is a Small Heading (.small-heading)
Tables
# First Name Tables
1 Michael Are formatted like this
2 Lucille Do you like them?
3 Success
4 Danger
5 Warning
6 Active
# First Name Tables
1 Michael This one is bordered and condensed
2 Lucille Do you still like it?
Back to top
Content Formatting

This is a lead paragraph.

This is an ordinary paragraph that is long enough to wrap to multiple lines so that you can see how the line spacing looks.

Muted color paragraph.

Warning color paragraph.

Danger color paragraph.

Info color paragraph.

Success color paragraph.

Emphasis color paragraph.

This is text in a small wrapper. NBD, right?


Twitter, Inc.
795 Folsom Ave, Suite 600
San Francisco, CA 94107
P: (123) 456-7890
Full Name
first.last@example.com

Here's what a blockquote looks like in Bootstrap. Use small to identify the source.

  • Normal Unordered List
  • Can Also Work
    • With Nested Children
  • Adds Bullets to Page
  1. Normal Ordered List
  2. Can Also Work
    1. With Nested Children
  3. Adds Bullets to Page

function preFormatting() {  // looks like this;  var something = somethingElse;  return true;}
Back to top
Forms
Legend

Example block-level help text here.



Validation states

Please provide a a valid value.
Please provide a valid value.

Required Fields

Back to top
Buttons

Main Buttons

The Primary .btn-primary is used as the Call to Action button. It should never be used as a standard button type.
The Standard .btn-standard is to used for all buttons that aren't the Call to Action.

Alternative Buttons

The Secondary .btn-secondary is used as a secondary call to action. It should never be used as a standard button type, or as the primary call to action.

The Standard (Dark) .btn-standard-dark is used as a standard button, but when the background color of the containing container calls for it.

Default Button

This is the bootstrap default button .btn-default that is used by many third party libraries. It can be treated as a standard button, primarily, when attached to a form element. i.e. Datepicker.

Button Link

Button Sizes

Use .btn-block-mobile on form submit buttons so they are smaller on desktop, and expand to full width on mobile.

Glyphicons

Alert Buttons

These buttons are to be used only inside an alert as shown in the example below.

Example

Heads up! This alert needs your attention, but it's not super important.


Loading States

The .disabled class is added to a button while loading.


Table Button

Back to top
Images

We use IMGIX to serve our images. This service assures the correct image size is delivered to the browser based on the size of the container and viewport of the device used to view the page.

Images are hosted on Amazon S3 but served from IMGIX, use the data-src="//crds-cms-uploads.imgix.net/content/images/ along with class imgix-fluid to take advantage of this service.


Rounded Edges with class img-rounded

Circles with class img-circle

Thumbnails with class img-thumbnail


For background images, the data-src needs to exist on the contain with the background along with class imgix-fluid-bg. Use class img-background to make the image cover the contain and center.

BACKGROUND IMAGES

Back to top
Back to top
Input Groups

.00

$ .00
Back to top
Back to top
Back to top
Back to top
Notices
Back to top
Alerts

Growl-style alerts will appears in a fixed position in the top center of the page.

Oh snap! Change a few things up and try submitting again.

Well done! You successfully read this important alert message.

Warning! Better check yourself, you're not looking too good.

Heads up! This alert needs your attention, but it's not super important.
Back to top
Labels and Badges
Default Primary Standard Secondary Standard (Dark) Success Warning Danger Info

Inbox 42

Back to top
Progress Bars
60% Complete
40% Complete (success)
20% Complete
60% Complete (warning)
80% Complete (danger)
35% Complete (success)
20% Complete (warning)
10% Complete (danger)
Back to top
Media Object
64x64

Media heading

Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin commodo. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis. Fusce condimentum nunc ac nisi vulputate fringilla. Donec lacinia congue felis in faucibus.
64x64

Media heading

Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin commodo. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis. Fusce condimentum nunc ac nisi vulputate fringilla. Donec lacinia congue felis in faucibus.
64x64

Nested media heading

Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin commodo. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis. Fusce condimentum nunc ac nisi vulputate fringilla. Donec lacinia congue felis in faucibus.
Back to top
Back to top
Panels
This is a header
This is a panel
This is a header
This is a panel
This is a header
This is a panel
This is a header
This is a panel
This is a header
This is a panel
This is a header
This is a list group panel
  • First Item
  • Second Item
  • Third Item
Back to top
Wells
Look, I'm in a well!
Look, I'm in a large well!
Look, I'm in a small well!
Back to top
Heros

This Is a Hero

Text is centered both vertically and horizontally.

Back to top
Billboards

.billboard-label

.billboard-headline


.billboard-subheadline

.billboard-label

.billboard-headline

.billboard-subheadline

"It's a great feeling to serve others who are less fortunate in our city, and it's what God calls us to do."

Back to top
Login Form
Back to top
Register Form
Back to top
Tooltips

Pellentesque {{styleguide.dynamicTooltipText}}, sit amet venenatis urna cursus eget nunc scelerisque viverra mauris, in aliquam. Tincidunt lobortis feugiat vivamus at left eget arcu dictum varius duis at consectetur lorem. Vitae elementum curabitur right nunc sed velit dignissim sodales ut eu sem integer vitae. Turpis egestas bottom pharetra convallis posuere morbi leo urna, fading at elementum eu, facilisis sed odio morbi quis commodo odio. In cursus delayed turpis massa tincidunt dui ut.

I can even contain HTML. Check me out!

Popovers & Info Icons

Load popover content from CMS

Info Icon Pattern

Popover on desktop, collapsable well on mobile

Additional info content. Pellentesque dynamic, sit amet venenatis urna cursus eget nunc scelerisque viverra mauris, in aliquam.
Cards

Profile Card Name

Profile Card Text

  • SHARE:

Profile Card Name

This image will be stacked on mobile.

  • SHARE:

Cards v2.0
Commodo Condimentum Euismod

Mattis Purus Vulputate

Lorem ipsum dolor sit amet consec te tur adipiscing elit, sed do eius mod tempor incididunt ut labore et dolore magna aliqua.

Dolor Porta Vulputate

Fusce Amet Consectetur Ornare

Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Maecenas faucibus mollis interdum.

Elit Inceptos

Ornare Vehicula Dolor

Fusce dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus. Nullam id dolor id nibh ultricies vehicula ut id elit.

Social Share
Large (32 x 32px)
Medium (20 x 20px)
Small (16 x 16px)
With Tooltips
With Custom URL Info
Note: To set your own custom URL information, change the directive's opening tag from:
<sn-addthis-toolbox class="addthis_crossroads_sharing clearfix addthis_32x32_style">
With this (using example.com):
<sn-addthis-toolbox class="addthis_crossroads_sharing clearfix addthis_32x32_style" data-url="//www.example.com" data-title="Example Homepage" data-description="Here is the Example description.">