Styling intermediate

Styling rules let you customize the appearance of existing UI components and elements in your repository site —
color schemes, typography, spacing, shapes, shadows, and more. It lets you to change the built-in themes to better match your institution’s branding guidelines.

Prerequisites

Before proceeding, ensure you are familiar with:

CSS — the core styling language of the web.
LESS — a CSS preprocessor adding variables, nesting, mixins, and more.

⚠️

Any changes made to files mentioned in this docs require running a development server with assets watcher for changes to take effect.

Global Variables

Global UI variables for a repository site can be defined or overridden inside the site.variables file located under the assets/less/site/globals folder in your repository project structure. This file lets you define or override LESS variables used as defaults by any existing UI element site-wide.

- - - site.variables
    - site.overrides

For a complete list of possible LESS styling variables, please refer to:

Invenio Theme Global Variables Reference SemanticUI Default Theme Variables Reference InvenioRDM Theming Documentation

You can also define your own variables here and use it later in your custom styling rules.

Global Stylesheet

The site.overrides is used for global styling rules, such as any font faces or CSS reset styles, that should be applied once and before any other component-specific style overrides:

- - - site.variables
    - site.overrides

Customize Individual UI Components

To customize the appearance of a specific UI component, you can override either its default variables and/or style rules.

For a full list of UI components available in a NRP repository site for you to customize, please refer to the:

Semantic UI docs Default Semantic UI component style definitions

Here’s an example of how to customize the Button component:

Using Variable Overrides

Look up the default variable definitions for the component you want to customize under the default {componentType}/{component}.variables definition and find out a variable that you want to tweak to get the desired effect. Then override that variable by defining it in the {componentType}/{component}.variables file under the /assets/semantic-ui/less/site/ folder structure in your repository project.

Default SemanticUI component variables Default Invenio Theme component variables

If we were tasked to tweak the buttons to have a shadow of size 16px and that cool rounded borders with radius of 8px, we need to go through the following process:

Find the right variable names

Look up the correct variable names in the default button.variables file.

We can see there, that the variables controlling the border radius and shadows are:

/Semantic-UI//src/themes/default/elements/button.variables


@borderRadius: @defaultBorderRadius;
/* ... */
@shadowDistance: 0em;
@shadowOffset: (@shadowDistance / 2);
@shadowBoxShadow: 0px -@shadowDistance 0px 0px @borderColor inset;

💡

When unsure about which variable controls what styles/appearance properties or what it’s being used for, you might need to consult the definition of the component of interest.

Create a `.variables` file with customizations

In order to override values of these LESS variables, we create a corresponding button.variables file. We need to respect the theme folder structure as imposed by Semantic UI theming system:

{componentType}s/{componentName}.variables

As the Button is a component of type element, the correct path for that file would be: /assets/semantic-ui/less/site/elements/button.variables. Place the variables that you want to override there and you are done!

/assets/semantic-ui/less/site/elements/button.variables


@borderRadius: 8px;
@shadowDistance: 16px;

ℹ️

You might need to manually create the folder structure if it doesn’t exist yet.

Style overrides

For situations, where there is no suitable variable defined on the component you want to tweak, you can completely override or add your own style rules for such a component.

For example, there is no way to affect button’s min-height attribute using LESS variables. If we were tasked to change buttons on our site to have min-height of 2rem, we need to do the following:

Find the rule you want to override

Look up styles definition (.less file) of your component of interest, e.g. for our button (we can see the rule controlling min-height there, it is ui.button):

/Semantic-Org/Semantic-UI/blob/master/src/definitions/elements/button.less


/*******************************
            Button
*******************************/
 
.ui.button {
  cursor: pointer;
  display: inline-block;
 
  min-height: 1em;
 
  outline: none;
  border: none;
  vertical-align: @verticalAlign;
  background: @background;
  color: @textColor;
 
  font-family: @fontFamily;
  // ...
}

Define custom rules in overrides

Using a similar approach to overriding variables, we put our style rules into a custom .overrides file. The path needs to respect the theme folder structure as imposed by the Semantic UI:

/{componentType}s/{componentName}.overrides

We then redefine the ui.button style there:

/assets/semantic-ui/less/site/elements/button.overrides


.ui.button {
  cursor: pointer;
  display: inline-block;
 
  min-height: 2em;
 
  outline: none;
  border: none;
  vertical-align: @verticalAlign;
  background: @background;
  color: @textColor;
 
  font-family: @fontFamily;
  // ... same declarations as in original rule
}

ℹ️