@rt-tools/ui-kit-v2 0.5.0 → 0.6.0

package/README.md

@@ -34,6 +34,20 @@ export const appConfig: ApplicationConfig = {
 @use '@rt-tools/ui-kit-v2/styles/tokens.css';
 ```
 
+Стили кита объявлены слоем каскада `rt-kit` — тремя подслоями в порядке `vendor`, `base`,
+`components`. Правило приложения, объявленное вне слоя, выигрывает у любого правила кита
+независимо от специфичности: перебирать её счётом и обходить чужую вёрстку больше не нужно.
+
+Объявления свойств на корне страницы в слой не уходят — их приложение перебивает порядком,
+объявляя своё после `tokens.css`.
+
+Подслой `vendor` — для чужого CSS, который чинит кит. Тема редактора текста подключается в
+него, иначе она выигрывает у правил кита и панель редактора перестраивается:
+
+```scss
+@import 'quill/dist/quill.snow.css' layer(rt-kit.vendor);
+```
+
 Иконки лежат отдельными файлами в `node_modules/@rt-tools/ui-kit-v2/src/assets/icons`: сборка
 копирует каталог в свою статику, а `provideRtIcons('/icons')` называет адрес, по которому он
 опубликован. Реестр забирает их одним проходом на подъёме и склеивает в inline-sprite, поэтому
@@ -97,6 +111,47 @@ provideRtKitLabels({
 доживает до рантайма) и то, что на них отвечают готовой строкой: подстановки вида `{{name}}`
 переводчик делает сам. Подпись, которой он не дал, берётся английской — поштучно, не набором.
 
+## Настройка компонента снаружи
+
+Компонент не берёт ступень шкалы там, где рисует себя: между ступенью и местом употребления
+стоит своё свойство компонента — `--rt-<блок>-<что>`. Объявлено оно в корне блока, значением по
+умолчанию стоит та самая ступень, поэтому без единой строки от приложения кит выглядит так же,
+как выглядел.
+
+Своими свойствами покрыты четыре рода назначений:
+
+| Род           | Имя свойства                        | Где применяется                                                 |
+| ------------- | ----------------------------------- | --------------------------------------------------------------- |
+| скругление    | `--rt-<блок>-*-radius`              | рамка блока, пузырь, значок, плашка, кольцо аватара             |
+| тень          | `--rt-<блок>-*-shadow`              | карточка, панель в перекрытии, кольцо фокуса, приподнятая точка |
+| толщина рамки | `--rt-<блок>-*-border-width`        | обводка, разделитель строк, дорожка, полоса под вкладкой        |
+| длительность  | `--rt-<блок>-*-transition-duration` | переход цвета, фона, размера и сдвига                           |
+
+Отступ, кегль и габариты остаются на ступенях намеренно: роль отступа одним словом не
+называется, и свойство под неё вышло бы именем места, а не именем роли.
+
+Приложение переопределяет свойство правилом той же цели и большей силы — наследования тут мало,
+объявление живёт на самом блоке:
+
+```css
+.my-app .rt-button {
+    --rt-btn-radius: 0;
+}
+```
+
+Часть, которую браузер уносит из поддерева блока — панель списка, меню, перетаскиваемая
+строка, — объявляет свойство на себе, и целиться в неё надо тоже отдельно:
+
+```css
+.my-app .rt-select__panel {
+    --rt-select-panel-shadow: none;
+}
+```
+
+Что ни один компонент этот порядок не обошёл, проверяет `pnpm run check:tokens-styles`: ступень,
+взятая в стилях компонента напрямую, роняет прогон. Показ на витрине — страница
+`Foundation / Design Tokens / Component Props`.
+
 ## Свой логотип
 
 `rt-logo` рисует то, что даст приложение: своих начертаний кит не везёт.
@@ -121,3 +176,19 @@ pnpm exec nx test @rt-tools/ui-kit-v2
 pnpm exec nx lint @rt-tools/ui-kit-v2
 pnpm exec stylelint "projects/ui-kit-v2/**/*.scss"
 ```
+
+## Переход на слой каскада
+
+Стили кита переехали в слой `rt-kit`, и это меняет вид у тех, кто настраивал кит поверх. Ошибки
+сборки не будет — узнаётся глазами, поэтому названо здесь прямо.
+
+- **Правило приложения теперь выигрывает у правила кита независимо от специфичности.** Место,
+  где кит перебивали поднятой специфичностью или обходом чужой вёрстки, продолжит работать, но
+  надобности в этом больше нет: обычное правило сильнее любого правила из слоя.
+- **Правило кита теперь проигрывает и чужой библиотеке, чей CSS объявлен вне слоя.** Тема
+  редактора текста подключается в подслой `vendor` — импортом с именем подслоя; подключённая
+  мимо, она перестраивает панель редактора.
+- **Кит больше не настаивает на своём восклицательным знаком.** Таблица в карточном виде
+  перестала перебивать `min-width` приложения: приложению, которому нужен и горизонтальный
+  скролл, и карточный вид, остаётся сузить свой селектор до широкого экрана.
+