Documentation

Introduction

Core

Components

Examples

Getting Started

To get started with Circle first you need to get Sass up and running on your working directory. To make setup easier, Circle uses Compass to watch for changed Sass files and configure settings around compiled CSS output. If you don't have Compass installed you can do this by running gem install compass.

Once installed go to the root directory of your Circle project and run compass watch. Circle comes pre-configured with the correct paths to compile CSS files to the /CSS directory. This configuration also sets the default Sass syntax to .sass as opposed to .scss. To change this configuration you can edit config.rb according to your preferences.

Working with Circle

If you wish to work off of what Circle provides out of the box it is as easy as just styling from the /sass/global.sass file or create new Sass files as needed.

Disclaimer

It is highly recommended to keep any additional Sass files separate from Circle's Core and Components library. The best way to do this is to avoid modifying any files in the /sass/circle directory. The primary reason to keep this directory unmodified is so upgrading to new releases of Circle doesn't compromise your project in the future.

Organization

Circle was designed to be highly modular with the expressed purpose of allowing you to easily get started with the basics, with the option to exclude what might be uncesscesary for your project without problematic dependencies. To best make use of this organziation, Circle was divided into two parts, Core and Components. Circle Core provides basic boilerplate styling for HTML elements with the addition of a grid framework for basic layouts. Circle Components is an extended library of classes and patterns that can be used to construct common interface elements and styling.

By default, Circle comes pre-configured to include both Core and Components. If you wish to only work with Circle's boilerplate styling you can remove @import "circle/components" on line 3 of /sass/global.sass.

If you wish to further customize what parts of the Components library you may wish to exclude, you can reference the /sass/circle/components directory to see the pieces broken out.

Core

The core of Circle includes styles for grids, standard elements, buttons, and forms. All other constructions using these elements are organized under the Components section of the documentation.

Bounds

Setting the outer bounds of your layout is defined using the .bounds class. By default the .bounds class applies centering with a max-width of 1080px but can easily be edited using the $layout-bounds variable in /sass/_variables.sass.

<div class="bounds">
  <!-- Layout goes here -->
</div>

Grids

Circle's grid system is based on percentage widths columns available in increments of 5% as well as thirds. The default gutter width is 30px between columns but can be easily modified by changing the variable $grid-gutter in the /sass/_variables.sass file.

Columns in the grid system follow the following class naming pattern:

// Pattern
.grid-[width of column as %]

////////////////////////////
// Examples

.grid-50 {
  width: 50%;
}

.grid-55 {
  width: 55%;
}

// One third width of parent
.grid-33 {
  width: 33.333%;
}

// Two thirds width of parent
.grid-66 {
  width: 66.666%;
}

Examples

10%
10%
10%
10%
10%
10%
10%
10%
10%
10%
20%
20%
20%
20%
20%
25%
25%
25%
25%
33%
33%
33%
33%
66%
70%
30%
50%
50%
100%

Nesting

If you wish to nest columns inside each other, wrap the nested columns in a container using the grid-parent class.

<div class="grid-60">

</div>

<div class="grid-40">
  <div class="grid-parent">
    <div class="grid-50">

    </div>
    <div class="grid-50">

    </div>
  </div>
</div>
60%
40%
50%
50%

Push / Pull Classes

If you want to swap the visual arrangement of columns, but not affect source order, you can use .grid-push-[%] and .grid-pull-[%] classes.

Form Grids

In order to utilize the power of grids for elements that need tighter gutters than your standard grid you can use form grids by following the same conventions as standard grids but use the following pattern .grid-form-[%]. Additionally, for grid nesting, use the .grid-form-parent class instead.

Typography

Type is all set with rems, so font-sizes and spacial relationships can be responsively sized based on a single <html> font-size property. By default Circle never changes the font-size, but it's there in case you need it for your project. All measurements are base 10 though so, an <h1> with 3.8rem font-size just means 38px.

The default typefaces used for Circle are Maison Neue Medium for body type and Maison Neue Normal for display type. These typefaces can be edited from the /sass/_variables.sass file by modifying the values for $display-font or $body-font. In order to make the display font the proper bold weight, please use the $bold variable as opposed to the standard bold value for font-weight.

Additionally, each heading's font size is defined by a variable in /sass/_variables.sass for easy modification. Default sizes are as follows.

