Kitten
Kitten is a components library based on Sass and React. It provides mixins to
create flexible components based on your own brand elements (colors, fonts,
typographic scale, etc.).You can check out Kitten's components on KissKissBankBank's styleguide.
It is an npm module coupled with a Rails engine that provides an integrated styleguide. It should eventually be separated into two different repositories.
Dependencies
- Ruby 2.2.4
- Bundler (
gem install bundler
) - Node ~> 6.0
Table of content
- Npm - Rails engine - CSS components - React components - Style GuideInstallation
You can choose to use the npm module only or with the Rails engine.Npm
npm install kitten-components --save-dev
Rails engine
Add this line to your application's Gemfile:# Style guide
gem 'kitten'
And these routes to your
routes.rb
:mount Kitten::Engine, at: '/kitten' if Rails.env.development?
You can then run
bundle
and restart your server.kitten
is designed to serve assets with Webpack
through React on Rails.For more detailed instructions, see Rails webpack configuration.
Usage
CSS components
Importkitten
and the components your want to use in your application:@import 'kitten';
@include k-Button;
You can define your own font families, typography settings and colors by overriding the the
$k-fonts
, $k-typography
and $k-colors
options. Check out the
default config
for an example.React components
You can render React components directly in your js bundle:const yourLoanSimulatorProps = {}
ReactDOM.render(
React.createElement(LoanSimulator, yourLoanSimulatorProps),
document.getElementById('loan-simulator')
)
Or, use React on Rails view helper in your
.erb
file:<%= react_component('LoanSimulator', props: your_loan_simulator_props) %>
Style guide
Kitten provides a styleguide interface through a Rails engine. You can run see it in your browser by downloading kitten and launching the app or by installing the style guide in your Rails app.The engine provides some configuration options that can be defined in
config/initializers/kitten.rb
:- webpackoutputbundle: This option is used to pass an output bundle name
application-bundle
.Example configuration:
Kitten.configure do |config|
config.webpack_output_bundle = 'your-custom-bundle'
end
Development
Components
Check out the guidelines to start creating new components!Install
$ bin/kitten install
Style guide
To launch the style guide with hot-reloading, installovermind
, then:$ bin/start
Then visit http://localhost:3003
Background app
To launch the style guide in the background without hot-reloading:$ bin/kitten start
Then visit http://localhost:3000
To stop the app:
$ bin/kitten stop
To check wether it is running or not:
$ bin/kitten status
To tail the app logs in real time:
$ bin/kitten log
Hit
Ctrl+C
to stop the tail.Production settings
To share the style guide with production settings (to share via ngrok for example), you can compile the assets and serve a production server:$ bin/rake staging:assets:precompile
$ REACT_ON_RAILS_ENV= rails s -b 0.0.0.0
Cleanup
To cleanup installed modules:bin/kitten cleanup
Style checker
$ yarn stylelint
Ruby specs
$ bundle exec rake
SassDoc
We use SassDoc to generate documentation from our components comments.Generate the documentation:
$ bundle exec rake sassdoc
# OR
$ yarn sassdoc
The documentation is accessible on development environment:
/kitten/sassdoc
.Component testing
To launch the JS tests:$ bin/kitten test
# OR
$ bin/test {PATH}/{FILE}.test.js
Check out the guidelines to know how to test kitten.
Contributing
To contribute code:- Create a pull request on GitHub with a clear title in English.
- Tag it
Needs reviews
, Needs testing
or Work in progress
.- Don't forget to update the
CHANGELOG.md
under the[unreleased]
section
``` - Breaking change: a breaking change. - Feature: a new feature. - Fix: a fix. ``
- Update the
KARLCHANGELOG.md` under the unreleased section if you added some
updates to the styleguide.To merge code into master:
- Make sure the code has been reviewed by someone.
- Make sure it has been tested.
- Merge using
Squash and merge
on GitHub. - Delete the branch.
Static Dump
To build an on disk static file mirror:$ bin/kitten buildstatic
- files are located in build/
Release
Only for KissKissBankBank collaboratorsLogin
If this is your first release, start by saving your npm credentials in your~/.npmrc
by calling:$ yarn login
Prepare the release pull request
- Pull
master
. - Update the
CHANGELOG.md
file:
[unreleased]
section.
Check that each mergedPR](https://github.com/KissKissBankBank/kitten/commits/master)
from the last release has an entry.
- Update the
KARL_CHANGELOG.md
file:
[unreleased]
section.- Update the version in
lib/kitten/version.rb
. - Update the version in
package.json
. - Run this command:
$ bundle exec rake kitten_prepare_release
- Follow the link to create the pull request on Github.
- Announce the release on KissKissBankBank's #kit-ui Slack channel with the
Release!
Once the pull request is accepted:- Merge the pull request into master.
- Delete the release branch.
- Run this command:
$ bundle exec rake kitten_release
- Update
done
column to released
column.Storybook
- To launch storybook in local
npm run storybook
Then visit http://localhost:6006
- To release
Storybook
simply run this command:
yarn deploy-storybook