projects/org/ideal-shop/V2-drupal11-bootstrap/THEME-SPEC.md

Спецификация ideal_theme (v2 Д2Б)

Версия: 2.0.0
Дата: 2026-03-23


Принцип

Bootstrap Barrio даёт: сетку, формы, компоненты
ideal_theme добавляет: магазинную специфику поверх

Не переписываем Bootstrap — только расширяем.


Структура файлов

web/themes/custom/ideal_theme/

├── ideal_theme.info.yml          объявление темы
├── ideal_theme.libraries.yml     подключение CSS/JS
├── ideal_theme.theme             PHP хуки

├── css/
   ├── tokens.css                дизайн-токены
   ├── product.css               карточка и страница товара
   ├── catalog.css               каталог и фильтры
   ├── cart.css                  корзина и checkout
   └── global.css                шапка, подвал, типографика

├── js/
   ├── cart-ajax.js              добавление в корзину без перезагрузки
   ├── filters.js                AJAX фильтры
   └── delivery-progress.js     прогресс до бесплатной доставки

└── templates/
    ├── layout/
       ├── page.html.twig
       ├── page--front.html.twig
       ├── region--header.html.twig
       └── region--footer.html.twig
    ├── commerce/
       ├── commerce-product--full.html.twig
       ├── commerce-product-variation.html.twig
       ├── commerce-cart-block.html.twig
       └── commerce-checkout-form--default.html.twig
    ├── views/
       ├── views-view-unformatted--products.html.twig
       └── views-view--products--page.html.twig
    └── components/
        ├── delivery-progress.html.twig
        └── cross-sell.html.twig

CSS: дизайн-токены (tokens.css)

:root {
  /* Цвета — полная шкала (см. DESIGN.md) */
  --color-brand-500:  hsl(220, 90%, 56%);  /* Primary */
  --color-brand-600:  hsl(220, 90%, 48%);  /* Hover */
  --color-brand-400:  hsl(220, 90%, 64%);  /* Light */
  --color-accent:     hsl(0, 72%, 58%);    /* Акцент */
  --color-success:    hsl(142, 70%, 40%);
  --color-warning:    hsl(38, 95%, 50%);
  --color-danger:     hsl(0, 80%, 50%);

  /* Нейтральные */
  --color-gray-900: hsl(220, 30%, 12%);
  --color-gray-500: hsl(220, 10%, 50%);
  --color-gray-200: hsl(220, 20%, 90%);
  --color-gray-100: hsl(220, 20%, 96%);
  --color-gray-50:  hsl(220, 20%, 98%);

  /* Семантические алиасы */
  --color-text:       var(--color-gray-900);
  --color-text-muted: var(--color-gray-500);
  --color-bg:         #ffffff;
  --color-bg-alt:     var(--color-gray-50);
  --color-border:     var(--color-gray-200);
  --color-link:       var(--color-brand-500);
  --color-link-hover: var(--color-brand-600);

  /* Типографика — системные шрифты (без Google Fonts) */
  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Arial, sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
  --font-size-sm: 0.875rem;
  --font-size-md: 1rem;
  --font-size-lg: 1.125rem;

  /* Скругления */
  --radius-sm:  4px;
  --radius-md:  6px;
  --radius-lg:  8px;
  --radius-xl:  12px;

  /* Тени */
  --shadow-sm:   0 1px 2px rgba(0,0,0,0.05);
  --shadow-md:   0 4px 6px rgba(0,0,0,0.1);   /* карточки */
  --shadow-lg:   0 10px 15px rgba(0,0,0,0.1); /* модалки */
  --shadow-hover: 0 4px 16px rgba(0,0,0,0.14);
}

Шаблоны: что переопределяем

Карточка товара

Bootstrap card + наши расширения:

┌──────────────────────┐
│  [ФОТО]              │ ← галерея
│  [БЕЙДЖ скидки]      │ ← badge Bootstrap
├──────────────────────┤
│  Название товара     │ ← card-title
│  ★★★★☆ (23)         │ ← fivestar
│  ──────────────────  │
│  1 990 ₽  ~~2 500~~  │ ← цена + зачёркнутая
├──────────────────────┤
│  [В корзину]         │ ← btn btn-primary
└──────────────────────┘

Страница товара

┌────────────────┬─────────────────────────┐
                  Название товара        
  ГАЛЕРЕЯ         ★★★★☆ · 23 отзыва    
  (carousel)      ─────────────────────  
                  2 490   ~~3 200~~     
                  [S] [M] [L] [XL]       │← варианты
                  В наличии: 5 шт.       │← остаток
                  ─────────────────────  
                  [В КОРЗИНУ]  []       
└────────────────┴─────────────────────────┘
Вкладки: Описание | Характеристики | Отзывы

Каталог

┌──────┬──────────────────────────────────┐
│      │  Сортировка: [популярные ▼]      │
│ Фильт│  ──────────────────────────────  │
│ -ры  │  [карточка] [карточка] [карточка]│
│      │  [карточка] [карточка] [карточка]│
│ side │  ──────────────────────────────  │
│ -bar │  [1] [2] [3] ... [пагинация]     │
└──────┴──────────────────────────────────┘

Мобильный: фильтры → кнопка → offcanvas

Корзина

Товары (2)                    Итого
─────────────────────         ──────────────────
[фото] Товар 1                Товары: 3 490 ₽
       1 990 ₽  × [1] +/−     Доставка: 300 ₽
                              ────────────────
[фото] Товар 2                Итого: 3 790 ₽
       800 ₽   × [2] +/−      [Оформить заказ]

───────────────────────
ЕЩЁ 1 210 ₽ ДО БЕСПЛАТНОЙ ДОСТАВКИ  ←  прогресс-бар
═══════════════════════

