Developing a Vue.js UI Kit for a 1C-Bitrix Project

Developing a Vue.js UI Kit for a 1C-Bitrix Project

On large Bitrix projects with a team of 3+ developers, the problem of interface inconsistency inevitably appears: buttons look different across different component templates, modal windows are implemented in three ways, dates are formatted in five variants. Every developer writes their own version because there is no shared standard.

A Vue.js UI kit is a library of reusable components that establishes a unified standard for the entire frontend of the project.

What a UI Kit Is and Why It Is Needed in a Bitrix Project

A UI kit is a set of base UI components with documentation: buttons, forms, notifications, modal windows, tables, icons, typography. Each component implements one visual/functional behavior and is used throughout the site via a unified API.

In the context of 1C-Bitrix this is especially relevant because a Bitrix site consists of dozens of component templates written independently. Without a UI kit, each template uses its own HTML structure and CSS classes for identical elements. With a UI kit — all templates use the same <AppButton>, <AppModal>, <AppAlert> components.

Architecture of a Vue UI Kit for Bitrix

Library structure:

/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 variables
│   └── index.js               // export of all components
├── dist/                      // compiled library
└── vite.config.js

Build mode. The UI kit is built in library mode via 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' } }
        }
    }
}

The result — ui-kit.umd.js and ui-kit.css, included globally in the site template, making components available to all Vue applications on the page.

Integration with the Bitrix template. In the site template's header.php:

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

Component Development Principles

Design tokens. All colors, spacing, fonts, and border radii are stored as CSS variables (--color-primary, --spacing-md, --border-radius-sm). Components use tokens, not hard-coded values. This allows supporting multiple themes or making design changes centrally.

Prop API as a contract. Each component has a documented set of props. For example, AppButton:

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

Slots for flexibility. Component content is passed via slots, not string props. AppModal with named slots header, body, footer — each slot can accept any content.

Accessible by default. Every interactive component implements basic accessibility: aria-label, focus management in modal windows, keyboard navigation in dropdowns.

Case Study: UI Kit for a Large Home Appliance Retailer

Client — a retailer with a catalog of 25,000 SKUs. Team: 4 frontend developers. Problem: the site had been developed over 3 years by different teams; CSS contained 8 different variants of "button" with slightly different styles, 3 modal window implementations (one in jQuery, one in Bootstrap, one custom), 2 notification variants.

First stage — audit: collected all unique UI elements from across the site. Generated a list of 47 element types requiring unification.

Second stage — design: jointly with the designer, formalized the design system (tokens, component composition, variants and states for each component).

Third stage — library development: wrote 24 Vue components covering all identified UI elements.

Key components:

• AppButton — 3 variants, 3 sizes, loading/disabled states
• AppInput / AppSelect / AppCheckbox / AppRadio — base form elements
• AppModal — focus management, close on Escape and click outside
• AppToast — notifications via useToast() composable
• AppDropdown — dropdown menu with keyboard navigation
• AppPagination — pagination component, replaced 3 custom implementations
• AppLoader — spinner and skeleton screens

Fourth stage — migration: gradually replaced old implementations with kit components. Started with new templates, then rewrote the most "messy" old ones.

Result: new features are developed faster — a developer picks a ready component rather than writing their own. Design reviews take less time — everything conforms to the design system.

Documentation

A UI kit without documentation is only a source of questions. For small projects, a README with examples for each component is sufficient. For larger ones — Storybook: interactive documentation where you can view all component states and copy usage examples.

Timeframes

Developing a base UI kit (15–25 components) — 3–5 weeks: auditing the existing UI, designing design tokens, developing components, writing documentation. Maintaining and extending the UI kit — an ongoing process as the project grows.

Bitrix projects often suffer from one common ailment: the button in the catalog looks different from the button in the blog, the checkout modal is styled a third way, and the error popup is a fourth. The cause is not the absence of a design system — sometimes it exists. The cause is that every new Bitrix component template was written by a separate developer from scratch, copying CSS classes by eye.

