Розробка 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 тижнів.