U.S. Web Design Standards 1.0

The Standards are an ever-evolving product. We’ve been listening to your feedback and using it as a basis for improvements and additions.

Here you’ll find our release notes — summaries of bug fixes, new features, and other updates introduced in each release.

Have suggestions for a new feature or bug fix? Open an issue in our repo.

Version 1.0.0

February 23, 2017

This is our first official major release. Read about our new release process and how we are updating the workflow to formally follow semantic versioning.

Fixed

• Disabled submit buttons without the usa-button class were accidentally styled via [type="submit"]:disabled. We now apply disabled styles only to .usa-button:disabled. See #1523.
• Checkbox inputs that are checked and disabled are now styled properly. See #1628.

Changes

We've made a couple of changes to our npm configuration: - We've upgraded lodash.debounce to a "production" dependency, which should solve the problem of missing dependencies for some user installations. - Our package.json now references the static "tarball" version of our release rather than the git endpoint, which means that you can npm install uswds without access to git.

The following are changes to our build tools and process that have no direct impact on the code itself: - The README, LICENSE, and CONTRIBUTING markdown documents are now included in our static and npm distributions. - Use stylelint to ensure that our SCSS files meet our own guidelines. - Measure JavaScript code coverage with istanbul and analyze coverage with code climate. - Commits (merges) to master are now automatically published to npm via our CI service.

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks: - @awolfe76

If you have questions about these upcoming changes, please feel free to email our team at uswebdesignstandards@gsa.gov.

Version 0.14.0

December 16, 2016

Fixed

• Fix styling of alert components that do not have a header #1430
• Fix government banner font glitch on smaller screen widths #1571
• Move *Required flag on forms to better placement for low vision users #1350

Changed

• Refactor header css to match the JavaScript asset restructuring work #1434
• Add ability to create a custom alert via Sass mixin
• Remove Politespace as a dependency #1385
• Use specific subset of Bourbon Neat, which allows us to remove Python as a language dependency #1554

If you have questions about these upcoming changes, please email our team.

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks:

And thank you to everyone for your comments and feedback!

Full Changelog

Version 0.13.3

December 01, 2016

Fixed

• The fonts were twice as large as they should have been. This was due to !default being added to $em-base, which created a null value for this font sizing. See #1590 for more details on the issue.
• Fix missing search box for extended header on smaller screens. See #1572 for more details on the issue.

Changed

• Added a WHOISUSING_USWDS.mdthat lists all of the websites and applications we know of that are currently using the Standards. This replaces the original wiki page. #1573
• Removed copy in the README.md around the repo split. #1589

If you have questions about these upcoming changes, please email our team.

Full Changelog

Version 0.13.2

December 01, 2016

⚠️ This release has a few known bugs: - Fix missing search box for extended header on smaller screens. #1572 - Issue around font sizing. #1590

We recommend upgrading to v0.13.3 of the Standards. If you are unable to do so, please use the attached uswds-0.13.2patch.css (un-minified) or uswds-0.13.2patch.min.css (minified) and uswds-0.13.2patch.map files on this release.

Changed

1. The header component has been broken up into more modular pieces, each with their own JavaScript tests (see code changes here). Here is the breakdown of what has been changed:
   • header/mobile is now navigation
   • header/search is now search
   • To support testing, the navigation and search JS modules both export an off() function for removing listeners added by the top-level export.
2. The utility functions for element classes (addClass(), removeClass(), and toggleClass()) have been replaced with a polyfill for the Element.classList property (see code changes here).
3. Some of the SCSS files have been reorganized (see code changes here and here). See the deprecation notes ("Upcoming backwards incompatible changes") below for more info.
4. Our README now includes more helpful instructions for users on various platforms and fixes some formatting (see code changes here).

Upcoming backwards incompatible changes

We are planning to make the following changes to the Draft U.S. Web Design Standards in future releases. In keeping will semantic versioning conventions, we will never intentionally introduce breaking changes without updating the minor and major versions accordingly. Here are the upcoming changes: 1. The Standards will no longer require jQuery or include it as part of the package you download. If you are using jQuery for other parts of your site, you will have to download it separately. It won’t come included in the Standards any more. We decided to make this change because we heard from our users that requiring jQuery for the WDS conflicted with other versions of jQuery they were already using. 2. We have reorganized some of our SCSS "partials", and will be removing the deprecated paths in a future release. If you import the USWDS into your own Sass or SCSS files, here is what you need to know: - We have replaced the SCSS all "entry point" with uswds, and set up an alias for all (_all.scss) to ease the transition for users of previous versions. Upgrade instructions: - replace@import 'all'; with @import 'uswds';, or - replace@import 'uswds/all'; to @import 'uswds/uswds'; - We have deprecated the SCSS uswds/defaults partial in favor of uswds/variables, and added !default to all of our variables so that they can be selectively overridden by a previous import. Upgrade instructions: - remove@import 'core/defaults'; or @import 'uswds/core/defaults'; - add@import 'core/variables'; if you don't import it already - move your variable customizations before @import 'core/variables'; for consistency - remove any unmodified variable declarations from your customizations to avoid accidentally overriding future changes - uswds/core/grid-settings is no longer necessary, as the grid settings are all declared in uswds/variables. Upgrade instructions: - remove@import 'core/grid-settings'; or @import 'uswds/core/grid-settings';