Variable Font Size
$h1 3.8rem
$h2 2.4rem
$h3 1.8rem
$h4 1.6rem
$h5 1.4rem
$h6 1.4rem

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Lists

  • Unordered lists have basic styles
  • They use the circle list style
    • Nested lists styled to feel right
    • Can nest either type of list into the other
  • Just more list items mama san
  1. Ordered lists also have basic styles
  2. They use the decimal list style
    • Ordered and unordered can be nested
    • Can nest either type of list into the other
  3. Last list item just for the fun

Buttons

Circle provides two buttons styles. The standard <button> is a basic outlined button while adding the .button-primary class makes the button more prominent with a solid colored background. Button styles are applied to a number of appropriate form elements, but can also be attached to anchors with the .button class. The color of the button can be edited using the $button-color variable in /sass/_variables.sass

<a class="button"></a>
<button></button>
<input type="button" />
<input type="submit" />
<input type="reset" />
Standard Button 
<a class="button button-primary"></a>
<button></button>
<input type="button" class="button-primary" />
<input type="submit" class="button-primary" />
<input type="reset" class="button-primary" />
Primary Button

Buttons with Icons

If you wish to put an icon inside your button you can add the .position-icon-left or .position-icon-right classes to the button to properly size and position the icon within the button.

<a class="button button-primary position-icon-left">
  <span class="icon-plus"></span>
  New Project
</a>
New Project 
<a class="button button-primary position-icon-right">
  New Project
  <span class="icon-plus"></span>
</a>
New Project

Forms

The core components of Circle provide styling for all form elements without the necessity for any additional classes. Custom variations for select menus and input[type="file"] are available.

Example Form

<form>
  <div class="grid-parent">
    <div class="grid-50">
      <label for="email">Email Address</label>
      <input type="email" placeholder="example@example.com" id="email">
    </div>
    <div class="grid-50">
      <label for="recipient">Gender</label>
      <select class="full-width" id="recipient">
        <option value="Option 1">Male</option>
        <option value="Option 2">Female</option>
        <option value="Option 3">Rather not say</option>
      </select>
    </div>
  </div>
  <label for="message">Message</label>
  <textarea class="full-width" placeholder="Your message..." id="message"></textarea>
  <label>
    <input type="checkbox">
    <span class="label-body">Send a copy to yourself</span>
  </label>
  <input class="button-primary" type="submit" value="Send Message">
</form>

Custom Select Menu

If you wish to style select menus beyond whats possible with CSS alone, Circle provides the following syntax. Simply wrap any select menu in an element with the .circle-select class.

<div class="circle--select">
  <select>
    <option>Option 1</option>
    <option>Option 2</option>
    <option>Option 3</option>
  </select>
</div>

Custom File Input

If you wish to style input[type="file"] fields beyond what’s possible with CSS alone there are two methods. The first method is by adding the .circle--input--file class on to the file input you wish to customize. Additionally you’ll need to add the data-text attribute with a value of the text you’d like for the button. There also is the option to give the button additional classes, such as button-primary, by applying that value to the data-state attribute. This method uses Javascript to wrap the input and assign the values assigned in the data-text and data-state attributes.

Syntax

<input type="file" class="circle--input--file" data-text="Upload File" data-state="button-primary" />

Output

<div class="button button-primary">
  Upload File
  <input type="file" />
</div>

The second method is if you wish to further customize your button with additonal elements such as an image or icon. Simply wrap the <input type="file" /> element in an element with the button class applied.

<div class="button position-icon-left">
  <span class="icon-plus"></span>
  Add Files
  <input type="file" />
</div>
Add Files

Tables

Table structures require being properly formed with <thead> and <tbody>.

Name Age Location
Adam Smith 67 Edinburgh, Scotland
Friedrich Hayek 92 London, England

Row Linking

Circle offers the ability to easily make entire table rows linkable to specific URL. Just add the .clickable-row along with the data-href attrubute with your URL to the <tr> tag. Optionally, you can also add the data-target attribute that acts identically to the target attribute used in <a> tags.

<tr class="clickable-row" data-href="http://www.wikipedia.com" data-target="_blank">
  <td>Wikipedia</td>
  <td>wikipedia.com</td>
</tr>

Code

Code styling is pretty basic. Just wrap anything in a <code> and it will appear like this. For blocks of code, wrap a <code> with a <pre> and it will look like the following.

This is some sample code!

Utilities

The following are some basic utility modifier classes that may be helpful in a number of situations.

