Develop

The library provides front-end developers & engineers a collection of reusable HTML and SCSS partials to build websites and user interfaces. Adopting the library enables developers to use consistent markup, styles, and behavior in prototype and production work.

Install
SCSS
Javascript
Web Fonts

Install

NPM

$ npm install --save @shs/ui-marcom

SCSS

Using the UI MarCom Sass files infers usage of the SCSS pre-processor. All Sass files use the *.scss file extension.

For transpiling Sass code, use node-sass based Sass compilers, for example, WebPack sass-loader or gulp-sass.

If you’re starting a new project without a boilerplate, you need to know about a few things to get started.

Autoprefixer

Make sure your build process uses autoprefixer to ensure vendor prefixes are automatically added to your output CSS.

Default element styles

CSS includes browser resets and set common styles on basic HTML elements. These styles are generally applied and may be overridden by adding a component class name.

Importing SCSS files

By using the Sass files in your project, you are able to control whether a component is transpiled into CSS or not. Each single component needs to be imported first, which do not result in any CSS output. You can leverage the cumulated Sass file with all imports by simply importing it to your projects SCSS.

@import "/node_modules/@shs/ui&#8209;marcom/scss/ddc.scss";

Transpiling CSS

To include desired components in your application CSS you have to call the components render mixin @include sh-component();.

Extending components

The render mixin empowers developers to easily customize Sass components.

1. Set option parameters:

@include sh-card(bottom-margin: 20px);

2. Add custom styles:

@include sh-card() {
  padding: 10px;
};

Namespacing

UI MarCom Components are prepared for prefixing class names. The global SCSS variable $prefix is prepended to any class attribute. Its empty by default but you can specify your own prefix by changing the mentioned SCSS variable to e.g. ui- before including the render mixins of component.

Icons

Some components depend on icons from the UI MarCom icon set. You can use any of them for appropriate purposes. Read the docs for details on how to use them.

Javascript

After you’ve installed UI MarCom through npm, you can grab a necessary JavaScript from node_modules/@shs/ui-marcom/js/.

1. Examine assets

The js folder contain a bunch of javascript files separated into three folders. gravity - some framework functionality plugins - the component classes vendor - the vendor scripts that are not installed through npm

2. Concat scripts

Your build process should concatenate all needed JavaScript files into a single file to reduce the amount of HTTP requests. Since all JavaScript is written in ES6, you may also compile it into ES5 to support legacy browsers.

3. Reference the script

<html>
  <body>
    <!-- put component snippets here -->
    <script src="node_modules/@shs/ui-marcom/js/ddc.min.js"></script>
  </body>
</html>

4. Init application

var app = new Application();

5. Hooking components

Many UI MarCom components have a corresponded JavaScript class. They are hooked to a component be adding the belonging js- prefixed classname in the HTML.

<div class="js-dropdown dropdown">
  …
</div>

6. Add custom JavaScript

app.ready(function () {
  // your custom JavaScript here
}

Web Fonts

The web font files are included as assets in the UI-MarCom NPM package.

Do not download the font files manually from another source. The compatibility and a seamless implementation of the UI-MarCom styles can only be guaranteed with the included font files.

Use web fonts in your project

After installing UI-MarCom as a dependency simply link to the stylesheet that defines the @font-face rules.

<!-- SH web fonts -->
<link rel="stylesheet" href="node_modules/@shs/ui-marcom/assets/fonts/webfonts/webfonts.css">

This straightforward method does not automatically put the assets in your build distribution folder. To do so, you have to copy the webfonts folder into the assets of your project and load the CSS file from there.

International font subsets

The SH-Bree Headline web fonts support multiple languages for international use. Due to loading performance the font is separated into subsets. The browser will load them as needed to render the glyphs in the text.

Charset	Web Font Subset
Basic Latin	55kB woff2 file
Cyrillic and Greek	22kB additional woff2 file
Middle East	37kB additional woff2 file
Thai	17kB additional woff2 file
Chinese, Japanese, Korean	To large to provide as web font
Other glyphs	No web font files available

The Siemens Sans web font supports extendet latin charset. There are no special character subsets available. Since it is used for all types of copy text, it is separated into seperate files for eache font style instead.

Fallbacks for none supported languages

For unsupported glyphs a suitable fallback font will be used to render the font. These fallbacks are defined as font stacks in the UI-MarCom styles.

Chinese, Japanese, Korean character sets are far to big to be loaded over the internet. Therefore all online applications are recommended to rely on the system fallback fonts.

If the fonts are installed on a users computer, these local files will be used to render the text. This saves valuable bandwith and makes the web application load faster.