@ai.all/ds7 1.0.0 → 2.0.0

package/01-architecture/ATOMIC-DESIGN.md

@@ -1,62 +1,68 @@
-# 01-Architecture · Atomic Design & Component Hierarchy
+# 01 · Atomic Design and component levels
 
-> Методология построения интерфейса основана на принципах [Atomic Design Брэда Фроста (Brad Frost)](https://atomicdesign.bradfrost.com/chapter-2/) с акцентом на **полную автономность (self-contained)** и **компонуемость (composability)** каждого блока.
+Components are organised in five levels, after [Brad Frost's Atomic Design](https://atomicdesign.bradfrost.com/chapter-2/). Each level depends only on the levels below it. The goal is that a block works anywhere: on a page, in a sidebar, in a modal, or nested inside another block.
 
 ---
 
-## 1. Пять уровней иерархии
+## 1. Levels
 
 ```
-[1. ATOMS]       ───> Неделимые кирпичики: кнопки, иконки, бейджи, инпуты, цены
-     │
-[2. MOLECULES]   ───> Связки атомов: карточка товара, карточка тарифа, навигация слайдера
-     │
-[3. ORGANISMS]   ───> Автономные виджеты: слайдер карточек, сетка преимуществ, FAQ, калькулятор
-     │
-[4. TEMPLATES]   ───> Каркасы секций и лэндингов: Hero-секция, шаблон направления
-     │
-[5. PAGES]       ───> Маршруты Nuxt (app/pages/*): получение данных из app/data/ и передача в шаблоны
+[1. Atoms]       indivisible parts: button, icon, badge, field, price
+      │
+[2. Molecules]   small groups of atoms: product card, plan card, slider controls
+      │
+[3. Organisms]   self-contained widgets: card slider, feature grid, FAQ, calculator
+      │
+[4. Templates]   section layouts that compose organisms
+      │
+[5. Pages]       routes: fetch data, set SEO, pass props
 ```
 
 ---
 
-## 2. Правила для каждого уровня
+## 2. Rules per level
 
-### Уровень 1: Атомы (`app/components/ui/`)
-- **Что входит:** `UiButton`, `UiIcon`, `UiPrice`, `UiProductBadge`, `UiField`, `UiLink`, `UiText`, `UiCrown`, `UiSun`.
-- **Правило изоляции:** Атомы абсолютно «слепы». Они не знают о существовании страниц, товаров или калькулятора. Управляются исключительно типизированными входными пропсами.
-- **Стилизация:** Базовый класс + короткие модификаторы (`.btn.-sun`, `.btn.-sm`, `.btn.-outline`).
+### Atoms — `app/components/ui/`
+- Examples: `UiButton`, `UiIcon`, `UiPrice`, `UiBadge`, `UiField`, `UiLink`.
+- Know nothing about pages, products or application state.
+- Styled with a base class and short modifiers: `.btn.-sun`, `.btn.-sm`, `.btn.-outline`.
 
-### Уровень 2: Молекулы (`app/components/ui/`)
-- **Что входит:** `UiProductCard` (карточка товара), `UiSectionHeading` (заголовок секции с eyebrow и подписью), `UiFeatureCard` (карточка преимущества), `UiPlanCard` (карточка тарифа/пакета), `UiSliderNav` (стрелки и точки).
-- **Правило изоляции:** Молекулы компонуются только из атомов и базовой HTML-разметки. Принимают данные через `defineProps` и слоты. Не имеют сайд-эффектов.
-- **Вложенность:** Молекула должна идеально смотреться и в 4-колоночном гриде на всю ширину страницы, и в узком сайдбаре (за счет `@container`).
+### Molecules — `app/components/ui/`
+- Examples: `UiProductCard`, `UiSectionHeading`, `UiFeatureCard`, `UiPlanCard`, `UiSliderNav`.
+- Built only from atoms and plain markup. Typed props and slots. No side effects.
+- Must look right in a four-column grid and in a narrow sidebar. Use container queries.
 
-### Уровень 3: Организмы (`app/components/ui/`, `sections/`, `site/`)
-- **Что входит:** `UiCardSlider` (универсальный слайдер), `UiFeatureGrid` (сетка преимуществ), `UiHeroHook` (плашка-крючок под Hero), `UiFaq` (аккордеон), `CalcPanel` (панель расчета), `SiteHeader`, `SiteFooter`.
-- **Правило изоляции:** Организмы функционально самодостаточны. Они сами управляют своим состоянием (скролл, активная вкладка, раскрытый аккордеон).
-- **Слоты:** Организмы-контейнеры обязаны работать через слоты (`<template #default="{ item }">`). Слайдер не должен быть зашит на товары — он крутит любые переданные молекулы.
+### Organisms — `app/components/ui/`, `sections/`, `site/`
+- Examples: `UiCardSlider`, `UiFeatureGrid`, `UiFaq`, `CalcPanel`, `SiteHeader`, `SiteFooter`.
+- Own their local state: scroll position, active tab, open accordion item.
+- Work through slots. A slider does not know that it shows products; it shows whatever molecules it receives.
 
-### Уровень 4: Шаблоны и Секции (`app/components/sections/`)
-- **Что входит:** `CalcSection`, `UiPageHero`, шаблоны направлений (`DirectionPage`).
-- **Правило:** Шаблоны соединяют организмы в законченный блок страницы, передавая в них структуру. Никакой захардкоженной логики под конкретные URL.
+### Templates and sections — `app/components/sections/`
+- Compose organisms into a complete block of a page.
+- No URL-specific logic and no hard-coded page content.
 
-### Уровень 5: Страницы (`app/pages/`)
-- **Что входит:** `index.vue`, `[slug].vue`, `movilidad.vue`, `mantenimiento.vue` и др.
-- **Правило:** Страницы отвечают **только** за 3 вещи:
-  1. Вызов composables для получения данных из `app/data/`;
-  2. Установку метатегов (`usePageSeo`);
-  3. Передачу данных в секции и шаблоны через пропсы.
-- **Запрет:** В файлах `app/pages/` **категорически запрещена прямая инлайн-верстка карточек, кастомных слайдеров и специфических сеток**.
+### Pages — `app/pages/`
+Pages do three things only:
+1. Call composables that read data from `app/data/`.
+2. Set page metadata (`usePageSeo`).
+3. Pass data to sections as props.
+
+Pages do not contain inline card markup, custom sliders or bespoke grids.
 
 ---
 
-## 3. Принцип «Внутрь чего-то еще и еще глубже»
+## 3. Embedding rule
+
+Every component must be placeable:
+1. in normal page flow;
+2. inside a modal;
+3. inside a tab or a calculator panel;
+4. inside a narrow sidebar or a drawer.
+
+Size comes from the parent box (`@container`), not from the screen (`@media`).
+
+---
 
-Любой компонент системы спроектирован так, чтобы его можно было вставить:
-1. В обычный поток страницы;
-2. Внутрь модального окна `UiModal`;
-3. Внутрь вкладки калькулятора или табов;
-4. Внутрь узкого сайдбара или всплывающей шторки.
+## 4. Brand first
 
-Компонент рассчитывает свои размеры не от экрана (`@media`), а от родительского блока (`@container`).
+Levels are built top-down from the brandbook. Atoms come from tokens and the sandbox entries in `02-design-system/BRANDBOOK-SANDBOX.md`. A component that exists only in a page is not finished until it is in the sandbox.

package/01-architecture/COMPONENT-ANATOMY.md

@@ -1,27 +1,24 @@
-# 01-Architecture · Component Anatomy & Container Queries
+# 01 · Component anatomy and container queries
 
-> Эталонный анатомический разрез Vue 3 SFC (Single File Component). По этой структуре строятся все компоненты в системе.
+The reference shape of a Vue 3 single-file component in DS7. The template file is in `templates/component.vue`.
 
 ---
 
-## 1. Анатомический шаблон компонента
+## 1. Shape
 
 ```vue
 <script setup lang="ts">
 /**
- * UiProductCard
- * Молекула карточки товара каталога.
- * Поддерживает адаптивность по контейнеру и каскадные модификаторы.
+ * UiProductCard — product card molecule.
+ * Container-aware. Modifiers are separate classes.
  */
 
-// 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
@@ -31,32 +28,27 @@ const props = withDefaults(defineProps<{
   specs: () => [],
   top: false,
   compact: false,
-  dark: false
+  dark: false,
 })
 
-// 2. Вычисляемые классы-модификаторы
 const rootClasses = computed(() => [
   'p-card',
   props.top && '-top',
   props.compact && '-compact',
   props.dark && '-dark',
-  props.badge && `-${props.badge}`
+  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>
@@ -65,7 +57,6 @@ const rootClasses = computed(() => [
       </dl>
     </div>
 
-    <!-- Футер с ценой и действием -->
     <div class="p-card__footer">
       <UiPrice v-if="price !== null" :amount="price" />
       <slot name="action" />
@@ -74,10 +65,6 @@ const rootClasses = computed(() => [
 </template>
 
 <style>
-/* 
- * Стили объявляются без scoped, но строго изолируются через префикс компонента.
- * Это позволяет внешним родителям каскадно переопределять CSS-переменные.
- */
 .p-card {
   --card-bg: var(--color-white);
   --card-ink: var(--color-ink);
@@ -91,7 +78,6 @@ const rootClasses = computed(() => [
   padding: var(--space-4);
 }
 
-/* Контейнерный запрос: адаптация под размер родительского блока */
 @container (max-width: 320px) {
   .p-card {
     padding: var(--space-2);
@@ -105,13 +91,11 @@ const rootClasses = computed(() => [
 
 ---
 
-## 2. Ключевые архитектурные правила:
+## 2. Rules
 
-1. **`container-type: inline-size`:**
-   Компонент всегда объявляет свой контейнер, если имеет адаптивные состояния. Он не зависит от ширины экрана (`@media`), а реагирует на ширину бокса, в который его поместили (`@container`).
-2. **Локальные CSS-переменные (`--card-bg`, `--card-ink`):**
-   Все цвета и параметры привязаны к переменным компонента. Модификатор меняет переменные, а не 10 дочерних селекторов.
-3. **Стабильный идентификатор `data-ref="CARD-01"`:**
-   Связывает живой компонент в коде с разделом в брендбуке на `/ui`.
-4. **Слоты с фоллбэками:**
-   Для медиа (`#art`) и кнопок (`#action`) используются слоты, позволяя переиспользовать разметку под любые типы контента.
+1. **Typed props.** Booleans for modifiers keep templates readable; `rootClasses` turns them into classes.
+2. **`container-type: inline-size`** on any component with responsive states. It reacts to its box, not to the screen.
+3. **Component-level custom properties** (`--card-bg`, `--card-ink`). Modifiers change the variables, not ten child selectors.
+4. **Stable ID** in `data-ref` (`CARD-01`). It links the live component to its entry in the brandbook.
+5. **Slots with fallbacks** for media and actions. The component works with any content in those slots.
+6. **A one-line summary** at the top of the file, as in the example.

package/01-architecture/MODIFIER-SYSTEM.md

@@ -1,33 +1,33 @@
-# 01-Architecture · Modifier System & Ancestry Scoping
+# 01 · Modifier system and ancestry scoping
 
-> Система модификаторов обеспечивает максимальное переиспользование кода без создания дублирующих компонентов.
+One base component, many variants, no duplicate components.
 
 ---
 
-## 1. Синтаксис отдельных классов-модификаторов
+## 1. Syntax
 
-Вместо длинных составных BEM-имен (`catalog-product-card--featured-large-dark`) используется компактная и легко читаемая схема: **базовый класс + отдельные короткие классы с дефисом**:
+Use a base class plus separate modifier classes. Each modifier starts with a dash:
 
 ```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>
+  <div class="p-card__art">…</div>
+  <h3 class="p-card__title">Panel 450 W</h3>
+  <div class="p-card__price">…</div>
 </article>
 ```
 
-### Преимущества:
-1. **Экономия байтов в HTML/CSS:** Классы короткие, вес страницы уменьшается.
-2. **Аддитивность:** Модификаторы можно комбинировать в любых сочетаниях (`-top -new`, `-dark -compact`).
-3. **Каскадное влияние:** Модификатор на корневом элементе прозрачно меняет свойства всех вложенных элементов.
+Why:
+- **Short class names** keep HTML and CSS small.
+- **Modifiers combine** freely: `-top -compact`, `-dark -lg`.
+- **Modifiers cascade:** a modifier on the root can change every child.
+
+Avoid long compound names such as `catalog-product-card--featured-large-dark`.
 
 ---
 
-## 2. Каскад стилей от модификатора
+## 2. Cascade from a modifier
 
 ```css
-/* Базовый компонент */
 .p-card {
   --card-bg: var(--color-white);
   --card-text: var(--color-ink);
@@ -38,10 +38,8 @@
   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);
@@ -50,52 +48,43 @@
   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);
+  --card-border: rgba(255, 255, 255, 0.12);
 }
 ```
 
----
+Modifiers change custom properties where possible. That keeps the number of selectors small.
 
-## 3. Управление контекстом от предка (Ancestry Scoping)
-
-Если один и тот же рабочий компонент (слайдер, форма, плашка хука) должен выглядеть иначе на определенной странице (например, на странице для бизнеса `/empresas` фон должен быть графитовым, а на главной — песочным):
+---
 
-❌ **Как делать НЕЛЬЗЯ:**
-Создавать два разных файла: `HookHome.vue` и `HookEmpresas.vue`.
+## 3. Context from an ancestor
 
-✅ **Как делать ПРАВИЛЬНО:**
-Использовать единый компонент `UiHeroHook`, а различия задавать через родительский контекст — класс страницы на теге `<body>`:
+Sometimes a shared component must look different on one page. Do not create a second component. Scope the difference by an ancestor:
 
 ```css
-/* Базовый хук везде */
+/* the hook everywhere */
 .hero-hook {
   background: var(--color-paper);
   color: var(--color-ink);
 }
 
-/* Тот же самый хук на странице для бизнеса (темная тема) */
-body.page-empresas .hero-hook {
+/* the same hook on a dark page */
+body.page-business .hero-hook {
   background: var(--color-ink-950);
   color: var(--color-white);
 }
 
-/* Тот же компонент внутри модального окна */
+/* the same hook inside a modal */
 .site-modal-box .hero-hook {
   background: transparent;
   padding: 0;
 }
 ```
 
-Благодаря настройке в `usePageSeo.ts` каждая страница Nuxt автоматически проставляет свой класс на `<body>` (`page-home`, `page-hogares`, `page-empresas`, `page-movilidad`, `page-equipamiento`).
+The page class on `<body>` is set by `usePageSeo` (`page-home`, `page-residential`, `page-business`, …). Wrong: `HookHome.vue` and `HookBusiness.vue`. Right: one `UiHeroHook` with context rules.

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

@@ -1,52 +1,52 @@
-# 02-Design-System · Brandbook & Sandbox (/ui)
+# 02 · Brandbook and sandbox (`/ui`)
 
-> Страница `/ui` в проекте — это не просто документация, а **живой интерактивный полигон компонентов (Storybook)** и единый язык коммуникации между человеком и ИИ.
+The `/ui` page of a project is a live sandbox: every foundation token and every base component, shown in its real code. It is the shared vocabulary between people and agents.
 
 ---
 
-## 1. Концепция стабильных меток компонентов (Component IDs)
+## 1. Stable component IDs
 
-Каждый переиспользуемый паттерн в дизайн-системе имеет уникальный краткий буквенно-цифровой идентификатор:
+Every reusable pattern has one short ID:
 
-| ID | Название компонента | Назначение |
+| ID | Name | Use |
 |---|---|---|
-| **`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 | Плашка-крючок под обложкой (калькулятор счёта, пробег) |
+| `BTN-01` | Primary button | main action; sun fill with an arrow |
+| `BTN-02` | Outline button | secondary action |
+| `CTL-01` | Segmented switch | tabs or periods |
+| `COUNTER-01` | Bounded numeric counter | number input with − / + buttons; variant `-inner` |
+| `PRICE-01` | Formatted price | amount with currency suffix and optional "from" label |
+| `CARD-01` | Base product card | catalogue item with modifiers |
+| `CARD-02` | Plan / tariff card | package with a list of options |
+| `SLD-01` | Card slider | scroll-snap slider with navigation |
+| `HOOK-01` | Overlap hook | panel that overlaps a cover image |
 
-### Как это используется в работе:
-Вместо того чтобы писать разработчику или ИИ:
-> *«Сделай мне карточку товара, где сверху картинка, снизу цена, обведи желтой рамочкой и поставь скругление 12px...»*
+**How it is used.** Instead of describing a card in full, say:
 
-Вы просто пишете:
-> *«Поставь в этот блок `CARD-01 -top` и кнопку `BTN-01`»*.
+> "Put `CARD-01 -top` in this block, with `BTN-01` as the action."
 
-И человек, и любой ИИ моментально понимают задачу на 100% однозначно, без разночтений и простыней текста.
+Both a person and an agent understand that without a second description.
 
 ---
 
-## 2. Интерактивная песочница на странице `/ui`
+## 2. What the sandbox shows
 
-Страница `/ui` (`app/pages/ui.vue`) содержит:
-1. **Интерактивные тумблеры состояний:**
-   Для каждого компонента выведены переключатели модификаторов:
-   - `[x] -top`
-   - `[x] -new`
-   - `[x] -compact`
-   - `[x] -dark`
-2. **Контекстный переключатель фона:**
-   Кнопки переключения подложки («На светлом фоне», «На темном фоне», «В модалке»), чтобы сразу видеть контрастность и поведение текста.
-3. **Кнопка «Скопировать код»:**
-   Рядом с каждым образцом расположена кнопка копирования эталонного Vue-сниппета для быстрой вставки в проект.
+1. **Modifier toggles** for each component: `-top`, `-new`, `-compact`, `-dark`.
+2. **Background switch:** light, dark, inside a modal. Contrast is visible on each.
+3. **Copy code** next to each example: the reference snippet for pasting into a project.
 
 ---
 
-## 3. Правило обновления брендбука
+## 3. Update rule
 
-Любой новый атом, молекула или токен, появляющийся в проекте, **обязан появиться на странице `/ui`**. Если компонента нет на `/ui`, он считается незавершенным.
-Страница `/ui` закрыта от индексации (`noindex, nofollow`) и исключена из `sitemap.xml`.
+Every new atom, molecule or token must appear in the sandbox before it is used on a page. A component that is missing from `/ui` is not finished. The sandbox is excluded from search indexing (`noindex, nofollow`) and from `sitemap.xml`.
+
+---
+
+## 4. Brand-first workflow
+
+1. Add or change foundations in `theme.css`.
+2. Add or change the entry in the sandbox.
+3. Build or change the component.
+4. Use the component on a page.
+
+Changing a token changes the sandbox first; the sandbox is the visual reference for review.

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

@@ -1,15 +1,12 @@
-# 02-Design-System · Minimalist Naming & CSS Minification
+# 02 · Naming conventions
 
-> Стандарт компактного и семантичного именования классов для уменьшения веса HTML/CSS и ускорения рендеринга.
+Short, semantic class names keep HTML small and make CSS readable. The formula and the rules are the same for every project.
 
 ---
 
-## 1. Принцип краткости без потери смысла
+## 1. Examples
 
-Длинные классы раздувают DOM-дерево, увеличивают объем передаваемого HTML и замедляют парсинг.
-Мы используем краткие, интуитивно понятные сокращения:
-
-| Было (громоздко) | Стало в DS7 (минималистично и чисто) |
+| Long name | DS7 name |
 |---|---|
 | `.catalog-product-card` | `.p-card` |
 | `.catalog-product-card--featured` | `.p-card.-top` |
@@ -21,23 +18,28 @@
 
 ---
 
-## 2. Формула синтаксиса классов
+## 2. Formula
 
 ```
-.[компонент]__ [элемент] .- [модификатор]
+.[component]          base name, short kebab-case
+.[component]__[part]  element, double underscore
+.-[modifier]          modifier, separate class with a leading dash
+.is-[state]           state
 ```
 
-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. Rules
+
+1. **No word appended to a base name.** `.btn-lg`, `.card-big`, `.hero-active` are wrong. Write `.btn.-lg`, `.card.-big`, `.hero.is-active`.
+2. **Size and colour words are modifiers.** `-sm`, `-lg`, `-sun`, `-dark`. Not `-big`, `-red`, `-orange`.
+3. **Element names describe the part.** `__title`, `__price`, `__art`, not `__text2` or `__left`.
+4. **Only tokens in values.** Naming does not replace the token rule in `TOKENS-SPEC.md`.
 
 ---
 
-## 3. Сжатие и минификация сборки
+## 4. Build-time minification
 
-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`).
+- Unused styles are removed when the site is generated. Only classes that appear in the output ship.
+- The CSS minifier removes comments and shortens values (`#ffffff` → `#fff`).
+- Critical CSS is inlined; the rest is a cached file with a content hash in its name.