itube-specs 0.0.922 → 0.0.923

package/DOCS/CONVENTIONS.md

@@ -0,0 +1,44 @@
+# Conventions
+
+Layer + every site. From an app: `node_modules/itube-specs/DOCS/CONVENTIONS.md`. Styles → `DOCS/STYLES.md`.
+Human-facing rationale → the layer's `README.md` (Russian).
+
+## Components
+
+`pathPrefix: true` → name = folder path + filename, repeated segments deduped by Nuxt. Folder is the
+namespace; filename must not repeat it.
+
+- `ui/icon.vue` → `<UiIcon>` · `player/core.vue` → `<PlayerCore>` · `info/grid.vue` → `<InfoGrid>` (not
+  `<InfoInfoGrid>`)
+- Folder root: `index.vue` when the deduped name is already multi-word (`card/video/index.vue` →
+  `<CardVideo>`); `main.vue` only when `index.vue` would give one word (`filter/main.vue` → `<FilterMain>`).
+  Never a single-word name — clashes with HTML elements.
+- BEM root class = kebab-case of the name: `<CardVideo>` → `.card-video`
+- `pathPrefix: true` mandatory — layers break component exports under `false` (nuxt/nuxt#30099)
+
+**App override:** an app defining the same name outranks the layer and wins auto-import; callers untouched.
+Don't fork a component when a prop expresses the difference.
+
+## Markup
+
+`<div>` is the fallback, not the default.
+
+| Need | Tag |
+|---|---|
+| text | `<span>` inline, `<p>` paragraph — never bare `<div>` |
+| structure | `header`, `nav`, `main`, `aside`, `footer`, `section`, `article` |
+| sequence of similar items | `<ul>`/`<ol>` + `<li>` — chip rows and tag clouds included |
+| action / navigation / collapsible | `<button>` / `<a>` / `<details>`+`<summary>` |
+| forms | `<label>`, `<fieldset>`, `<legend>`, native `<input>` types |
+| emphasis, figures | `<em>`/`<strong>`, `<figure>`/`<figcaption>` — not style-only spans |
+
+## TypeScript
+
+- Semicolons always. No code comments unless asked.
+- Domain string sets: `as const` PascalCase objects in `runtime/constants/`, type via
+  `typeof X[keyof typeof X]`. Never `enum` — it survives into the bundle, and `import type` erases it so
+  `X.Member` is `undefined` at runtime in a published layer; you also can't assign a raw API/URL/cookie string
+  to an enum. String values, not numeric (`0` is falsy — `if (spotType)` misreads member `0` as absent;
+  `AdSpotType` is numeric, a wart, don't copy). Framework unions (Nuxt status) stay unions.
+- `.vue` templates are NOT typechecked — `tsc` doesn't read them, `vue-tsc` isn't a gate. A clean `tsc` says
+  nothing about template expressions. Read them, or `npx vue-tsc --noEmit` ad hoc past pre-existing noise.

package/DOCS/STYLES.md

@@ -0,0 +1,127 @@
+# Styles
+
+Canonical for every itube site — the layer owns 100% of the SCSS; apps have an empty `assets/scss/` override
+slot. Read before touching any `<style lang="scss">`, `assets/scss/**`, or a theme token. Paths are
+layer-relative; from an app: `node_modules/itube-specs/DOCS/STYLES.md`. Human-facing version → `README.md`.
+
+## Co-location
+
+- Component and page styles in the SFC's own `<style lang="scss">`. **No `scoped`** — flat BEM isolates.
+- Nothing per-component or per-page in `assets/scss/`.
+- Tree: `assets/scss/` → `vars/` (palette, vars, tokens, z-index), `themes/`, `mixins/`, `base/`, `layout/`,
+  `main.scss`. `css` entry is `main.scss`, loads only `vars/tokens`, `base`, `layout`.
+- **Never `@use 'vars'`/`'mixins'` in an SFC block** — auto-injected by the *app's*
+  `vite.css.preprocessorOptions.scss.additionalData` + `loadPaths`.
+- Sass-loaded global partials: `@use` relatively within their own root, bare specifiers across roots
+  (layer↔app) so `loadPaths` resolves.
+- The layer has no `sass` package — layer styles compile only inside an app, never in the layer's vitest.
+
+## Themes
+
+Dir per theme: `assets/scss/themes/<name>/_theme.scss`. App picks one via `theme:` in its
+`config/site.config.ts` (read by its `nuxt.config.ts` *and* `app.config.ts` — `useAppConfig()` doesn't exist at
+config time), appends `themes/<theme>/` to `loadPaths`; `@forward 'theme'` in `vars/_index.scss` resolves
+there because no `_theme.scss` sits beside it.
+
+**Dir-per-theme is load-bearing** — Sass needs a literal `@use`/`@forward` path, so only the folder can vary.
+
+`loadPaths = [<app>/assets/scss, <layer>/assets/scss/themes/<theme>, <layer>/assets/scss]`. App first → a site
+overrides any partial by name (its `vars/_theme.scss` wins over loadPaths).
+
+**Every token must exist in every theme** — a missing one is a hard Sass error that kills the app build. Two
+guards, both pre-commit + CI:
+
+| Script | Proves | Blind spot |
+|---|---|---|
+| `check:themes` | themes declare the same top-level `$name:` set (`$surfaces` / `$button-variant-overrides` contents ignored — a theme may leave either empty) | token declared in **no** theme |
+| `check:styles` | every `<style>` block compiles against every theme, same preamble + loadPaths as Vite; names the failing theme (~1.5s) | — |
+
+## BEM
+
+`.block {}`, `.block__element {}`, `.block.--modifier {}` — modifier prefix `--`.
+
+**No nesting**, every selector flat with its full class name. `&` only for pseudo-classes, pseudo-elements,
+state modifiers (`&::after`, `&:focus-visible`, `&.--open`).
+
+```scss
+.layout-header {}
+.layout-header__logo {}   // not .layout-header { &__logo {} }
+```
+
+## Hover
+
+**Always `@include hover(<properties>)`, never `&:hover`.** Wraps in `@media (hover: hover)` (on touch a hover
+sticks after a tap), declares `--transition` for the listed properties, pairs `:hover` with `:focus-visible`.
+
+```scss
+.ui-btn.--muted {
+  @include hover(background-color, border) { background-color: $button-muted-bg--hover; }
+}
+```
+
+Applies to the current selector only, so hovering one element to restyle another is written flat inside your
+own media query:
+
+```scss
+@media (hover: hover) {
+  .card-round:is(:hover, :focus-visible) .card-round__img { transform: scale(1.05); }
+}
+```
+
+## Tokens
+
+Never hardcode a color, size or z-index.
+
+| File | Holds | Type |
+|---|---|---|
+| `vars/_palette.scss` | `$color-indigo-600` — raw palette | SCSS var |
+| `themes/<theme>/_theme.scss` | `$chips-text`, `$button-bg--hover` — colors, one per theme | SCSS var |
+| `vars/_vars.scss` | `$radius-*`, `$blur-*`, `$spacing` — static non-color | SCSS var |
+| `vars/_tokens.scss` | `--header-height` — changes at a breakpoint or set via JS | CSS custom prop |
+
+- Changes at a breakpoint or set via JS → CSS custom property. Everything else → SCSS var.
+- **Palette is private**, consumed only by theme files. A component must never use `$color-*` — add the token
+  to **every** theme first.
+- **No semantic tier** (`$text-muted`, `$role-border-subtle`) — themes reference palette directly.
+- Theme files hold **colors only**; radius/blur/static → `vars/_vars.scss`.
+
+### Context-dependent colors
+
+Never a theme flag in a component. Two mixins, driven from the theme file:
+
+- `surface($name)` — block declares itself an island (`.ui-popup { @include surface(overlay); }`), contents
+  pick up colors by cascade. Theme supplies deltas via `$surfaces`; no differentiation → `$surfaces: ()`.
+  Components read `var(--input-bg, #{$input-bg})`, so a single color can still be overridden directly.
+- `button-variant($key)` — place asks, theme answers by name via `$button-variant-overrides`. The element's
+  class still reflects the `theme=` prop, so the mixin prints `--button-variant` as a DevTools marker.
+
+`appConfig.theme` — structural differences only (different element, extra icon, `v-if`).
+
+### Naming
+
+`$<block>-<element>?-<modifier>?-<property>-<state>?`
+
+- block = component root · element = BEM element, optional · modifier = variant, optional
+- property — always present, always short: `bg`, `text`, `border`, `radius`, `icon`, `shadow`. Never the full
+  CSS name (`$button-background` → `$button-bg`, `$input-border-radius` → `$input-radius`). `color` is banned
+  as a property — ambiguous, use `text`.
+- state — last, after `--`: `hover`, `active`, `focus`, `disabled`, `checked`, `current`, `error`
+
+State goes last even when it reads worse: `$video-playlist-card-bg--active`, NOT
+`$video-playlist-card-active-bg`. A state-looking word can be a sub-element: `$filter-popup-active-chip-bg` is
+`active-chip`.
+
+Text-only elements (`title`, `name`, `subtext`, `description`, `label`, `count`) may drop `-text`:
+`$video-card-title`.
+
+## Typography and breakpoints
+
+- Type: `@include font-sm` (14/20), `font-xs` (12/16), `font-base` (16/24) — never raw
+  `font-size`/`line-height`.
+- Breakpoints: `@include from-br(sm)`, `to-br(xs)`. Container: `from-cq($bp)`. JS mirror of `$brkpnts` in
+  `config/`, guarded by `check:breakpoints`.
+
+**All mixins** (auto-injected, never `@use`): `font-4xs|3xs|xs|2xs|sm|md|base|lg|xl|2xl|3xl|4xl`,
+`from-br|to-br`, `from-cq|to-cq`, `hover`, `surface`, `button-variant`, `page|page-title|page-footer-links`,
+`video-card|video-card-grid|video-card-poster`, `area-point`. Signatures — SCSS-mixins table in the app's
+`DOCS/CATALOG.md`.

package/README.md

@@ -143,6 +143,12 @@ assets/scss/themes/dark/_theme.scss
 подставляет приложение, и компилирует по разу на тему. То же, что делает Vite, — значит ловит и неизвестные
 миксины, и неверные аргументы `@include`, и показывает, в какой теме падает.
 
+**Промежуточного семантического слоя нет** — темы ссылаются на палитру напрямую, без тира вида
+`$text-muted` / `$role-border-subtle`. Сайты форкаются с принципиально разными схемами, и каждому
+селектору может понадобиться произвольный цвет, а не одна из горстки ролей. Такой слой либо оброс бы
+ролью на селектор (и перестал быть семантическим), либо компоненты начали бы тянуться в обход него.
+Имя токена по компоненту, который он обслуживает, держит соответствие честным.
+
 Контекстные различия (контрол внутри попапа, вариант кнопки, зависящий от темы) решают миксины
 `surface()` и `button-variant()` из `mixins/`: место объявляет себя, а значения даёт тема через карты
 `$surfaces` / `$button-variant-overrides`. Компоненты про темы не знают. `appConfig.theme` — только

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "itube-specs",
   "type": "module",
-  "version": "0.0.922",
+  "version": "0.0.923",
   "main": "./nuxt.config.ts",
   "types": "./types/index.d.ts",
   "scripts": {
@@ -74,7 +74,8 @@
     "assets/scss/base/",
     "assets/scss/layout/",
     "assets/scss/main.scss",
-    "nuxt.config.ts"
+    "nuxt.config.ts",
+    "DOCS/"
   ],
   "devDependencies": {
     "@intlify/eslint-plugin-vue-i18n": "^4.5.1",