DHL Design Components
Design Component Library for digital DHL products build with Fractal.
Development Process
Setting up your development environment
You'll need a recent version of nodejs to work on DHL Design Components. We use the LTS node version. You can use nvm to easily install and manage different versions of node on your system.
node -v
# or
nvm current
Code editor recommendations
We recommend to use VS Code as editor, with the following plugins:
Linting and code styling
-
EditorConfig support for
.editorconifgfile - ESLint to lint JavaScript
- Styelint to lint CSS and SASS
Code formmatting
Prettier to format our code. Activate ESLint and Stylelint integration in VS Code Settings:
"prettier.eslintIntegration": true,
"prettier.stylelintIntegration": true,Template language
Twig Language 2, because we use Twig template engine for our Fractal templates. Also activate Emmet HTML support in Twig files in VS Code Settings:
"emmet.includeLanguages": {
"twig": "html"
},Checking out repository
NOTE: If you expect to commit updated or new dependencies, please ensure you are using npm 5, which will also update
package-lock.jsoncorrectly when you install or upgrade packages.
Once node is installed, clone the repo and run npm install
git clone git@github.com:strichpunkt-design/dhl-design-components.git
cd dhl-design-components
npm i
Running development server
npm run start
open http://localhost:3000
npm run start runs a Fractal development server instance with BrowserSync integration and Webpack HMR support with webpack-dev-middleware
Building Components
Each component requires the following items in order to be complete:
- A template file which provides the component's markup using the Twig template engine. Filename: component-name.twig
- A component class using vanilla JS and SCSS. Filename: component-name.{js,scss}
- A README which contains developer documentation on the component, including usage. Filename: README.md
- Optional: A component configuration which provides additional data, defines variants and determines how Fractal handles the component. There are a number of configuration options you can set. Filename: component-name.config.js
To ensure a consistent structure run npm run generate and enter the component name to create all component files. Enter the component name as follows:
- Use Kebab Case (example-component-name)
- Only lowercase letters [a-z] and dashes are allowed
npm run generate
? Pattern name: example-component-name
You'll find additional information about how Fractal handles components in the Fractal documentation.
Multi Brand Support
Only add styles if they are not yet defined in the base SCSS and cannot be set using a SCSS variable. Think of "extending" the base not "overriding" when you add new styles in this file.
Submitting Pull Requests
Commit message conventions
When commiting or submitting PRs, make sure you're following our commit message conventions (which are the same as angular's); our commit-msg hook should automatically enforce this.
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Type
Must be one of the following:
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing or correcting existing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
Scope
The scope could be anything specifying place of the commit change. For example ComponentName, page-test, webpack, package, linting, ...
You can use * when the change affects more than a single scope.
Subject
The subject contains succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize first letter
- no dot (.) at the end
Dependencies
Polyfills and Ponyfills
| Polyfill | Description | Included in library |
|---|---|---|
| IntersectionObserver Polyfill | Add support for the native IntersectionObserver API. | nope |
| ResizeObserver Polyfill | Add support for the native ResizeObserver API. Used as Ponyfill. | yep |
| Smoothscroll Polyfill | Add support for scroll-behavior
|
nope |
| focus-visible | Add support for CSS :focus-visible
|
yep |