feat(visual): added guide for new components with css vars only, reverted changes for docs

NikGurev · NikGurev · commit 886e33e4f67c · 2024-09-03T18:10:31.000+03:00
diff --git a/angular.json b/angular.json
@@ -71,10 +71,7 @@
                         "styles": [
                             {
                                 "input": "apps/docs/src/main.scss"
-                            },
-                            "apps/docs/src/styles/koobiq/default-theme/css-tokens-light.css",
-                            "apps/docs/src/styles/koobiq/default-theme/css-tokens-dark.css"
-
+                            }
                         ],
                         "scripts": [],
                         "vendorChunk": true,
diff --git a/apps/docs/scripts/build-tokens.js b/apps/docs/scripts/build-tokens.js
@@ -44,8 +44,6 @@ function buildTokens(themeConfig) {
         delete extendedPlatform.platforms.figma;
 
         extendedPlatform.platforms.css.files[0].options.selector = `.${platform.skin}`;
-        extendedPlatform.platforms.css.files[1].options.selector = '.theme-light';
-        extendedPlatform.platforms.css.files[2].options.selector = '.theme-dark';
 
         const StyleDictionaryExtended = StyleDictionary.extend(extendedPlatform);
         delete StyleDictionaryExtended.platforms.figma;
diff --git a/apps/docs/src/styles/koobiq/default-theme/css-tokens-dark.css b/apps/docs/src/styles/koobiq/default-theme/css-tokens-dark.css
@@ -2,7 +2,7 @@
  * Do not edit directly
  */
 
-.theme-dark {
+.kbq-dark {
   --kbq-theme-default: hsla(216, 100%, 50%, 100%);
   --kbq-success-default: hsla(104, 64%, 50%, 100%);
   --kbq-warning-default: hsla(38, 100%, 35%, 100%);
diff --git a/apps/docs/src/styles/koobiq/default-theme/css-tokens-light.css b/apps/docs/src/styles/koobiq/default-theme/css-tokens-light.css
@@ -2,7 +2,7 @@
  * Do not edit directly
  */
 
-.theme-light {
+.kbq-light {
   --kbq-theme-default: hsla(216, 100%, 50%, 100%);
   --kbq-success-default: hsla(104, 64%, 50%, 100%);
   --kbq-warning-default: hsla(38, 100%, 35%, 100%);
diff --git a/docs/guides/theming-2.0.md b/docs/guides/theming-2.0.md
@@ -0,0 +1,43 @@
+### Что нового?
+
+Теперь использование компонентов стало проще! Мы движемся к полной изоляции компонентов, что позволит вам легко подключать и использовать их. Кроме того, мы убрали необходимость пробрасывать токены для задания цветов компонентам.
+
+### Как использовать?
+
+1. Импортируйте компонент
+2. Просто добавьте класс `kbq-light` к элементу <body> вашего HTML-документа для использования светлой темы и `kbq-dark` для темной темы.
+
+Для переключения тем используйте [ThemeService.](https://github.com/koobiq/angular-components/blob/main/packages/components/core/services/theme.service.ts#L24)
+
+### Доступные селекторы для темной и светлой темы
+
+Вот таблица доступных селекторов для темной и светлой тем:
+
+| Тема    | Селекторы                                  |
+| ------- | ------------------------------------------ |
+| Темная  | .kbq-dark, .theme-dark, .kbq-theme-dark    |
+| Светлая | .kbq-light, .theme-light, .kbq-theme-light |
+
+Мы рекомендуем использовать те селекторы, которые указаны в сервисе `ThemeService` (`kbq-theme-dark` для темной и `kbq-theme-light` для светлой).
+
+### Как задать кастомные значения компоненту дизайн-системы?
+
+Изменить цвета, размеры и шрифты можно задав соответствующие значения css-переменным компонента.
+Например:
+
+```css
+.kbq-theme-dark {
+    --kbq-alert-default-contrast-container-background: custom-color;
+    --kbq-alert-default-contrast-container-title: custom-color;
+}
+```
+
+### Откуда теперь брать значения дизайн-токенов для компонентов?
+
+Все актуальные значения для компонентов хранятся в репозитории [@koobiq/design-tokens](https://github.com/koobiq/design-tokens). В репозитории Angular-компонентов затем преобразуются в CSS-переменные.
+Хранение дизайн-токенов в отдельном репозитории позволяет переиспользовать их в других проектах. Сгенерированные на основе дизайн-токенов CSS-переменные позволяет более удобно использовать компоненты и ускоряют их разработку, в том числе проведение дизайн-ревью.
+
+### Что планируется сделать дальше?
+
+Мы планируем применить эти улучшения ко всем компонентам и использовать семантические значения для CSS-переменных компонентов, такие как `var(--kbq-size-m)` вместо `12px`.
+Это сделает код более читаемым и поддерживаемым.
diff --git a/packages/components-dev/index.html b/packages/components-dev/index.html
@@ -21,7 +21,7 @@
 
         <title>Dev Example</title>
     </head>
-    <body class="kbq-app-background">
+    <body class="kbq-app-background kbq-light">
         <app />
     </body>
 </html>
diff --git a/packages/components/alert/alert-tokens.scss b/packages/components/alert/alert-tokens.scss
@@ -1,4 +1,4 @@
-:root {
+.kbq-alert {
     --kbq-alert-size-normal-container-border-radius: 12px;
     --kbq-alert-size-normal-container-padding-top: 0;
     --kbq-alert-size-normal-container-padding-right: 8px;
@@ -63,6 +63,9 @@
         sans-serif;
     --kbq-alert-font-text-text-transform: null;
     --kbq-alert-font-text-font-feature-settings: 'calt', 'kern', 'liga', 'ss01', 'ss04';
+}
+
+:where(.kbq-light, .theme-light, .kbq-theme-light) {
     --kbq-alert-default-contrast-container-background: hsla(229, 15%, 92%, 100%);
     --kbq-alert-default-contrast-container-title: hsla(229, 15%, 15%, 100%);
     --kbq-alert-default-contrast-container-text: hsla(229, 15%, 15%, 100%);
@@ -95,7 +98,7 @@
     --kbq-alert-colored-theme-container-text: hsla(229, 15%, 15%, 100%);
 }
 
-.kbq-dark {
+:where(.kbq-dark, .theme-dark, .kbq-theme-dark) {
     --kbq-alert-default-contrast-container-background: hsla(229, 15%, 25%, 100%);
     --kbq-alert-default-contrast-container-title: hsla(229, 15%, 80%, 100%);
     --kbq-alert-default-contrast-container-text: hsla(229, 15%, 80%, 100%);
diff --git a/tools/cspell-locales/ru.json b/tools/cspell-locales/ru.json
@@ -39,6 +39,7 @@
         "инпуте",
         "кастомизируемых",
         "кастомное",
+        "кастомные",
         "кликает",
         "контрол",
         "контролам",
diff --git a/tools/tokens/build-each-component.js b/tools/tokens/build-each-component.js
@@ -30,10 +30,20 @@ const dictionaryMapper = (dictionary, outputReferences) => {
     return dictionary.allTokens.map(formatProperty).join('\n');
 };
 
+const filterTokens = (dictionary, predicate) => {
+    const filteredTokens = dictionary.allTokens.filter(predicate);
+    return { ...dictionary, allTokens: filteredTokens, allProperties: filteredTokens };
+};
+
 StyleDictionary.registerFormat({
     name: 'kbq-css/component',
     formatter: function ({ dictionary, options = {} }) {
-        const { outputReferences, selector = ':root', darkThemeSelector = '.kbq-dark' } = options;
+        const {
+            outputReferences,
+            component,
+            lightThemeSelector = ':where(.kbq-light, .theme-light, .kbq-theme-light)',
+            darkThemeSelector = ':where(.kbq-dark, .theme-dark, .kbq-theme-dark)'
+        } = options;
 
         const allTokens = applyCustomTransformations(dictionary);
 
@@ -45,18 +55,16 @@ StyleDictionary.registerFormat({
         );
 
         // formatting function expects dictionary as input, so here initialize a copy to work with different tokens
-        const baseDictionary = { ...dictionary };
-        const darkDictionary = { ...dictionary };
-
-        baseDictionary.allTokens = baseDictionary.allProperties = baseDictionary.allTokens.filter(
-            (token) => token.attributes.light || token.attributes.type === 'size' || token.attributes.font
-        );
-        darkDictionary.allTokens = darkDictionary.allProperties = darkDictionary.allTokens.filter(
-            (token) => token.attributes.dark
+        const baseDictionary = filterTokens(
+            dictionary,
+            (token) => token.attributes.type === 'size' || token.attributes.font
         );
+        const lightDictionary = filterTokens(dictionary, (token) => token.attributes.light);
+        const darkDictionary = filterTokens(dictionary, (token) => token.attributes.dark);
 
         return Object.entries({
-            [selector]: baseDictionary,
+            [`.kbq-${component}`]: baseDictionary,
+            [lightThemeSelector]: lightDictionary,
             [darkThemeSelector]: darkDictionary
         })
             .map(([key, currentDictionary]) => {
@@ -81,7 +89,10 @@ const main = async () => {
                     // give access to light/dark/palette tokens to resolve reference manually
                     ['light', 'dark', 'palette'].includes(token.attributes.category),
                 format: 'kbq-css/component',
-                prefix: 'kbq'
+                prefix: 'kbq',
+                options: {
+                    component
+                }
             };
         });
 
