AI DIAL UI Kit
The AI DIAL UI Kit is an production-ready React component library designed to streamline your development process. It features a collection of base components, such as Buttons, Inputs, Dropdowns, and more — allowing you to effortlessly reuse elements, quick and easy.
Table of Contents
- ✨ Highlights
- 📖 Documentation
- 🚀 Quick Start
- Development
- 🎨 Theming & Customization
- ♿ Accessibility
- 📖 Storybook
- 🚀 Usage in Projects
- 🤖 AI Agent MCP Server
- 🤝 Contributing
- 🔒 Security
- 📄 License
- 🌟 Related Projects
✨ Highlights
- 🎨 Unified User Experience: Ui Kit usage helps with design consistency across AI DIAL applications
- ⚡ Modern Stack: Built with latest React, TypeScript, Vite, and Tailwind CSS
- 🎨 Highly Customizable: Deep theming capabilities with CSS custom properties
- 🧪 Well-Tested: Comprehensive test coverage (70%+) with Vitest and React Testing Library
- 📚 Storybook Ready: Includes interactive component documentation and development playground
- 🛠️ Developer Experience: Leverage ESLint and Prettier for maintainable code quality
- 📦 Distribution Ready: Deployed as NPM package ready for easy integration
📖 Documentation
Explore our components and their usage in our interactive Storybook documentation.
🚀 Quick Start
Prerequisites
- Node.js >= 22.2.0
- npm >= 10.7.0
Installation
npm install @epam/ai-dial-ui-kit
Basic Usage
import { DialPrimaryButton } from '@epam/ai-dial-ui-kit';
import '@epam/ai-dial-ui-kit/styles.css';
function App() {
return (
<div>
<DialPrimaryButton onClick={() => alert('Hello AI DIAL!')} />
</div>
);
}
Optional: Markdown Components CSS
If you're using the MarkdownEditor (loaded through LazyMarkdownEditor), you need to import the required CSS files globally in your application (e.g., in your root layout or main entry point):
import '@uiw/react-markdown-preview/markdown.css';
import '@uiw/react-md-editor/markdown-editor.css';
This ensures the CSS is loaded once per application rather than being bundled with each component instance, reducing bundle size.
Development
Controlled dropdown menus
ButtonDropdown accepts controlled open / onOpenChange or an uncontrolled
defaultOpen. Its dropdownProps forwards search, placement and menu sizing
options to Dropdown. Set iconAfter={null} for an icon-only trigger; otherwise
the default chevron follows the effective open state.
DropdownItem.subMenuOpen and onSubMenuOpenChange let a host retain the active
submenu across presentation changes. Omitting them preserves the default
uncontrolled behavior. An already-open submenu restores focus on mount, and the
kit owns arrow navigation, RTL placement, Escape and focus return. renderSubMenu
can provide custom content without placeholder children. Leaf items forward
iconAfter as trailing content alongside the existing disabled/danger states.
Prerequisites
- Node.js >= 22.2.0
- npm >= 10.7.0
- Git
Development Setup
-
Clone the repo
git clone https://github.com/epam/ai-dial-ui-kit.git cd ai-dial-ui-kit -
Install Dependencies
npm install -
Start Development Environment
# Start Storybook for component development npm run storybook # Run tests in watch mode npm run test -- --watch # Start Vite dev server npm run dev
Running Tests
# Run all tests with coverage
npm run test
Project Structure
src/
├── components/ # React components
│ ├── Button/ # Example component
│ │ ├── Button.tsx
│ │ ├── Button.spec.tsx
│ │ └── Button.stories.tsx
│ └── ...
├── styles/ # Global styles and Tailwind configuration
│ ├── buttons.scss
│ ├── typography.scss
│ └── tailwind-entry.scss
├── types/ # TypeScript type definitions
└── index.ts # Main entry point
🎨 Theming & Customization
The library uses CSS custom properties for comprehensive theming. Override these variables to match your brand:
:root {
/* Background layers */
--bg-layer-0: #000000;
--bg-layer-1: #0C101D;
--bg-layer-2: #171B21;
/* Text colors */
--text-primary: ##EEF1F7;
--text-secondary: #9CA3AF;
--text-tertiary: #6B7280;
...
}
Full list of variables is available here
Corner radii of the 2.0 controls are themable the same way. Each defaults to the fully rounded pill the buttons ship with, so setting nothing keeps the stock look:
:root {
--radius-control: 12px; /* Button at standard and large size */
--radius-control-small: 8px; /* Button at ElementSize.Small */
--radius-control-icon: 9999px; /* IconButton, ToggleIconButton — any size */
}
Labelled and icon-only buttons read separate variables on purpose: a design that wants squarer action buttons usually still wants its icon buttons round.
These are defaults, not overrides: a rounded-* utility passed to a single
control through className still wins, because a consumer's utilities are
emitted after this package's stylesheet.
Overlay stacking
Overlays render in a portal at the end of <body>, so they stack against the
host's own fixed and sticky chrome — a header, a side sheet, an embedding
overlay. They sit on a four-step ladder driven by one variable:
| Layer | Utility | z-index | Components |
|---|---|---|---|
| Popup | z-popup | var(--z-overlay, 52) | Popup backdrop, both generations |
| Floating panel | z-floating | --z-overlay + 1 | Dropdown and Select overlays, submenus, Calendar |
| Interactive panel | z-interactive-tooltip | --z-overlay + 2 | InteractiveTooltip |
| Tooltip | z-tooltip | --z-overlay + 3 | Tooltip, both generations |
To lift every overlay above a host layer, set the base once:
:root {
--z-overlay: 1000; /* popup 1000, dropdown 1001, interactive tooltip 1002, tooltip 1003 */
}
Each layer is a fixed step above the one below, so raising the base never
reorders them: a dropdown still opens above the popup it sits in, and a tooltip
above the dropdown row that triggered it. Set the variable on :root, or in the
class a ThemeScope re-applies to its portalled overlays — a portal escapes any
other wrapper, so a value set only there never reaches the overlay.
A single overlay can still be moved on its own: a z-* utility passed to a
Dropdown's listClassName, a Popup's overlayClassName, an
InteractiveTooltip's contentClassName or a Calendar's panelClassName
replaces the layer's own step rather than landing beside it, because
mergeClasses knows the ladder utilities are z-index.
Public class names
Some hosts need to restyle a part of a component the props do not reach — the
padding of a menu's row list, the radius of a row, the caret badge of an icon
trigger. The kit's own classes are Tailwind utilities and hashed module locals,
so a host that reaches for them ends up on selectors that break on the next
upgrade: [class*='_selectedItem_'], > div:nth-child(2) > button,
[role='none'][aria-label='dropdown'] — the last of which is an accessibility
contract and, being a plain English string, is not one a localised host can rely
on either.
Every design-system 2.0 component therefore stamps a stable class on the element that draws it. They are exported as one record:
import { DIAL_KIT_CLASS } from '@epam/ai-dial-ui-kit';
DIAL_KIT_CLASS.menuItem; // 'dial-kit-menuitem'
.dial-kit-dropdown-list {
padding-block: 0;
}
.dial-kit-menuitem {
border-radius: 8px;
}
Nothing in dist/index.css selects on them: they carry no declarations of their
own and exist only as selectors, so a host's rule needs no !important it would
not otherwise need. Renaming one, or moving it to a different element, is a
breaking change and goes through the migration-guide process.
Feedback and status
| Key | Class | Element |
|---|---|---|
spinner | dial-kit-spinner | The role="status" root of a Spinner |
progressBar | dial-kit-progress-bar | The outermost element of a ProgressBar — its wrapper, or the track when it has neither label nor readout |
skeleton | dial-kit-skeleton | The root of a Skeleton |
notification | dial-kit-notification | The Notification surface, including every toast and section-message wrapper |
noDataContent | dial-kit-no-data-content | The empty-state root of NoDataContent |
loginScreen | dial-kit-login-screen | The section root of a LoginScreen |
stateScreen | dial-kit-state-screen | The section root of a StateScreen |
liveRegion | dial-kit-live-region | The always-mounted wrapper of a LiveRegion, or of an announced CaptionText / ErrorText |
transferQueue | dial-kit-transfer-queue | The role="status" panel of a TransferQueue: header, rows and aggregate bar |
Text
| Key | Class | Element |
|---|---|---|
highlight | dial-kit-highlight | The text element of a Highlight |
captionText | dial-kit-caption-text | The caption line under a field |
errorText | dial-kit-error-text | A caption in its error variant, additive to captionText |
label | dial-kit-label | The Label root, wrapping its label element and its info button |
labelledText | dial-kit-labelled-text | The root of a LabelledText, wrapping its caption and value |
Containers
| Key | Class | Element |
|---|---|---|
steps | dial-kit-steps | The ol root of a Steps |
cardShell | dial-kit-card-shell | The article element of a CardShell |
analyticsCard | dial-kit-analytics-card | The root of an AnalyticsCard |
analyticsBar | dial-kit-analytics-bar | The root of an AnalyticsBar, stacked or inline |
analyticsBarGroup | dial-kit-analytics-bar-group | The root of an AnalyticsBarGroup, which is its accordion |
analyticsHistogram | dial-kit-analytics-histogram | The root of an AnalyticsHistogram |
collapsibleSidebar | dial-kit-collapsible-sidebar | The aside element of a CollapsibleSidebar |
resizableContainer | dial-kit-resizable-container | The content box inside a ResizableContainer's resize frame |
resizeHandle | dial-kit-resize-handle | The role="separator" element of a ResizeHandle |
popup | dial-kit-popup | The role="dialog" panel of a Popup |
bottomSheet | dial-kit-bottom-sheet | The role="dialog" panel of a BottomSheet |
bottomSheetOverlay | dial-kit-bottom-sheet-overlay | The backdrop of a BottomSheet, which holds the panel |
sideDrawer | dial-kit-side-drawer | The role="dialog" panel of a SideDrawer, open or closed |
confirmationPopup | dial-kit-confirmation-popup | A ConfirmationPopup's panel, additive to popup |
accordion | dial-kit-accordion | The root of an Accordion |
folderPath | dial-kit-folder-path | The breadcrumb root of a FolderPath |
breadcrumbs | dial-kit-breadcrumbs | The nav element of a Breadcrumbs trail |
breadcrumbsItem | dial-kit-breadcrumbs-item | One segment of it: the link, button or span that draws the label |
Menus and overlays
| Key | Class | Element |
|---|---|---|
dropdown | dial-kit-dropdown | The trigger wrapper of a Dropdown |
dropdownList | dial-kit-dropdown-list | The role="none" item list inside a dropdown overlay, and a submenu's own list. Both generations |
dropdownSearch | dial-kit-dropdown-search | The search row above the item list of a searchable Dropdown |
menuItem | dial-kit-menuitem | One overlay row: a dropdown item, a Select option, a submenu trigger or child |
menuItemCheck | dial-kit-menuitem-check | The trailing check of a chosen MenuItemMark.Check row |
tooltip | dial-kit-tooltip | The bubble of a Tooltip |
interactiveTooltip | dial-kit-interactive-tooltip | The panel of an InteractiveTooltip |
ellipsisTooltip | dial-kit-ellipsis-tooltip | The text element of an EllipsisTooltip, which is also its trigger |
Fields
| Key | Class | Element |
|---|---|---|
search | dial-kit-search | The Search field box, additive to dial-kit-input |
passwordInput | dial-kit-password-input | The PasswordInput field box, additive to dial-kit-input |
numberInput | dial-kit-number-input | The NumberInput field box, additive to dial-kit-input |
tagInput | dial-kit-tag-input | The TagInput field box, additive to dial-kit-input |
autocompleteTagInput | dial-kit-autocomplete-tag-input | The AutocompleteTagInput field box, additive to dial-kit-input |
select | dial-kit-select | The root of a Select |
inlineSelect | dial-kit-inline-select | The trigger button of an InlineSelect |
calendar | dial-kit-calendar | The root of a Calendar, in every mode |
schemaRenderer | dial-kit-schema-renderer | The root of a SchemaRenderer |
schemaRendererSection | dial-kit-schema-renderer-section | One collapsible SchemaRenderer section card, at any depth |
fileDropzone | dial-kit-file-dropzone | The drop area of a FileDropzone |
fileIcon | dial-kit-file-icon | The root of a FileIcon: glyph or spinner, and the shared badge |
fileName | dial-kit-file-name | The row of a FileName: its type icon, the name and any details |
folderName | dial-kit-folder-name | The FileName row of a FolderName, additive to fileName |
sharedEntityIndicator | dial-kit-shared-entity-indicator | The badge of a SharedEntityIndicator, including the one on a FileIcon |
badge | dial-kit-badge | The root of a Badge: the label box, with its icon when it has one |
avatar | dial-kit-avatar | The root of an Avatar: the image, or the initials box that replaces it |
entityIdentity | dial-kit-entity-identity | The root row of an EntityIdentity: icon, type label, name and version |
selectedEntityCard | dial-kit-selected-entity-card | The bordered card of a SelectedEntityCard, not the wrapper that also holds its error |
formSection | dial-kit-form-section | The section root of a FormSection: heading row, description and content |
radioGroupPopupField | dial-kit-radio-group-popup-field | The root of a RadioGroupPopupField |
Controls
| Key | Class | Element |
|---|---|---|
switch | dial-kit-switch | The row of a Switch: the control and its label |
checkbox | dial-kit-checkbox | The row of a Checkbox |
checkboxBox | dial-kit-checkbox-box | The decorative box a CheckboxBox draws |
radio | dial-kit-radio | The row of a Radio |
radioGroup | dial-kit-radio-group | The root of a RadioGroup |
segmentedControl | dial-kit-segmented-control | The role="radiogroup" track of a SegmentedControl |
segmentedControlItem | dial-kit-segmented-control-item | One segment of it |
tabs | dial-kit-tabs | The outermost element of a Tabs — the heading wrapper, or the tab list when there is no sectionLabel |
tabList | dial-kit-tab-list | The role="tablist" inside it, in either orientation |
tab | dial-kit-tab | One tab inside it |
tabSelected | dial-kit-tab-selected | The selected tab, in either orientation |
tabsSectionLabel | dial-kit-tabs-section-label | The sectionLabel heading above a Tabs |
tag | dial-kit-tag | A Tag pill, including a TagInput's rows |
filterChips | dial-kit-filter-chips | The role="group" row of a FilterChips; its chips carry dial-kit-tag |
toggleIconButton | dial-kit-toggle-icon-button | A ToggleIconButton, additive to dial-kit-base-icon-button |
toggleChip | dial-kit-toggle-chip | The <button aria-pressed> of a ToggleChip |
closeButton | dial-kit-close-button | A CloseButton, additive to dial-kit-base-icon-button |
infoButton | dial-kit-info-button | An InfoButton, additive to dial-kit-base-icon-button |
buttonDropdown | dial-kit-button-dropdown | The wrapper of a ButtonDropdown |
Components with no entry, and why
Some 2.0 components are deliberately absent, because the element a host would target already carries a stable class:
| Component | Target it already |
|---|---|
Button and its six variant wrappers | dial-kit-base-button (plus a per-variant class such as dial-kit-primary-solid-button) |
IconButton and its five variant wrappers | dial-kit-base-icon-button |
FabButton | dial-kit-fab-button |
Input | dial-kit-input |
Textarea | dial-kit-textarea |
Slider | dial-kit-slider |
MarkdownEditor | dial-kit-markdown-editor |
Grid | dial-kit-grid (exported as GRID_ROOT_CLASS) |
Five more contribute no element of their own, and are addressed through what
they render: ThemeScope (a display: contents wrapper), MultiSelectTags
(Tags), TooltipContainer / TooltipTrigger, and ErrorBoundary (its
LiveRegion and fallback StateScreen).
Two neighbouring elements are reached through props instead, and keep being: a
Dropdown's floating panel takes listClassName, and a Popup's backdrop
takes overlayClassName.
♿ Accessibility
Naming icon-only controls
DialFabButton, DialIconButton, and IconButton render no text, so they need an
explicit accessible name. Pass aria-label; if you pass only a string
tooltipProps.tooltip, it is used as the label instead. Do not rely on the tooltip
alone to convey the name — a tooltip's aria-describedby lands on a wrapper element
rather than on the control, and tooltips are suppressed entirely on mobile.
InfoButton names itself from caption for the same reason. Pass a short
aria-label when the caption is a full sentence, so the name stays scannable.
Target size (WCAG 2.5.5, Level AAA)
Standard-size buttons render at 40×40 but expose a 44×44 pointer target via the
dial-kit-enhanced-target utility, which grows the target with a transparent
pseudo-element. The visible control is unchanged, so layouts keep their existing
metrics. WCAG 2.5.5 measures the region that accepts a pointer action, not the
visible decoration.
A control too small for a 44px target to clear its neighbours uses
dial-kit-minimum-target instead, which applies the same pseudo-element at the
Level AA minimum of 24×24 (WCAG 2.5.8).
These controls are documented exceptions and meet Level AA (2.5.8, 24×24) but not AAA:
| Control | Size | Why it is excluded |
|---|---|---|
ElementSize.Small variants | 24×24 | A 44px target overhangs 10px per side and would overlap adjacent controls in dense toolbars |
ButtonAppearance.Link | content | Exempt under the 2.5.5 Inline exception; expanding it would overlap surrounding copy |
DialCloseButton | icon-sized | Renders h-auto w-auto, so its target follows the caller's icon size |
DialInfoButton, InfoButton | 24×24 | Fixed small affordance, same overlap constraint as small variants |
Standard 2.0 fields (Input, Select, RadioGroupPopupField) | 40px tall | The pointer target spans the full field width but stays 4px short of 44 vertically; the height is a shared form design token, not a per-control choice. .dial-kit-input clips its overflow, so the pseudo-element cannot grow the target either |
Tag remove button | 16×16 rendered | Reaches 24×24 through dial-kit-minimum-target; a 44px target would overhang 14px per side and swallow the neighbouring tags of a TagInput row |
Clickable Tag | 32px tall | A 44px target would overhang 6px per side and swallow the neighbouring chips of a filter row; the tag is already wider than 24px on both axes |
ToggleChip | 32px tall | Same pill as a clickable Tag: a 44px target would overhang 6px per side and swallow the neighbouring chips of a toggle row; the chip is already wider than 24px on both axes |
Radio circle | 20×20 rendered | Reaches 24×24 through dial-kit-minimum-target; a 44px target would overhang 12px per side and swallow the adjacent label. Clicking the label selects the radio, so the practical target is wider |
Checkbox box | 20×20 rendered | Reaches 24×24 through dial-kit-minimum-target; a 44px target would overhang 12px per side and swallow the adjacent label. Clicking the label toggles the checkbox, so the practical target is wider |
Slider track row | 24px tall | The pointer target spans the full track width but is only 24px tall; a 44px row would add 20px of dead space to every form the slider sits in, and the thumb is dragged rather than tapped |
Breadcrumbs segment link | content | Exempt under the 2.5.5 Inline exception — a segment is a text link in a line of text, and expanding it would overlap the segments beside it |
Breadcrumbs overflow button | 16×16 rendered | Reaches 24×24 through dial-kit-minimum-target; a 44px target would overhang 14px per side and swallow the segments on either side of it in an inline trail |
SegmentedControl segment | 32px tall | Sits 4px from its neighbours inside a 40px track, so a 44px target would overhang 6px per side and swallow the adjacent segments; the segment is already wider than 24px on both axes |
ResizeHandle | 8px wide pointer strip | The handle has to sit exactly on the panel boundary, so a 44px-wide strip would swallow content on both sides of it — essential to the control. It is a focusable separator, so the resize is also available from the keyboard with the arrow keys |
ResizableContainer resize handle | 10px wide pointer strip | The handle has to sit exactly on the panel boundary, so a 44px-wide strip would swallow content on both sides of it — essential to the control. It is a focusable separator, so the resize is also available from the keyboard with the arrow keys |
Give small-variant controls at least 20px of surrounding space if you need to reach AAA in a specific layout, or use the standard size instead.
📖 Storybook
Storybook is a handy library for documenting and developing of UI components.
Stories
To run fully interactive storybook:
Development mode
npm run storybook
# Open http://localhost:6006
Production Build
npm run build-storybook
Production start
npx http-server ./storybook-static
# Open http://127.0.0.1:8080/
Documents
To run documents only:
Development mode
npm run storybook-docs
# Open http://localhost:54800/
Production build
npm run build-storybook-docs
Production start
npx http-server ./storybook-static
# Open http://127.0.0.1:8080/
Storybook provides:
- 📖 Interactive component documentation
- 🎨 Visual testing playground
- ♿ Accessibility testing tools
- 📱 Responsive design testing
- 🎯 Component isolation
🚀 Usage in Projects
Next.js Integration
- Install the package. React is the only peer you have to supply — everything the kit renders with, it installs itself.
npm install @epam/ai-dial-ui-kit
npm install react react-dom
Add the editor package only if you use the Markdown editor
(LazyMarkdownEditor). It is an optional peer, so npm install stays quiet
without it, and the kit only reaches for it when the editor actually mounts:
npm install @uiw/react-md-editor
- Import style in the root layout of the project:
// app/layout.tsx
import "@epam/ai-dial-ui-kit/styles.css";
- Usage example
// app/page.tsx
"use client";
import { DialPrimaryButton } from "@epam/ai-dial-ui-kit";
export default function Home() {
return (
<div className="w-full h-full flex flex-col gap-3 items-center justify-center">
<h1>Test library</h1>
<DialPrimaryButton onClick={() => alert('Hello AI DIAL!')} />
</div>
);
}
Tree Shaking
Import only the components you need:
// ✅ Good - Tree shakable imports
import { DialPrimaryButton, DialInput } from '@epam/ai-dial-ui-kit';
import '@epam/ai-dial-ui-kit/styles.css'; // Import styles separately
// ❌ Avoid - Imports entire library
import * as UIKit from '@epam/ai-dial-ui-kit';
🤖 AI Agent MCP Server
The AI DIAL UI Kit includes a built-in MCP (Model Context Protocol) server that enables AI agents to discover components, types, hooks, and utilities programmatically. This allows AI assistants to generate accurate, type-safe component code without hallucination.
Component results are ranked generation 2.0 first — the current design system, exported without the Dial prefix — and each legacy Dial* component points at its 2.0 replacement, so agents land on the right component by default.
For setup, configuration, and detailed resources, see the MCP Server Guide.
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details on:
- Code style guidelines
- Testing requirements
- Pull request process
🔒 Security
If you discover a security vulnerability, please refer to our Security Policy.
📄 License
Apache 2.0 - see the LICENSE file for details.
🌟 Related Projects
- AI-DIAL - Entrypoint for all AI Dial projects
Made with ❤️ by EPAM Systems