A Vue.js UI kit is a library of reusable components with a unified visual language that integrates into the Bitrix project and is used across different parts of the site.

Why a UI Kit in Vue.js Specifically, and Not Just CSS

A pure CSS library solves the problem of uniform appearance. But it does not solve the problem of uniform behavior: dropdown behavior, multi-select logic, appearance animations, error handling. Vue components encapsulate both appearance and behavior.

The second argument — the ability to use components in Bitrix templates without complex dependencies. Vue 3 with the Composition API allows creating components that are easily embedded at any point in an HTML page via createApp.

UI Kit Structure for a Bitrix Project

Typical set of components:

Base:

• UiButton — all button types (primary, secondary, ghost, danger, icon-only) with loading/disabled states
• UiInput — text fields with labels, hints, error/success states
• UiSelect — custom select with search and multi-select
• UiCheckbox, UiRadio, UiToggle
• UiTextarea

Feedback:

• UiModal — managed modal window with portal via Teleport
• UiToast — notifications (success/error/warning/info), queue
• UiAlert — inline warning block
• UiLoader — spinners and skeleton screens

Navigation and structure:

• UiTabs — tab switching
• UiAccordion — accordion for FAQ, specifications
• UiPagination — page navigation (wrapper around Bitrix logic)
• UiBreadcrumb — breadcrumbs

E-commerce specific:

• UiProductCard — product card with add-to-cart events
• UiQuantityInput — product quantity counter
• UiRating — star rating
• UiGallery — photo gallery with zoom and swipe

Integration with Bitrix Templates

UI kit components are used in Bitrix component templates in two ways:

Mounting individual components. For each Vue component on the page:

// In the Bitrix component template:
import { createApp } from 'vue'
import UiModal from '@/ui-kit/UiModal.vue'

createApp(UiModal, {
  title: 'Request a call',
  onClose: () => console.log('closed')
}).mount('#modal-container')

Single Vue application per page. For pages with many interactive elements (cart, catalog with filter) — mount one application that includes the required UI kit components.

Design Tokens and CSS Variables

The UI kit must not contain hard-coded colors and spacing. All visual parameters — via 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);
}

These variables are defined once in variables.css and overridden for a specific project without modifying components. Changing the color theme = changing the variables.

Documentation and Storybook

A UI kit without documentation is an incomplete tool. Minimum documentation: for each component, document props, events, slots, and usage examples.

For large projects — Storybook. Lets developers see all components in different states without running the site, and lets designers compare against mockups. For Bitrix projects, Storybook runs as a standalone dev environment independent of PHP.

Case Study: UI Kit for a Federal Retailer

Client — a retail chain, Bitrix Enterprise, 3 developers on the team. Problem: over 4 years of development, 12 button variants, 6 popup variants, and 4 contact form variants had accumulated — each written separately. A new developer did not know what to reuse and wrote yet another variant.

Task: create a UI kit and document the components so that a developer uses existing components rather than writing from scratch.

Work:

1. Audit of existing components: inventory of all UI element variants on the site.
2. Design revision: jointly with the designer, defined the "canonical" look for each element.
3. Development of 24 Vue 3 components with Composition API: base + e-commerce-specific.
4. CSS variables: 40 design tokens for colors, spacing, border radii, shadows.
5. Storybook with 80+ stories — each component in each state.
6. Documentation in Confluence: props, events, code examples.
7. Refactoring: replaced 3 most critical Bitrix templates to use the UI kit.

Development time: 6 weeks. After launch, the speed of new feature development increased, and the number of visual discrepancies in new features dropped to zero.

Timeframes

Base UI kit (15–20 components, documentation, CSS tokens) — 4–6 weeks. Full UI kit for a large e-commerce project (30–50 components, Storybook, documentation) — 8–14 weeks.