npm package: @pollux-docaposte/core-design-system
Description: A UI library of web-components following the Core Design System guidelines
Latest version: 1.0.2

# Core Design System

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

## Tech Stack

- 🔧 [Stencil](https://stenciljs.com/) to build reusable **web-components**. It uses **TypeScript** under the hood for type safety.
- 🎨 Pure CSS for **Design Tokens**.
- 📚 [Storybook](https://storybook.js.org) for UI component development and **Accessibility** check.
- ✅ [Chromatic](https://www.chromatic.com/) for **Design Review**, to prevent UI regressions and bugs in components.
- 📦 [NPM](https://www.npmjs.com/) for packaging and distribution.

## Install

```bash
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:


```html
<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

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

In the root file of the app:

```ts
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:

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

Or in the global css file:

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

If needed they can be imported separately:

```css
/* 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:

```css
/* 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;
}
```