Skip to main content
`Ctrl`+`K`
⚠️The latest release refactored our HTML, so double-check your custom CSS rules!⚠️

# Style and design

This describes the principles and infrastructure behind the style and design aspects of this theme.

## Design principles and inspiration

Here are a few guiding principles for the design of this theme:

- Use minimalistic visual elements. This theme should not have “strong visual opinions” beyond a clean and minimal design. For example, use whitespace instead of color blocks to separate content, use unintrusive visual elements where possible, use color sparingly, etc.

- Focus on a single book use-case. This theme is designed for the use-case where a person has documentation for a single reader archetype, where all aspects of the documentation may be exposed to the reader. This means we follow a two-column layout with a single navigation bar across all pages. Header navigation should require more customization.

- Add design elements from the Tufte theme. The Edward Tufte CSS theme defines several styles and elements that are unique for communicating ideas with data. We give a few of these (like margin content) special treatment, and generally assume Tufte knows what he’s doing.

This theme draws inspiration and borrows design elements from the following themes:

- The PyData Sphinx Theme

- The Furo theme

- The Edward Tufte CSS theme

- GitBook

- The Tailwind CSS docs

## SCSS build process

Our SCSS source files at in `src/sphinx_book_theme/assets/styles`. We use the Sphinx Theme Builder to compile these assets and bundle them with the theme at `src/sphinx_book_theme/theme/sphinx_book_theme/static/styles`.

These compiled files are not checked in to `git` history.

You can run the compilation process with `tox` like so:

    $ tox -e compile

or you may manually run this if you have installed the `sphinx-theme-builder` with this command:

    $ stb compile

## CSS/SCSS naming conventions

We try to follow the `block__element--modifier` naming convention for CSS.

This is aspirational! Many of our HTML elements do not quite follow this naming, and over time we hope to continue making adjustments to get closer to this frameowrk.

## SCSS folder structure

Our SCSS files follow the structured described in the sass-guidelines guide. For a high-level overview, see the file `/assets/styles/index.scss`.

Note

We also inherit a lot of SCSS rules from the PyData Sphinx Theme styles.