Разработка UI-kit на Vue.js для проекта 1С-Битрикс

Разработка UI-kit на Vue.js для проекта 1С-Битрикс

На крупных Битрикс-проектах с командой из 3+ разработчиков рано или поздно появляется проблема несогласованности интерфейса: кнопки выглядят по-разному в разных шаблонах компонентов, модальные окна реализованы тремя способами, даты форматируются в пяти вариантах. Каждый разработчик пишет «свой» вариант, потому что общего стандарта нет.

UI-kit на Vue.js — это библиотека переиспользуемых компонентов, которая устанавливает единый стандарт для всей фронтенд-части проекта.

Что такое UI-kit и зачем он нужен в Битрикс-проекте

UI-kit — это набор базовых UI-компонентов с документацией: кнопки, формы, уведомления, модальные окна, таблицы, иконки, типографика. Каждый компонент реализует одно визуальное/функциональное поведение и используется везде на сайте через единый API.

В контексте 1С-Битрикс это особенно актуально, потому что Битрикс-сайт — это десятки шаблонов компонентов, которые пишутся независимо. Без UI-kit каждый шаблон использует собственную HTML-структуру и CSS-классы для одинаковых элементов. С UI-kit — все шаблоны используют один и тот же компонент <AppButton>, <AppModal>, <AppAlert>.

Архитектура Vue UI-kit для Битрикса

Структура библиотеки:

/local/js/ui-kit/
├── src/
│   ├── components/
│   │   ├── AppButton.vue
│   │   ├── AppInput.vue
│   │   ├── AppModal.vue
│   │   ├── AppAlert.vue
│   │   ├── AppSelect.vue
│   │   └── ...
│   ├── composables/
│   │   ├── useModal.js
│   │   └── useToast.js
│   ├── tokens/
│   │   └── design-tokens.css  // CSS-переменные
│   └── index.js               // экспорт всех компонентов
├── dist/                      // скомпилированная библиотека
└── vite.config.js

Режим сборки. UI-kit собирается в режиме library через Vite:

// vite.config.js
export default {
    build: {
        lib: {
            entry: './src/index.js',
            name: 'BitrixUIKit',
            formats: ['umd'],
            fileName: 'ui-kit',
        },
        rollupOptions: {
            external: ['vue'],
            output: { globals: { vue: 'Vue' } }
        }
    }
}

Результат — ui-kit.umd.js и ui-kit.css, которые подключаются глобально в шаблоне сайта и делают компоненты доступными для всех Vue-приложений на странице.

Интеграция с Битрикс-шаблоном. В header.php шаблона сайта:

$APPLICATION->AddHeadScript('/local/js/ui-kit/dist/ui-kit.umd.js');
$APPLICATION->SetAdditionalCSS('/local/js/ui-kit/dist/ui-kit.css');

Принципы разработки компонентов

Дизайн-токены. Все цвета, отступы, шрифты, радиусы хранятся как CSS-переменные (--color-primary, --spacing-md, --border-radius-sm). Компоненты используют токены, а не захардкоженные значения. Это позволяет поддерживать несколько тем или вносить изменения в дизайн централизованно.

Prop API как контракт. Каждый компонент имеет задокументированный набор props. Например, AppButton:

variant: 'primary' | 'secondary' | 'ghost'
size: 'sm' | 'md' | 'lg'
loading: boolean
disabled: boolean

Слоты для гибкости. Контент компонентов передаётся через слоты, а не через строковые props. AppModal с named slots header, body, footer — каждый слот может принять любой контент.

Accessible by default. Каждый интерактивный компонент реализует базовую доступность: aria-label, управление фокусом в модальных окнах, keyboard navigation в dropdown.

Кейс: UI-kit для крупного интернет-магазина бытовой техники

Клиент — ритейлер с каталогом 25 000 SKU. Команда: 4 фронтенд-разработчика. Проблема: сайт разрабатывался 3 года разными командами, в CSS было 8 разных вариантов «кнопки» с немного разными стилями, 3 реализации модальных окон (одна на jQuery, одна на Bootstrap, одна кастомная), 2 варианта нотификаций.

Первый этап — аудит: собрали все уникальные UI-элементы со всего сайта. Получили список из 47 типов элементов, которые нужно унифицировать.

Второй этап — проектирование: совместно с дизайнером зафиксировали дизайн-систему (токены, компонентный состав, варианты и состояния каждого компонента).

Третий этап — разработка библиотеки: написали 24 Vue-компонента, покрывающих все выявленные UI-элементы.

Ключевые компоненты:

• AppButton — 3 варианта, 3 размера, состояния loading/disabled
• AppInput / AppSelect / AppCheckbox / AppRadio — базовые элементы форм
• AppModal — управление фокусом, закрытие по Escape и клику вне
• AppToast — уведомления через composable useToast()
• AppDropdown — выпадающее меню с keyboard navigation
• AppPagination — компонент пагинации, заменил 3 кастомные реализации
• AppLoader — spinner и skeleton-экраны

Четвёртый этап — миграция: постепенно заменяли старые реализации на компоненты из kit. Начали с новых шаблонов, затем переписали самые «грязные» старые.

Результат: новые фичи разрабатываются быстрее — разработчик берёт готовый компонент, а не пишет свой. Дизайн-ревью занимает меньше времени — всё соответствует дизайн-системе.

Документация

UI-kit без документации — только источник вопросов. Для небольших проектов достаточно README с примерами для каждого компонента. Для больших — Storybook: интерактивная документация, где можно посмотреть все состояния компонента и скопировать пример использования.

Сроки