Class Description
.centered Centers the element when a width or max-width is applied.
.full-width Makes the element full width by applying width: 100%.
.max-full-width Makes the element max width by applying max-width: 100%.
.hide Hides element using display: none.
.hide-text Hides text using font-size: 0.
.unloaded Removes bullets from list elements.
.align-top Aligns text to the top of the <td> when applied on a <table> or <td>.
.align-right Aligns text to the right.
.positive Assigns color to text that conveys a positive connotation (default color is green). This color can be globally defined by editing the value for the $positive variable in _variables.sass
.negative Assigns color to text that conveys a negative connotation (default color is red). This color can be globally defined by editing the value for the $negative variable in _variables.sass.
.secondary-label Assigns color to text that conveys secondary or of complimentary importance (default color is light purple). This color can be globally defined by editing the value for the $secondary-label variable in _variables.sass.

Components

Circle additionally includes numerous common components you might want to use. All components use the .circle prefix to delineate them from other custom constructions you might want to create for your own purposes. These components are all optional and will be found at the top of the sass/global.sass. You can easily include or exclude these using @import "circle/components".

Main Header

The main header component uses the .circle--header class and it's background color can be easily modified using the $header-color variable in /sass/_variables.sass.

Title

<header class="circle--header">
  <h1><a>Title</a></h1>
  <nav>
    <ul class="circle--inline">
      <li><a>Item 1</a></li>
      <li><a>Item 2</a></li>
      <li><a>Item 3</a></li>
    </ul>
  </nav>
</header>

Page Header

