@ai.all/ds7 1.0.0 → 2.0.0

package/02-design-system/TOKENS-SPEC.md

@@ -1,88 +1,102 @@
-# 02-Design-System · Tokens Specification
+# 02 · Design tokens
 
-> Дизайн-токены определяют визуальную ДНК проекта. Все значения объявляются через CSS Custom Properties в файле `theme.css`.
+Tokens are the foundations: the named values every component uses. They live as CSS custom properties in `app/assets/css/theme.css`. Components read tokens only; they never contain raw values.
+
+Format for tools that need it: the [W3C Design Tokens Format Module (2025.10)](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/), with `$value` and `$type`.
 
 ---
 
-## 1. Палитра цветов (Semantic Color System)
+## 1. Colour
 
 ```css
 :root {
-  /* Базовые цвета поверхностей */
-  --color-paper: #f7f5ef;        /* Теплый фон страниц */
-  --color-white: #ffffff;        /* Белые плашки и карточки */
-  --color-ink: #1f1b16;          /* Основной контрастный текст */
-  --color-ink-500: #6b6459;      /* Второстепенный поясняющий текст */
-  --color-ink-100: rgba(31, 27, 22, 0.08); /* Границы и разделители */
-  --color-ink-950: #12100d;      /* Глубокий темный фон для инверсий */
-
-  /* Фирменный солнечный акцент */
-  --color-sun: #ffd84d;          /* Теплый солнечный акцент */
-  --color-sun-hover: #ffcf2e;    /* Состояние ховера */
-
-  /* Семантические цвета */
-  --color-success: #2e7d32;      /* Подтверждение, экономия */
-  --color-warning: #ed6c02;      /* Предупреждение */
-  --color-error: #d32f2f;        /* Ошибки */
+  /* surfaces and text */
+  --color-paper: #f7f5ef;             /* page background */
+  --color-white: #ffffff;             /* cards, panels */
+  --color-ink: #1f1b16;               /* main text */
+  --color-ink-500: #6b6459;           /* secondary text */
+  --color-ink-100: rgba(31, 27, 22, 0.08); /* borders, dividers */
+  --color-ink-950: #12100d;           /* dark inversions */
+
+  /* brand accent */
+  --color-sun: #ffd84d;
+  --color-sun-hover: #ffcf2e;
+
+  /* semantic */
+  --color-success: #2e7d32;
+  --color-warning: #ed6c02;
+  --color-error: #d32f2f;
 }
 ```
 
-> **Правило контрастности:** Желтый цвет `--color-sun` запрещено использовать для текста. Он применяется только как фоновая заливка кнопок (`.btn.-sun`), бейджей или подложка-маркер (`box-shadow: inset 0 -0.3em 0 var(--color-sun)`).
+**Contrast rule.** `--color-sun` is never used for text. It is a fill (buttons), a badge background, or a marker (`box-shadow: inset 0 -0.3em 0 var(--color-sun)`).
+
+**Measure, do not estimate.** When a palette changes, check the contrast of every text and border pair with a tool, and record the result in the brandbook.
 
 ---
 
-## 2. Ритм вертикальных и горизонтальных отступов (Spacing Scale)
+## 2. Spacing
 
 ```css
 :root {
-  --space-1: 0.25rem;  /* 4px */
-  --space-2: 0.5rem;   /* 8px */
-  --space-3: 0.75rem;  /* 12px */
-  --space-4: 1rem;     /* 16px */
-  --space-6: 1.5rem;   /* 24px */
-  --space-8: 2rem;     /* 32px */
-  --space-12: 3rem;    /* 48px */
-  --space-16: 4rem;    /* 64px */
-
-  /* Семантический интервал секций (Responsive) */
-  --space-single: clamp(1.2rem, 3vw, 2.2rem);  /* Внутренний отступ блоков */
-  --space-double: clamp(2.4rem, 6vw, 4.5rem);  /* Стандартный интервал секций */
-  --space-triple: clamp(3.6rem, 9vw, 6.5rem);  /* Крупные разделы на десктопе */
-
-  /* Базовая сетка страницы */
-  --content-width: 78rem;  /* 1248px */
+  --space-1: 0.25rem;   /* 4 px */
+  --space-2: 0.5rem;    /* 8 px */
+  --space-3: 0.75rem;   /* 12 px */
+  --space-4: 1rem;      /* 16 px */
+  --space-6: 1.5rem;    /* 24 px */
+  --space-8: 2rem;      /* 32 px */
+  --space-12: 3rem;     /* 48 px */
+  --space-16: 4rem;     /* 64 px */
+
+  /* responsive section rhythm */
+  --space-single: clamp(1.2rem, 3vw, 2.2rem);
+  --space-double: clamp(2.4rem, 6vw, 4.5rem);
+  --space-triple: clamp(3.6rem, 9vw, 6.5rem);
+
+  /* page grid */
+  --content-width: 78rem;               /* 1248 px */
   --page-gutter: clamp(1rem, 3.5vw, 2rem);
 }
 ```
 
 ---
 
