Styling in Horizon (SCSS)¶
Horizon uses SCSS (not to be confused with Sass) to style its HTML. This guide is targeted at developers adding code to upstream Horizon. For information on creating your own branding/theming, see Customizing Horizon.
The base SCSS can be found at
This directory should only contain the minimal styling for functionality
code that isn’t configurable by themes.
horizon.scss is a top level file
that imports from the
components/ directory, as well as other base styling
files; potentially some basic page layout rules that Horizon relies on to
Currently, a great deal of theming is also kept in the
in this directory, but that will be reduced as we proceed with the new code
default theme stylesheets can be found at
├── _styles.scss ├── _variables.scss ├── bootstrap/ └── ... └── horizon/ └── ...
The top level
_variables.scss contain imports from
The “bootstrap” directory¶
This directory contains overrides and customization of Bootstrap variables, and markup used by Bootstrap components. This should only override existing Bootstrap content. For examples of these components, see the Theme Preview Page.
bootstrap/ ├── _styles.scss ├── _variables.scss └── components/ ├── _component_0.scss ├── _component_1.scss └── ...
_styles.scssimports the SCSS defined for each component.
_variables.scsscontains the definitions for every Bootstrap variable. These variables can be altered to affect the look and feel of Horizon’s default theme.
componentsdirectory contains overrides for Bootstrap components, such as tables or navbars.
The “horizon” directory¶
This directory contains SCSS that is absolutely specific to Horizon; code here should not override existing Bootstrap content, such as variables and rules.
horizon/ ├── _styles.scss ├── _variables.scss └── components/ ├── _component_0.scss ├── _component_1.scss └── ...
_styles.scssimports the SCSS defined for each component. It may also contain some minor styling overrides.
_variables.scsscontains variable definitions that are specific to the horizon theme. This should not override any bootstrap variables, only define new ones. You can however, inherit bootstrap variables for reuse (and are encouraged to do so where possible).
componentsdirectory contains styling for each individual component defined by Horizon, such as the sidebar or pie charts.
Adding new SCSS¶
To keep Horizon easily themable, there are several code design guidelines that should be adhered to:
- Reuse Bootstrap variables where possible. This allows themes to influence styling by simply overriding a few existing variables, instead of rewriting large chunks of the SCSS files.
- If you are unable to use existing variables - such as for very specific functionality - keep the new rules as specific as possible to your component so they do not cause issues in unexpected places.
- Check if existing components suit your use case. There may be existing components defined by Bootstrap or Horizon that can be reused, rather than writing new ones.
Theme Preview Page¶
When the DEBUG setting is set to
True, the Developer
dashboard will be present in Horizon’s side nav. The Bootstrap Theme Preview
panel contains examples of all stock Bootstrap markup with the currently
applied theme, as well as source code for replicating them; click the
symbol when hovering over a component.
A second theme is provided by default at
openstack_dashboard/themes/material/. When adding new SCSS to horizon, you
should check that it does not interfere with the Material theme. Images of how
the Material theme should look can be found at https://bootswatch.com/paper/.
This theme is now configured to run as the alternate theme within Horizon.