certify_design_system_gem

certify_design_system_gem

Ruby Gem that delivers assets of the Certify Design System to Rails and Jekyll

Download

Certify Design System Gem

Certify Design System Gem This gem supplies the Certify Design System Assets to either Jekyll or Rails applications. More info on Design System can be found at the Design System Documentation Site.

Table of Contents

  • Installation
    • Requirements
    • Building
  • Usage
  • Additional Configuration
  • Testing
  • Changelog
  • License
  • Contributing
  • Security Issues

Installation

Add this line to your application's Gemfile:

For Development use the unpacked gem:

gem 'certify_design_system', path: "#{path_to_upacked_gem_files}"

Or use the GitHub Repository:

gem 'certify_design_system', git: '[email protected]:USSBA/certify_design_system_gem.git', branch: 'master'

And then execute:

$ bundle

Requirements

note: The gem has hard dependencies on the bourbon and sass gems but not the JQuery gem, as JQuery can be required through CDN (Content Delivery Network) instead. The same is the case with JQueryUI, which can be added manualy or though CDN.

For tests Jekyll, Capybara and Rails are dependencies. Test-only dependencies are listed on the Gemfile but absent from the gemspec since using it in rails doesn't require Jekyll be loaded and vice-versa.

Building

To build a gem run the rake build command:

$ bundle exec rake build

Usage

Instructions on how to use the Certify Design System components can be found at the Design System Documentation Site.

Rails

Javascript

Add the jquery-rails gem to the Gemfile

gem 'jquery-rails'

Add the following to application.js on the Rails application (JQuery must be required above the gem)

//= require jquery
//= require cds

Stylesheets

Add the sass-rails gem to the Gemfile

gem 'sass-rails'

Add the following to application.css.scss on the Rails application

@import 'cds';

Because the bourbon version required is old the gem sets this variable:

$output-bourbon-deprecation-warnings: false !default;

Rails Asset Precompile

For images and fonts you may need to precompile:

Run asset precompile $ bin/rails assets:precompile

Using SVGs in an Rails view

To use the SVGs in a Rails view, the rails image_path helper can be used inside an ERB code block.

<svg aria-hidden="true" class="sba-c-icon sba-c-icon--gold">
  <use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href=<%= "#{image_path('svg-sprite/sprite.svg')}#archive" %> ></use>
</svg>

Jekyll

Add gem to your Gemfile under jekyll_plugins. This gem requires jekyll-assets and it must be loaded before in the Gemfile.

group :jekyll_plugins do
  gem 'jekyll-assets'
  gem 'certify_design_system'
end

Add this to your _config.yml:

plugins:
  - jekyll-assets
  - bourbon

assets:
  digest: false
  sources:
    - app/assets/javascripts
    - app/assets/stylesheets
    - app/assets/fonts
    - app/assets/images
    - core

See the documentation on the jekyll-assets gem for more details.

Make sure to require JQuery before any of the javascript resources. You can use JQuery's CDN:

<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>

Because the bourbon version required is old the gem sets this variable:

$output-bourbon-deprecation-warnings: false !default;

Use the jekyll-assets tags to load assets: (The sass files can be individually loaded with the @import function into a file that is preprocessed, but the fonts may not work.)

{% asset cds.js %}
{% asset cds.scss %}
{% asset certify-sba-gov-logo_on-white.png %}
{% asset svg-sprite/sprite.svg %}

Additionally all the fonts need to me added individually:

{% asset sourcesanspro-regular-webfont.ttf %}
{% asset sourcesanspro-regular-webfont.woff %}
{% asset sourcesanspro-regular-webfont.woff2 %}
{% asset sourcesanspro-regular-webfont.eot %}

{% asset sourcesanspro-bold-webfont.ttf %}
{% asset sourcesanspro-bold-webfont.woff %}
{% asset sourcesanspro-bold-webfont.woff2 %}
{% asset sourcesanspro-bold-webfont.eot %}

Additional Configuration

Using Firefox headless instead of Chrome.

Firefox may provide a more consistent experience for testing accross environments as its screenshots are the same size regardless of retina display.

Install the geckodriver: brew install geckodriver

Make sure you don't have the gem: geckodriver-helper installed. If you have it installed you must uninstall it for Firefox to work.

Add this to test_helper_rails.rb and remove Chrome sections:

Capybara.register_driver :firefox_headless do |app|
  options = ::Selenium::WebDriver::Firefox::Options.new
  options.args << '--headless'
  options.args << '--marionette'

  Capybara::Selenium::Driver.new(app,
    browser: :firefox,
    marionette: true,
    options: options)
end
Selenium::WebDriver::Firefox::Binary.path = "#{path_to_firefox_executable}"
Capybara.javascript_driver = :firefox_headless

The path to the firefox executable is different for every machine, for example: "/Applications/FirefoxDeveloperEdition.app/Contents/MacOS/firefox".

Then switch Capybara's js driver:

Capybara.configure do |config|
  config.app_host              = 'http://localhost:7000'
  config.default_driver        = :firefox_headless
  config.javascript_driver     = :firefox_headless
  config.server_port           = 7000
  config.default_max_wait_time = 10
end

Note:

  • The test_json_asset_manifest test may not work with Firefox Developer Edition due to the way it renders JSON so use a text rendering for the JSON instead. Using text instead.
  • Setting the binary for Firefox is not ideal.

Importing as Sass.

If you wish to use the variables in the scss, be aware that that if you import cds.scss from a scss file it will look for the fonts where ever that file sits.

For example:

assets/stylesheets/my-theme.scss:

@import "cds";

body {
  background: $color-gray;
}

Then the fonts search for in assets/stylesheets thus you'll have to load them manually there.

Testing

Run bundle install and bundle exec rake test to run all tests.

Changelog

This gem uses semantic versioning. Version is stored in lib/certify_design_system/version.rb. Please look at the releases page for information on the version releases.

License

Please look at LICENSES.md for full License information.

Contributing

Please look at CONTRIBUTING.md for information on how to contribute.

We strive for a welcoming and inclusive environment for the Certify Design System project.

Please follow this guidelines in all interactions:

  1. Be Respectful: use welcoming and inclusive language.
  2. Assume best intentions: seek to understand other's opinions.

Security Issues

Please do not submit an issue on GitHub for a security vulnerability. Please contact the development team through the Certify Help Desk at [email protected].

Be sure to include all the pertinent information.

The agency reserves the right to change this policy at any time.

minimalacademicresumeportfoliodocumentationwikitailwindbootstrapdarkecommercegithub-pagesblog