A gem including base styles and javascript for Code for America products, for use in Rails applications.
View the current version of the styleguide at https://honeycrisp.herokuapp.com.
We are not currently seeking contributions from the public.
If you have any thoughts or questions about the project, get in touch at styleguide@codeforamerica.org or the #honeycrisp-design-system channel in the Code for America Slack.
Add this line to your application's Gemfile:
gem 'cfa-styleguide', git: 'https://github.com/codeforamerica/honeycrisp-gem', branch: :mainAnd then execute:
$ bundleOr install it yourself as:
$ gem install cfa-styleguideThe styleguide gem is pre-1.0.0 release, and should be considered as being in beta.
We do our best to keep things stable between minor version releases; however, decisions about deprecation and breaking changes are made given our knowledge about the usage of the gem by active projects maintained and developed by Code for America staff.
When upgrading the gem between patch versions (e.g. 0.7.1 to 0.7.2), expect no breakage.
When upgrading the gem between minor versions (e.g. 0.7.1 to 0.8.0), be sure to review the changelog and migration guide.
If you encounter any breaking changes that we have not documented, please let us know by opening an issue!
To use the Honeycrisp CSS, you have two options:
@import 'cfa_styleguide_main'; to application.scss. This file includes all SCSS present in the gem.To use selectively (recommended), import individual SCSS files into your application.scss. Here is an example:
/* Vendor */
@import 'bourbon';
@import 'neat/neat';
@import "normalize";
@import 'honeycrisp/atoms/variables';
@import 'variables'; // example of in-app overide
/* Atoms */
@import 'honeycrisp/atoms/grid';
@import 'honeycrisp/atoms/base';
@import 'honeycrisp/atoms/spacing';
@import 'honeycrisp/atoms/utilities';
@import 'honeycrisp/atoms/typography';
/* Molecules */
@import 'honeycrisp/molecules/data-table';
/* Organisms */
@import 'honeycrisp/organisms/sidebar';
/* Templates */
@import 'honeycrisp/templates/styleguide';
/* Your custom SCSS */Note: If you take this approach, be sure to include bourbon, neat, and normalize, as they are vendorized dependencies for our grid system and other styles.
Add //= require cfa_styleguide_main to application.js.
Add mount Cfa::Styleguide::Engine => "/cfa" to routes.rb.
Visit any of the following routes to view the styleguides:
`<your hostname>/cfa/styleguide`
`<your hostname>/cfa/styleguide/cbo-dashboard`
`<your hostname>/cfa/styleguide/cbo-analytics`
`<your hostname>/cfa/styleguide/current`
`<your hostname>/cfa/styleguide/custom-docs`cfa_styleguide_main.scssTo override the styleguide's variables (e.g. use #000000 for $color-background rather than as defined in the gem), require your own file that redefines the variables in your application.scss like so:
```scss
@import 'my_variable_file'
@import 'cfa_styleguide_main'
``` To use variables provided by the style guide gem remove require_tree directives from your application.scss and use use @import statements instead (from stack overflow)
```scss
# do not use
*= require_tree .
```
```scss
# use instead
@import 'things_to_import'
```git clone).ruby-versiongem install bundler -v "$(grep -A 1 "BUNDLED WITH" Gemfile.lock | tail -n 1)"
gem install bundler you usually get Can't find gem bundler (>= 0.a) with executable bundle (Gem::GemNotFoundException), more details herebin/setup to install dependencies.You must install Chromedriver to run tests; on MacOS with Homebrew, run brew bundle install
Run bin/rails s to start a webserver with a test app that has the engine mounted, then visit http://localhost:3000.
If the gem is being used in another project's Gemfile, the source can be locally overridden within the other project's Gemfile in two ways:
Change the bundler configuration to use the local gem repository
In the terminal, run bundle config local.cfa-styleguide /path/to/honeycrisp-gem
To install this gem onto your local machine, run bundle exec rake install.
When finished with development, remove this configuration by running bundle config --delete local.cfa-styleguide and bundle install
Change your Gemfile to point to the local gem repository
Alternatively, you can change host project's Gemfile to point to a local copy of this repository. For example, changing:
gem 'cfa-styleguide', '~> 0.7', github: 'codeforamerica/honeycrisp-gem'to
gem 'cfa-styleguide', '~> 0.7', path: '../honeycrisp-gem'where ../honeycrisp-gem is the path (relative or absolute) to this repo on the local filesystem.
After updating the Gemfile with these changes, you will need to run bundle install.
When finish, just revert the Gemfile to the original version and bundle install again.
Run rake assets:package
Check the dist directory for all the assets required and copy/paste them into your project!
A small test suite is available—please add to it!
To run, run rake or rspec spec.
Before you start:
.env file with a Github Personal Access Token (CHANGELOG_GITHUB_TOKEN=) so that the Changelog data can be retrieved from the Github API.To release a new version, on main branch run:
# Update version number, changelog, and create git commit:
$ bundle exec rake release[patch] # major, minor, patch
# ...and follow subsequent directions.If you see the error zsh: no matches found, escape the square brackets. e.g. bundle exec rake release\[patch\].
The gem is available as open source under the terms of the MIT License.
Everyone interacting in this project’s codebase, issue trackers, chat rooms and mailing lists is expected to follow the Code for America code of conduct.