Домен: Web UI Kit

Назначение

• общий слой интерфейса: shadcn/ui поверх Base UI и Tailwind v4
• продуктово-нейтральные компоненты без знания API, роутера и предметной области
• одни и те же токены в приложении и в Storybook

Структура

• foundations/ — токены темы, ThemeProvider, общие утилиты. Не компоненты. tokens.css — единственный источник значений; styles.css (монорепо) и ../styles.package.css (npm-пакет) лишь подключают Tailwind поверх него и отличаются областью сканирования.
• primitives/ — компоненты реестра shadcn поверх Base UI: один элемент управления на файл (button, input, dialog, table, sidebar, …). Добавляются через shadcn add, а не вручную — иначе следующий апдейт реестра молча затрёт локальные правки.
• blocks/ — композиции примитивов под повторяющуюся задачу: dashboard/ (MetricCard, ChartCard, ProportionBar), data/ (DataTable, VirtualList, FilterBar, PropertyList, …), shell/ (AppShell, TopBar, SidebarNav, PageHeader, WizardLayout, Stepper), states/ (EmptyState, ErrorState, AsyncState, ConfirmDialog, StatusPill).
• stories/ — Storybook, структура повторяет слои: overview.stories.tsx, foundations/, primitives/, blocks/, compositions/. fixtures.ts — общие тестовые данные.

Root index.ts — стабильный публичный фасад @sellerai/web-ui-kit; продуктовый код импортирует только его, без глубоких путей внутрь библиотеки.

Границы

Правила проверяются линтером (eslint.ui-kit-boundaries.config.mjs):

• ui-kit не импортирует @sellerai/web-* — иначе общий слой становится продуктовым
• ui-kit не загружает данные: ни @sellerai/common-generated-api, ни @tanstack/react-query; блоки получают данные и колбэки пропсами
• продуктовый код импортирует фасад целиком, без @sellerai/web-ui-kit/<путь>
• строки самого ui-kit (a11y-подписи, дефолты кнопок диалогов) берутся из shared namespace common через react-i18next напрямую — зависеть от @sellerai/web-i18n нельзя
• feature-specific схемы, копирайт и бизнес-состояние в ui-kit не входят

Куда класть новый компонент

• один элемент управления из реестра shadcn → primitives/
• повторяющаяся связка примитивов, которую можно вставить в чужой продукт, поменяв только props → blocks/
• знает про API, роутер или конкретную фичу → это не ui-kit, ему место в feature-библиотеке

Storybook

• npx nx storybook web-storybook — dev server на порту 4400
• npx nx build-storybook web-storybook — статическая сборка
• npx nx typecheck web-storybook — типизация сторис и .storybook/ (обычные tsconfig приложения их не покрывают: сторис ничем не импортируются, поэтому без этой цели ошибка в них всплывает только при запуске Storybook)
• тулбар переключает светлую и тёмную тему через реальный ThemeProvider
• порядок разделов задан storySort в preview.tsx: Overview → Foundations → Primitives → Blocks → Compositions, от «что это вообще» к всё более собранному
• UI Kit/Overview — с чего начинать: слои, границы, куда класть новый компонент
• UI Kit/Foundations — цвета, типографика, отступы и радиусы; значения читаются из живых CSS-переменных, поэтому страница не расходится с foundations/styles.css

Публикация в npm

Кит публикуется как @sellerai/ui-kit, чтобы Figma Make собирал экраны из настоящих компонентов. Подробности и статус — .ai/changes/ui-kit-npm-figma-make/PLAN.md.

npm run ui-kit:publish               # проверить, собрать и опубликовать
npm run ui-kit:publish -- --dry-run  # только проверки, без публикации

Скрипт проверяет чистоту дерева, авторизацию, доступ к скоупу и занятость версии, пересобирает пакет из исходников и сверяет содержимое тарболла. Учётные данные он не трогает — нужен заранее выполненный npm login в том же окружении, где запускается скрипт.

Поднять версию заодно: npm run ui-kit:publish -- --version patch.

2FA обязательна

С 9 декабря 2025 npm не публикует пакет без одного из двух:

• 2FA на аккаунте (npmjs.com → Account → Two-Factor Authentication). npm предлагает passkey (WebAuthn): на Mac это Touch ID, отдельное приложение не нужно. Публикация тогда подтверждается в браузере, кода не будет. Если 2FA настроена приложением-аутентификатором, скрипт спросит одноразовый код; его можно передать сразу: -- --otp 123456.
• Granular access token с галкой «bypass 2FA» (npmjs.com → Access Tokens, скоуп @sellerai, Read and write). Работает сейчас, но npm его сворачивает: с августа 2026 такие токены лишены управляющих операций, с января 2027 потеряют и право публиковать. Для CI целевой вариант — trusted publishing через OIDC.

Без этого npm отдаёт 403 Two-factor authentication ... is required to publish packages.

Там же изменилось время жизни сессии: npm login выдаёт её на 2 часа, после чего npm whoami снова отвечает ENEEDAUTH и нужно войти заново.

Две вещи делаются руками один раз: организация sellerai на npmjs.org (https://www.npmjs.com/org/create, free-плана достаточно для публичных пакетов) и npm login.

Сборка без публикации — npx nx build web-ui-kit: dist/index.js, типы и предсобранный dist/styles.css. Потребителю Tailwind не нужен.