uswds-rails

⚠️ Deprecation Notice (2019-05-03) ⚠️ This gem is deprecated and will no longer receive updates. Users are encouraged to use the latest version of USWDS and rails/webpacker.

A Ruby gem for integrating the U.S. Web Design System into a Ruby on Rails application.

Gem Downloads Build Dependencies Maintainability Coverage

Getting Started

Before installing and using uswds-rails, you'll want to have Ruby 2.2.9 (or newer) installed on your computer. There are plenty of ways to go about this, but my preference is rbenv. If you're developing on a Mac and using Homebrew, installing rbenv is super easy.

uswds-rails might work with other versions of Ruby, but it's developed in 2.5.1 and automatically tested against 2.2.9, 2.3.8, 2.4.6, and 2.5.1 by Travis CI.

Installation

Add uswds-rails to your Ruby on Rails project's Gemfile:

ruby '2.5.1'

source 'https://rubygems.org'
source 'https://rails-assets.org'

gem 'rails', '~> 5.1'
gem 'uswds-rails', '~> 1.4'

Run bundle install to install uswds-rails and its dependencies.

Usage

uswds-rails makes available to your Rails application the fonts, images, JavaScript files, and stylesheets from the U.S. Web Design System. Including the files varies depending on type.

The most basic integration looks like:

// In `app/assets/stylesheets/application.scss`
@import "uswds/uswds";

// In `app/assets/javascripts/application.js`
//= require "uswds/uswds";

Adding those lines to your project's application.scss and application.js will include everything from the U.S. Web Design System (fonts, JavaScript, and stylesheets).

Don't want to include the entire stylesheet in your project? Not to worry! You may include individual SCSS files by using uswds-rails' app/assets/stylesheets/uswds/uswds.scss as a guide.

Contributing

For details on setting up your development environment and contributing to this project, see CONTRIBUTING.md.

Acknowledgments

This project woudn't exist without the 18F team's hard work on the U.S. Web Design System.

uswds-rails is written and maintained by Jason Garber.

License

uswds-rails is freely available under the MIT License. Portions of the project contain code released under different licenses. See LICENSE.md for additional licensing information.