-## 3. Тени и глубина поверхностей (Elevation)
-
-Вместо случайных значений `box-shadow` используются строгие семантические токены:
+## 3. Elevation
 
 ```css
 :root {
-  /* Обычные карточки и панели в состоянии покоя */
-  --shadow-lift: 0 4px 16px -2px rgba(31, 27, 22, 0.06);
+  --shadow-lift: 0 4px 16px -2px rgba(31, 27, 22, 0.06);   /* resting cards */
+  --shadow-hover: 0 12px 32px -4px rgba(31, 27, 22, 0.12); /* hover, open items */
+  --shadow-modal: 0 24px 64px -8px rgba(18, 16, 13, 0.24); /* modal dialogs */
+}
+```
 
-  /* Приподнятые карточки при ховере или раскрытые элементы */
-  --shadow-hover: 0 12px 32px -4px rgba(31, 27, 22, 0.12);
+Use these three. Do not write ad-hoc `box-shadow` values in components.
 
-  /* Всплывающие модальные окна */
-  --shadow-modal: 0 24px 64px -8px rgba(18, 16, 13, 0.24);
+---
+
+## 4. Radius
+
+```css
+:root {
+  --radius-sm: 0.375rem;  /* 6 px — badges, chips */
+  --radius-md: 0.75rem;   /* 12 px — cards, inputs */
+  --radius-lg: 1.25rem;   /* 20 px — large section panels */
+  --radius-full: 9999px;  /* pills, round buttons */
 }
 ```
 
 ---
 
-## 4. Скругления (Border Radius)
+## 5. Breakpoints
 
 ```css
 :root {
-  --radius-sm: 0.375rem; /* 6px — бейджи, кнопки-чипы */
-  --radius-md: 0.75rem;  /* 12px — карточки, инпуты */
-  --radius-lg: 1.25rem;  /* 20px — большие секционные плашки */
-  --radius-full: 9999px; /* Таблетки, круглые кнопки */
+  --bp-sm: 480px;   /* one column below this */
+  --bp-md: 800px;   /* tablet-portrait boundary */
+  --bp-lg: 900px;   /* two-column grids collapse here */
+  --bp-xl: 1200px;  /* desktop layout */
 }
 ```
+
+Media queries use these values. Components prefer container queries.

package/03-performance-web-vitals/ASSETS-PIPELINE.md

@@ -1,71 +1,62 @@
-# 03-Performance · Smart Assets Pipeline (Tight-Trim & Responsive Media)
+# 03 · Assets pipeline: tight trim and responsive images
 
-> Стандарт подготовки и вставки графики. Исключает вставку «сырых» тяжелых файлов и гарантирует идеальный LCP.
+Images are prepared before they reach the code. Raw exports make pages heavy and products small.
 
 ---
 
-## 1. Правило обрезки избыточных полей (Tight-Trim)
+## 1. Tight trim
 
-Частая ошибка: дизайнер экспортирует PNG/WebP карточки товара или оборудования на холсте 1000×1000 px, где 60% площади — это прозрачные пустые поля вокруг предмета.
+Typical problem: a product PNG exported on a 1000 × 1000 canvas where most pixels are empty transparent margin.
 
-### Почему это плохо:
-* Файл весит лишние байты из-за пустых пикселей;
-* Картинку невозможно ровно отцентрировать по сетке;
-* На мобильных экранах сам товар становится крошечным из-за огромных невидимых полей.
+Costs: extra bytes, off-centre objects in grids, and tiny products on phones.
 
