Getting Started

The Comet design system offers quick ways for designers and developers to craft experiences cohesively together.

Comet is built to provide a lightweight and basic set of components and templates for web sites and apps. Comet provides an easy-to-implement starting point you can build with, and does not intend to provide solutions to all possible UX needs.

Can't find something you need? Request a style or component, and we’ll build it if it’s applicable across the portfolio. Additionally, you can use helpful smaller patterns and atomic elements as you compose components and pages of your own.

For Designers

Designers can browse guidelines on visual style including color, typography, iconography, and space as well as review each fully built component.

For Developers

As a front-end developer, you can engage with Comet in many ways:

  • Download compiled CSS to host on your product’s server along with markup you copy.
  • Build Comet source code to use nunjucks macro templates and Stylus style definitions.
  • Extend Comet’s solutions using @extends functions aligned with your markup and style.

Download the latest Comet CSS, Javascript, fonts, and icon sprite and add references to these files as link and script elements in your page <HEAD>. Include comet.js after jquery.

Download Comet v2.14.0

<link rel="stylesheet" href="/path/to/fonts/comet_fonts.css">
<link rel="stylesheet" href="/path/to/comet.css">
<script src="/path/to/jquery.min.js"></script>
<script src="/path/to/comet.js"></script>
                

Build Comet locally by downloading the latest version of the complete repository as a ZIP file or cloning the remote repository to your local machine.

Comet uses a grunt-based local environment that leverages nunjucks templates and Stylus to style components using tokens.

Visual Style

The library’s base of tokens, color, space and typography are found in the /src/library/base/styles folder and provide a foundation for cohesive visual style.

You can @import these stylus files directly into your project and take advantage of Comet variables and mixins within your project, as the library does with the /src/library/base/styles/comet.styl file.

Component Markup, Style, and Script

Comet components are a combination of style, markup and script in unique folders per component in the /src/library/components directory.

For example, the Button component is built using three files:

/src/library/components/buttons/buttons.njk

/src/library/components/buttons/buttons.styl

/src/library/components/buttons/buttons.js

All component styles are included in:

full/path/to/comet.styl

All component scripts are concatenated into:

full/path/to/comet.js

You can also refer to and import individual component stylus and Javascript.

Component Macros

All Comet components are built using nunjucks macros that you can use within your own environment. All component macros are concatenated into:

/src/library/components/comet.njk

Import component macros using this concatenated file with the following import:

{% import "comet.njk" as comet %}
                

Once imported, reference a macro directly:

{{ comet.button(variations=["primary"], text="Primary Button") }}
                

to produce the following result:

<button class="comet-button comet-button--primary">Primary Button</button>
                

Extend component styles using @extend to compose your own style and markup rather than using the markup and classes Comet provides by default. For example:

<button class=”accept-terms”>Accept Terms and Conditions</button>
                
@import “your-comet-folder/src/library/base/styles/comet.styl”;

.accept-terms {
    @extend .comet-button;
    @extend .comet-button--primary;
}
                

Starting a Page

To render Comet components properly, set the following head properties in your HTML file:

<!DOCTYPE html lang="en-us">

<head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="format-detection" content="telephone=no">
    <meta http-equiv="x-ua-compatible" content="ie=edge">
    <meta charset="utf-8">
</head>
...
                

Adding Components

Once your page refers to these assets, you can begin adding Comet components. Just copy and paste code snippets from the Comet Doc Site to use them in your project.

To add a button, include the following markup (or similarly, refer to the button macro) in your page.

<button class="comet-button comet-button--primary">
    My First Button
</button>
                

Refer to component documentation for additional snippets you can copy and paste directly into a page.

Separate Project Files from Comet Files

Avoid modifying files in /src/library/base/ and existing component files directly. Doing so will inhibit your ability to upgrade when a new version of Comet is released. Instead, consider composing your own extensions to style and components in a separate folder such as /src/library/base/extensions/ and /src/library/components/[my-new-component]/ respectively.

Browser Support

Comet supports modern browsers, including the latest Chrome and Firefox as well as Safari 6+, iOS 7+, Adnroid 4.4+, and IE11. Components are built to gracefully degrade when possible in older browsers such as IE 10.

Older Browsers

Comet does not support IE versions 10 and prior.

Some simpler components may look fine in unsupported browsers.

  • Grids will not work in IE 9 or below.
  • SVG Icons will only work if svg4everybody is included on the page. We recommend using the version bundled with your version.

Coding Conventions

When contributing to Comet, please use the following conventions when authoring markup, style and script.

HTML

  • Use soft tabs with four spaces.
  • Use indentation for nested elements
  • Use double quotes, never single quotes, on attributes.
  • Use the HTML5 doctype - <!DOCTYPE html>.
  • Set the <html> lang attribute.
  • Set IE Compatibility mode <meta> tag to x-ua-compatible.
  • Set character encoding <meta> tag to utf-8.
  • Do not add values for boolean attributes
<input type="checkbox" checked/>
                
<input type="checkbox" checked="true" />
                

CSS

  • Use soft tabs with four spaces.
  • Keep individual selectors to a single line when grouping selectors.
  • Put each declaration on its own line for more accurate error reporting.
  • Do not include vendor prefixes. Autoprefixer automatically adds these when the CSS is compiled.
  • Alphabetize properties within selectors
  • Use classes over generic element tag for optimal rendering performance.
.comet-link {
    color: $text-color-link-default;
}
                
a {
    color: $text-color-link-default;
}
                
  • Place media queries inline with component/element selectors.
.comet-component-name {
    color: $text-color-link-default;

    @media screen and (min-width: $breakpoint) {
        color: $text-color-link-alternate;
    }
}
                
.comet-component-name {
    color: $text-color-link-default;
}

@media screen and (min-width: $breakpoint) {
    .comet-component-name {
        color: $text-color-link-alternate;
    }
}
                

CSS Reset

  • The Comet team has decided to build all of its components without the use of a reset. Products that consume Comet may already be using a reset and setting our own could cause conflicts with existing products.

Stylus

  • Use semicolons, colons and brackets
  • Do not use Stylus’ sparse syntax.
  • List mixins/extends before properties
  • Reference the .stylintrc file in the repo for further Stylus formatting

Javascript

  • Reference the .eshintrc file in the repo for JS formatting

Text Editor Settings

  • Use soft-tabs set to four spaces.
  • Trim trailing white space on save.
  • Set encoding to UTF-8.
  • Add a new line at end of file