Setting the base visual language, components, and guidelines that help define the next generation of USAJOBS.
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:
- Sass (.scss) files are compiled by node-sass, a wrapper around the very fast libsass C/C++ preprocessor.
- rem units for positioning instead of em
- Sticking closer to the BEM methodology.
- 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.
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.
Media queries are built mobile first. A full table of our breakpoints can be found on the Grid page.
- CSS selectors from the U.S. Web Design Standards are prefixed with
- CSS selectors from this design systerm are prefixed with
- Objects in CSS are separated by single dashes. Multi-word objects are separated by an underscore (For example:
- Uses modular CSS for scalable, modular, and flexible code.
- Uses nesting when appropriate. Nest minimally with up to three levels of nesting.
- Global variables are defined in the _variables.scss file. This is where custom theming can be done to change site-wide colors, fonts, etc.
- Hard-coded magic numbers are avoided and, if necessary, defined in the
- 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:
- HTML markup for the components are located in:
_visual, _elements, _componentsin the site root.
- Sass styles are located in:
_scss (/base, /element, /component). Compiled CSS is located in:
- JS is located in:
- Fonts are located in:
- Images and icons are located in:
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.
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.
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.
- Incomplete: A new addition to the system that is still under work and is not yet ready for review.
- Proposed: A new addition to the system, proposed by a team member, that has not yet been reviewed by the entire Design team.
- Under Review: A component or element that is actively being reviewed by the Design team.
- Design Complete: The component or element has been reviewed by the Design team and guidelines need to be created.
- Available: The component or element is complete and ready to be used.
- Deployed: The component or element has been deployed to production.
- Best Practice: The component or element has been deployed for some length of time and is now considered best practice.
- Unavailable: A previously available or deployed component or element is now considered lacking and should not be used.