-### Стандарт DS7 (Tight-Trim):
-1. **Кадрирование по контуру:** Все прозрачные поля вокруг объекта обрезаются вплотную (если вокруг нет реальной рассеянной тени).
-2. **Прозрачный фон:** Изображения оборудования (панели, инверторы, зарядки) сохраняются на прозрачном фоне, чтобы легко ложиться на светлые, темные и цветные подложки.
-3. **Стабильное соотношение сторон:** В коде карточки задается контейнер со стабильным `aspect-ratio` (например, `aspect-ratio: 4/3` или `1/1`), а сама картинка центрируется через `object-fit: contain`.
+Rules:
+1. **Crop to the object** along its outline, keeping a real soft shadow if the design has one.
+2. **Keep transparency** for product cut-outs so they sit on light, dark and coloured backgrounds.
+3. **Fix the box.** The container has a stable `aspect-ratio` (`4/3` or `1/1`); the image is centred with `object-fit: contain`.
 
 ---
 
-## 2. Адаптивная вставка через `<picture>` и `srcset`
+## 2. Responsive images
 
-Каждое растровое изображение подготавливается под конкретные размеры экрана:
+Every raster image ships in several sizes. The reference component is `UiImg`: it takes a `src` string, builds a `srcset` from the generated variants, and writes `width`, `height` and lazy-loading attributes.
+
+Generated sizes (default): **400, 800 and 1200 px wide**, WebP, quality 82. Images smaller than 900 px are not resized up.
 
 ```html
-<picture>
-  <!-- 1. Мобильные устройства (ширина до 640px): компактный легкий файл -->
-  <source 
-    media="(max-width: 640px)" 
-    srcset="/images/p/hero-mobile.webp 1x, /images/p/hero-mobile@2x.webp 2x" 
-    type="image/webp"
-  >
-  <!-- 2. Десктопные экраны: полноразмерный файл с поддержкой Retina -->
-  <source 
-    srcset="/images/p/hero.webp 1x, /images/p/hero@2x.webp 2x" 
-    type="image/webp"
-  >
-  <!-- 3. Фоллбэк img с явными габаритами для нулевого CLS -->
-  <img 
-    src="/images/p/hero.webp" 
-    alt="Instalación solar fotovoltaica en Sevilla" 
-    width="1600" 
-    height="900" 
-    fetchpriority="high" 
-    loading="eager" 
-    decoding="async"
-  >
-</picture>
+<img
+  src="/images/p/hero-1200.webp"
+  srcset="/images/p/hero-400.webp 400w, /images/p/hero-800.webp 800w, /images/p/hero-1200.webp 1200w"
+  sizes="(max-width: 800px) 100vw, 60vw"
+  width="1200" height="900"
+  alt="Solar installation on a rooftop"
+  fetchpriority="high" loading="eager" decoding="async"
+>
 ```
 
+Use `UiImg` rather than writing this by hand in every page.
+
 ---
 
-## 3. Правило `fetchpriority` и `loading`:
+## 3. Loading priorities
 
-| Расположение изображения | `loading` | `fetchpriority` | `decoding` | Назначение |
-|---|---|---|---|---|
-| **Главный баннер Hero (LCP)** | `eager` | `high` | `async` | Мгновенно загружается первым |
-| **Карточки товаров (2-й экран)** | `lazy` | `auto` | `async` | Загружается перед появлением в поле зрения |
-| **Нижние секции, отзывы, футер** | `lazy` | `low` | `async` | Загружается только при доскролле |
+| Position | `loading` | `fetchpriority` | `decoding` |
+|---|---|---|---|
+| The LCP image above the fold | `eager` | `high` | `async` |
+| Cards below the fold | `lazy` | `auto` | `async` |
+| Footer and late sections | `lazy` | `low` | `async` |
+
+Only one image is the LCP image on a page. Mark it, do not mark several.
 
 ---
 
-## 4. Скрипт автоматической подготовки ассетов
+## 4. Asset script
+
+Keep a small script in `tools/` (Sharp or Python) that:
+- takes new images from a source folder;
+- trims transparent margins;
+- writes WebP (and AVIF where useful) at 400, 800 and 1200 px;
+- writes `app/data/image-variants.json`, the manifest `UiImg` reads;
+- has a `--check` mode that fails when a referenced image has no manifest entry.
 
