@pollux-docaposte/core-design-system

Core Design System

A UI library of web-components following the Core Design System guidelines.

Tech Stack

• 🔧 Stencil to build reusable web-components. It uses TypeScript under the hood for type safety.
• 🎨 Pure CSS for Design Tokens.
• 📚 Storybook for UI component development and Accessibility check.
• ✅ Chromatic for Design Review, to prevent UI regressions and bugs in components.
• 📦 NPM for packaging and distribution.

Install

npm install @pollux-docaposte/core-design-system

Usage

Vanilla HTML

Easiest way to start using Core as web-components is by adding a script tag and stylesheet link:

<script type="module" src="https://cdn.jsdelivr.net/npm/@pollux-docaposte/core-design-system/dist/web-components/web-components.esm.js"></script>

<link href="https://cdn.jsdelivr.net/npm/@pollux-docaposte/core-design-system/dist/collection/tokens/index.css" rel="stylesheet">

Any Core component added to the webpage will automatically load. This includes writing the component tag directly in HTML, or using JavaScript such as document.createElement('core-button').

JS apps

npm install @pollux-docaposte/core-design-system

In the root file of the app:

import { defineCustomElements } from '@pollux-docaposte/core-design-system/loader'
// import Design Tokens
import '@pollux-docaposte/core-design-system/dist/collection/tokens/index.css'
// Register components as custom elements
defineCustomElements()

Any Core component added to the webpage will automatically load.

Design Tokens

All the core components are using Design Tokens so it is recommended to import them all in the project as global styles.

In the root file of the app:

import '@pollux-docaposte/core-design-system/dist/collection/tokens/index.css'

Or in the global css file:

@import '@pollux-docaposte/core-design-system/dist/collection/tokens'

If needed they can be imported separately:

/* e.g: importing color tokens only  */
@import '@pollux-docaposte/core-design-system/dist/collection/tokens/colors'

Typography specificities

The Typography Design Tokens are using Inter font already distributed in the Core package. If the global token file is imported it can be used right away.

Each Typography Design Token is a set of multiple style properties (font-size, line-height...) so they're not available as CSS variables like other tokens but as CSS utility classes. The CSS properties of a specific Typography Design Token can also be returned by using getTypographyTokenValue('token-name') helper available in @pollux-docaposte/core-design-system/dist/collection/tokens/typography/index.ts. This can be helpful for CSS-in-JS.

Note: To replace Inter by another font, the CSS file @pollux-docaposte/core-design-system/dist/collection/tokens/typography/inter.css can be used as reference to create a new CSS file with the same utility classes.

Theming

By default the Design Tokens are scoped to the :root to be global. CSS variables can be scoped easily like below:

/* Any CSS selector can be used to scope variables */
/* e.g: [data-theme="theme-a"] */
.theme-a {
    --design-token-name: value;
}
.theme-b {
    --design-token-name: another-value;
}