Creating custom themes

Creating custom themes

Themes are written in SCSS. Currently there is no support for alternative CSS pre-processers.

Adding custom themes is a five step process. The code below can be used as a template for developing new themes:

1. Create the _settings.scss file.
2. Add the core theme SCSS, as well as any fonts and images that the theme uses.
3. Create an index.js with a list of the theme's assets.
4. Add a themes directory to the project containing the new theme.
5. Add a themes_directory entry to the config.yml.

A completed theme's structure will look something like this:

my-theme
  ├── _settings.scss
  ├── application.scss
  ├── fonts
  │   └── MyFont.otf
  ├── images
  │   └── sprites.png
  ├── index.js

1. Create the _settings.scss

List all the variables and mixins that you want to be made available to the end-user.

// _settings.scss

$black: #222;
$white: #fff;

2. Add the core theme styles

Create an entry-point SCSS file for the styles. You can import other files or libraries as you like and b-ber will add these up during compilation.

// application.scss

@import 'settings';

body {
    font-size: 1em;
}

3. Create the index.js

This should list all of the assets that your theme is using and define an entry point for the theme. The entry point is a relative path to the main SCSS file.

You can copy, paste, and modify the code below for your own index.js file:

module.exports = {
    name: 'my-theme',               // Required, must be a unique name
    entry: './application.scss',    // A relative or absolute path to the main SCSS file
    fonts: [                        // An array of the fonts used in the theme, or just an empty array
        'MyFont.otf'
    ]
    images: [                       // An array of the images used in the theme, or just an empty array
        'sprites.png'
    ],
}

4. Add a themes directory

The themes directory can live in a project, or anywhere on your computer. In this case we're including it in the project itself:

my-project
  ├── README.md
  ├── _project
  ...
  ├── config.yml
  ├── my-themes
  │   └── my-theme
  │       ├── _settings.scss
  │       ├── application.scss
  │       ├── fonts
  │       │   └── MyFont.otf
  │       ├── images
  │       │   └── sprites.png
  │       └── index.js
  ...

5. Tell b-ber where you are storing your theme

Tell b-ber where you are storing your theme by adding a themes_directory entry to the main config.yml file:

env: production
theme: sans
src: _project
dist: project
themes_directory: ./my-themes

If you're using a theme on multiple projects, you can store the theme in a higher-level directory on your machine and reference the path from the individual config.yml files:

├── my-projects
│       ├── my-first-project
│       │     ├── config.yml
│       │     ├── _project
│       │     ...
│       └── my-second-project
│             ├── config.yml
│             ├── _project
│             ...
├── my-themes
        └── my-theme
              ├── _settings.scss
              ├── application.scss
              ├── fonts
              │   └── MyFont.otf
              ├── images
              │   └── sprites.png
              └── index.js

# my-first-project/config.yml

env: production
theme: my-theme
src: _project
dist: project
themes_directory: ../my-themes

# my-second-project/config.yml

env: production
theme: my-theme
src: _project
dist: project
themes_directory: ../my-themes