Installation and usage

The theme is published in two forms, on each release tag:

  • an npm package, @astrae/bulma-theme, with the compiled CSS and the Sass sources;

  • a Python package, teklia-bulma-theme, a Django application serving the compiled CSS and teklia.js as static files.

Both are hosted on the Teklia GitLab package registry, not on the public npmjs.com and pypi.org registries.

The theme replaces Bulma: it already contains all of Bulma’s CSS. Do not load Bulma’s own stylesheet next to it.

In a JavaScript project (npm)

Install the package

Point the @astrae scope to the Teklia registry in the .npmrc file of your project:

@astrae:registry=https://gitlab.teklia.com/api/v4/packages/npm/

Then install the package:

npm install @astrae/bulma-theme

You can then either use the compiled CSS as is, or compile the Sass sources to configure the theme.

Use the compiled CSS

This is the simplest option, when you do not need to change any Bulma variable. The package ships css/teklia.css (with its source map) and css/teklia.min.css.

With a bundler (Vite, webpack…), import it from your JavaScript entry point:

import '@astrae/bulma-theme/css/teklia.min.css'

Or copy it with your static files and link it from your HTML:

<link rel="stylesheet" href="/static/teklia.min.css">

Use the Sass sources

Use the Sass sources when you want to configure Bulma variables, or to use Bulma variables, functions and mixins in your own styles.

The package entry point is loaded with @use, and accepts any Bulma variable in its with (…​) clause:

@use '@astrae/bulma-theme' as theme with (
  $radius: 0.5rem, (1)
  $danger: #d32f2f
);

.my-component {
  border-color: theme.$primary; (2)
  border-radius: theme.$radius;

  @include theme.mobile { (3)
    border-radius: 0;
  }
}
1 Any Bulma variable declared with !default can be configured. See the list of Bulma variables.
2 All Bulma members (variables, functions and mixins) are forwarded by the theme.
3 For example Bulma’s responsive mixins.

Like Bulma, the theme needs node_modules in the Sass load paths, as it loads bulma/sass:

sass --load-path=node_modules styles.scss styles.css

Configure your bundler accordingly, so that bulma/sass/…​ resolves to node_modules/bulma/sass/…​.

The Teklia brand cannot be configured

The brand variables are set by teklia.scss and are not !default: $primary, $link, $family-primary, $grey-dark, $grey-light, $control-border-width and $input-shadow. Passing one of them in with (…​) fails with:

This variable was not declared with !default in the @used module

This is on purpose: all Teklia products share the same brand.

Only Bulma variables can be configured this way. The variables of the theme’s own components (for example the range slider sizes and colors) are internal to the theme. See the page of each component to know how to customize it.

Add the theme switch script

The light / dark theme switch relies on a small script, teklia.js, described in Light and dark themes.

teklia.js is not shipped in the npm package, which only contains the CSS and Sass files. Copy it from the repository (or from the CI build artifacts) into your project, or reproduce its behavior in your framework, as explained in Writing your own switch.

In a Django project

Install the package

Install teklia-bulma-theme from the Teklia GitLab PyPI registry, for example by adding the registry as an extra index:

pip install teklia-bulma-theme --extra-index-url https://gitlab.teklia.com/api/v4/projects/<PROJECT_ID>/packages/pypi/simple

The package depends on django-bulma, which renders Django forms with Bulma’s markup. Follow its own documentation to use it.

Enable the application

Add teklia_bulma_theme to the INSTALLED_APPS of your settings, so that Django finds its static files:

INSTALLED_APPS = [
    # ...
    "django.contrib.staticfiles",
    "teklia_bulma_theme",
]

Load the theme in your base template

{% load static %}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    {# Synchronous and before the stylesheet, so a stored theme is applied before the first paint #}
    <script src="{% static 'teklia_bulma_theme/js/teklia.js' %}"></script>
    <link rel="stylesheet" href="{% static 'teklia_bulma_theme/css/teklia.css' %}">
  </head>
  <body>
    {% block content %}{% endblock %}
  </body>
</html>

The static files available are:

Path Content

teklia_bulma_theme/css/teklia.css

Compiled theme, with teklia.css.map as its source map.

teklia_bulma_theme/css/teklia.min.css

Minified theme, for production.

teklia_bulma_theme/js/teklia.js

Light / dark theme switch. See Light and dark themes.

External resources

The compiled CSS imports two fonts from Google Fonts: Nunito (the Teklia font, used for the text) and Source Sans Pro. The browser downloads them from fonts.googleapis.com when the page loads.

The theme does not include an icon font. The examples of this documentation use Font Awesome, which must be loaded separately, like with plain Bulma.

Working on the theme

To change the theme itself, clone the repository, then:

# Install the pre-commit hooks (only needed once)
pre-commit install

# Install Bulma and Sass
npm install

# Build teklia.css once
npm run build

# Rebuild teklia.css on every change
npm run start

# Build both teklia.css and teklia.min.css, as done in CI
npm run production

Then:

  1. change teklia.scss (brand variables) or the files in src/ (Bulma configuration, overrides and components);

  2. build the theme;

  3. check the result on demo.html, in both light and dark themes. When adding a component, add it to demo.html too, so it can be reviewed.

Building this documentation

This documentation is an Antora site, in the docs/ folder:

npm install
npx antora antora-playbook.yml

The site is generated in public/.

Releasing

Both package versions, in package.json and pyproject.toml, must be identical. Once they are bumped, make release commits them, tags the version and pushes the tag: the CI then publishes the npm and Python packages.