npm package: @springernature/elements
Description: Springernature’s documented design system
Author: SpringerNature
Latest version: 0.0.1-alpha.20

# 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)](https://nodejs.org/en/download/) 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:

```bash
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 utility 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
```css
@import '../../node_modules/@springernature/elements/themes/springernature/scss/core.scss';
```
- Import the `enhanced` theme into your enhanced styles

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

- If needed, import the `utilities` of the theme into your styles

```css
@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
```css
@import '../../node_modules/@springernature/elements/themes/nature/scss/core.scss';
```
- Import the `enhanced` theme into your enhanced styles

```css
@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

```css
@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:
```css
@import '../../node_modules/@springernature/elements/components/eds-c-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:

```css
@import '../../node_modules/@springernature/elements/components/eds-c-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:
```html
'../../node_modules/@springernature/elements/component/template.hbs’
```

## Design tokens

In Elements we use [Design Tokens](https://css-tricks.com/what-are-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.

For more detailed information on how to use design tokens, [go to the tokens readme](https://github.com/springernature/elements/blob/main/tokens/readme.md)

## JavaScript

Import the script from `elements` and then execute it.

For example:
```js
import {header} from '@springernature/elements/eds-c-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 new component

To create a new component with the name `my-component`, you need to create a new folder within `/components`, for example: `/components/my-component` and create the following files within that folder:
- `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 `component-name.token.scss` and `component-name.scss`.
- `index.scss` , a sass file which imports the component tokens and styles from the sass folder

### Tests after component creation

You also need to create a `my-component.test.js`, using [Jest](https://jestjs.io/).

You need to include tests checking that:
- 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


## Development Docs

The documentation site for Elements also lives in this repository. It uses a static site generator called [Eleventy](https://www.11ty.dev/).

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.