-В папке `tools/` рекомендуется держать легковесный скрипт (Python / Sharp), который:
-* Принимает новые картинки;
-* Обрезает прозрачные поля (`trim`);
-* Конвертирует в WebP и AVIF с качеством 82%;
-* Генерирует мобильные копии (`-400.webp`) и ретина-копии (`@2x.webp`).
+Commit the manifest with the images it describes.

package/03-performance-web-vitals/CRITICAL-CSS.md

@@ -1,46 +1,39 @@
-# 03-Performance · Critical CSS & Zero Render-Blocking
+# 03 · Critical CSS and render-blocking
 
-> Как гарантировать First Contentful Paint (FCP) менее 0.4 секунды и 100 баллов в Google Lighthouse по категории Performance.
+A stylesheet in `<head>` blocks rendering until it has downloaded and parsed. On a slow mobile network a 50–150 KB stylesheet delays the first paint noticeably.
 
 ---
 
-## 1. В чём проблема стандартного CSS
+## 1. Split
 
-Когда браузер загружает обычную веб-страницу:
-1. Скачивается `index.html`;
-2. Браузер находит в `<head>` тег `<link rel="stylesheet" href="/_nuxt/entry.css">`;
-3. **Рендеринг страницы полностью блокируется (белый экран)**, пока файл `entry.css` (часто 50–150 КБ) скачивается по мобильной сети и парсится;
-4. Пользователь видит контент только через 1.5–3.0 секунды.
+- **Above the fold:** header, page grid, typography and the first screen. Needed for the first paint.
+- **Below the fold:** calculators, reviews, map, footer, modals. Needed later.
 
 ---
 
-## 2. Архитектура Critical CSS в Nuxt 4
-
-Critical CSS разделяет стили сайта на две части:
-1. **Above-the-fold (Критический CSS):** Стили шапки, сетки контейнера, типографики и фонового блока первого экрана (Hero).
-2. **Below-the-fold (Вторичный CSS):** Стили калькулятора, отзывов, карты, футера, модальных окон.
-
-### Настройка в `nuxt.config.ts`:
+## 2. Nuxt configuration
 
 ```ts
 export default defineNuxtConfig({
   experimental: {
-    // Автоматическое извлечение и встраивание критических стилей в HTML
-    inlineSSRStyles: true
-  }
+    inlineSSRStyles: true,   // inline the CSS each page uses during generation
+  },
 })
 ```
 
-### Как это работает:
-При статической генерации (`npx nuxt generate`):
-* Nuxt парсит HTML каждой страницы и определяет классы, нужные для первого экрана;
-* Эти правила вставляются прямо внутрь `<style>` в `<head>` документа `index.html`;
-* Полная таблица стилей подключается асинхронно: `<link rel="preload" as="style">`.
+During `nuxt generate`:
+- each page is rendered and the classes it uses are collected;
+- those rules are inlined in `<style>` in the page `<head>`;
+- the full stylesheet is loaded afterwards with `rel="preload"`.
+
+---
+
+## 3. What to measure
+
+Record First Contentful Paint and render-blocking requests on a real phone, with the build and date, in `docs/METRICS.md`. Lab numbers from a sandbox are not evidence for this.
 
 ---
 
-## 3. Результат для пользователя и Google Lighthouse
+## 4. Budget
 
-* Браузер получает `index.html` и **в ту же миллисекунду рисует идеальный первый экран**, не делая ни одного дополнительного сетевого запроса за CSS.
-* **FCP (First Contentful Paint):** снижается с 1.8s до **0.35s**.
-* **Speed Index:** зеленая зона (98–100 баллов).
+Keep the entry stylesheet small enough to inline without delaying HTML. Set a budget in `docs/METRICS.md` and check it when the stylesheet changes.

package/03-performance-web-vitals/FONTS-ZERO-CLS.md

@@ -1,43 +1,39 @@
-# 03-Performance · Fonts & Zero Layout Shift (CLS = 0.000)
+# 03 · Fonts and zero layout shift
 
