@mr.slonn/my-scss-theme 1.0.0

package/README.md

@@ -0,0 +1,182 @@
+# @mr.slonn/my-scss-theme
+
+SCSS-тема с чётко зафиксированным архитектурным контрактом.  
+**Этот файл README.md является контрактом использования пакета.**
+
+Пакет предназначен для установки через npm и использования в Sass  
+с применением модульной системы (`@use`, `@forward`).
+
+---
+
+## Установка
+
+```bash
+npm install @mr.slonn/my-scss-theme
+````
+
+Пакет не содержит JavaScript и не имеет runtime-зависимостей.
+
+---
+
+## Архитектурный контракт
+
+В пакете **строго разделены две роли**.
+Смешивание этих ролей **запрещено**.
+
+### 1. API-модуль
+
+API предоставляет:
+
+* переменные
+* функции
+* миксины
+
+Свойства API:
+
+* **не генерирует CSS**
+* **не имеет side effects**
+* безопасен для повторного `@use`
+* предназначен для использования в компонентах и библиотеках
+
+### 2. CSS entrypoint
+
+CSS entrypoint:
+
+* генерирует utility-классы
+* генерирует CSS-компоненты
+* используется **только** в корневом entry-файле проекта
+
+❗ Эти роли **запрещено смешивать**.
+Это ограничение Sass, а не рекомендация.
+
+---
+
+## Использование API (основной сценарий)
+
+Используется в компонентах, библиотеках и темах.
+
+```scss
+@use "@mr.slonn/my-scss-theme" as theme;
+
+.card {
+  padding: theme.spacing(4);
+  border-radius: theme.$radius-md;
+}
+```
+
+### Гарантии API
+
+* не генерирует CSS
+* не имеет side effects
+* безопасен для повторного `@use`
+* не зависит от порядка подключения
+* предназначен для переиспользования
+
+---
+
+## Генерация CSS (entrypoint проекта)
+
+Используется **ТОЛЬКО** в корневом entry-файле проекта
+(`main.scss`, `entry.scss`, `app.scss` и т.п.).
+
+```scss
+@use "@mr.slonn/my-scss-theme/scss/main";
+```
+
+Поведение:
+
+* подключает utilities
+* подключает components
+* генерирует готовые CSS-классы
+
+---
+
+## Запрещённые сценарии
+
+```scss
+// ЗАПРЕЩЕНО: использование CSS entrypoint как модуля
+@use "@mr.slonn/my-scss-theme/scss/main" as theme;
+
+// ЗАПРЕЩЕНО: ожидание CSS от API
+@use "@mr.slonn/my-scss-theme";
+```
+
+Нарушение контракта приводит к:
+
+* дублированию CSS
+* конфликтам Sass-модулей
+* неявным ошибкам сборки
+
+---
+
+## Структура пакета (зафиксировано)
+
+```text
+my-scss-theme/
+├── index.scss              # npm API entrypoint (ТОЛЬКО @forward)
+├── package.json
+└── scss/
+    ├── api.scss            # чистый API
+    ├── main.scss           # CSS entrypoint
+    ├── abstracts/
+    │   └── _index.scss
+    ├── utilities/
+    │   └── _index.scss
+    └── components/
+        └── _index.scss
+```
+
+---
+
+## Обоснование архитектуры
+
+* Sass строго разделяет модули и side effects
+* SCSS npm-пакет не является JavaScript-пакетом
+* `index.scss` пакета обязан быть чистым API
+
+Данная структура:
+
+* соответствует канону Sass
+* масштабируется
+* безопасна для автоматического использования (включая AI)
+
+---
+
+## Контракт для AI
+
+### Разрешено
+
+```scss
+@use "@mr.slonn/my-scss-theme" as theme;
+```
+
+### Разрешено только в entrypoint проекта
+
+```scss
+@use "@mr.slonn/my-scss-theme/scss/main";
+```
+
+### Запрещено
+
+```scss
+@use "@mr.slonn/my-scss-theme/scss/main" as theme;
+```
+
+---
+
+## Версионирование
+
+* **PATCH** — исправления, не ломающие API
+* **MINOR** — расширение API
+* **MAJOR** — изменение структуры или контрактов
+
+---
+
+## Статус
+
+* совместим с `install_npm_packages`
+* протестирован через `npx sass`
+* готов для production-использования
+
+```
+```

package/index.scss

@@ -0,0 +1 @@
+@forward "scss/api";

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@mr.slonn/my-scss-theme",
+  "version": "1.0.0",
+  "license": "MIT",
+  "files": [
+    "index.scss",
+    "scss",
+    "README.md"
+  ]
+}

package/scss/.sassdocrc

@@ -0,0 +1,85 @@
+{
+  "package": {
+    "name": "Theme Moexp",
+    "version": "1.0.0",
+    "description": "Основная SCSS тема с архитектурным подходом"
+  },
+   "groups": {
+    "undefined": "Общее",
+    "main": "Главная точка входа",
+    "abstracts": "Абстракции (индекс)",
+    "utilities": "Утилиты (индекс)",
+    "colors": "Цвета",
+    "typography": "Типографика",
+    "spacing": "Отступы",
+    "radius": "Скругления",
+    "mixins": "Миксины",
+    "mixins-color": "Миксины → Цвета",
+    "mixins-shadow": "Миксины → Тени",
+    "mixins-focus": "Миксины → Фокус",
+    "mixins-gradient": "Миксины → Градиенты",
+    "mixins-layout": "Миксины → Раскладка",
+    "mixins-image": "Миксины → Изображения",
+    "mixins-a11y": "Миксины → Доступность",
+    "mixins-reset": "Миксины → Сброс",
+    "mixins-text": "Миксины → Текст",
+    "mixins-flex": "Миксины → Flex",
+    "animations": "Анимации",
+    "animations-timing": "Анимации → Timing",
+    "animations-easing": "Анимации → Easing",
+    "animations-keyframes": "Анимации → Keyframes",
+    "animations-transition": "Анимации → Transitions",
+    "animations-animate": "Анимации → Animate",
+    "animations-hover": "Анимации → Hover",
+    "animations-focus": "Анимации → Focus",
+    "animations-button": "Анимации → Buttons",
+    "animations-icon": "Анимации → Icons",
+    "animations-a11y": "Анимации → A11y",
+    "buttons": "Кнопки",
+    "buttons-variables": "Кнопки → Переменные",
+    "buttons-base": "Кнопки → Базовый миксин",
+    "buttons-variants": "Кнопки → Варианты",
+    "buttons-modifiers": "Кнопки → Модификаторы",
+    "buttons-classes": "Кнопки → CSS-классы",
+    "cards": "Карточки",
+    "cards-variables": "Карточки → Переменные",
+    "cards-base": "Карточки → Базовые",
+    "cards-hover": "Карточки → Hover",
+    "cards-variants": "Карточки → Варианты",
+    "cards-sizes": "Карточки → Размеры",
+    "cards-parts": "Карточки → Части",
+    "cards-blur": "Карточки → Blur",
+    "cards-featured": "Карточки → Featured",
+    "cards-vertical": "Карточки → Vertical",
+    "cards-image": "Карточки → Image",
+    "grid": "Сетка",
+    "grid-variables": "Сетка → Переменные",
+    "grid-functions": "Сетка → Функции",
+    "grid-container": "Сетка → Контейнер",
+    "grid-responsive": "Сетка → Респонсивный",
+    "grid-presets": "Сетка → Пресеты",
+    "grid-item": "Сетка → Элементы",
+    "grid-limit": "Сетка → Ограничение",
+    "grid-areas": "Сетка → Области",
+    "grid-display": "Сетка → Display",
+    "grid-expand": "Сетка → Expand",
+    "patterns": "Декоративные паттерны",
+    "patterns-base": "Паттерны: Базовые",
+    "patterns-stripes": "Паттерны: Полосы",
+    "patterns-dots": "Паттерны: Точки",
+    "patterns-grid": "Паттерны: Сетка",
+    "patterns-checkerboard": "Паттерны: Шахматка",
+    "patterns-noise": "Паттерны: Шум",
+    "patterns-utils": "Паттерны: Утилиты",
+    "patterns-pseudo": "Паттерны: Псевдоэлементы",
+    "utilities": "Утилиты (индекс)",
+    "utilities-visibility": "Утилиты: Видимость",
+    "utilities-spacing": "Утилиты: Отступы",
+    "utilities-text": "Утилиты: Текст",
+    "components": "Компоненты (индекс)",
+    "components-chip": "Компоненты → Chip"
+    "section-title": "Section Title",
+    "section-title-variables": "Section Title → Переменные",
+    "section-title-base": "Section Title → Базовые"
+  }
+}

package/scss/_font-vars.scss

@@ -0,0 +1,25 @@
+/* stylelint-disable */
+////
+/// Переменные шрифтов (без @font-face)
+///
+/// Этот файл генерируется автоматически таском `gulp fonts`.
+/// **Не редактируйте вручную!**
+///
+/// Используйте этот файл в компонентах, где нужны только переменные.
+/// Для полного подключения шрифтов используйте _fonts.scss
+///
+/// @group fonts
+/// @author Gulp fonts task
+/// Generated: 2026-01-31T10:24:19.279Z
+////
+
+/// Шрифт golos text
+/// @type String
+/// @group fonts
+$font-golos-text: 'golos text', sans-serif;
+
+/// Шрифт literata
+/// @type String
+/// @group fonts
+$font-literata: 'literata', sans-serif;
+

package/scss/_fonts.scss

@@ -0,0 +1,139 @@
+/* stylelint-disable */
+////
+/// Автоматически сгенерированные @font-face правила
+///
+/// Этот файл генерируется автоматически таском `gulp fonts`.
+/// **Не редактируйте вручную!**
+///
+/// @group fonts
+/// @author Gulp fonts task
+/// @since 1.0.0
+///
+/// Generated: 2026-01-31T10:24:19.281Z
+/// Font base path: /local/common/theme-moexp/fonts
+/// Total font families: 14
+////
+
+// Re-export переменных для обратной совместимости
+@forward "font-vars";
+
+@font-face {
+    font-family: 'golos text';
+    font-style: normal;
+    font-weight: 900;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Golos-Text/golos-text_black.woff2') format('woff2');
+}
+
+@font-face {
+    font-family: 'golos text';
+    font-style: normal;
+    font-weight: 700;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Golos-Text/golos-text_bold.woff2') format('woff2');
+}
+
+@font-face {
+    font-family: 'golos text';
+    font-style: normal;
+    font-weight: 600;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Golos-Text/golos-text_demibold.woff2') format('woff2');
+}
+
+@font-face {
+    font-family: 'golos text';
+    font-style: normal;
+    font-weight: 500;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Golos-Text/golos-text_medium.woff2') format('woff2');
+}
+
+@font-face {
+    font-family: 'golos text';
+    font-style: normal;
+    font-weight: 400;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Golos-Text/golos-text_regular.woff2') format('woff2');
+}
+
+@font-face {
+    font-family: 'golos text';
+    font-style: normal;
+    font-weight: 1 999;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Golos-Text/golos-text_vf.woff2') format('woff2');
+}
+
+@font-face {
+    font-family: 'literata';
+    font-style: normal;
+    font-weight: 700;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Literata/literata_bold.woff2') format('woff2'),
+         url('/local/common/theme-moexp/fonts/Literata/literata_bold.woff') format('woff');
+}
+
+@font-face {
+    font-family: 'literata';
+    font-style: italic;
+    font-weight: 700;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Literata/literata_bold-italic.woff2') format('woff2'),
+         url('/local/common/theme-moexp/fonts/Literata/literata_bold-italic.woff') format('woff');
+}
+
+@font-face {
+    font-family: 'literata';
+    font-style: italic;
+    font-weight: 400;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Literata/literata_italic.woff2') format('woff2'),
+         url('/local/common/theme-moexp/fonts/Literata/literata_italic.woff') format('woff');
+}
+
+@font-face {
+    font-family: 'literata';
+    font-style: normal;
+    font-weight: 500;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Literata/literata_medium.woff2') format('woff2'),
+         url('/local/common/theme-moexp/fonts/Literata/literata_medium.woff') format('woff');
+}
+
+@font-face {
+    font-family: 'literata';
+    font-style: italic;
+    font-weight: 500;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Literata/literata_medium-italic.woff2') format('woff2'),
+         url('/local/common/theme-moexp/fonts/Literata/literata_medium-italic.woff') format('woff');
+}
+
+@font-face {
+    font-family: 'literata';
+    font-style: normal;
+    font-weight: 400;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Literata/literata_regular.woff2') format('woff2'),
+         url('/local/common/theme-moexp/fonts/Literata/literata_regular.woff') format('woff');
+}
+
+@font-face {
+    font-family: 'literata';
+    font-style: normal;
+    font-weight: 600;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Literata/literata_semibold.woff2') format('woff2'),
+         url('/local/common/theme-moexp/fonts/Literata/literata_semibold.woff') format('woff');
+}
+
+@font-face {
+    font-family: 'literata';
+    font-style: italic;
+    font-weight: 600;
+    font-display: swap;
+    src: url('/local/common/theme-moexp/fonts/Literata/literata_semibold-italic.woff2') format('woff2'),
+         url('/local/common/theme-moexp/fonts/Literata/literata_semibold-italic.woff') format('woff');
+}
+