@ai.all/ds7 0.0.0-stage → 1.0.0

package/01-architecture/ATOMIC-DESIGN.md

@@ -0,0 +1,62 @@
+# 01-Architecture · Atomic Design & Component Hierarchy
+
+> Методология построения интерфейса основана на принципах [Atomic Design Брэда Фроста (Brad Frost)](https://atomicdesign.bradfrost.com/chapter-2/) с акцентом на **полную автономность (self-contained)** и **компонуемость (composability)** каждого блока.
+
+---
+
+## 1. Пять уровней иерархии
+
+```
+[1. ATOMS]       ───> Неделимые кирпичики: кнопки, иконки, бейджи, инпуты, цены
+     │
+[2. MOLECULES]   ───> Связки атомов: карточка товара, карточка тарифа, навигация слайдера
+     │
+[3. ORGANISMS]   ───> Автономные виджеты: слайдер карточек, сетка преимуществ, FAQ, калькулятор
+     │
+[4. TEMPLATES]   ───> Каркасы секций и лэндингов: Hero-секция, шаблон направления
+     │
+[5. PAGES]       ───> Маршруты Nuxt (app/pages/*): получение данных из app/data/ и передача в шаблоны
+```
+
+---
+
+## 2. Правила для каждого уровня
+
+### Уровень 1: Атомы (`app/components/ui/`)
+- **Что входит:** `UiButton`, `UiIcon`, `UiPrice`, `UiProductBadge`, `UiField`, `UiLink`, `UiText`, `UiCrown`, `UiSun`.
+- **Правило изоляции:** Атомы абсолютно «слепы». Они не знают о существовании страниц, товаров или калькулятора. Управляются исключительно типизированными входными пропсами.
+- **Стилизация:** Базовый класс + короткие модификаторы (`.btn.-sun`, `.btn.-sm`, `.btn.-outline`).
+
+### Уровень 2: Молекулы (`app/components/ui/`)
+- **Что входит:** `UiProductCard` (карточка товара), `UiSectionHeading` (заголовок секции с eyebrow и подписью), `UiFeatureCard` (карточка преимущества), `UiPlanCard` (карточка тарифа/пакета), `UiSliderNav` (стрелки и точки).
+- **Правило изоляции:** Молекулы компонуются только из атомов и базовой HTML-разметки. Принимают данные через `defineProps` и слоты. Не имеют сайд-эффектов.
+- **Вложенность:** Молекула должна идеально смотреться и в 4-колоночном гриде на всю ширину страницы, и в узком сайдбаре (за счет `@container`).
+
+### Уровень 3: Организмы (`app/components/ui/`, `sections/`, `site/`)
+- **Что входит:** `UiCardSlider` (универсальный слайдер), `UiFeatureGrid` (сетка преимуществ), `UiHeroHook` (плашка-крючок под Hero), `UiFaq` (аккордеон), `CalcPanel` (панель расчета), `SiteHeader`, `SiteFooter`.
+- **Правило изоляции:** Организмы функционально самодостаточны. Они сами управляют своим состоянием (скролл, активная вкладка, раскрытый аккордеон).
+- **Слоты:** Организмы-контейнеры обязаны работать через слоты (`<template #default="{ item }">`). Слайдер не должен быть зашит на товары — он крутит любые переданные молекулы.
+
+### Уровень 4: Шаблоны и Секции (`app/components/sections/`)
+- **Что входит:** `CalcSection`, `UiPageHero`, шаблоны направлений (`DirectionPage`).
+- **Правило:** Шаблоны соединяют организмы в законченный блок страницы, передавая в них структуру. Никакой захардкоженной логики под конкретные URL.
+
+### Уровень 5: Страницы (`app/pages/`)
+- **Что входит:** `index.vue`, `[slug].vue`, `movilidad.vue`, `mantenimiento.vue` и др.
+- **Правило:** Страницы отвечают **только** за 3 вещи:
+  1. Вызов composables для получения данных из `app/data/`;
+  2. Установку метатегов (`usePageSeo`);
+  3. Передачу данных в секции и шаблоны через пропсы.
+- **Запрет:** В файлах `app/pages/` **категорически запрещена прямая инлайн-верстка карточек, кастомных слайдеров и специфических сеток**.
+
+---
+
+## 3. Принцип «Внутрь чего-то еще и еще глубже»
+
+Любой компонент системы спроектирован так, чтобы его можно было вставить:
+1. В обычный поток страницы;
+2. Внутрь модального окна `UiModal`;
+3. Внутрь вкладки калькулятора или табов;
+4. Внутрь узкого сайдбара или всплывающей шторки.
+
+Компонент рассчитывает свои размеры не от экрана (`@media`), а от родительского блока (`@container`).

package/01-architecture/COMPONENT-ANATOMY.md

@@ -0,0 +1,117 @@
+# 01-Architecture · Component Anatomy & Container Queries
+
+> Эталонный анатомический разрез Vue 3 SFC (Single File Component). По этой структуре строятся все компоненты в системе.
+
+---
+
+## 1. Анатомический шаблон компонента
+
+```vue
+<script setup lang="ts">
+/**
+ * UiProductCard
+ * Молекула карточки товара каталога.
+ * Поддерживает адаптивность по контейнеру и каскадные модификаторы.
+ */
+
+// 1. Входные типизированные пропсы
+const props = withDefaults(defineProps<{
+  title: string
+  description?: string
+  price?: number | null
+  badge?: 'top' | 'new' | 'sale'
+  specs?: Array<{ label: string; value: string }>
+  // Булевые пропсы-модификаторы для удобства в шаблонах:
+  top?: boolean
+  compact?: boolean
+  dark?: boolean
+}>(), {
+  description: '',
+  price: null,
+  specs: () => [],
+  top: false,
+  compact: false,
+  dark: false
+})
+
+// 2. Вычисляемые классы-модификаторы
+const rootClasses = computed(() => [
+  'p-card',
+  props.top && '-top',
+  props.compact && '-compact',
+  props.dark && '-dark',
+  props.badge && `-${props.badge}`
+])
+</script>
+
+<template>
+  <article :class="rootClasses" data-ref="CARD-01">
+    <!-- Слот для изображения или графического арта -->
+    <div class="p-card__art">
+      <slot name="art" />
+    </div>
+
+    <!-- Информационная часть -->
+    <div class="p-card__body">
+      <h3 class="p-card__title">{{ title }}</h3>
+      <p v-if="description" class="p-card__desc">{{ description }}</p>
+
+      <!-- Список характеристик (одна колонка) -->
+      <dl v-if="specs.length" class="p-card__specs">
+        <div v-for="s in specs" :key="s.label">
+          <dt>{{ s.label }}</dt>
+          <dd>{{ s.value }}</dd>
+        </div>
+      </dl>
+    </div>
+
+    <!-- Футер с ценой и действием -->
+    <div class="p-card__footer">
+      <UiPrice v-if="price !== null" :amount="price" />
+      <slot name="action" />
+    </div>
+  </article>
+</template>
+
+<style>
+/* 
+ * Стили объявляются без scoped, но строго изолируются через префикс компонента.
+ * Это позволяет внешним родителям каскадно переопределять CSS-переменные.
+ */
+.p-card {
+  --card-bg: var(--color-white);
+  --card-ink: var(--color-ink);
+
+  container-type: inline-size;
+  display: flex;
+  flex-direction: column;
+  background: var(--card-bg);
+  color: var(--card-ink);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+}
+
+/* Контейнерный запрос: адаптация под размер родительского блока */
+@container (max-width: 320px) {
+  .p-card {
+    padding: var(--space-2);
+  }
+  .p-card__title {
+    font-size: 0.9rem;
+  }
+}
+</style>
+```
+
+---
+
+## 2. Ключевые архитектурные правила:
+
+1. **`container-type: inline-size`:**
+   Компонент всегда объявляет свой контейнер, если имеет адаптивные состояния. Он не зависит от ширины экрана (`@media`), а реагирует на ширину бокса, в который его поместили (`@container`).
+2. **Локальные CSS-переменные (`--card-bg`, `--card-ink`):**
+   Все цвета и параметры привязаны к переменным компонента. Модификатор меняет переменные, а не 10 дочерних селекторов.
+3. **Стабильный идентификатор `data-ref="CARD-01"`:**
+   Связывает живой компонент в коде с разделом в брендбуке на `/ui`.
+4. **Слоты с фоллбэками:**
+   Для медиа (`#art`) и кнопок (`#action`) используются слоты, позволяя переиспользовать разметку под любые типы контента.

package/01-architecture/MODIFIER-SYSTEM.md

@@ -0,0 +1,101 @@
+# 01-Architecture · Modifier System & Ancestry Scoping
+
+> Система модификаторов обеспечивает максимальное переиспользование кода без создания дублирующих компонентов.
+
+---
+
+## 1. Синтаксис отдельных классов-модификаторов
+
+Вместо длинных составных BEM-имен (`catalog-product-card--featured-large-dark`) используется компактная и легко читаемая схема: **базовый класс + отдельные короткие классы с дефисом**:
+
+```html
+<!-- Карточка товара: топовая, новинка, компактный размер -->
+<article class="p-card -top -new -compact">
+  <div class="p-card__art">...</div>
+  <h3 class="p-card__title">Panel Solar 450W</h3>
+  <div class="p-card__price">...</div>
+</article>
+```
+
+### Преимущества:
+1. **Экономия байтов в HTML/CSS:** Классы короткие, вес страницы уменьшается.
+2. **Аддитивность:** Модификаторы можно комбинировать в любых сочетаниях (`-top -new`, `-dark -compact`).
+3. **Каскадное влияние:** Модификатор на корневом элементе прозрачно меняет свойства всех вложенных элементов.
+
+---
+
+## 2. Каскад стилей от модификатора
+
+```css
+/* Базовый компонент */
+.p-card {
+  --card-bg: var(--color-white);
+  --card-text: var(--color-ink);
+  --card-border: var(--color-ink-100);
+
+  background: var(--card-bg);
+  color: var(--card-text);
+  border: 1px solid var(--card-border);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+/* Модификатор: TOP товар */
+.p-card.-top {
+  --card-border: var(--color-sun);
+  box-shadow: var(--shadow-lift);
+}
+.p-card.-top .p-card__title {
+  font-weight: 700;
+}
+
+/* Модификатор: Компактный режим */
+.p-card.-compact {
+  padding: var(--space-2);
+}
+.p-card.-compact .p-card__title {
+  font-size: 0.85rem;
+}
+
+/* Модификатор: Темная тема */
+.p-card.-dark {
+  --card-bg: var(--color-ink-950);
+  --card-text: var(--color-white);
+  --card-border: var(--color-ink-800);
+}
+```
+
+---
+
+## 3. Управление контекстом от предка (Ancestry Scoping)
+
+Если один и тот же рабочий компонент (слайдер, форма, плашка хука) должен выглядеть иначе на определенной странице (например, на странице для бизнеса `/empresas` фон должен быть графитовым, а на главной — песочным):
+
+❌ **Как делать НЕЛЬЗЯ:**
+Создавать два разных файла: `HookHome.vue` и `HookEmpresas.vue`.
+
+✅ **Как делать ПРАВИЛЬНО:**
+Использовать единый компонент `UiHeroHook`, а различия задавать через родительский контекст — класс страницы на теге `<body>`:
+
+```css
+/* Базовый хук везде */
+.hero-hook {
+  background: var(--color-paper);
+  color: var(--color-ink);
+}
+
+/* Тот же самый хук на странице для бизнеса (темная тема) */
+body.page-empresas .hero-hook {
+  background: var(--color-ink-950);
+  color: var(--color-white);
+}
+
+/* Тот же компонент внутри модального окна */
+.site-modal-box .hero-hook {
+  background: transparent;
+  padding: 0;
+}
+```
+
+Благодаря настройке в `usePageSeo.ts` каждая страница Nuxt автоматически проставляет свой класс на `<body>` (`page-home`, `page-hogares`, `page-empresas`, `page-movilidad`, `page-equipamiento`).

package/02-design-system/BRANDBOOK-SANDBOX.md

@@ -0,0 +1,52 @@
+# 02-Design-System · Brandbook & Sandbox (/ui)
+
+> Страница `/ui` в проекте — это не просто документация, а **живой интерактивный полигон компонентов (Storybook)** и единый язык коммуникации между человеком и ИИ.
+
+---
+
+## 1. Концепция стабильных меток компонентов (Component IDs)
+
+Каждый переиспользуемый паттерн в дизайн-системе имеет уникальный краткий буквенно-цифровой идентификатор:
+
+| ID | Название компонента | Назначение |
+|---|---|---|
+| **`BTN-01`** | Primary Action Button | Главная кнопка с заливкой `--color-sun` и стрелкой `→` |
+| **`BTN-02`** | Outline Secondary Button | Второстепенная контурная кнопка |
+| **`CTL-01`** | Segmented Tab Switcher | Сегментный переключатель вкладок/периодов |
+| **`PRICE-01`** | Formatted Solar Price | Ценник с суффиксом валюты и опциональной пометой «от» |
+| **`CARD-01`** | Base Product Card | Базовая карточка товара каталога с модификаторами |
+| **`CARD-02`** | Plan / Tariff Card | Карточка тарифа/пакета со списком опций |
+| **`SLD-01`** | Card Carousel / Slider | Универсальный слайдер со `scroll-snap` и навигацией |
+| **`HOOK-01`** | Hero Overlap Hook | Плашка-крючок под обложкой (калькулятор счёта, пробег) |
+
+### Как это используется в работе:
+Вместо того чтобы писать разработчику или ИИ:
+> *«Сделай мне карточку товара, где сверху картинка, снизу цена, обведи желтой рамочкой и поставь скругление 12px...»*
+
+Вы просто пишете:
+> *«Поставь в этот блок `CARD-01 -top` и кнопку `BTN-01`»*.
+
+И человек, и любой ИИ моментально понимают задачу на 100% однозначно, без разночтений и простыней текста.
+
+---
+
+## 2. Интерактивная песочница на странице `/ui`
+
+Страница `/ui` (`app/pages/ui.vue`) содержит:
+1. **Интерактивные тумблеры состояний:**
+   Для каждого компонента выведены переключатели модификаторов:
+   - `[x] -top`
+   - `[x] -new`
+   - `[x] -compact`
+   - `[x] -dark`
+2. **Контекстный переключатель фона:**
+   Кнопки переключения подложки («На светлом фоне», «На темном фоне», «В модалке»), чтобы сразу видеть контрастность и поведение текста.
+3. **Кнопка «Скопировать код»:**
+   Рядом с каждым образцом расположена кнопка копирования эталонного Vue-сниппета для быстрой вставки в проект.
+
+---
+
+## 3. Правило обновления брендбука
+
+Любой новый атом, молекула или токен, появляющийся в проекте, **обязан появиться на странице `/ui`**. Если компонента нет на `/ui`, он считается незавершенным.
+Страница `/ui` закрыта от индексации (`noindex, nofollow`) и исключена из `sitemap.xml`.

package/02-design-system/NAMING-CONVENTIONS.md

@@ -0,0 +1,43 @@
+# 02-Design-System · Minimalist Naming & CSS Minification
+
+> Стандарт компактного и семантичного именования классов для уменьшения веса HTML/CSS и ускорения рендеринга.
+
+---
+
+## 1. Принцип краткости без потери смысла
+
+Длинные классы раздувают DOM-дерево, увеличивают объем передаваемого HTML и замедляют парсинг.
+Мы используем краткие, интуитивно понятные сокращения:
+
+| Было (громоздко) | Стало в DS7 (минималистично и чисто) |
+|---|---|
+| `.catalog-product-card` | `.p-card` |
+| `.catalog-product-card--featured` | `.p-card.-top` |
+| `.catalog-product-card__description` | `.p-card__desc` |
+| `.section-heading-eyebrow` | `.s-head__eye` |
+| `.overlap-panel` | `.panel.-overlap` |
+| `.hook-bill-calculator` | `.hook.-bill` |
+| `.button-variant-primary-large` | `.btn.-sun.-lg` |
+
+---
+
+## 2. Формула синтаксиса классов
+
+```
+.[компонент]__ [элемент] .- [модификатор]
+```
+
+1. **Компонент:** Короткое имя блока (`.btn`, `.p-card`, `.field`, `.slider`).
+2. **Элемент (если требуется):** Отделяется двумя подчеркиваниями (`.p-card__art`, `.p-card__body`, `.p-card__title`, `.p-card__price`).
+3. **Модификатор:** Отдельный класс через дефис (`.-top`, `.-dark`, `.-new`, `.-sm`, `.-lg`, `.-compact`).
+
+---
+
+## 3. Сжатие и минификация сборки
+
+1. **PurgeCSS / Tailwind Tree-Shaking:**
+   Все неиспользуемые стили вычищаются при сборке `nuxt generate`. В финальный CSS попадают только реально задействованные классы.
+2. **CSS Nano / Lightning CSS:**
+   Минификатор удаляет комментарии, склеивает правила, сокращает цвета (`#ffffff` → `#fff`, `0px` → `0`) и преобразует повторяющиеся структуры в сжатый бинарный вид для передачи по gzip/brotli.
+3. **Разделение критических и второстепенных стилей:**
+   Критический CSS встраивается в HTML, а вторичные стили сжимаются и кэшируются на год (`Cache-Control: immutable`).

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

@@ -0,0 +1,88 @@
+# 02-Design-System · Tokens Specification
+
+> Дизайн-токены определяют визуальную ДНК проекта. Все значения объявляются через CSS Custom Properties в файле `theme.css`.
+
+---
+
+## 1. Палитра цветов (Semantic Color System)
+
+```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;        /* Ошибки */
+}
+```
+
+> **Правило контрастности:** Желтый цвет `--color-sun` запрещено использовать для текста. Он применяется только как фоновая заливка кнопок (`.btn.-sun`), бейджей или подложка-маркер (`box-shadow: inset 0 -0.3em 0 var(--color-sun)`).
+
+---
+
+## 2. Ритм вертикальных и горизонтальных отступов (Spacing Scale)
+
+```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 */
+  --page-gutter: clamp(1rem, 3.5vw, 2rem);
+}
+```
+
+---
+
+## 3. Тени и глубина поверхностей (Elevation)
+
+Вместо случайных значений `box-shadow` используются строгие семантические токены:
+
+```css
+:root {
+  /* Обычные карточки и панели в состоянии покоя */
+  --shadow-lift: 0 4px 16px -2px rgba(31, 27, 22, 0.06);
+
+  /* Приподнятые карточки при ховере или раскрытые элементы */
+  --shadow-hover: 0 12px 32px -4px rgba(31, 27, 22, 0.12);
+
+  /* Всплывающие модальные окна */
+  --shadow-modal: 0 24px 64px -8px rgba(18, 16, 13, 0.24);
+}
+```
+
+---
+
+## 4. Скругления (Border Radius)
+
+```css
+:root {
+  --radius-sm: 0.375rem; /* 6px — бейджи, кнопки-чипы */
+  --radius-md: 0.75rem;  /* 12px — карточки, инпуты */
+  --radius-lg: 1.25rem;  /* 20px — большие секционные плашки */
+  --radius-full: 9999px; /* Таблетки, круглые кнопки */
+}
+```

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

@@ -0,0 +1,71 @@
+# 03-Performance · Smart Assets Pipeline (Tight-Trim & Responsive Media)
+
+> Стандарт подготовки и вставки графики. Исключает вставку «сырых» тяжелых файлов и гарантирует идеальный LCP.
+
+---
+
+## 1. Правило обрезки избыточных полей (Tight-Trim)
+
+Частая ошибка: дизайнер экспортирует PNG/WebP карточки товара или оборудования на холсте 1000×1000 px, где 60% площади — это прозрачные пустые поля вокруг предмета.
+
+### Почему это плохо:
+* Файл весит лишние байты из-за пустых пикселей;
+* Картинку невозможно ровно отцентрировать по сетке;
+* На мобильных экранах сам товар становится крошечным из-за огромных невидимых полей.
+
+### Стандарт DS7 (Tight-Trim):
+1. **Кадрирование по контуру:** Все прозрачные поля вокруг объекта обрезаются вплотную (если вокруг нет реальной рассеянной тени).
+2. **Прозрачный фон:** Изображения оборудования (панели, инверторы, зарядки) сохраняются на прозрачном фоне, чтобы легко ложиться на светлые, темные и цветные подложки.
+3. **Стабильное соотношение сторон:** В коде карточки задается контейнер со стабильным `aspect-ratio` (например, `aspect-ratio: 4/3` или `1/1`), а сама картинка центрируется через `object-fit: contain`.
+
+---
+
+## 2. Адаптивная вставка через `<picture>` и `srcset`
+
+Каждое растровое изображение подготавливается под конкретные размеры экрана:
+
+```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>
+```
+
+---
+
+## 3. Правило `fetchpriority` и `loading`:
+
+| Расположение изображения | `loading` | `fetchpriority` | `decoding` | Назначение |
+|---|---|---|---|---|
+| **Главный баннер Hero (LCP)** | `eager` | `high` | `async` | Мгновенно загружается первым |
+| **Карточки товаров (2-й экран)** | `lazy` | `auto` | `async` | Загружается перед появлением в поле зрения |
+| **Нижние секции, отзывы, футер** | `lazy` | `low` | `async` | Загружается только при доскролле |
+
+---
+
+## 4. Скрипт автоматической подготовки ассетов
+
+В папке `tools/` рекомендуется держать легковесный скрипт (Python / Sharp), который:
+* Принимает новые картинки;
+* Обрезает прозрачные поля (`trim`);
+* Конвертирует в WebP и AVIF с качеством 82%;
+* Генерирует мобильные копии (`-400.webp`) и ретина-копии (`@2x.webp`).

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

@@ -0,0 +1,46 @@
+# 03-Performance · Critical CSS & Zero Render-Blocking
+
+> Как гарантировать First Contentful Paint (FCP) менее 0.4 секунды и 100 баллов в Google Lighthouse по категории Performance.
+
+---
+
+## 1. В чём проблема стандартного CSS
+
+Когда браузер загружает обычную веб-страницу:
+1. Скачивается `index.html`;
+2. Браузер находит в `<head>` тег `<link rel="stylesheet" href="/_nuxt/entry.css">`;
+3. **Рендеринг страницы полностью блокируется (белый экран)**, пока файл `entry.css` (часто 50–150 КБ) скачивается по мобильной сети и парсится;
+4. Пользователь видит контент только через 1.5–3.0 секунды.
+
+---
+
+## 2. Архитектура Critical CSS в Nuxt 4
+
+Critical CSS разделяет стили сайта на две части:
+1. **Above-the-fold (Критический CSS):** Стили шапки, сетки контейнера, типографики и фонового блока первого экрана (Hero).
+2. **Below-the-fold (Вторичный CSS):** Стили калькулятора, отзывов, карты, футера, модальных окон.
+
+### Настройка в `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  experimental: {
+    // Автоматическое извлечение и встраивание критических стилей в HTML
+    inlineSSRStyles: true
+  }
+})
+```
+
+### Как это работает:
+При статической генерации (`npx nuxt generate`):
+* Nuxt парсит HTML каждой страницы и определяет классы, нужные для первого экрана;
+* Эти правила вставляются прямо внутрь `<style>` в `<head>` документа `index.html`;
+* Полная таблица стилей подключается асинхронно: `<link rel="preload" as="style">`.
+
+---
+
+## 3. Результат для пользователя и Google Lighthouse
+
+* Браузер получает `index.html` и **в ту же миллисекунду рисует идеальный первый экран**, не делая ни одного дополнительного сетевого запроса за CSS.
+* **FCP (First Contentful Paint):** снижается с 1.8s до **0.35s**.
+* **Speed Index:** зеленая зона (98–100 баллов).

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

@@ -0,0 +1,63 @@
+# 03-Performance · Fonts & Zero Layout Shift (CLS = 0.000)
+
+> Как исключить «прыжки» текста при загрузке шрифтов и свести показатель Cumulative Layout Shift (CLS) к абсолютному нулю.
+
+---
+
+## 1. Анатомия проблемы FOUT и прыжков текста
+
+Когда веб-шрифт Montserrat подгружается через `@font-face`:
+1. Браузер сначала рисует текст стандартным системным шрифтом (Arial или Helvetica);
+2. У системного шрифта другая ширина букв и высота строки (x-height);
+3. Через секунду подгружается `montserrat.woff2`, шрифт переключается, строки переносятся на новое место, и **вся страница дергается вниз на 20–40 пикселей**.
+4. Пользователь случайно кликает не туда, а Google фиксирует плохой показатель CLS (> 0.15).
+
+---
+
+## 2. Комплексное решение проблемы в DS7
+
+### Шаг 1: Прямой Preload в `<head>`
+Не ждем, пока CSS файл будет прочитан. Браузер начинает качать шрифт с первой миллисекунды:
+
+```ts
+// nuxt.config.ts -> app.head
+link: [
+  {
+    rel: 'preload',
+    href: '/fonts/montserrat-latin-var.woff2',
+    as: 'font',
+    type: 'font/woff2',
+    crossorigin: 'anonymous'
+  }
+]
+```
+
+### Шаг 2: Модуль `@nuxtjs/fontaine` (Синхронизация пропорций)
+Fontaine анализирует геометрию шрифта Montserrat и создает локальный псевдо-шрифт:
+
+```css
+@font-face {
+  font-family: 'Montserrat-Fallback';
+  src: local('Arial');
+  ascent-override: 95.8%;
+  descent-override: 28.2%;
+  line-gap-override: 0%;
+  size-adjust: 101.4%;
+}
+```
+
+**Магия Fontaine:** Буквы локального системного шрифта искусственно сжимаются и растягиваются так, чтобы **пиксель-в-пиксель занимать то же пространство**, что и Montserrat. 
+Когда реальный шрифт скачивается, форма букв меняется, но **ни одна строчка на странице не сдвигается**.
+
+### Шаг 3: `font-display: swap`
+Шрифт отображается мгновенно, экран не ждет загрузки (нет белого текста FOIT).
+
+---
+
+## 3. Чек-лист проверки CLS = 0.000
+
+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` и не выталкивают контент.