-> Как исключить «прыжки» текста при загрузке шрифтов и свести показатель Cumulative Layout Shift (CLS) к абсолютному нулю.
+Text that jumps when a web font arrives moves the whole page and raises CLS. This document describes how DS7 avoids that.
 
 ---
 
-## 1. Анатомия проблемы FOUT и прыжков текста
+## 1. The problem
 
-Когда веб-шрифт Montserrat подгружается через `@font-face`:
-1. Браузер сначала рисует текст стандартным системным шрифтом (Arial или Helvetica);
-2. У системного шрифта другая ширина букв и высота строки (x-height);
-3. Через секунду подгружается `montserrat.woff2`, шрифт переключается, строки переносятся на новое место, и **вся страница дергается вниз на 20–40 пикселей**.
-4. Пользователь случайно кликает не туда, а Google фиксирует плохой показатель CLS (> 0.15).
+1. The browser draws text with a system font first (Arial or Helvetica).
+2. The system font has different glyph widths and line heights from the brand font.
+3. When the brand font arrives, lines re-wrap and content moves, often 20–40 px.
 
 ---
 
-## 2. Комплексное решение проблемы в DS7
+## 2. The approach
 
-### Шаг 1: Прямой Preload в `<head>`
-Не ждем, пока CSS файл будет прочитан. Браузер начинает качать шрифт с первой миллисекунды:
+### Step 1: preload one weight
+Preload the weight used on the first screen, as `woff2`, from the document `<head>`:
 
 ```ts
-// nuxt.config.ts -> app.head
-link: [
-  {
-    rel: 'preload',
-    href: '/fonts/montserrat-latin-var.woff2',
-    as: 'font',
-    type: 'font/woff2',
-    crossorigin: 'anonymous'
-  }
-]
+// nuxt.config.ts → app.head.link
+{
+  rel: 'preload',
+  href: '/fonts/brand-latin-var.woff2',
+  as: 'font',
+  type: 'font/woff2',
+  crossorigin: 'anonymous',
+}
 ```
 
-### Шаг 2: Модуль `@nuxtjs/fontaine` (Синхронизация пропорций)
-Fontaine анализирует геометрию шрифта Montserrat и создает локальный псевдо-шрифт:
+### Step 2: matched fallback
+A fallback `@font-face` built from a system font, with metrics adjusted to the brand font:
 
 ```css
 @font-face {
-  font-family: 'Montserrat-Fallback';
+  font-family: 'Brand Fallback';
   src: local('Arial');
   ascent-override: 95.8%;
   descent-override: 28.2%;
@@ -46,18 +42,18 @@ Fontaine анализирует геометрию шрифта Montserrat и с
 }
 ```
 
-**Магия Fontaine:** Буквы локального системного шрифта искусственно сжимаются и растягиваются так, чтобы **пиксель-в-пиксель занимать то же пространство**, что и Montserrat. 
-Когда реальный шрифт скачивается, форма букв меняется, но **ни одна строчка на странице не сдвигается**.
+The values come from the brand font's metrics (the `@nuxtjs/fontaine` module computes them). When the brand font loads, glyphs have the same advance widths and line boxes, so text does not move.
 
-### Шаг 3: `font-display: swap`
-Шрифт отображается мгновенно, экран не ждет загрузки (нет белого текста FOIT).
+### Step 3: `font-display: swap`
+Text appears at once with the fallback and swaps when the brand font is ready. No invisible text.
 
 ---
 
-## 3. Чек-лист проверки CLS = 0.000
+## 3. Checklist
 
-1. [x] Preload для основного начертания шрифта (`.woff2`).
-2. [x] Настроен fallback через Fontaine (`size-adjust`).
-3. [x] У всех логотипов и SVG-иконок жестко заданы атрибуты `width` и `height`.
-4. [x] У всех карточек и медиа-блоков зафиксирован CSS `aspect-ratio`.
-5. [x] Плавающие панели (`SiteIntro`, куки-баннер) позиционируются через `position: fixed` и не выталкивают контент.
+- [ ] One preloaded weight for the first screen.
+- [ ] Fallback with `size-adjust` and the override metrics.
+- [ ] Every logo and inline SVG has `width` and `height`.
+- [ ] Every card and media box has a fixed `aspect-ratio`.
+- [ ] Fixed-position panels (cookie banner, intro) do not push content.
+- [ ] Measured CLS recorded in `docs/METRICS.md` on a real device.

