The Things Network Stylebook

The goal of this project is to contain a shared set of styles and related assets for use on several website properties of The Things Network. It does not enforce a particular CSS preprocessor or build flow and allows us to adopt global styles step by step.

Why Less?

The source stylesheets are in Less because it was the only format that can be automatically converted to SCSS and Stylus.

Documentation

The docs folder uses dist/scss to demonstrate the styles and is a usage example at the same time. You can view the documentation via GitHub Pages.

Usage

1. Depend on the repository, e.g. via NPM:

   npm install --save thethingsnetwork/stylebook

   You can also lock in to a certain branch or commit.

2. Import a stylesheet in the language you use:

   @import 'ttn/ttn-variables';
      
   body {
   	color: $ttn-color-brand;
   }

   This example assumes you run Sass with --load-path node_modules/stylebook/dist/scss to not have to give the full path on every import.

Stylesheets

There are different strategies for using the stylesheets:

• dist/*/ttn/variables: Just TTN variables. For projects where you want to have full control over the actual styles.
• dist/*/ttn/ttn: The above plus TTN components.
• dist/*/ttn/bootstrap-variables: TTN and Bootstrap variables. For projects where you'd like to override additional Bootstrap variables before importing (maybe just parts of) Bootstrap.
  • You can import parts of Bootstrap from dist/*/bootstrap. Be aware that the Sass version has components wrapped in another bootstrap folder.
• dist/*/ttn/bootstrap: All of the above plus all of Bootstrap.
  • This also imports dist/*/ttn/bootstrap-overrides for customisations of Bootstrap that cannot be done via variables.

Development

1. Install Ruby

2. Install Bundler:

   $ gem install bundler

3. Install Ruby dependencies via Bundler:

   $ bundle install

4. Install Node.js and NPM.

5. Install Node.js dependencies via NPM:

$ npm install

6. Update styles in src using Less.

7. Run convert to update dist with Less, SCSS, Stylus and CSS versions and process docs/src.

   $ npm run convert

NOTE: Running npm install will overwrite the git pre-commit hook to execute npm run convert & npm run add automagically on every commit so you can ignore step 7.

Conventions

• Variables, selectors and mixins should start with ttn- so that they do not conflict with other frameworks or custom styles on the site.

Default variables

Both Stylus and Sass support variable defaults. Less does not and promotes lazy loading instead. Because we use Less as source to convert to Sass and Stylus this is an issue. So bin/convert does has replacements to make all variables in Stylus and Sass defaults, except dist/*/ttn/bootstrap-variables so it can use but also override Bootstrap variabls.

Tests

To run all tests:

npm install
npm test

To update expected with actual output:

UPDATE=1 npm test

TODO

• Add more base variables.
• Add styles for custom components.
• Include TTN assets logos.
• Maybe even include common templates and scripts?