С этим берут: [Товар A] [Товар B]  ← cross-sell

JS: что пишем

Файл Что делает
cart-ajax.js Добавление в корзину без перезагрузки страницы
filters.js AJAX фильтрация, обновление count у чекбоксов
delivery-progress.js Пересчёт прогресса при изменении корзины

Компоненты без аналога в Bootstrap

Компонент Файл Описание
Прогресс доставки delivery-progress.html.twig «Ещё X ₽ до бесплатной»
Cross-sell блок cross-sell.html.twig «С этим берут»
Варианты товара внутри product--full Кнопки выбора (размер, цвет, объём)
Статус остатка внутри product--full «В наличии / Мало / Нет»
Таймер акции внутри card/product--full Обратный отсчёт до конца скидки

Реализация страниц

Главная (HOME)

Блок страницы Drupal компонент Фаза
Шапка (Header) Block: ideal_header (Bootstrap Barrio region) Ф2
Hero баннер View: ideal_hero (слайдер, тип: Banner node) Ф2
USP блок Block: ideal_usp (статический, Twig) Ф2
Категории View: ideal_categories (таксономия Commerce) Ф3
Хиты продаж View: ideal_bestsellers (Commerce + флаг) Ф3
Акции / баннеры View: ideal_promotions (Commerce Promotion) Ф7
SEO-текст Node body (тип: Page) Ф2
Футер Block: ideal_footer (Bootstrap Barrio region) Ф2

Bootstrap Barrio: регионы header / content / footer / sidebar_first
ideal_theme: переопределяет шаблоны views, добавляет карусель через Bootstrap JS


Каталог / Категория (CATEGORY)

Блок страницы Drupal компонент Фаза
Хлебные крошки Block: system_breadcrumb_block Ф3
Шапка категории Node (тип: Category) — title + body Ф3
Подкатегории View: ideal_subcategories (таксономия) Ф3
Сетка товаров View: ideal_catalog (Commerce + Facets) Ф3
Фильтры сайдбар Facets (Search API) — desktop sticky Ф3
Фильтры мобайл Facets bottom sheet (Bootstrap offcanvas) Ф3
Сортировка Views exposed filter (sort_by) Ф3
SEO-текст Node body (свёрнутый) Ф3

Bootstrap Barrio: layout — sidebar_first + content (двухколоночный)
ideal_theme: переопределяет views-view.html.twig, добавляет AJAX фильтрацию


Карточка товара (PRODUCT)

Блок страницы Drupal компонент Фаза
Галерея Commerce Product field: images (Bootstrap Carousel в Twig) Ф3
Название, артикул Commerce Product: title, field_sku Ф3
Рейтинг Fivestar module + отдельный field Ф7
Цена Commerce Price field Ф3
Варианты (цвет/размер) Commerce Product Variation attributes Ф3
В корзину Commerce Add to Cart form Ф3
В избранное ❤️ Commerce Wishlist (ideal_shop_wishlist) Ф7
Доставка/оплата Block: ideal_delivery_info (статик) Ф4
Табы (описание/хар-ки/отзывы) Bootstrap Tabs + field groups Ф3/Ф7
Похожие товары View: ideal_related (Commerce + taxonomy) Ф7
С этим покупают View: ideal_upsell (Commerce) Ф7
Schema.org Metatag module + JSON-LD Ф3

Bootstrap Barrio: layout — content full (одноколоночный, широкий)
ideal_theme: переопределяет commerce-product--full.html.twig + twig шаблоны


Корзина (CART)

Блок страницы Drupal компонент Фаза
Список товаров Commerce Cart form (переопределённый Twig) Ф4
+/- количество Commerce Cart AJAX update Ф4
Mini-cart (flyout) Commerce Cart block (sidebar/header) Ф4
Промокод Commerce Promotion — coupon code field Ф7
Прогресс до бесплатной Block: ideal_free_delivery (custom) Ф4
Upsell (добавьте ещё) View: ideal_upsell_cart Ф7
Итого / "Оформить" Commerce Cart summary block Ф4
Пустая корзина Twig template: commerce-cart-empty.html.twig Ф4

Bootstrap Barrio: layout — content + sidebar_second (итого справа)
ideal_theme: переопределяет commerce-cart.html.twig, AJAX без перезагрузки


Checkout (CHECKOUT)

Шаг / блок Drupal компонент Фаза
Прогресс-бар шагов Commerce Checkout progress block Ф4
Шаг 1: Контакты Commerce Checkout pane: contact_information Ф4
Шаг 2: Доставка Commerce Checkout pane: shipping (Commerce Shipping) Ф5
Карта ПВЗ СДЭК СДЭК Widget (JS) + Commerce Shipping plugin Ф5
Шаг 3: Оплата наличные Commerce Payment pane (cash on delivery) Ф4
Шаг 3: ЮKassa Commerce Payment pane (ЮKassa gateway plugin) Ф5
Шаг 4: Подтверждение Commerce Checkout pane: review Ф4
Страница спасибо Commerce Checkout: order_complete pane Ф4
Мини-заказ справа Commerce Order summary block Ф4
Согласие с офертой Commerce Checkout pane: terms_of_service Ф4
Гостевой checkout Commerce Checkout pane: guest_login Ф4

Bootstrap Barrio: минимальный layout (без sidebar), максимальная ширина контента
ideal_theme: переопределяет commerce-checkout-*.html.twig + шаг-прогресс

Рынки:
- RU (Ф4-5): телефон + имя, СДЭК/курьер, ЮKassa/СБП/наличные
- EU (Ф10): First/Last name, DHL, Stripe + VAT поле
- NA (Ф10): First/Last name, State/ZIP, Stripe


← Назад | Стек → | BUILD-PLAN →