If you have questions about these upcoming changes, please email our team.

Full Changelog

Version 0.13.1

October 06, 2016

NEW Page templates and government banners

This release includes the addition of two different page templates and government verification banners.

Upcoming backwards incompatible change

In the near future, the Draft U.S. Web Design Standards will no longer include jQuery as part of its package. Users will be required to include jQuery(v2.2.0+) when using the Standards. If you have questions about this upcoming change, please email our team at uswebdesignstandards@gsa.gov.

Fixed

• Reduce specificity on inputs #891
• Fix search bar #1481
• Add missing 5/12 and 7/12 grid items #1383
• Fixing mobile.js from having duplicative events from firing #1496

Changed

• Add background color for thead > tr > td
• Add font smoothing mixin #1427#1440
• De-nest grids #971

Full Changelog

Version 0.12.1

September 09, 2016

This is a patch level release that adds missing images for the mobile version of the new headers component into the src directory. In version 0.12.0 they were added as part of the website/docs assets and not part of the package itself. Please use v0.12.1 in place of v0.12.0!

Full Changelog

Version 0.12.0

September 01, 2016

Updated to 0.12.1: Release 0.12.0 was missing some images for the new Headers component. You may run into issues using 0.12.0 on your project.

Please use version 0.12.1 in place of 0.12.0!

This release includes the addition of a headers component, which helps users identify where they are and provides them a quick, organized way to reach the main sections of a website. Check out our documentation to learn more about our most recently added component.

Upcoming backwards incompatible change

In the near future, the Draft U.S. Web Design Standards will no longer include jQuery as part of its package. Users will be required to include jQuery(v2.2.0+) when using the Standards. If you have questions about this upcoming change, please email our team at uswebdesignstandards@gsa.gov.

Fixed

• Fix search bar doc links to accessibility guidelines
• Design downloads on WDS site are not current #37

Changed

• Use Sass variable for font path
• Refactor JavaScript to remove jQuery dependency #1351
• IE bug on secondary links search form #1404
• New UI component: Headers and navigation #1312
• Make CSS background image path links a Sass variable #1007

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks:

And thank you to everyone for your comments and feedback!

Full Changelog

Version 0.11.1

August 18, 2016

Fixed

• Remove hash for javascript:void(0); in code examples.

Changed

• Simplify lists to use browser defaults #1091.
• Using sr-only mixin for .usa-sr-only class.
• Generate component example code using gulp tasks.
• Removing JavaScript from website #1353.

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks:

And thank you to everyone for your comments and feedback!

Full Changelog

Version 0.11.0

August 04, 2016

Accordion backwards-compatible changes

In this release, we've refactored the accordion code so that it is easier to use, less specific, and more concise. The accordion functionality from previous releases will still work and there are instructions on how to make the upgrade when it best suits the needs of your project.

Fixed

• Copyediting for 18F style

Changed

• [Search bar]: Reduce font size in 'Medium' and 'Small' bars #594
• [Image links]: Remove Firefox patch on media_link class
• [Accordion]: Code refactoring #1338
• [Website]: Update incorrect documentation on variables

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks:

And thank you to everyone for your comments and feedback!

Full Changelog

Version 0.10.0

July 21, 2016

We have been made aware that we didn't explicitly outline a backwards-incompatible change for the accordion component in v0.9.4, and we'd like to apologize for any inconvenience this may have caused you or your team. In the release notes for 0.9.4, we've added directions on how to update your accordions with these changes when you make this upgrade.

Backwards-incompatible changes version

In this release, we've made a specific backwards-incompatible change to the the structure of the scss files. Prior to this release, users could update their project specific scss variables by changing the values in _variables.scss. This release removes that file and from the core import and will require users to manually add their application-specific Sass files.

Fixed

• Remove dead link from form controls and form templates accessibility section #1313
• Small screen + landscape mode = impossible to scroll because of header height (Moto E, Android 4.4, Chrome 44) #345
• Unordered lists nested inside ordered lists appear ordered #1328

Changed

• Remove variables.scss file #1168

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks:

And thank you to everyone for your comments and feedback!

Full Changelog

Version 0.9.6

July 14, 2016

Fixed