For headings that describe a particular page use the .circle--page--header as a container around your <h[#]> tags. Using a container with this class also sets the context for other styling of supporting lines of text. See it in action here.

<div class="circle--page--header">
  <h2>Page Title</h2>
  <p>Optional supporting text</p>
</div>

Page Title

Optional supporting text

Article Header

For article pages you can use the .circle--article--header class. Within this container you can use the .circle--article--section class for the section sub-heading, .circle--article--title for the article title, and .circle--article--byline for by lines. See it in action here.

<div class="circle--article--header">
  <h4 class="circle--article--section">Section Title</h4>
  <h1 class="circle--article--title">Article Title</h1>
  <p class="section--article--byline">Article by <a>Author Name</a></p>
</div>

Section Title

Article Title

Article by Author Name

Fluid Sandwich

Circle's fluid sandwich component offers a table layout-like structure for situations where you want two sides of a layout fixed to the width of their contents (the bread) while a middle column flexes to fill the difference (the meat). The group of classes includes .circle--fluid for the parent element, .circle--fluid--cell for each child column, and .circle--fluid--primary for the column that flexes to fill in the difference.

<header class="circle--header">
  <div class="circle--fluid">
    <div class="circle--fluid--cell">
      <h1 class="hide-text circle--logo"><a class="logo">Circle</a></h1>
    </div>

    <div class="circle--fluid--cell circle--fluid--primary">
      <input type="text" placeholder="Search" />
    </div>

    <div class="circle--fluid--cell">
      <nav>
        <ul>
          <li><a>Item 1</a></li>
          <li><a>Item 2</a></li>
          <li><a>Item 3</a></li>
        </ul>
      </nav>
    </div>
  </div>
</header>

Lists

Circle components include some variations on lists you might find useful for your applications.

Inline Lists

Using the .circle--list--inline class on lists removes the default list styling and places items inline.

<ul class="circle--list--inline">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
  <li>Item 4</li>
</ul>
  • Item 1
  • Item 2
  • Item 3

Filter Lists

Filter lists is a styling used for if you have a list of filter options and need to deliniate an item as the selected filter from the rest.

<ul class="circle--filter--list">
  <li><a class="selected">Item 1</a></li>
  <li><a>Item 2</a></li>
  <li><a>Item 3</a></li>
</ul>

Clone Lists

Clone lists are lists that let users add and/or remove list items dynamically. One common use case is a form that builds lists item by item -- a to-do list application, for example. Clone lists use the .circle--clone--list class applied to a <ul> or <ol>. Additionally, an anchor with the class .circle--clone--add needs to be nested inside the children <li> elements. Optionally, there can be an achor to remove the list item using the .circle--clone--remove class. Remove links are hidden by default in the case that there is only one list item.

<ul class="circle--clone--list">
  <li>
    <input type="text" placeholder="Item" />
    <a class="circle--clone--add">Add</a>
    <a class="circle--clone--remove">Remove</a>
  </li>
</ul>

Pilled List

Pilled lists are lists of links where one item has a selected state. Common uses could be page tabs or filters.

<ul class="circle--clone--list">
  <li><a class="selected">Item 1</a></li>
  <li><a>Item 2</a></li>
  <li><a>Item 3</a></li>
</ul>

Dropdowns

Conversation

Circle provides styling for lists of messages for instances where you might want to display a chat.

  • How are things?

    3 hours ago

  • Great! How are things? Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

    3 hours ago

<ul class="circle--message--list">
  <li class="circle--message">
    <div class="circle--avatar">
      <img src="../images/f-spore.png" />
    </div>
    <p class="circle--message--text">How are things?</p>
    <p class="circle--message--timestamp">3 hours ago</p>
  </li>

  <li class="circle--message circle--message--author">
    <div class="circle--avatar">
      <img src="../images/m-spore.png" />
    </div>
    <p class="circle--message--text">Great! How are things? Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
    <p class="circle--message--timestamp">3 hours ago</p>
  </li>
</ul>

Tables

Circle provides alternate styling for tables used for results listing.

<table class="circle--table">
  <thead>
    <th>Account</th>
    <th class="align-right">Balance</th>
  </thead>
  <tbody>
    <tr>
      <td>
        <h3>Checking</h3>
        <p>#346698-09</p>
      </td>
      <td class="align-right">
        <h3 class="positive">$5,984.23</h3>
        <p>USD</p>
      </td>
    </tr>
    <tr>
      <td>
        <h3>Savings</h3>
        <p>#346698-09</p>
      </td>
      <td class="align-right">
        <h3 class="positive">$21,481.03</h3>
        <p>USD</p>
      </td>
    </tr>
    <tr>
      <td>
        <h3>Visa Card</h3>
        <p>#346698-09</p>
      </td>
      <td class="align-right">
        <h3 class="negative">-$85.17</h3>
        <p>USD</p>
      </td>
    </tr>
  </tbody>
</table>
<!-- The .align-right class is a generic utility class that aligns text to the right -->
<!-- The .positive and .negative classes are generic utility classes for assigning colors -->
Account Balance

Checking

#346698-09

$5,984.23

USD

Savings

#346698-09

$21,481.03

USD

Visa Card

#346698-09

-$85.17

USD

Forms

Circle offers some basic sizing and grouping components for form elements.

Field Classes

For cases where you want your form fields contents to take on the styling that immitates the output, use the following classes.

Class Description
.circle--input--h1 Contents take on the styling of the <h1> tag.
.circle--input--h2 Contents take on the styling of the <h2> tag.
.circle--input--h3 Contents take on the styling of the <h3> tag.
.circle--input--h4 Contents take on the styling of the <h4> tag.
.circle--input--h5 Contents take on the styling of the <h5> tag.
.circle--input--h6 Contents take on the styling of the <h6> tag.

Textareas

By default, <textarea> do not allow for scrolling. Instead, textareas automatically grow to fit the content written within. In terms of styling empty textareas, Circle provides the .circle--input--textarea class in the case that you want the default height of a textarea to be equal to the height of a standard text <input>.

<textarea placeholder="Title" class="circle--textarea--input circle--input--h2"></textarea>

<textarea placeholder="Description"></textarea>

Search Input

Circle offers a component for search fields with a combined button.

<div class="circle--search">
  <input type="search" placeholder="Search..." />
  <button class="icon-search"></button>
</div>

Icons

Circle uses an icon set based on Feather with some custom additions. Icons are embedded as a font so they can be used in CSS or embedded directly into HTML using the appropriate class. The following table supplies the Sass variables, which map to the character codes for each icon, and classes you'll need for depending on which method you choose. All the Sass variables for icons can be found in /sass/_variables.sass

CSS Embedding

.box
  padding: 15px
  border-radius: 8px
  border: 2px solid #eee
  &:after
    font-size: 19px
    font-family: $icon-font
    content: $icon-arrow-right
    color: $link

Direct Embedding

<span class="icon-arrow-right"></span>
Icon Class Variable
.icon-chevron-down $icon-chevron-down
.icon-chevron-left $icon-chevron-left
.icon-chevron-right $icon-chevron-right
.icon-chevron-up $icon-chevron-up
.icon-arrow-up $icon-arrow-up
.icon-arrow-down $icon-arrow-down
.icon-arrow-left $icon-arrow-left
.icon-arrow-right $icon-arrow-right
.icon-message-tail-right $icon-message-tail-right
.icon-message-tail-left $icon-message-tail-left
.icon-plus $icon-plus
.icon-search $icon-search
.icon-eye $icon-eye
.icon-paper-clip $icon-paper-clip
.icon-mail $icon-mail
.icon-toggle $icon-toggle
.icon-layout $icon-layout
.icon-link $icon-link
.icon-bell $icon-bell
.icon-lock $icon-lock
.icon-unlock $icon-unlock
.icon-ribbon $icon-ribbon
.icon-image $icon-image
.icon-signal $icon-signal
.icon-target $icon-target
.icon-clipboard $icon-clipboard
.icon-clock $icon-clock
.icon-watch $icon-watch
.icon-air-play $icon-air-play
.icon-camera $icon-camera
.icon-video $icon-video
.icon-disc $icon-disc
.icon-printer $icon-printer
.icon-monitor $icon-monitor
.icon-server $icon-server
.icon-cog $icon-cog
.icon-heart $icon-heart
.icon-paragraph $icon-paragraph
.icon-align-justify $icon-align-justify
.icon-align-left $icon-align-left
.icon-align-center $icon-align-center
.icon-align-right $icon-align-right
.icon-book $icon-book
.icon-layers $icon-layers
.icon-stack $icon-stack
.icon-stack-2 $icon-stack-2
.icon-paper $icon-paper
.icon-paper-stack $icon-paper-stack
.icon-zoom-in $icon-zoom-in
.icon-zoom-out $icon-zoom-out
.icon-reply $icon-reply
.icon-circle-plus $icon-circle-plus
.icon-circle-minus $icon-circle-minus
.icon-circle-check $icon-circle-check
.icon-circle-cross $icon-circle-cross
.icon-microphone $icon-microphone
.icon-record $icon-record
.icon-skip-back $icon-skip-back
.icon-rewind $icon-rewind
.icon-play $icon-play
.icon-pause $icon-pause
.icon-stop $icon-stop
.icon-fast-forward $icon-fast-forward
.icon-skip-forward $icon-skip-forward
.icon-shuffle $icon-shuffle
.icon-repeat $icon-repeat
.icon-folder $icon-folder
.icon-umbrella $icon-umbrella
.icon-moon $icon-moon
.icon-thermometer $icon-thermometer
.icon-drop $icon-drop
.icon-sun $icon-sun
.icon-cloud $icon-cloud
.icon-cloud-upload $icon-cloud-upload
.icon-cloud-download $icon-cloud-download
.icon-upload $icon-upload
.icon-download $icon-download
.icon-location $icon-location
.icon-location-2 $icon-location-2
.icon-map $icon-map
.icon-battery $icon-battery
.icon-head $icon-head
.icon-briefcase $icon-briefcase
.icon-speech-bubble $icon-speech-bubble
.icon-anchor $icon-anchor
.icon-globe $icon-globe
.icon-box $icon-box
.icon-reload $icon-reload
.icon-share $icon-share
.icon-marquee $icon-marquee
.icon-marquee-plus $icon-marquee-plus
.icon-marquee-minus $icon-marquee-minus
.icon-tag $icon-tag
.icon-power $icon-power
.icon-command $icon-command
.icon-alt $icon-alt
.icon-esc $icon-esc
.icon-bar-graph $icon-bar-graph
.icon-bar-graph-2 $icon-bar-graph-2
.icon-pie-graph $icon-pie-graph
.icon-star $icon-star
.icon-volume $icon-volume
.icon-mute $icon-mute
.icon-content-right $icon-content-right
.icon-content-left $icon-content-left
.icon-grid $icon-grid
.icon-grid-2 $icon-grid-2
.icon-columns $icon-columns
.icon-loader $icon-loader
.icon-bag $icon-bag
.icon-ban $icon-ban
.icon-flag $icon-flag
.icon-trash $icon-trash
.icon-expand $icon-expand
.icon-contract $icon-contract
.icon-maximize $icon-maximize
.icon-minimize $icon-minimize
.icon-plus $icon-plus
.icon-minus $icon-minus
.icon-check $icon-check
.icon-cross $icon-cross
.icon-move $icon-move
.icon-delete $icon-delete
.icon-menu $icon-menu
.icon-archive $icon-archive
.icon-inbox $icon-inbox
.icon-outbox $icon-outbox
.icon-file $icon-file
.icon-file-add $icon-file-add
.icon-file-add-subtract $icon-file-add-subtract
.icon-help $icon-help
.icon-open $icon-open
.icon-ellipsis $icon-ellipsis