Разработка базового UI-kit (15–25 компонентов) — 3–5 недель: аудит существующего UI, проектирование дизайн-токенов, разработка компонентов, написание документации. Поддержка и расширение UI-kit — постоянный процесс по мере роста проекта.

Проекты на Битриксе часто страдают одной общей болезнью: кнопка в каталоге выглядит иначе, чем кнопка в блоге, модальное окно оформления заказа — третьим образом, а всплывающее сообщение об ошибке — четвёртым. Причина не в отсутствии дизайн-системы — иногда она есть. Причина в том, что каждый новый шаблон компонента Битрикса писался отдельным разработчиком с нуля, копируя CSS-классы «на глаз».

UI-kit на Vue.js — это библиотека переиспользуемых компонентов с единым визуальным языком, которая интегрируется в Битрикс-проект и используется в разных частях сайта.

Зачем UI-kit именно на Vue.js, а не просто CSS

Чисто CSS-библиотека решает задачу единообразного внешнего вида. Но не решает задачу единообразного поведения: поведение дропдауна, логика мультиселекта, анимации появления, обработка ошибок. Vue-компоненты инкапсулируют и внешний вид, и поведение.

Второй аргумент — возможность использовать компоненты в шаблонах Битрикса без сложных зависимостей. Vue 3 с Composition API позволяет создавать компоненты, которые легко встраиваются в любую точку HTML-страницы через createApp.

Структура UI-kit для Битрикс-проекта

Типовой набор компонентов:

Базовые:

• UiButton — кнопки всех типов (primary, secondary, ghost, danger, icon-only) с состояниями loading/disabled
• UiInput — текстовые поля с лейблами, подсказками, состояниями ошибки/успеха
• UiSelect — кастомный селект с поиском и мультивыбором
• UiCheckbox, UiRadio, UiToggle
• UiTextarea

Обратная связь:

• UiModal — управляемое модальное окно с порталом через Teleport
• UiToast — уведомления (success/error/warning/info), очередь
• UiAlert — встроенный блок предупреждения
• UiLoader — спиннеры и skeleton-экраны

Навигация и структура:

• UiTabs — переключение вкладок
• UiAccordion — аккордеон для FAQ, характеристик
• UiPagination — постраничная навигация (обёртка вокруг логики Битрикса)
• UiBreadcrumb — хлебные крошки

Специфичные для e-commerce:

• UiProductCard — карточка товара с событиями добавления в корзину
• UiQuantityInput — счётчик количества товара
• UiRating — звёздный рейтинг
• UiGallery — фотогалерея с zoom и swipe

Интеграция с шаблонами Битрикса

Компоненты UI-kit используются в шаблонах Битрикс-компонентов двумя способами:

Монтирование отдельных компонентов. Для каждого Vue-компонента на странице:

// В шаблоне компонента Битрикса:
import { createApp } from 'vue'
import UiModal from '@/ui-kit/UiModal.vue'

createApp(UiModal, {
  title: 'Заказать звонок',
  onClose: () => console.log('closed')
}).mount('#modal-container')

Единое Vue-приложение на страницу. Для страниц с большим количеством интерактивных элементов (корзина, каталог с фильтром) монтируем одно приложение, которое включает нужные компоненты UI-kit.

Токены дизайна и CSS-переменные

UI-kit не должен содержать хардкод цветов и отступов. Все визуальные параметры — через CSS custom properties:

:root {
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-danger: #dc2626;
  --radius-button: 6px;
  --shadow-modal: 0 20px 60px rgba(0,0,0,.2);
}

Эти переменные задаются один раз в variables.css и переопределяются для конкретного проекта без изменения компонентов. Смена цветовой темы = смена переменных.

Документация и storybook

UI-kit без документации — неполный инструмент. Минимальная документация: для каждого компонента фиксируем props, events, slots и примеры использования.

Для крупных проектов — Storybook. Позволяет разработчику видеть все компоненты в разных состояниях без запуска сайта, дизайнеру — сверять с макетом. Для Битрикс-проектов Storybook запускается как отдельная dev-среда, не зависящая от PHP.

Кейс: UI-kit для федерального ритейлера

Клиент — торговая сеть, сайт на Битрикс «Энтерпрайз», 3 разработчика в команде. Проблема: за 4 года разработки накопилось 12 вариантов кнопки, 6 вариантов попапа, 4 варианта формы обратной связи — каждый написан отдельно. Новый разработчик не знал, что переиспользовать, и писал ещё один вариант.

Задача: создать UI-kit и задокументировать компоненты так, чтобы разработчик использовал готовое, а не писал с нуля.

Работа:

1. Аудит существующих компонентов: инвентаризация всех вариантов UI-элементов на сайте.
2. Дизайн-ревизия: совместно с дизайнером определили «каноничный» вид каждого элемента.
3. Разработка 24 компонентов Vue 3 с Composition API: базовые + e-commerce-специфичные.
4. CSS-переменные: 40 токенов дизайна для цветов, отступов, радиусов, теней.
5. Storybook с 80+ историями — каждый компонент в каждом состоянии.
6. Документация в Confluence: props, events, примеры кода.
7. Рефакторинг: заменили 3 наиболее критичных шаблона Битрикса на использование UI-kit.

Срок разработки: 6 недель. После запуска скорость разработки нового функционала выросла, количество визуальных расхождений в новых фичах упало до нуля.

Сроки

Базовый UI-kit (15–20 компонентов, документация, CSS-токены) — 4–6 недель. Полный UI-kit для крупного e-commerce-проекта (30–50 компонентов, Storybook, документация) — 8–14 недель.