<h2 align="center">Astro Design System 💅</h2>
<p align="center">

<p align="center">
  <i>✨ Component library based on our design system 🛠</i>
</p>

## Installation

```bash
$ yarn add @astro-my/design-system

# or

$ npm install --save @astro-my/design-system
```

### Required peer dependencies

This component library comes with some [peer dependencies](https://docs.npmjs.com/files/package.json#peerdependencies) which are required to be available in any project consuming it. These include but may not be limited to: `moment`, `moment-timezone`, `react`, `react-dom`, `react-intl`,`@material-ui/core`,`@material-ui/icons` and `react-router-dom`. An up-to-date list with their respective version ranges can be found in the [package.json](https://bitbucket.org/DigitalPlumbing/de-design-system/src/master/package.json). Please make sure all packages are installed within your application for the component library to be able to work as expected.

### Importing

The package's main export contains all UI components.

```js
import {
  Header,
  Article,
  Grid,
  Footer,
  // etc.
} from '@astro-my/design-system';
```

#### Importing CSS variables

When you are developing your application using UI Kit components, chances you want to use the same design tokens as our design system. We provide them through both **CSS variables** and **JavaScript variables**.

<details>
<summary>Show details</summary>

We expose the **CSS variables** from the `@astro-my/design-system/materials/custom-properties.css` file.

**Importing css variables in css files**

You will need a [postcss-import](https://github.com/postcss/postcss-import) plugin, and a postcss variable plugin: either [postcss-custom-properties](https://github.com/postcss/postcss-custom-properties) or [postcss-css-variables](https://github.com/MadLittleMods/postcss-css-variables) would work.

```css
@import '@astro-my/design-system/materials/custom-properties.css';

.container {
  padding: var(--spacing-l);
}
```

```js
// wherever you process your CSS
postcss([postcssImportPlugin(), postcssCustomProperties()]);
```

**Using postcss-custom-properties and importFrom**

The ui-kit css variables can also be injected using [postcss-custom-properties](https://github.com/postcss/postcss-custom-properties), removing the need to import them directly inside your css files.

```css
/* no import required! */
.container {
  padding: var(--spacing-l);
}
```

```js
// wherever you process your CSS
postcss([
  postcssCustomProperties({
    preserve: false,
    importFrom: require.resolve(
      '@astro-my/design-system/materials/custom-properties.css'
    ),
  }),
]);
```

**Accessing JavaScript variables and design tokens**

You can also access the JavaScript variables like this

```js
import { customProperties } from '@astro-my/design-system';

const primary = customProperties.colorPrimary;
```

> Please look at the [file](materials/custom-properties.js) itself to inspect which variables are available (_documentation will be provided in the future_).

</details>

## Motivation

- Declarative components serving as a design guide
- Shared independently from the application's code base
- Used across different apps consumed by different teams
- Shared language between developers and designers

## Documentation and Storybook

Available at http://designsystem.eco.astro.com.my.