@weksik/ui-lib

Библиотека токенов, темы и React-компонентов на чистом CSS (React 19, Ark UI, ESM-only, MIT).

React component library with design tokens and a theme, built on Ark UI and plain CSS.

• Storybook: ссылка появится после развёртывания.
• Репозиторий: https://github.com/w3k5/ui-lib

Установка

pnpm add @weksik/ui-lib react react-dom lucide-react

react, react-dom (19) и lucide-react — peer-зависимости, их ставит приложение.

Стили

Подключите стили один раз в точке входа приложения. Есть два варианта.

Всё сразу — styles.css: токены, базовые стили, общие примитивы и CSS всех компонентов.

import '@weksik/ui-lib/styles.css';

По компонентам — core.css (токены, reset, базовые стили, общие примитивы полей, списков и скримов) плюс CSS только тех компонентов, которые используются. Каждый компонент доступен отдельным подпутём — JS и CSS:

import '@weksik/ui-lib/core.css';
import '@weksik/ui-lib/button.css';
import '@weksik/ui-lib/dialog.css';

import { Button } from '@weksik/ui-lib/button';
import { Dialog } from '@weksik/ui-lib/dialog';

Имя подпути — kebab-case от имени компонента: IconButton → @weksik/ui-lib/icon-button и @weksik/ui-lib/icon-button.css. CSS компонента сам приносит стили компонентов, которые он рендерит (например, password-input.css — стили Input и IconButton), отдельно их подключать не нужно. Все компоненты также экспортируются из корня: import { Button } from '@weksik/ui-lib'.

Стили лежат в каскадных слоях @layer wk.reset, wk.tokens, wk.base, wk.components. Обычный (неслоёный) CSS приложения побеждает их без !important. Классы библиотеки начинаются с wk-.

Шрифты

import '@weksik/ui-lib/fonts.css';

IBM Plex Sans и IBM Plex Mono (латиница, кириллица, latin-ext) и фолбэк-гарнитуры с подогнанными метриками на время загрузки. Подключение необязательно: без него текст набирается системными шрифтами из стека токенов.

Тема

Светлая, тёмная и системная тема. Атрибут data-theme ставится на <html>, вместе с ним обновляется <meta name="theme-color">.

Чтобы тема применялась до загрузки бандла (без вспышки светлого фона), вставьте результат getThemeScript() инлайн-скриптом в <head> — при серверном рендере или при сборке HTML:

import { getThemeScript } from '@weksik/ui-lib';

<head>
  <script dangerouslySetInnerHTML={{ __html: getThemeScript() }} />
</head>;

В приложении — контроллер темы:

import { theme } from '@weksik/ui-lib';

theme.init(); // применяет сохранённый выбор и следит за системной темой
theme.set('dark'); // 'light' | 'dark' | 'system'
theme.get(); // текущий выбор

theme — контроллер по умолчанию (ключ localStorage — wk.theme). Свой ключ — createThemeController({ storageKey: 'app.theme' }); тот же ключ передайте в getThemeScript({ storageKey: 'app.theme' }). Готовый переключатель — компонент ThemeToggle.

Вложенный элемент с data-theme="dark" или data-theme="light" сам задаёт цвета и фон своей области.

Уведомления

Хранилище тостов создаётся один раз на уровне модуля, Toaster рендерится один раз в корне приложения:

// toaster.ts
import { createToaster } from '@weksik/ui-lib';

export const toaster = createToaster();

// App.tsx
import { Toaster } from '@weksik/ui-lib';
import { toaster } from './toaster';

export function App() {
  return (
    <>
      {/* … */}
      <Toaster toaster={toaster} aria-label="Уведомления" closeLabel="Закрыть" />
    </>
  );
}

toaster.create({ title: 'Сохранено', type: 'success' }); // 'info' | 'success' | 'error'

Поля формы

Field даёт полю подпись, подсказку и текст ошибки и связывает их с полем (id, aria-describedby). Поле внутри — Input, Textarea, NumberInput, PasswordInput, Select, MultiSelect, Combobox, Checkbox, Switch, DateRangeField, DatePicker, DateRangePicker — получает их из контекста:

import { Field, Input } from '@weksik/ui-lib';

<Field label="Название" hint="До 80 символов" error={error} required>
  <Input name="title" />
</Field>;

Непустой error делает поле недопустимым (aria-invalid); disabled, required и readOnly у Field приходят на поле.

Тексты в компонентах (подписи кнопок, сообщения) передаются только пропсами: встроенных строк нет, язык интерфейса выбирает приложение.

Для агентов (LLM)

В пакете лежат контракты для агентов, сгенерированные из исходников этой версии:

• node_modules/@weksik/ui-lib/llms.txt — список компонентов с подпутями и подключение;
• node_modules/@weksik/ui-lib/llms-full.txt — пропсы из TS-типов и JSDoc, примеры из stories, токены и правила дизайна.

Для Claude Code есть скилл с этими правилами:

claude plugin marketplace add w3k5/ui-lib
claude plugin install weksik-ui-lib@weksik-ui-lib

Сниппет для CLAUDE.md (или AGENTS.md) проекта:

## UI

- Интерфейс — на `@weksik/ui-lib`. Перед использованием компонента читай его раздел в
  `node_modules/@weksik/ui-lib/llms-full.txt` (пропсы, примеры); не пиши API по памяти.
- Только обычный CSS и токены `--wk-*`; Tailwind и CSS-in-JS не использовать. Классы `wk-*` не
  переопределять: неслоёный CSS приложения и так сильнее слоёв библиотеки.
- Строки интерфейса (подписи, `aria-label`) передаются пропсами; поля формы — внутри `Field`.

Версии

Пакет в версии 0.x: API ещё меняется. До 1.0 несовместимые изменения выходят в minor-версиях (0.2.0 → 0.3.0), patch-версии совместимы. Фиксируйте диапазон ~0.x.y или точную версию и читайте CHANGELOG перед обновлением minor.