Here are a few high level quick starts when using StyleBitz with your project. If you are using Rails, please read that section linked above.
Good news! libSass is a real thing and StyleBitz Sass framework passes all the tests.
We recommend that you wire up your Sass paths so that properly scoped and package independent imports work. What does this mean? It means that StyleBitz can not prefer any package manager over another. When we @import "bourbon"; it is up to you wire up the Sass paths. This is done for you automatically when using StyleBitz with RubyGems. Otherwise, you have to do this for each of our primary deps listed here.
Setting up a development version of StyleBitz will allow you to easily edit documentation and make global framework contributions. You can also use StyleBitz' Rails engine to prototype new pages.
Clone the StyleBitz repository to your local drive. If you are new to git, we recommend using GitHub for Mac. To either develop StyleBitz or contribute to the living style guide's documentation, you will need Ruby installed, which is already present on OS X. If you use a Ruby version manager, we recommend developing StyleBitz with Ruby v2.1 or later.
StyleBitz uses Capybara for both its unit and integration tests. The following terminal commands need to be run from the root of the cloned StyleBitz repository if this is your first time setting up both Ruby and StyleBitz. Remember, do not type the $ symbol. It is there to indicate that that these are terminal commands only.
Our Sass resources can be found in the app/assets/stylesheets directory. From here everything related to StyleBitz proper is defined in the _style_bitz.scss main file or the adjacent style_bitz directory. From here Sass files are organized within a clean directory structure that follows our core/more philosophy. The living style guide uses StyleBitz to build itself. Its main Sass file is in the same stylesheets directory and it too has a matching directory named style_bitz_style_guide to keep them isolated.
The Rails Engine of the StyleBitz gem is organized like most Rails applications. We use an isolated namespace to keep our controllers, views, and helpers from negatively affecting host applications. As we develop new helpers it is important to maintain the sb_ method name prefixes since Rails mixes all helpers all the time.
Local Dev Server
You need a development server to see the local version of the StyleBitz living style guide. This way you can see what is changed at either the code or documentation level. For those that use the Pow rack server, you can symlink to the StyleBitz repository like a normal Rails app. If you do not have Pow installed, you can use the Rake command to start a development server. Once running, you can access StyleBitz at http://style_bitz.dev/ if you are using Pow or http://0.0.0.0:3000/ if using our Rake server.
$ bundle exec rake server
The StyleBitz living style guide is authored in easy to use Markdown syntax. Specifically we use GitHub Flavored Markdown which allows us to embed syntax highlighted code examples. All style guide pages reside within the app/views/style_bitz/style_guide directory and have a .md file extension.
Any new new Markdown file added here will automatically be available to use. For example, the foo.md file would be accessed at the /style_bitz/foo URL path. Markdown files are automatically parsed and given a table of contents using semantic names for each <h2> tag which are given the special style guide presentation on each page. Please, <h4> tags within each documentation segment. For example:
## Primary Section
#### Other Related Section
Please take the time to consider the content and contextual link to any other style guide pages as needed. For example, this [our Sass usage](/style_bitz/technology-sass#usage) will generate a link with the text of "our Sass usage" that links to our Sass Framework page. The #usage is called an anchor and is optional. In this example, it will jump to that section on the page.
If you are using images in the documentation, we recommend hosting them on GitHub's user content server. To do this, open this GitHub page and just drag your image to the comment input box. Your image will automatically upload and you can copy the URL into the HTML snippet below.
That image would take up half the right side of the page from the medium breakpoint upward. Full page for mobile first. Check out the style guides _page.scss for more classes or write your own.
Updates & Deploys
Updates to the StyleBitz master repository branch will trigger an automatic deploy to Heroku of the living style guide. This normally happens in only a few minutes. It is recommended that you run the tests before committing.
$ bundle exec rake test
Please check our Jenkins Builds for the complete run. Jenkins leverages our usage of the Appraisal gem to run all tests on supported Rails versions.
Use this Keep a CHANGELOG article for a good reference on how we want to maintain ours.
New sb-Icon--google Google icon.
All non-mobile Homepage to force desktop layout.
LiveEngage elements (to replace the old LivePerson links)
LiveEngage helper function (to render the LiveEngage elements based on kill switch)
Old code for ECS A/B testing, the LivePerson links.