This is an example project that uses hologram to build this style guide. The instructions listed below assume that you have already installed Node / NPM, and have the Apple Developer Tools installed on your machine.
Hologram is a Ruby gem that parses specially formatted comments in your Sass/CSS and turns them into a living styleguide.
The two main directories that you will be interacting with are styleguide-theme and styles.
The former directory is home to the Header and Footer of your styleguide, as well as any static assets you might need to theme it (Yes, you can style the styleguide via this directory). Note that the Header and Footer are simple HTML files, wherein you can pull in 3rd party assets (in this case: Font Awesome, and the Roboto Web Font). Hologram is smart enough to spit out the content of your styleguide in between said header and footer, so don't worry about having to know any Ruby!
Where the fun begins is the styles folder, which is home to a list of Sass files. To get your project kickstarted, we've added Bootstrap 4 to this directory. In any case, feel free to write vanilla CSS, or SCSS-flavored Sass -- the only requirement is that any new files you add to the directory are imported in the style.scss file. For example, if you were to add a new file to the directory called _toasts.scss, be sure to add a corresponding statement in style.scss.
@import 'toasts';
In order for that element to be added to the styleguide, add a Hologram Comment to the top of the file.
/*doc
---
title: Toasts
name: toast
category: components
---
Toasts are not only delicious to eat, but they also...
```html_example
<div class="toast">
<p>I'm a paragraph inside the toast</p>
</div>
```
*/
As if we needed another tool, there's another one that you should be aware of: Gulp. We use Gulp to perform a bunch of tedious tasks that would otherwise get in the way of us doing what we do best: designing. Namely, it does the following:
- Processes and concatenates all of the
.scssfiles inside of thestylesdirectory and chucks them into a dynamically generatedbuilt-stylesdirectory. - Runs the
hologramcommand to create the styleguide as per the brand new stylesheet from Step #1. The output of this step is a brand newstyleguide-distdirectory. - Spins up a web server that points to the
styleguide-distdirectory described above. - Watches any changes to your
.scssfiles and runs steps 1-3 again.
Recommend using RVM so you don't have to chown to use your system Ruby. Follow the steps at their site to download and restart your shell session.
https://docs.npmjs.com/getting-started/installing-node
xcode-select --install
npm install -g gulp-cli
npm install
gem install bundler
bundle install
gulp
A web browser should open at http://localhost:8080
- Download the CF CLI
$ cf login$ cf create-space [spacename][i]$ cf target -o "[orgname]" -s "[spacename]"[i]$ cf pushto deploy your styleguide using the staticfile buildpack using the manifest
[i] This can also be managed online via PWS
Make sure you have the Heroku CLI downloaded. Then login to heroku and install the static website cli:
heroku login
heroku plugins:install heroku-cli-static
Create a new Heroku site, and set the buildpack config
heroku create
heroku buildpacks:set https://github.com/hone/heroku-buildpack-static
Initialize the static directory. In our case it's the styleguide-dist folder.
heroku static:init
You should ECHO out something like this:
? Enter the directory of your app: styleguide-dist
? Drop `.html` extensions from urls? No
? Path to custom error page from root directory:
{
"root": "styleguide-dist",
"clean_urls": false
}
Now deploy! Scale up a web server, open & enjoy :)
heroku static:deploy
heroku ps:scale web=1
heroku open
Here's our same styleguide, running on Heroku => https://arcane-tundra-22168.herokuapp.com/
Wraith uses a headless browser to create screenshots of webpages on different environments(or at different moments in time) and then creates a diff of the two images; the affected areas are highlighted in blue. For more information visit Wraith's homepage or their Github page.
You can use PhantomJS or CasperJS for a headless browser. CasperJS will allow you to pass along a selector to take screenshots of a component.
brew install phantomjs
brew install imagemagick
brew install casperjs
Add Wraith as a dependency to your Gemfile
bundle
If you're capturing images in your local environment make sure the server is running. To run regression tests against the styleguide:
gulp
For Wraith Capture: Given two domains, Wraith will take screenshots of both and compare them. This is good for comparing test and live versions of the same site.
gulp wraith-capture
alias wraith capture test/configs/capture.yaml
For Wraith History: Compare the same domain over time. This is good for checking that your website continues to look the same (especially useful if your site relies on third-party components).
gulp wraith-history
alias wraith history test/configs/history.yaml
For Wraith Latest: Capture new shots to compare to a baseline image.
gulp wraith-capture
alias wraith latest test/configs/history.yaml
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent