Extending Semantic UI#

Volto uses Semantic UI and React Semantic UI (via semantic-ui-less) as development framework. It helps you to create websites with responsive layouts using human-friendly HTML. Semantic UI treats words and classes as exchangeable concepts. Classes use syntax from natural languages like noun/modifier relationships, word order, and plurality to link concepts intuitively.

Semantic-UI-LESS has a builtin theming engine based on the following concepts:

  • LESS definitions files (split in globals, collections, elements, etc) to define the basic styles (ex: definitions/modules/tab.less)

  • A semantic.less file which imports all the available definition files

  • Each definition file (ex tab.less is integrated with the theming engine by importing the magic theme.config

  • which defines the theme name for each component, so that the theme variable overrides get loaded for that component

  • a Semantic-UI theme is based on a folder structure that mirrors the definition files structure, with 2 types of files for each definition file: <name>.variables and name.overrides. The theme.config (which all definition files import), via its theme.less import tries to import these variable and overrides files from the default theme, then the theme folder, then the site folder (which acts as an override for the theme). The theme.less is Semantic-UIs theming engine.

Volto comes with its own implementation of theme.config (by shadowing, via webpack resolve aliases, the ../../theme.config import path).

Volto's theme is called Pastanaga, which is a typical Semantic-UI theme. For the new elements and components that don't exist in Semantic-UI, the Pastanaga theme uses the extras folder, which isn't fully using the Semantic-UI theming engine.

The key to success in Volto theming is to understand how Semantic-UI's theming engine works and how to manipulate it. Reading the theme.less and understanding it is a must.

Each Volto project brings its own src/theme.js, which is the entry point for Volto's CSS.

import 'semantic-ui-less/semantic.less';
import '@plone/volto/../theme/themes/pastanaga/extras/extras.less';

By simply providing your own copy of semantic.less (and changing the above import), you can tweak which basic semantic-ui definitions are loaded, or even create new elements.

& {
  @import '@eeacms/volto-eea-design-system/../theme/themes/eea/extras/hero';
}