aikit

The Problem

Building an AI‑driven chat UI requires a consistent visual language, accessible components, and the ability to theme or extend without fighting the underlying framework. Teams often cobble together ad‑hoc widgets, which leads to duplicated code, inconsistent accessibility, and costly redesigns when the product’s branding changes.

What This Does

@gravity-ui/aikit delivers a ready‑made, SDK‑agnostic React component library organized by Atomic Design. Core UI pieces live under src/components/atoms/ (e.g., ActionButton, Alert, ChatDate), while higher‑level composites are in molecules/, organisms/, templates/, and pages/. All components are written in TypeScript (.tsx/.ts files) and styled with SCSS that exposes CSS variables for theming (src/themes/). The library ships with Storybook (.storybook/), visual regression tests (Playwright fixtures in playwright/), and a registration system for custom message types (src/types/).

Key files that illustrate the architecture:

src/components/atoms/ActionButton/ActionButton.tsx – an atom with tooltip logic. src/components/pages/ChatContainer/index.tsx (implied by README) – the page‑level container that assembles atoms, molecules and hooks. src/hooks/useChat.ts (example hook location) – provides SDK‑agnostic state handling. src/themes/default.scss – defines the CSS variable palette used throughout the UI.

How To Use It

Install – the presence of package.json and npm scripts indicates an npm‑based workflow. npm ci # install exact versions from package-lock.json Run the component catalogue – Storybook is configured in .storybook/main.ts. npm run storybook # launches http://localhost:6006 Run the test suite – Visual regression tests use Playwright; CI is defined in .github/workflows/ci.yml. npm test # executes jest + playwright tests Add the library to a project – import the top‑level container as shown in README.md. import { ChatContainer } from '@gravity-ui/aikit'; import type { ChatType, TChatMessage } from '@gravity-ui/aikit';

// …component code from README Theme customization – override any CSS variable defined in src/themes/.scss via a <style> block or a custom SCSS file imported before the library. No runtime configuration file is required; theming is purely CSS‑based.

No hidden environment variables or build scripts are required for basic usage; the library is a pure UI dependency.

Real‑World Use

A SaaS product that offers multiple AI assistants can embed ChatContainer in its dashboard. Each assistant is represented as a ChatType object; messages are stored in a centralized store (e.g., Redux). The UI automatically adapts to dark/light mode by swapping the CSS variable set defined in src/themes/default.scss. Custom message bubbles are added by registering a new type through the exported registerMessageComponent hook (found in src/utils/messageRegistry.ts).

import { registerMessageComponent } from '@gravity-ui/aikit'; import CustomMessage from './CustomMessage';

registerMessageComponent('custom', CustomMessage);

Code Health & Issues

Bugs / Risks – Low – All atoms have visual regression tests (tests/...visual.spec.tsx) and snapshots, reducing UI regressions. No obvious unsafe patterns detected. SDLC – Medium – CI pipelines (.github/workflows/.yml) run lint, unit, and Playwright tests, but the repo lacks a release script that publishes the package; publishing must be handled manually or via a separate workflow. Documentation – Low – Docs are comprehensive (docs/GETTING_STARTED.md, docs/ARCHITECTURE.md) and Storybook is published, but there is no explicit versioning guide for breaking changes. Dependencies – Low – package-lock.json is present, and linting (.eslintrc, .prettierrc.js) is enforced via Husky hooks, indicating good hygiene. No secrets or hard‑coded credentials are present. Test Coverage – Medium – 71 test files cover most atoms; however, higher‑level pages (e.g., ChatContainer) have limited visual tests, which could hide integration regressions.

Overall, the codebase follows a clear separation of concerns, and the testing/CI setup is solid.

The Bottom Line

@gravity-ui/aikit provides a well‑structured, TypeScript‑first UI kit for AI chat interfaces, with strong theming support and a mature testing pipeline. It is ready for integration in medium‑to‑large React applications that need a consistent, accessible chat UI. Small teams should verify that the higher‑level page components meet their specific workflow requirements, as test coverage there is lighter.