@team23/design-system/README.md

A set of (S)CSS Rules for basic styling that should be a common base for all projects in TEAM23 SE.

# Design System

A set of (S)CSS Rules for basic styling that should be a common base for all projects in TEAM23 SE.

[Published using NPM.](https://www.npmjs.com/package/@team23/design-system)

## How to use it in your projects
#### Install package as dependency
```
npm i @team23/design-system
```
#### Import styles
`@import '@team23/design-system/theme';` *only once* in your main style file to have access to all global classes and placeholders.

`@import '@team23/design-system/utilities';` in every file you want to use some helper mixins or functions

### Customization
Every variable from the variables folder can be overridden for each app individually.

```scss
/* Import all variables and utilities */

$base-size: 1rem;
$spacing-xs: 4rem;

$color-mapping-for-utilities: (
    grey: #888,
);

$color-mapping-for-background: (
    primary: (
        heading: yellow,
    ),
);

@import '@team23/design-system/utilities';
@import '@team23/design-system/theme';
```

Note: you cannot import the utilities before overwriting the variables.

## Structure

```
theme/
|
|- abstracts/
|   |- _color.scss              # mixins to work with colors
|   |- _spacing.scss            # mixins to work with spacing
|   |- _typography.scss         # mixins to work with typography
|
|- ui/
|   |- _base.scss               # global styling that might want to stay in the design system
|   |- _color.scss              # utility classes to work with color
|   |- _reset.scss              # base styling to reset browser defaults
|   |- _spacing.scss            # utility classes to work with spacing
|   |- _typography.scss         # utility classes to work with typography
|
|- variables/
|   |- _base.scss               # base css variables
|   |- _color.scss              # variables to define available colors (e.g. colors and mappings)
|   |- _spacing.scss            # variables to define available spacings (e.g. sizes and names)
|   |- _typography.scss         # variables to define typography (e.g. font-sizes and family)
|
|- vendors/
|   |- _primeflex.scss          # primeflex integration with some required variables
|   |- (_primeng.scss)            # all variables used for the prime frameworks (not ready yet, not part of the default import)
|
|- utilities                    # a collection of all utilities. can be imported seperately
|- index                        # all classes to import once in your app

```

## What's inside?

### Colors
A collection of classes and CSS Variables to style the color/background-color.
```html
<div class="color-error"></div>

<div class="background-primary"></div>
```
### Typography
A collection of classes and mixins to style the font-size/weight/style.
```html
<div class="heading-large"></div>

<div class="text"></div>
```

### Spacing
A collection of classes and one mixin to style spacings (margin/padding).
```html
<div class="p-m"></div>

<div class="-mt-xxl"></div>
```
### Utilities
To quickly create layouts we decided to use some utility classes. Therefor we do use parts of [Primeflex](https://www.primefaces.org/primeflex/):
- grid
- display
- position
- flexbox
- gap


### Custom CSS
There are different ways to use the different aspects of the design system in your custom component styles
#### Colors
Since colors are defined using css variables you can use them directly when needed:
```css
.card {
    color: var(--color-text-on-secondary);
    background-color: var(--background-secondary);
}
```
#### Spacing
Since spacing classes are generated based on a config it is not possible to include them directly. There is one mixin for all spacings:
```css
.card {
    @include set-spacing(pt-m);
    @include set-spacing(pl-m);
}
```
#### Typography
Since typography is defined explicitly it's not possible to use only one mixin. There is one mixin for every typography type
```css
.card {
    @include text-small;
    @include text-bold;
}
```