itube-specs 0.0.858 → 0.0.859

package/README.md

@@ -1,11 +1,14 @@
 # itube-specs
 
 Общий **Nuxt Layer** для сайтов itube. Держит единую базу: компоненты, composables, сервисы, утилиты,
-runtime-хелперы, типы, lib-данные, а также middleware, SSR-плагины и BFF-хендлеры (`server/api`).
+runtime-хелперы, типы, lib-данные, middleware, SSR-плагины, BFF-хендлеры (`server/api`) и **весь SCSS —
+палитру, темы, миксины и глобальные стили**.
 Приложения расширяют слой (`extends: ['itube-specs']`) и форкаются под разные сайты одной ниши —
 поэтому слой должен оставаться **самодостаточным и site-agnostic**.
 
 > Bitbucket: https://bitbucket.org/luckytube/specs/src/master/
+>
+> Заводишь новый сайт поверх слоя — [**NEW_SITE_CHECKLIST.md**](./NEW_SITE_CHECKLIST.md).
 
 ---
 
@@ -81,10 +84,52 @@ lib/           # статические scheme/config-данные (barrel index
 middleware/    # глобальные: auth.global, normalize.global, age.global
 plugins/       # SSR/клиент: country/countries/mobile (SSR), services.client, sentry.client, adv
 server/        # BFF: api/** (тонкие прокси к внешнему API), utils/metrics, plugins/*, tasks
+assets/
+  icons/       # спрайты/svg для <UiIcon>
+  scss/
+    vars/      # _palette (сырые $color-*), _vars (скаляры), _tokens (CSS custom props), _z-index, _index
+    themes/    # по папке на тему: light/_theme.scss, dark/_theme.scss — токены по компонентам
+    mixins/    # font-sizes, breakpoints, accessibility, page, video-card, surface, button
+    base/      # document, global, hacks, animations, loading
+    layout/    # layout, page
+    main.scss  # точка входа: vars/tokens + base + layout
 ```
 
-> `middleware`/`plugins`/`server` обязаны быть в `files` (whitelist) — иначе не попадут в паблиш
-> (см. раздел `files`/`exports`).
+> `middleware`/`plugins`/`server` и каждая подпапка `assets/scss/*` обязаны быть в `files` (whitelist) —
+> иначе не попадут в паблиш (см. раздел `files`/`exports`).
+
+---
+
+## Темы
+
+Темы живут здесь, по папке на тему, и раздаются всем сайтам:
+
+```
+assets/scss/themes/light/_theme.scss
+assets/scss/themes/dark/_theme.scss
+```
+
+Приложение только **выбирает** одну — `theme:` в его `config/site.config.ts`. Оттуда значение читают
+и `app.config.ts` (в рантайм), и `nuxt.config.ts`, который добавляет `themes/<theme>/` в Sass
+`loadPaths`. `@forward 'theme'` в `vars/_index.scss` резолвится туда, потому что рядом с ним
+`_theme.scss` нет.
+
+**Папка-на-тему обязательна:** Sass требует литеральный путь в `@use`/`@forward`, значит имя файла
+всегда `_theme.scss`, а варьироваться может только папка. Плоские `themes/light.scss` потребовали бы
+`@forward 'themes/light'` — литерал, который нельзя подставить на билде.
+
+Приоритет `loadPaths` — приложение первым, поэтому сайт может перекрыть любой партиал по имени:
+свой `assets/scss/vars/_theme.scss` в проекте выиграет у темы слоя (относительный резолв Sass старше
+`loadPaths`). Это точка пер-сайтовой темизации.
+
+**Все токены обязаны быть во всех темах.** Отсутствующий токен — жёсткая ошибка Sass в момент, когда
+тема выбрана, то есть падает вся сборка сайта, а не «поехал цвет». Сверять набор имён после любой
+правки темы.
+
+Контекстные различия (контрол внутри попапа, вариант кнопки, зависящий от темы) решают миксины
+`surface()` и `button-variant()` из `mixins/`: место объявляет себя, а значения даёт тема через карты
+`$surfaces` / `$button-variant-overrides`. Компоненты про темы не знают. `appConfig.theme` — только
+для структурных различий (`v-if`, другой элемент), никогда для цвета.
 
 ---
 
@@ -117,8 +162,9 @@ ad-конфиг), теперь читается из `runtimeConfig.public` (з
   `lib/` (scheme, css-breakpoints), middleware (`auth`/`normalize`/`age`), SSR-плагины
   (`country`/`mobile`/`services`/`sentry`/`adv`), BFF-хендлеры `server/api/**` — всё site-agnostic.
 - **Приложение:** только per-site — **значения** config (флаги/реклама/локали) через `runtimeConfig.public`
-  (слой держит пустые контейнеры-заглушки), `assets/scss` (токены), страницы, i18n-локали и остаток
-  `server/`, завязанный на локали (`locale-guard`, `site/languages`, `is-locale-blocked`).
+  (слой держит пустые контейнеры-заглушки), i18n-локали, `public/` и **выбор темы** (`theme:` в
+  `config/site.config.ts`). Своего SCSS у приложения нет: `assets/scss/` — пустой слот-оверрайд.
+  `server/` целиком в слое, включая locale-кластер.
 
 ---
 
@@ -128,10 +174,14 @@ ad-конфиг), теперь читается из `runtimeConfig.public` (з
 
 - **Компоненты** — `pathPrefix: true`: имя = папка + файл (`ui/icon.vue` → `<UiIcon>`), BEM-класс = kebab
   тега. Корень папки — `index.vue` (или `main.vue`, если иначе имя было бы односложным).
-- **`as const`** вместо `enum` — доменные наборы в `runtime/constants/`.
+- **`as const`** вместо `enum` — доменные наборы в `runtime/constants/`, тип через
+  `typeof X[keyof typeof X]`. В enum не положить строку из API, он остаётся в бандле, и в
+  опубликованном пакете `import type` на нём ломается в рантайме. Фреймворковые union'ы не
+  оборачивать. Подробнее — в [CLAUDE.md](./CLAUDE.md).
 - **Стили** — co-location в `<style lang="scss">` без `scoped`, flat-BEM, только дизайн-токены.
-  ⚠️ Токены (`vars`/`mixins`) инжектит **приложение** — в слое нет `assets/scss` и `sass`, стили компонентов
-  компилируются только внутри приложения.
+  `vars` и `mixins` **авто-инжектятся** через `additionalData` приложения, поэтому в блоке компонента
+  `@use` писать не надо. Сам `sass` в слое не установлен — SCSS компилируется внутри приложения, но
+  все исходники (палитра, темы, миксины) лежат здесь.
 - **Разметка** — семантические теги, `<div>` только когда ничего не подходит.
 - **TS/JS** — всегда точка с запятой, без лишних комментариев.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "itube-specs",
   "type": "module",
-  "version": "0.0.858",
+  "version": "0.0.859",
   "main": "./nuxt.config.ts",
   "types": "./types/index.d.ts",
   "scripts": {