feat: update theming docs

core-ds · Sep 24, 2020 · 2ceba6d · 2ceba6d
1 parent 0d2e819
commit 2ceba6d
Showing 1 changed file with 35 additions and 61 deletions.
diff --git a/docs/2.theming.stories.mdx b/docs/2.theming.stories.mdx
@@ -12,12 +12,12 @@ import styles from './2.theming.stories.css';
 
 ## Темизация
 
-Темы для компонентов доступны в пакете [@alfalab/core-components-themes](https://www.npmjs.com/package/@alfalab/core-components-themes).
+Темы для компонентов доступны в пакете [@alfalab/core-components/themes](https://www.npmjs.com/package/@alfalab/core-components/themes).
 
 Пакет имеет следующую структуру:
 
 ```
-@alfalab/core-components-themes
+@alfalab/core-components/themes
 ├── component1
 |  └── click.css
 |  └── corp.css
@@ -42,12 +42,12 @@ import styles from './2.theming.stories.css';
 
 - В корне пакета лежат css-темы (_click.css и др._), которые переопределяют переменные всех компонентов.
 - В папках находятся темы, разбитые по компонентам.
-- Помимо pure-css тем, доступны миксины из папки `mixins`.
+- Помимо css тем, доступны миксины из папки `mixins`.
 
-Пример pure-css темы:
+Пример css темы:
 
 ```css
-/* @alfalab/core-components-themes/click.css */
+/* @alfalab/core-components/themes/click.css */
 
 :root {
     /**
@@ -63,7 +63,7 @@ import styles from './2.theming.stories.css';
 Пример mixin-темы:
 
 ```css
-/* @alfalab/core-components-themes/mixins/click.css */
+/* @alfalab/core-components/themes/mixins/click.css */
 
 @import './input/click.css';
 @import './button/click.css';
@@ -77,47 +77,40 @@ import styles from './2.theming.stories.css';
 
 ## Использование
 
-### Базовый пример с arui-scripts
+**Core-Components** предоставляет два способа темазации компонентов — в зависимости от того, будете ли вы использовать нативные css-переменных в проде, либо они будут обрабатываться через [postcss-custom-properties](https://github.com/postcss/postcss-custom-properties).
 
-```js
-// Установите пакет с темами
-yarn add @alfalab/core-components-themes
-
-// Подключите в package.json нужную тему
-"aruiScripts": {
-    "сomponentsTheme": "./node_modules/@alfalab/core-components-themes/click.css"
-}
-
-// Вы прекрасны 😽
-```
-
-### Детальная настройка темизации
+### 1. Использование нативных css-переменных
 
-Использовать темы можно несколькими способами, в зависимости от требований и особенностей сборки проекта:
+В этом случае, вам будут доступны все возможности для темизации компонентов:
+- Глобальная темизация
+- Динамическая темизация
+- Темизация по классу
+- Миксины
 
-#### 1. Использование нативных css-переменных
+Для этого, подключите файл с темой в основной js или css файл, после подключения основных стилей.<br/>
+Отключите обработку css переменных, если она включена.
 
-В этом случае, вам доступны все возможности темизации.
-
-- **pure-css**:
+- **Подключение темы в css-файле**:
 
 ```css
 /* Глобально применяем тему */
-@import '~@alfalab/core-components-themes/click.css';
+@import '~@alfalab/core-components/themes/click.css';
 
 /* Применяем тему только для инпута */
-@import '~@alfalab/core-components-themes/input/click.css';
+@import '~@alfalab/core-components/themes/input/click.css';
 ```
 
+- **Подключение темы в js-файле**:
+
 ```jsx
-import '@alfalab/core-components-themes/click.css';
-import '@alfalab/core-components-themes/input/click.css';
+import '@alfalab/core-components/themes/click.css';
+import '@alfalab/core-components/themes/input/click.css';
 ```
 
-- **mixins**:
+- **Точечная темизация с помощью миксинов**:
 
 ```css
-@import '~@alfalab/core-components-themes/mixins/dark.css';
+@import '~@alfalab/core-components/themes/mixins/dark.css';
 
 .dark-block {
     /* Применяем тему к конкретному блоку */
@@ -126,7 +119,7 @@ import '@alfalab/core-components-themes/input/click.css';
 ```
 
 ```css
-@import '~@alfalab/core-components-themes/mixins/input/dark.css';
+@import '~@alfalab/core-components/themes/mixins/input/dark.css';
 
 .dark-input {
     /* Темизируем определенный инпут */
@@ -138,50 +131,31 @@ import '@alfalab/core-components-themes/input/click.css';
 
 - Для поддержки миксинов — используйте [postcss-mixins](https://github.com/postcss/postcss-mixins)
 
-- Если вы используете [arui-scripts](https://github.com/alfa-laboratory/arui-scripts), то вам нужно отключить транспайлинг переменных (preserve = true):
+- Если вы используете [arui-scripts](https://github.com/alfa-laboratory/arui-scripts) — [отключите](https://github.com/alfa-laboratory/arui-scripts#тонкая-настройка) обработку переменных с помощью опции `keepCssVars: true`
 
-```js
-// arui-scripts.overrides.js в корне проекта
-// https://github.com/alfa-laboratory/arui-scripts#тонкая-настройка
-
-const {
-    createPostcssConfig, // функция для создания конфигурационного файла postcss
-    postcssPlugins, // список плагинов
-    postcssPluginsOptions, // коллекция конфигураций плагинов
-} = require('arui-scripts/configs/postcss.config');
-
-module.exports = {
-    postcss: () => {
-        const newOption = {
-            ...postcssPluginsOptions,
-            '@alfalab/postcss-custom-properties': {
-                ...postcssPluginsOptions['@alfalab/postcss-custom-properties'],
-                preserve: true,
-            },
-        };
-        return createPostcssConfig(postcssPlugins, newOption);
-    },
-};
+```json
+"aruiScripts": {
+    "keepCssVars": true
+}
 ```
 
-#### 2. Транспайлинг переменных при сборке
+### 2. Темизация при включенной обработке переменных
 
-В этом случае доступно использование только pure-css тем.
+В этом случае вам будут доступны только глобальные css темы, которые меняют вид всех компонентов сразу.
 
 - Если вы используете [arui-scripts](https://github.com/alfa-laboratory/arui-scripts) — подключите нужную тему в `package.json`:
 
 ```json
 "aruiScripts": {
-    "сomponentsTheme": "./node_modules/@alfalab/core-components-themes/click.css"
+    "сomponentsTheme": "./node_modules/@alfalab/core-components/themes/click.css"
 }
 ```
 
-* Иначе, используйте [alfa-laboratory/postcss-custom-properties](https://github.com/alfa-laboratory/postcss-custom-properties), указав в `importFrom` путь к файлу с темой.
+- Иначе, используйте плагин [postcss-custom-properties](https://github.com/postcss/postcss-custom-properties), указав в `importFrom` путь к файлу с темой. При этом css-переменные должны вырезаться (`preserve=false`)
 
 ```js
 postcssCustomProperties({
-    preserve: true,
-    importFrom: './node_modules/@alfalab/core-components-themes/click.css',
+    importFrom: './node_modules/@alfalab/core-components/themes/click.css',
 });
 ```