package/03-performance-web-vitals/HYDRATION-STRATEGY.md

@@ -1,51 +1,68 @@
-# 03-Performance · Hydration Strategy & TBT Minimization
+# 03 · Hydration strategy
 
-> Как избавиться от зависаний интерфейса (Total Blocking Time < 50ms) при первом входе на страницу.
+Static HTML appears first. Then the framework attaches event handlers to each component (hydration). On a phone with many interactive components this can block the main thread for hundreds of milliseconds, and taps are ignored during that time.
 
 ---
 
-## 1. В чём опасность полной гидратации
+## 1. Principle
 
-Nuxt генерирует чистый статический HTML. Браузер быстро его отображает, но затем запускается процесс **гидратации (Hydration)**:
-* Vue начинает «оживлять» каждый компонент на странице, вешать слушатели событий и инициализировать реактивные объекты;
-* Если на странице 15 секций (калькулятор, карта проектов, чат, модалки, слайдеры), этот процесс может занять **250–500 мс** на среднем мобильном процессоре;
-* В это время страница «висит» — пользователь тыкает по меню или кнопке, а клик не срабатывает.
+Hydrate only what the visitor needs now.
 
----
+- **Critical:** navigation, the first interactive element, forms the visitor sees.
+- **Idle:** chat widgets, cookie banner, sound controls, modals that are not open.
+- **On visibility:** heavy sections below the fold (maps, charts, interactive calculators).
 
-## 2. Стратегия отложенной гидратации в DS7
+---
 
-### 1. Отложенные второстепенные виджеты (`requestIdleCallback`)
-Виджеты, которые не нужны в первую секунду (чат WhatsApp, куки-баннер, модалка звонка, звуковые эффекты), гидрируются только тогда, когда процессор свободен:
+## 2. Idle widgets
 
 ```vue
 <script setup lang="ts">
-const shouldHydrateIdle = ref(false)
+const ready = ref(false)
 
 onMounted(() => {
   if ('requestIdleCallback' in window) {
-    window.requestIdleCallback(() => { shouldHydrateIdle.value = true })
+    window.requestIdleCallback(() => { ready.value = true })
   } else {
-    setTimeout(() => { shouldHydrateIdle.value = true }, 1500)
+    setTimeout(() => { ready.value = true }, 1500)
   }
 })
 </script>
 
 <template>
   <ClientOnly>
-    <SiteChat v-if="shouldHydrateIdle" />
-    <SiteCookieBanner v-if="shouldHydrateIdle" />
+    <SiteChat v-if="ready" />
+    <SiteCookieBanner v-if="ready" />
   </ClientOnly>
+}
 </template>
 ```
 
-### 2. Ленивая гидратация по скроллу (`when-visible`)
-Тяжелые интерактивные секции ниже первого экрана (интерактивная карта проектов `HomeProjectMap`, модель дня и ночи `HomeDayNight`) гидрируются только тогда, когда пользователь приближается к ним при прокрутке.
+Note for the banner: it must not hide content while it waits. Reserve its space with a fixed position.
+
+---
+
+## 3. Visibility
+
+Heavy sections use lazy components that hydrate when they approach the viewport:
+
+```vue
+<LazyHomeProjectMap hydrate-on-visible />
+```
+
+---
+
+## 4. Passive listeners
+
+Scroll and touch listeners that never call `preventDefault` are registered as passive, so the browser can scroll without waiting for the script:
 
-### 3. Пассивные слушатели событий (`passive: true`)
-В компоненте `UiCardSlider` и любых событиях скролла/тача:
 ```ts
 window.addEventListener('scroll', onScroll, { passive: true })
 track.addEventListener('touchstart', onTouchStart, { passive: true })
 ```
-Браузер заранее знает, что скрипт не отменит стандартную прокрутку страницы (`preventDefault`), и скроллит страницу с максимальной частотой 120 FPS без микро-фризов.
+
+---
+
+## 5. Measuring
+
+Total Blocking Time and Interaction to Next Paint are measured on a real device, not in a sandbox. Record the results in `docs/METRICS.md`.