EPMRPP-90022 || UI-kit docs. Add theming description

README.md

@@ -23,6 +23,93 @@ pnpm add @reportportal/ui-kit
 
 ## Usage
 
+1. Import the library styles at the top-level of your application:
+
+```jsx
+import '@reportportal/ui-kit/dist/style.css';
+```
+
+2. To use the components in your project, import them from the package:
+
+```jsx
+import { Button } from '@reportportal/ui-kit';
+
+const MyComponent = () => (
+    <Button>Button</Button>
+);
+```
+
+**Note:** In the future we plan to calibrate the build process to prebuild styles individually for each component and enable tree-shaking.
+
+### Theming
+
+All components are provided with the `light'` theme by default.
+To use the `dark` theme, you need to wrap your application with the `ThemeProvider` component and pass the `dark` theme as a prop:
+
+```jsx
+import { ThemeProvider, Button } from '@reportportal/ui-kit';
+
+const MyComponent = () => (
+    <ThemeProvider theme="dark">
+        <Button>Dark theme button</Button>
+    </ThemeProvider>
+);
+```
+
+`ThemeProvider` can be nested to provide different themes for different parts of the application if needed.
+
+```jsx
+import { ThemeProvider, Button } from '@reportportal/ui-kit';
+
+const MyComponent = () => (
+    <ThemeProvider theme="light">
+        <Button>Light theme button</Button>
+        <ThemeProvider theme="dark">
+            <Button>Dark theme button override</Button>
+        </ThemeProvider>
+    </ThemeProvider>
+);
+```
+
+### Custom themes
+
+The `ThemeProvider` component provides the ability to pass custom themes to the application.
+
+To use a custom theme, you need to pass an object with the custom theme name as a key and the custom theme class name as a value to the `customThemes` prop of the `ThemeProvider` component:
+
+```jsx
+import { ThemeProvider, Button } from '@reportportal/ui-kit';
+
+const MyComponent = () => (
+    <ThemeProvider customThemes={{ 'my-theme': 'my-custom-theme' }} theme="my-theme">
+        <Button>Custom theme button</Button>
+        <ThemeProvider theme="dark">
+            <Button>Dark theme button override</Button>
+        </ThemeProvider>
+    </ThemeProvider>
+);
+```
+
+Then just override the ui-kit CSS custom properties in your custom theme class:
+
+```scss
+.my-custom-theme {
+  --rp-ui-kit-font-family-base: OpenSans, Segoe UI, Tahoma, sans-serif;
+  --rp-ui-kit-color-primary: green;
+  --rp-ui-kit-color-primary-hover: #69e569;
+  --rp-ui-kit-color-primary-focused: var(--rp-ui-kit-color-primary-hover);
+  --rp-ui-kit-color-primary-pressed: var(--rp-ui-kit-color-primary-hover);
+}
+```
+
+CSS custom properties and their default values can be found in the [themes](./src/assets/styles/themes).
+
+The number of custom themes is not limited and actual theme can be easily switched by changing the `theme` prop.
+
+## Components
+
+To see a published showcase of the latest components released with its API and use cases, follow the [link]() (to be provided).
+
 ## Build process
 
 We use [vite](https://vitejs.dev/) as a build tool.
@@ -48,19 +135,23 @@ To create a ready-to-deploy version of the Storybook run
 npm run build:storybook
 ```
 
-To see a published showcase of the latest components released, follow the [link]() (to be provided).
-
 ### Code style
 
+We follow the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) and use [ESLint](https://eslint.org/) to enforce it.
+
 ### CSS
 
+We use [SCSS](https://sass-lang.com/) as a CSS preprocessor.
+
 #### Theming
 
 The project uses [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) to provide colors/fonts/etc. values for different themes via theme-specific CSS classes.
 All components get the appropriate theme values at runtime based on the cascading nature of CSS.
 
 This approach was chosen because it is easy to implement and maintain, and CSS Custom Properties are part of [WEB standards](https://www.w3.org/TR/css-variables-1/) and supported by [all major browsers](https://developer.mozilla.org/en-US/docs/Web/CSS/--*#browser_compatibility).
 
+The CSS custom properties that come from DS are prefixed with `rp-ui-kit-base` to avoid conflicts with other CSS properties and can be found in the [base.scss](./src/assets/styles/themes/base.scss).
+
 ### External libs
 
 - [classnames](https://www.npmjs.com/package/classnames) - used for conditionally joining class names together.
@@ -69,3 +160,5 @@ This approach was chosen because it is easy to implement and maintain, and CSS C
 - [rc-scrollbars](https://www.npmjs.com/package/rc-scrollbars) - used for custom scrollbars.
 
 ### Testing
+
+To be provided.

src/assets/styles/themes/base.scss

@@ -3,7 +3,7 @@
 @use "../fonts/index";
 @import "light";
 
-// TODO: Use corresponding naming to separate base DS variables from the theme-specific. Discuss with uX
+// TODO: Use corresponding naming to separate base DS variables from the theme-specific. Discuss with UX
 :root {
   /* colors */