Elements

Elements single release guide

We are changing the way we release Elements from the existing individual packages in the frontend-toolkits repository to a single package release in a new elements repository.

This will make it easier for you to install and use the components and themes of the Design System. It will also make it easier for us to maintain and scale.

Requirements

This is a Node-based repository, so you will need to have Node and NPM (Node Package Manager) installed.

To use Elements components and themes you need:

• npm version 7 or higher
• Node.js version 18.14.0 or higher
• Dart Sass to compile your styles

Installation

You will get all of the components and themes by installing the single package.

To install the Elements themes and components, enter the following command in your Terminal:

npm install @springernature/elements

The package contains components, themes and utilities.

The brand-context will now be known as themes. At first, we’ll support the springer-nature and nature themes.

For now, the utilities will be empty. We will develop their functionality in future releases. At the moment you can find the utilitiy classes inside the themes.

For any component you want to use, import the relevant sass file from the component scss folder path.

Import the styles

Step 1: import the Theme:

If you are working on a project with the Springer Nature theme then include the theme like this:

• Import the core theme into your core styles

@import '../../node_modules/@springernature/elements/themes/springernature/scss/core.scss';

• Import the enhanced theme into your enhanced styles

@import '../../node_modules/@springernature/elements/themes/springernature/scss/enhanced.scss';

• If you need them, import the utilities of the theme into your styles as a single import for all of them

@import '../../node_modules/@springernature/elements/themes/springernature/scss/utilities.scss';

If you are working on a project with the Nature theme then include the theme like this:

• Import the core theme into your core styles

@import '../../node_modules/@springernature/elements/themes/nature/scss/core.scss';

• Import the enhanced theme into your enhanced styles

@import '../../node_modules/@springernature/elements/themes/nature/scss/enhanced.scss';

• If you need them, import the utilities of the theme into your styles as a single import for all of them

@import '../../node_modules/@springernature/elements/themes/nature/scss/utilities.scss';

Step 2: import the styles for the component.

For the Springer Nature theme, import the scss by adding this to your component sass file:

@import '../../node_modules/@springernature/elements/components/card/';

This imports the index.scss file that includes springernature theme and the styles for the component.

If you want to use the nature theme, import the nature scss file:

@import '../../node_modules/@springernature/elements/components/card/nature';

This imports the nature.scss file that includes springernature theme, the nature theme and the styles for the component.

Templates

The location of the template has moved. It used to be in the view folder. Now it is in the root folder of the component.

Consume the .hbs file that you find inside the component folder.

Example of a file path:

'../../node_modules/@springernature/elements/component/template.hbs’

Design tokens

In Elements we use Design Tokens.

Currently, the Elements team generates the json for the design tokens. We are working on a process to allow you to do this yourself.

If you want to create a new component, you can still follow this guideline and hardcode the variables inside the component-name.token.scss. Then, a member of the Elements team will create the json for the design tokens as part of the review of the pull request or at a later point in time.

JavaScript

Import the script from elements and then execute it.

For example:

import {header} from '@springernature/elements/nature-header/js/header';
header();

New data folder

In the single release package, components will now have a data folder.

Here you will find:

• a schema.json file
• an example.json file

Creating a component

There is now a command you can run to help you to create new components.

Enter the following command in your Terminal, in the root folder:

npm run create

You will be prompted with the question:

What is the name of the new component?

The system then creates a new folder in the components folder based on your answer.

For example, if you enter my-component as the component name, the system will create the following files automatically:

• my-component.hbs, a handlebars template for the component
• my-component.schema.json, a schema for the data that will be used to compile the my-component.hbs template
• my-component.example.json, some example data to fit the schema and compile the template
• A sass folder with an index.scss, component-name.token.scss and component-name.scss.

In the sass folder there is a component-name.token.scss file. This file contains the variables used inside the component-name.scss.

Import component-name.token.scss and component-name.scss into index.scss.

Tests after component creation

The system will also create a test file, my-component.test.js, using Jest.

To test your component you can run:

npm run create:test

This test will check that the:

• template, schema, and example data files exist
• example data file fits the schema
• template can be compiled and rendered using the example data
• rendered HTML passes basic accessibility standards

To author your component, adapt the given files to create a data structure and template that work together correctly and continue to pass these tests.

Development Docs

The documentation site for Elements also lives in this repository. It uses a static site generator called Eleventy.

To run the docs site locally:

1. Navigate to the /site folder (cd site)
2. Run npm i to install the dependencies
3. Run npm start to start a local server

Depending on the developmental state of the docs site, you may not see much (or any) content. See what Eleventy is generating by exploring the /site/build folder.