Stylabilla

What is Stylabilla for?

Stylabilla is the CSS-only living styleguide for the Usabilla product (both public facing widgets and the customer application), that implements our design styleguide (sketch file, invision file).

It is inspired by Stripe's approach.

Stylabilla structure

src/
|-- assets/
|---- fonts/
|---- images/
|-- components/
|-- ....
|-- index.scss

docs/
|-- kss-assets/
|---- fonts/
|---- images/
|---- kss.css
|-- index.html

Build structure

dist/
|-- assets/
|---- images/
|-- stylabilla.css

dist-docs/
|-- kss-assets/
|---- images/
|---- kss.css
|-- index.html
...
|-- ***.html

static/
|-- assets/
|---- fonts/
|------ MiloOT.woff
|------ MiloOT.woff2
|------ ****.woff
|------ ****.woff2

Fonts

Fonts are self hosted on docker container which is in charge to build a static nginx webserver that will expose the fonts. The static docker container will be built and deploy to staging automatically on merge, and to production when a new tag gets created.

Contributing to Stylabilla

Stylabilla is "internal open source", meaning that we welcome contributions from anyone working at Usabilla. See CONTRIBUTING.md for details on how to contribute. Most importantly, note that we use semantic-release and therefore any commits with the type "feat" or "fix" or have "BREAKING CHANGE" in the message will automatically release a new version to NPM.

The project is under development and changing all the time and we don't recommend using it in your own projects if you don't work at Usabilla, but it may give you some ideas for your own living styleguide.

Using Stylabilla

Via CDN

Useful for ULab or internal projects or anywhere you want to quickly include Stylabilla.

Include the following link in your page. Replace the version number (v1.5.0 below) to the keyword latest to use the latest release, or to the release version wanted (the badge below displays the latest version):

<link rel="stylesheet" href="https://static.usabilla.com/stylabilla/v1.5.0/stylabilla.css"/>

Via Yarn/NPM and Webpack

Larger frontend projects at Usabilla will want to install Stylabilla as a package so that it can be compiled and minified with any other project specific CSS.

yarn add @usabilla/stylabilla

Make sure webpack correctly packages Stylabilla by editing your scss/css and woff/woff2 webpack configuration rules to have the exclude property, the url-loader and the css-loader as follows:

{
  test: /\.png$/,
  exclude: {
    test: /node_modules/,
    exclude: /stylabilla/,
  },
  loader: 'file-loader',
},
{
  test: /\.(css|scss)$/,
  exclude: {
    test: /node_modules/,
    exclude: /stylabilla/
  },
  use: ['style-loader',
     {
      loader: 'css-loader',
    },],
},
{
  test: /\.(woff|woff2)$/,
  exclude: {
    test: /node_modules/,
    exclude: /stylabilla/
  },
  loader: 'url-loader?name=assets/fonts/[name].[ext]',
}

Also if you want your loader to find Stylabilla fonts and images, be sure to override the assets variable before importing Stylabilla. You can then include the css and fonts in your application with:

$sb-assets-path: '~@usabilla/stylabilla/src/assets/';
import '@usabilla/stylabilla';

Or just the files you want by importing into a scss file with:

@import "~@usabilla/stylabilla/src/components/button";

Run yarn upgrade @usabilla/stylabilla while it is under heavy development to keep up to date.

It can also be useful to link to your local version of Stylabilla while you are working on both repos. Run yarn link in Stylabilla, and yarn link @usabilla/stylabilla in your project.

Updating

Stylabilla follows semantic versioning. You should be able to update patch and minor versions without requiring any changes to your code.