• Fixed an incorrect reference on the typography page. #1274
• Fixed some code sample styles. #1274
• Styled the site footer by class to prevent further problems with the footer component. #1274
• Remapped routes on deployments. #1308
• Fixed linter errors. #1274

Changed

• Removed the splash page to provide quicker access to the UI components. #1274
• Added a sticky horizontal navigation bar to expand the site content. #1274
• Added our product roadmap and component maturity scale. #1274
• Eliminated the Visual Design section of the site to prevent confusion, and moved Typography and Colors into the side navigation. #1274
• Expanded the Getting Started instructions for developers and designers #1274
• Separated the design file downloads by file type. #1274
• On mobile, moved the Menu button to the right side and added collapsible sections in the mobile navigation. #1274 and #1314
• Updated the styling of the disclaimer bar to make it less obtrusive. #1274
• For each of the components, we changed the maturity levels to reflect our updated Component Maturity Scale. #1274
• We added an unstyled button mixin. #1274
• We also added a media link mixin that can be used on images inside of links to get proper focus states. #1274
• We updated the grids’ outer margins from 30px to 15px on mobile to increase viewable screen space. #1274
• We fixed the alignment of checkboxes and radio buttons (for IE11 and below) so that they’re vertically aligned. #1300
• We adjusted the max width of lead text to 75 characters. #1274
• Updated our sidenav navigation items to make the line spacing more comfortable when the menu drops to more than one line #1274
• Changed the sidenav in the page navigation so it’s displayed via Jekyll instead of CSS (this prevents CodeSniffer false positives!). #1274

We love outside contributions!

The continued success of the Standards relies on contributions from folks like you. To make a contribution, file an issue in our repo (and do let us know if you have any questions).

View the full changelog here.

Version 0.9.5

July 07, 2016

Fixed

• Links in CONTRIBUTING.md are broken #1270
• Sass build errors #1208& 1264
• Fix deploy path #1269
• "Downloadable Zip File" button doesn't follow standards #1291
• Prevent example search bars from reloading page when clicked #595
• Not all accordions work without JavaScript #1245
• Fix remaining lint issues #1190
• Input width in error state
• Inconsistent text line breaks in footer in IE 11 #460
• Removed max-width on forms #327
• Date input error width #1094
• Slim footer contact links incorrectly aligned in IE 10 #540
• "Return to top" link in footers #990
• Social media icons too small to respond consistently when tapped (multiple devices) #346

Changed

• Addition of checklist of steps to take prior to submitting a pull request
• Removed visual regression testing (trial expired)
• Addition of user testing environment https://github.com/18F/web-design-standards/issues/1249
• Create heading margin class https://github.com/18F/web-design-standards/issues/503
• Installed autopilot for zero-downtime-push
• Split up UI Components structure into individual files
• Add icons to external links https://github.com/18F/web-design-standards/issues/575
• Updated link examples and removed non-underlined text links https://github.com/18F/web-design-standards/issues/812

Visual Design Assets

The links below reference the visual design assets that have been affected by this current release. To view these assets, check out the official Github repo. - Added grid templates for desktop, tablet, and mobile (AI and Sketch) - Consolidated color palette, typography, and sticker sheet files (AI) - Added typography and color swatches to the sticker sheet file (Sketch) - Added Sketch Palette file for installing color palette in Sketch - Corrected errors in text sizes and styles (AI and Sketch) - Created separate paths for all form fields (Sketch) - Indented list style - Removed style for links without surrounding text

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks:

And thank you to everyone for your comments and feedback!

Full Changelog

Version 0.9.4

July 21, 2016

Backwards incompatible changes

In this release, there is a specific backwards incompatible change to the accordion component. Users will need to update their HTML to remove the aria-expanded="false" and aria-hidden="true" attributes from accordion panels that aren't expanded by default. This makes the content of these panels accessible without JS. This change was introduced here.

Fixed

• Navigation fix for smaller screens #1223

Changed

• Added Screener visual regression testing (trial)
• Add auto deployment to release space for QA testing on releases
• Addition of design contribution guidelines
• Update GA tracking code
• Update a11y docs on form templates and controls #792
• Line breaks on typography page #615
• Make accordion content accessible without JavaScript #1122
• Documentation pages have duplicate ids #1225

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks:

And thank you to everyone for your comments and feedback!

Full Changelog

Version 0.9.3

June 01, 2016

Backwards incompatible changes

In this release, there are several backwards incompatible changes. These changes were implemented to help in the ease of workflow, open source contributions and overall manageability of the Draft U.S. Web Design Standards repo. - Removal of dist directory from the main repository file/folder structure, refs https://github.com/18F/web-design-standards/issues/1148 - Changing 18f-pages branch to master and 18-pages-staging branch to staging

Fixed

