@amboss/design-system 0.27.2 → 1.0.0-canary-1

package/README.md

@@ -27,96 +27,88 @@ To build storybook run `npm run build-storybook`
 - Add `skip-release` label to skip the release
 - If you want your commit to skip ci, add "[skip ci]" to your commit message.
 
-## Overview
+### Codebase Overview
 
-1. [Tech stack](#tech-stack)
-2. [Folder structure](#folder-structure)
-3. [Build](#build)
-4. [\*.d.ts for styles](#dts-for-styles)
-5. [Tokens, styles and theming](#tokens-styles-and-theming)
-6. [Assets](#assets)
-7. [Media queries](#media-queries)
+**1. [Tech stack](#tech-stack)**<br/>
+**2. [Linting](#linting)**<br/>
+**3. [Folder structure](#folder-structure)**<br/>
+**4. [Build](#build)**<br/>
+**5. [Tokens, styles and theming](#tokens-styles-and-theming)**<br/>
+**6. [Assets](#assets)**<br/>
+**7. [Media queries](#media-queries)**<br/>
 
-### Tech stack
+## Tech stack
 
-Code: **typescript + scss**
+- Code: **typescript**
+- Styles: **emotion.js**
+- Framework: **react**
+- Bundler: **webpack**
+- Environment: **storybook**
+- Tokens: **[style-dictionary](https://github.com/amzn/style-dictionary)**
+- Testing: **jest + react testing library**
 
-Framework: **react**
+## Linting
 
-Bundler: **webpack**
+As for linting and formatting, you can configure your editor to automatically lint and format your code on save. For this purpose, we're using [Prettier](https://prettier.io/) and [ESLint](https://eslint.org/). If you need to do it manually, you can run:
 
-Environment: **storybook**
-
-Tokens: **[style-dictionary](https://github.com/amzn/style-dictionary)**
+```sh
+npm run lint
+```
 
-Testing: **jest + react testing library**
+> This command is also run as a **pre-push hook** and in the pipeline.
 
-### Folder structure
+## Folder structure
 
-<pre>
+```
 |-- .storybook
-   |-- components
-       |-- ColorGrid.tsx
-       |-- SizeGrid.tsx
-   |-- main.js
-   |-- preview.js
+    |-- components
+        |-- ColorGrid.tsx
+        |-- SizeGrid.tsx
+    |-- main.js
+    |-- preview.js
 |-- assets
-   |-- fonts
-      |-- Lato.woff
-|-- build    (autogenerated)
-|-- build-tokens    (autogenerated)
-     |-- _assets_fonts.scss
-     |-- _variables.scss
-     |-- _theme.scss
-     |-- _colors.json
-     |-- _theme.json
+    |-- fonts
+        |-- Lato.woff
+|-- build (autogenerated)
+|-- build-tokens (autogenerated)
+    |-- assets
+        |-- icons.json
+        |-- icons16.json
+    |-- _colors.json
+    |-- _sizes.json
+    |-- visualConfig.ts
 |-- docs
-   |-- Design-principles.mdx
+    |-- Design-principles.mdx
+|-- static
+    |-- image-for-storybook.png
 |-- tokens
-    |-- themes
-        |-- dark.json
-        |-- light.json
-    |-- assets.json
-    |-- colors.json
+    |-- themes
+        |-- dark.json
+        |-- light.json
+    |-- assets.json
+    |-- colors.json
 |-- src
-   |-- components
-      |-- Button
-          |-- Button.tsx
-          |-- Button.scss
-          |-- Button.scss.d.ts    (autogenerated)
-          |-- Button.stories.tsx
-          |-- Button.test.tsx
-   |-- shared
-       |-- _fonts.scss
-   |-- types
-	   |-- index.ts
-   |-- index.ts
-
-</pre>
-
-### Build
-
-There are 3 stages of a build.
-
-1. Generate type definitions for styles
-2. Generate variables and mixins for tokens
-3. Bundle all exported components
-
-#### Generate type definitions for styles
-
-Files like `Button.scss.d.ts` are autogenerated, and they are added to .gitignore.
-
-Type definitions are generating automatically:
+    |-- index.ts
+    |-- components
+        |-- Button
+            |-- Button.tsx
+            |-- Button.stories.tsx
+            |-- Button.test.tsx
+    |-- shared
+        -- mediaQueries.ts
+    |-- types
+        |-- index.ts
+```
 
-- in watch mode while `npm run start` is running
-- after npm install
-- before build
+## Build
 
-You can generate \*d.ts manually using `npm run type-styles` and `npm run type-styles:watch`
+There are 3 stages of a build.
 
-[Why we need \*.d.ts for styles?](#dts-for-styles)
+1. Generate variables, theme values and assets from tokens
+2. Build all exported components with babel (preset-react, preset-typescript)
+2. Bundle all built components with webpack
 
-#### Generate variables and mixins from tokens
+### Generate variables, theme values and assets from tokens
 
 In order to structure our tokens we use **[style-dictionary](https://github.com/amzn/style-dictionary)**.
 This tool is used for creation a content of `./build-tokens` folder where we keep all the scss variables and mixins.
@@ -130,155 +122,121 @@ New variables and mixins gets generated automaticaly:
 You can generate tokens manually using `npm run tokens` and `npm run tokens:watch`
 
 We use tokens to control the most atomic values in styles and themes.
+
 How does it work?
+
 We have a set of .json files that are located in `./tokens` folder, and we have a `style-dictionary` as a tool for converting .json in to various formats.
+
 For example:
-We have a file - `./tokens/colors.json` that gets converted into `./build-tokens/_variables.scss` and `./build-tokens/_colors.json`.
-`_variables.scss` is directly imported in other `.scss` files.
+
+We have a file - `./tokens/colors.json` that gets converted into part of `./build-tokens/visualConfig.ts` and `./build-tokens/_colors.json`.
+
+`visualConfig.ts` is used later as a source for emotion.js theme.
+
 `_colors.json` is imported inside `./.storybook/components/ColorGrid.tsx` in order to present in storybook all the colors we currently have.
 
-The configuration for `style-dictionary` is inside `./style-dictionary.config.json`. In this config we use 2 custom formatters and 1 custom filter, all of them defined in `./style-dictionary.build.js`.
+The configuration for `style-dictionary` is inside `./style-dictionary/style-dictionary.config.json`. In this config we use some custom transforms, filters and formatters, all of them defined in `./style-dictionary/style-dictionary.build.js`.
 
-**custom/format/scss** - a formatter that is used for generation a .json files for tokens like colors, size, weight and so on. These .json files are imported in storybook for presentation.
-**custom/format/theme-scss** - a formatter that is used for generation a `_theme.scss` that contains a `@theme` mixin.
-**custom/filter/only-vars** - a filter for excluding theme and assets from processing them as variables.
+**custom/format/emotion-visual-config** - a formatter that generates visualConfig.ts that contains all variables and themed values.
+
+**custom/filter/emotion-build-tokens** - a filter for all token categories that should go to visutal config.
+
+**custom/format/json** - a formatter for generation .json files per category. This formatter also add `isUsed` flag to according token.
+
+**custom/format/sub-theme-types** - a formatter that generates type definitions for sub-themes.
+
+**custom/assets/svg** - a transformer that adds a path name to dictionary of svg icons.
 
 [More about tokens, themes and styles.](#tokens-styles-and-theming)
 
-#### Bundle all exported components
+### Bundle all exported components
 
 Before publish the design system for npm we run `npm run build` that bundles everything that is exported from `./src/index.ts`.
 
-We use webpack + typescript for bundling. For all `/\.ts(x?)$/` files webpack uses a ts-loader as a rule which is implicitly using `tsconfig.json`.
+We use webpack + babel for bundling. For all `/\.ts(x?)$/` files webpack uses a babel-loader as a rule which is implicitly using `tsconfig.json` and `.babelrc`.
 
-For styles we use sass-loader + css-loader with enabled modules for namespacing all css selectors.
+For styles we use emotion.js.
 
 What in the bundle?
 
-- JS code that is compiled from typescript
-- css rules that are namespaced using css-loader
+- JS code that is compiled from .tsx files (includes common components and emotion.js styled components)
 - I svg icons that are inlined
 
 fonts that are base64-ed currently taken off the build
 
-### .d.ts for styles
-
-We use type definitions for style in order to improve quality of a product overall. One example:
+## Tokens, styles and theming
 
-```js
-import styles from "./button.scss";
+Currently, we have 4 types of tokens:
 
-type ButtonProps = {
-  size: "s" | "m" | "l",
-};
+- atomic values, like colors, sizes, shadows.
+- font assets, that are basically base64 of font files. (not used in production)
+- theme values, that are referencing atomic different atomic values
+- svg icon assets, that are inlined to a json file
 
-export const Button = ({ size }: ButtonProps) => (
-  <button className={styles[size]} />
-);
-```
+As we use Emotion.js all tokenized values are accessible via theme provider. <br />
 
-Here with type definitions we are sure that `button.scss` contain all 3 classes (.s, .m, and .l). Otherwise, it won't compile.
+Basically during the build phase we generate big objects of variables and themed values for each theme (currently light and dark). <br />
 
-### Tokens, styles and theming
+We call this object `ambossVisualConfiguration`.
 
-Currently, we have 3 types of tokens:
+Particular themes from ambossVisualConfiguration has to be imported and passed to the theme provider at the consumer side.<br />
 
-- atomic values, like colors, sizes, shadows.
-- font assets, that are basically base64 of font files.
-- theme values, that are referencing atomic different atomic values
-- svg icon assets, that are inlined to a json file
+<br />
+Atomic values are straight forward and simply converted to `variables`.
 
-Atomic values and font assets are straight forward and simply converted to scss variables.
-After build all atomic values can't be imported as `@import "build-tokens/variables";`
-Fonts are imported inside `./src/shared/_fonts` and never used directly (it doesn't make sense).
-In the application simply `@import "src/shared/fonts";`.
+After build all atomic values are passed to `theme.variables` by emotion.
 
-Theme values are little more complex. When theme token is precessed we generate several entities. All of them are located in `./build-tokens/_theme.scss`
+Example:
+```
+const StyledContainer - styled.div(
+  ({ theme }) => ({
+    marginTop: theme.variables.size.spacing.s
+  })
+);
+```
 
-1. A number of scss-maps with all the theme variables for each theme.
-2. A `@theme` mixin, that include all themes.
-3. A list of scss variables with the name of entries in the maps (see point 1). This is just for IDE auto-complition.
+Theme tokens are little more complex. We generate separate VisualConfig for each theme, but together with that we generate type definition that describe any of the themes. This enables developers not care about current theme and how many themes are there.
 
-As the result developers are free to use a `@theme` mixin for particular css properties with no worries about active theme and amount of themes.
+After build all themes values are passed to `theme.values` by emotion.
 
 Example:
 
-```scss
-@import "build-tokens/theme";
-@import "build-tokens/variables";
-@import "src/shared/fonts";
-
-.primary {
-  @include theme("color", $theme-color-text-primary);
-  font-family: $Lato;
-  margin: 0;
-}
-
-.secondary {
-  @include theme("color", $theme-color-text-secondary);
-}
-
-.s {
-  font-size: $size-font-text-s;
-  line-height: $size-line-height-text-s;
-}
-
-.m {
-  font-size: $size-font-text-m;
-  line-height: $size-line-height-text-m;
-}
-
-.normal {
-  font-weight: $weight-normal;
-}
-
-.bold {
-  font-weight: $weight-bold;
-}
 ```
+const StyledContainer - styled.div(
+  ({ theme }) => ({
+    backgroundColor: theme.values.color.background.layer_2
+  })
+);
+```
+
+Sub-themes are folowing the same concept as themes. Developer can fully rely on `theme.values` object. As long as component in runtime is wrapped in `SubThemeProvider` and it's tokens listed in "tokens/themes/sub-themes/...", all values will be set correctly and automaticaly.
+
+> Note that not all tokens are enabled in sub-themes. Make sure to add missing ones to "tokens/themes/sub-themes/...".
+
+> Components that has "Sub-themed" badge are already in.
 
-### Assets
+## Assets
 
 - assets are defined in `tokens/assets.json`
 - with the help from style-dictionary we create a json file with tokens (`/build-tokens/assets/`)
 - those json files supposed to be imported in the ts module (see Icons.tsx)
 - in order to secure `d.ts` filed in the build we "manually" copy asset jsons on the `postbuild` phase (see package.json)
 
-### Media queries
+## Media queries
 
 There is an API for media-query related props: an array of 3 elements [small, medium, large], for respective screen sizes.
-for example `<Box space=["xs", "xl", "xxl"] />` will set `xs` for small screens, `xl` for medium screens and `xxl` for large.
+
+For example `<Box space=["xs", "xl", "xxl"] />` will set `xs` for small screens, `xl` for medium screens and `xxl` for large.
 
 Basically, if you see a type of `MQ<Whatever>` you can provide an array of 3 `Whatever`s.
 
 In order to add a media query support to your components:
 
-> mq mixin from media-queries module will create a set of media-query selectors.
-
-```scss
-@import "src/shared/media-queries";
-
-@include mq(".align-left") {
-  text-align: left;
-}
-
-@include mq(".align-right") {
-  text-align: right;
-}
-
-@include mq(".align-center") {
-  text-align: center;
-}
-```
-
-> import getMediaQueryClasses from mediaQueries module to create classnames compatible with mixin above.
-> note that third parameter is a prefix to classname.
-
 ```ts
-import cn from "classnames";
+import React from "react";
 
-import { getMediaQueryClasses } from "../../shared/mediaQueries";
-import styles from "./Box.scss";
+import styled from "@emotion/styled";
+import { mq } from "../../shared/mediaQueries";
 
 type TextAlignment = "left" | "center" | "right";
 
@@ -286,9 +244,14 @@ type BoxProps = {
   alignText: TextAlignment | MQ<TextAlignment>;
 };
 
-export const Box = ({ alignText }: BoxProps) => (
-  <button
-    className={cn(...getMediaQueryClasses(alignText, styles, "align-"))}
-  />
+export const Box = styled.div<BoxProps>(
+  ({ alignText = "left" }) =>
+    mq({
+      textAlign: [
+        alignText,
+        { left: "left", right: "right", center: "center" },
+      ],
+    })
 );
 ```
+