# 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/grep`ing 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

## 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?

> 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
Email address
Password
File input

Example block-level help text here.

Time Picker
Number Counter
Number Slider
Media Object Inputs

#### Media heading (active)

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

#### Media heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

#### Media heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

#### Media heading (active)

Lorem ipsum dolor sit amet, consectetur adipisicing elit.

Date Picker

Check me out

Remember me

#### Validation states

Input
Input with success
Input with warning Please provide a a valid value.
Input with error Please provide a valid value.

#### Required Fields

Example
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

- Primary button example

  Table Button

- Primary button example

  Table Button

- Standard button example

  Table Button

- Standard button example

  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
Dropdowns
Back to top
Input Groups
.00
$ .00
Back to top
Navs

Back to top
Back to top
Pagination

- Prev
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- Next

- Prev
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- Next

- Prev
- Next

Back to top
Notices
This is an example of a notice that we would put at the bottom of the page. This can be fine print or messages that aren't as important as an alert. It just uses a combination of the `.panel`, `.text-muted` and `.small` classes.
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

#### 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.

#### 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.

#### 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
List Groups

- Cras justo odio
- Dapibus ac facilisis in
- Morbi leo risus
- Porta ac consectetur ac
- Vestibulum at eros

- Cras justo odio
- Dapibus ac facilisis in
- Morbi leo risus
- Porta ac consectetur ac
- Vestibulum at eros

#### List group item heading

Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.

#### List group item heading

Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.

#### List group item heading

Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.

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
Modal
Tooltips
Dynamic Tooltip Text
Dynamic Tooltip Popup Text

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!

Or use custom triggers, like focus:
Popovers & Info Icons

##### Load popover content from CMS

##### Info Icon Pattern

Popover on desktop, collapsable well on mobile

Label
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.">