• Image optimization
• JS and SCSS linting errors
• Radio button and table alignment
• Input box height issues in Firefox #957
• Adding unit tests #1156
• jQuery reference errors, refs #1171
• Fixing broken images on the website #1205
• Fix accessibility issues on accordion component #1181 and #1120
• Fix document outline in the footer component #794

Changed

• Adding issue and pull request templates
• Addition of gulp-autoprefixer to gulp workflow
• Moving to Circle CI and removing Travis CI
• Fixing jQuery and code preview errors #1193
• Checkbox and radio inputs from not appearing on iOS Voiceover [#1182](https://github.com/18F/web-design-standards/issues/1182]
• Making disabled button non-clickable on IE 10 #493
• Adding white background to tables #353

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks:

And thank you to everyone for your comments and feedback!

Full Changelog

Version 0.9.2

May 17, 2016

Fixed

• Broken JS references in input field toggle components JS.
• Broken jQuery reference in accordion component JS.
• Added error border style to textareas and selects, #1103.
• Mismatched variables between defaults and variables files.
• Incorrect button sizes at different screen sizes, #463.
• Typo in README, #1090

Changed

• Changed documentation to reference new URL, which is standards.usa.gov.
• Added Circle CI configuration for continuous deployment to cloud.gov.
• Changed radio/checkbox HTML example to be a better representation of the name attribute, #1107
• Removed type from select elements, #1109.

Contributors

Full Changelog

Version 0.9.1

March 29, 2016

Fixed

• Accordion component now works when there are other classes on the main usa-accordion element. #1083

Changed

• Use Bourbon's font stack variables
• Remove .ruby-version
• Rename 18f-pages yaml file to .18f-pages.yml
• Update README documentation around files and usage
• Update gulp workflow for watching changes during development
• Add copy-vendor-sass as a pre task where needed
• Remove google-fonts.css legacy file from documentation site
• Add Windows support for building the project

Full Changelog

Version 0.9.0

March 14, 2016

This version introduces several backwards-incompatibility changes that will affect usage of the Standards. Here are a few things to note as you upgrade to version 0.9.0.

Deprecated/backwards incompatible

The Draft U.S. Web Design Standards website is no longer hosted at the root level of the directory — it's now hosted from /docs. The zip file for the uswds is no longer located in the Standards repository. You can now find it on our GitHub releases page.

What’s new?

Repository folder structure

This version of the Standards has an updated folder structure, which includes several new areas that assist automation of the workflow.

This updated folder structure features /config, /src, /docs, and /dist directories at the root level of the repository. Here’s an overview of the items you’ll find in each of these directories:

/dist

This folder contains the compiled CSS and bundled JavaScript files, along with image and font files that are distributed to our users. These are the only files you need to start using the Standards in your own project.

/config

This folder contains a gulp folder with all the configurations necessary for running various gulp tasks if you want to build the Standards yourself.

/src

This folder contains all of the source files you’ll need to use before you compile the Standards that are used prior to compilation of the Standards. None of these files are minified, by any means, and they’re what you should use when you make contributions to the source files themselves.

/docs

This folder contains the Jekyll site that generates the Standards website.

Building the entire Standards website and download

If you’d like to move beyond working with the code and components included in our ZIP file and work with the files used to generate the Standards website, you can build out everything using gulp or npm.

gulp workflow

The Draft Web Design Standards uswds package (the ZIP download and the files needed to use the Standards on your project) and style guide website (our public site that displays examples of each component and the HTML code) are built using gulp. To use gulp, first make sure you've installed it on your machine globally. For more information on installing gulp, check out this document. Check out our CONTRIBUTING file to learn more about how to use the new gulp workflow.

npm installation

You can now install the Draft U.S. Web Design Standards using npm. Check out our README file to learn more about how to install using this new method and how to implement the Standards into in your project.

Kudos

We'd like to thank all the contributors who worked on our current release! We appreciate your service and all the time you spent making the Standards even better. Big kudos to the following folks: - @burgwyn - @pra85 - @lboonebah - @skonzem - @tysongach - @ismamz - @nickjs

And thank you to everyone for your comments and feedback.

Full Changelog

Version 0.8.3

January 27, 2016

• Adds package.json for npm support
• Various content updates
• Adds @jeremiak as a contributor (thank you!)
• Refactor and clarification of SCSS structure
• Updates the new naming convention as Draft Web Design Standards
• Resolves #885, #840, #863, #899, #903, #905, #906, #912, #916, #920, #949, #955.

Version 0.8.2

November 24, 2015

Adds Sketch and OmniGraffle files to design assets.

Adds various bug fixes to the web design standards.

Version 0.8.1

October 19, 2015

Adds various bug fixes to the standards site. Adds a new Change Log which includes a chronologically ordered list of notable changes for each version of the project.

Version 0.8

October 14, 2015

This is the initial release, 0.8.