--- permalink: /getting-started/ layout: styleguide title: Getting started lead: Setting the base visual language, components, and guidelines that help define the next generation of USAJOBS. ---

For developers

The UI components are built on a solid HTML foundation, progressively enhanced to provide core experiences across browsers. All users get critical information and experiences. New browsers get the prettiest experiences, while older browsers get less pretty, but usable ones. If JavaScript fails, users will still get a robust HTML foundation.

CSS

This repo sticks fairly closely to the 18F CSS Coding Styleguide with some exceptions. Read the coding styleguide first and the refer to this list for the differences:

  1. Sass (.scss) files are compiled by node-sass, a wrapper around the very fast libsass C/C++ preprocessor.
  2. rem units for positioning instead of em
  3. Sticking closer to the BEM methodology.
  4. Our architecture is a bit flatter. We have base elements (color, typography, buttons) and components made of those elements (alerts, modals, navigation). We don't differentiate between components and modules.

Preprocessing

The CSS foundation of this site is built with the Sass preprocessor language. The Sass is the scss flavor and is compiled by node-sass, a wrapped around the very fast libsass C/C++ preprocessor.

Frameworks

Uses Bourbon for its simple and lightweight Sass mixin library, and the Neat library for the grid framework. Bourbon and Neat are open-source products from thoughtbot.

USAJOBS is migrating away from Bootstrap due to the difficulty in adapting its opinionated styles to bespoke design work and the extra markup it requires in placing semantic layout instructions directly in HTML classes. This Design System is intended to replace Bootstrap over time.

Breakpoints

Media queries are built mobile first. A full table of our breakpoints can be found on the Grid page.

Architecture

  1. CSS selectors from the U.S. Web Design Standards are prefixed with usa (For example: .usa-button).
  2. CSS selectors from this design systerm are prefixed with usajobs (For example: .usajobs-button).
  3. Objects in CSS are separated by single dashes. Multi-word objects are separated by an underscore (For example: .usajobs-button-cool_feature-active).
  4. Uses modular CSS for scalable, modular, and flexible code.
  5. Uses nesting when appropriate. Nest minimally with up to three levels of nesting.
  6. Global variables are defined in the _variables.scss file. This is where custom theming can be done to change site-wide colors, fonts, etc.
  7. Hard-coded magic numbers are avoided and, if necessary, defined in the _variables.scss file.
  8. Spacing units are as much as possible defined as rem or em units so they scale appropriately with text size. Pixels can be used for detail work and should not exceed 5px (For example: 3px borders).

Where things are:

  1. HTML markup for the components are located in: _visual, _elements, _components in the site root.
  2. Sass styles are located in: _scss (/base, /element, /component). Compiled CSS is located in: css/usajobs-design-system-base.css.
  3. JS is located in: js/.
  4. Fonts are located in: fonts.
  5. Images and icons are located in: img.

Browser support:

The standards are designed to support both older and newer browsers through progressive enhancement, and officially support Internet Explorer 9 and up, and the latest versions of Chrome, Firefox, and Safari. Internet Explorer 8 and below generally see very low usage today, and most agency websites should be able to safely begin support at Internet Explorer 9.

For designers

All of the designs meet the WCAG 2.0 AA accessibility guidelines and are compliant with Section 508 of the Americans with Disabilities Act. If you choose to customize them, ensure they continue to meet the requirements listed in the “Accessibility” section of each design.

Maturity Scale

Given that we have just started to formulate the Design System the system is not yet stable. Thus some design decisions are still being considered, documentation is sparse, and components are being rapidly added and removed. Thus maturity tags will be placed at the top of each page of the Design System to help explain what state the component or element is in within the design process.

  1. Incomplete: A new addition to the system that is still under work and is not yet ready for review.
  2. Proposed: A new addition to the system, proposed by a team member, that has not yet been reviewed by the entire Design team.
  3. Under Review: A component or element that is actively being reviewed by the Design team.
  4. Design Complete: The component or element has been reviewed by the Design team and guidelines need to be created.
  5. Available: The component or element is complete and ready to be used.
  6. Deployed: The component or element has been deployed to production.
  7. Best Practice: The component or element has been deployed for some length of time and is now considered best practice.
  8. Unavailable: A previously available or deployed component or element is now considered lacking and should not be used.