Styling intermediate

Styling rules are useful when you need to customize the appearance of existing UI components and elements in your repository site. This can include changing the color scheme, fonts, sizing, or other visual aspects.

Prerequisites

Before diving into styling, it's recommended that you have a basic understanding of:

CSS (opens in a new tab) (Cascading Style Sheets): a styling language used to control the layout and appearance of web pages.
LESS (opens in a new tab): a CSS preprocessor that extends the functionality of CSS with features like variables, nesting, and mixins.

Global Variables

The site.variables file allows you to define or override LESS variables that are used as defaults by all existing UI elements site-wide. This file is located in the ui/branding/semantic-ui/less/globals folder:

- - 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

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 Components

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

For a full list of UI components usable in a NRP repository site, please refer to:

Semantic UI docs Default Semantic UI component style definitions

Here's an example of how to customize the Button (opens in a new tab) component:

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 branding folder.

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 (opens in a new tab) 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 (opens in a new tab) of the component of interest.

Create .variables file with customizations

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

{themeName}/{componentType}s/{componentName}.variables

As we use the default theme and the Button is a component of type element (opens in a new tab), the correct path would end with: default/elements/button.variables. Place just the variables that we need to customize there and we're done.

ui/branding/semantic-ui/less/default/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 (opens in a new tab) (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 imposed by Semantic UI:

{themeName}/{componentType}s/{componentName}.overrides

We redefine the ui.button class there:

ui/branding/semantic-ui/less/default/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
}

ℹ️

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

(optional) Combine with custom variables

You can further combine the two customization approaches described here. Create a custom LESS variable and reference it from this overriden rule, to make min-height easily tweakable like other variable-driven button attributes:

ui/branding/semantic-ui/less/default/elements/button.variables

@minHeight: 2rem;

ui/branding/semantic-ui/less/default/elements/button.overrides

.ui.button {
  cursor: pointer;
  display: inline-block;
 
  min-height: @minHeight;
  // ... same declarations as above

Theme Colors