@tk-kit/design-system

Дизайн-система проектов tk-kit: переиспользуемые UI-компоненты, хуки и утилиты, опубликованные как публичный npm-пакет на npmjs.com, Storybook для разработки и просмотра компонентов.

Стек

TypeScript, React 19, Vite, Tailwind CSS v4, shadcn/ui (Radix UI), Storybook, опубликовано на npmjs.com.

Установка зависимостей

pnpm install

При первом запуске может потребоваться подтвердить выполнение build-скриптов нативных зависимостей — это уже настроено в pnpm-workspace.yaml (allowBuilds), повторно подтверждать не нужно.

Структура проекта

design-system/
├── src/
│   ├── components/
│   │   ├── base/           # базовые UI-компоненты (Button, Input, Dialog...)
│   │   ├── form/            # компоненты для форм (TextField, FileUploadField...)
│   │   └── icons/            # иконки (генерируются автоматически, см. ниже)
│   ├── hooks/                # переиспользуемые хуки
│   ├── lib/                   # утилиты, zod-схемы
│   ├── styles/                # глобальные стили, токены, переменные Tailwind
│   └── index.ts               # публичная точка входа пакета — единственное
│                               # место, откуда что-либо доступно потребителям
├── scripts/
│   └── generate-icons-index.ts  # автогенерация index.ts для папки icons
├── .storybook/                  # конфигурация Storybook
├── vite.config.ts                # конфиг для Storybook/Vitest
├── vite.config.lib.ts             # конфиг для сборки библиотеки (lib mode)
└── pnpm-workspace.yaml             # разрешённые build-скрипты зависимостей

Как добавить новый компонент

1. Создай папку компонента внутри src/components/base/ (или src/components/form/, если это поле формы):

   src/components/base/my-component/
   ├── my-component.tsx
   ├── my-component.variants.ts   # если используется cva
   ├── my-component.stories.tsx
   └── index.ts

2. В index.ts папки компонента — именованный реэкспорт:

   export { MyComponent } from './my-component'
   export type { MyComponentProps } from './my-component'

3. Добавь экспорт в публичный src/index.ts — без этого шага компонент не попадёт в собранный пакет и будет недоступен в приложениях-потребителях:

   export { MyComponent, type MyComponentProps } from '@/components/base/my-component'

4. Напиши историю в my-component.stories.tsx, чтобы компонент был виден в Storybook со всеми вариантами (variant, size, disabled и т.д.).

5. Проверь визуально через Storybook (см. ниже), при необходимости — через pnpm link в тестовом приложении.

Как добавить иконку

1. Положи .tsx-файл иконки в src/components/icons/, имя файла в формате kebab-case, суффикс -icon (например arrow-up-icon.tsx).

2. Запусти автогенерацию реэкспортов:

   pnpm generate:icons

   Скрипт сам пересоберёт src/components/icons/index.ts со всеми иконками из папки. Файл генерируемый — руками не редактируется, перезапишется при следующей сборке.

   Запускается автоматически при pnpm build, отдельный запуск нужен только если хочешь сразу увидеть иконку в Storybook без полного билда.

Важные принципы дизайн-системы

• Дизайн-система не должна напрямую зависеть от инфраструктуры конкретного приложения (роутер, стейт-менеджер, HTTP-клиент). Если компоненту нужен роутинг — используется паттерн инверсии через проп as (см. компонент Link), а не прямой импорт react-router-dom.
• Библиотеки форматирования/работы с данными без привязки к окружению (date-fns, react-number-format, react-dropzone и т.п.) — можно использовать напрямую как обычные зависимости.
• Любой новый компонент обязан иметь .stories.tsx файл.
• Публичный API пакета — только то, что явно реэкспортировано в src/index.ts. Не используем широкие export * для компонентов (только для иконок и zod-схем, где это оправдано).

Запуск Storybook локально

pnpm storybook

Откроется на http://localhost:6006. Hot reload работает автоматически при изменении файлов компонентов и .stories.tsx.

Запуск Storybook через Docker (как на сервере)

docker compose build storybook
docker compose up storybook

Откроется на http://localhost:6006.

Сборка пакета (для публикации)

pnpm build

Генерирует иконки, прогоняет проверку типов, собирает dist/ (ESM + CJS + типы + стили) через vite.config.lib.ts.

Проверить итоговую сборку перед публикацией можно через:

pnpm pack

— создаст .tgz-архив, который можно установить в тестовое приложение командой pnpm add /путь/к/архиву.tgz и проверить вживую (стили, типы, импорты).

Публикация новой версии

Публикация происходит автоматически через GitLab CI, только при пуше git-тега — обычный пуш в main пакет не публикует (только обновляет Storybook).

Версию поднимаем командой npm version — она сама обновляет package.json, создаёт коммит и git-тег нужного формата (vX.Y.Z), вручную ничего не редактируем:

# 1. Закоммить изменения кода
git add .
git commit -m "feat: добавлен компонент MyComponent"

# 2. Поднять версию (сама создаст commit "vX.Y.Z" и git-тег vX.Y.Z)
npm version patch   # багфикс, без изменения API
# npm version minor  # новый компонент/хук, без breaking changes
# npm version major  # сломан/изменён публичный API

# 3. Запушить коммит и тег одной командой
git push --follow-tags

CI запускает job build-package только когда тег соответствует формату vX.Y.Z (например v0.2.0). Так как тег создаёт сам npm version, версия в package.json и имя тега всегда совпадают автоматически.

Если версия уже была опубликована — job упадёт с ошибкой E403/cannot publish over previously published version (npm registry не разрешает переопубликовать существующую версию). В этом случае просто поднимите версию ещё раз (npm version patch) и запушьте новый тег.

Правила версионирования:

| Что изменилось | Версия | |------------------------------------------|-----------------| | Новый компонент / хук, без breaking changes | minor (0.X.0) | | Багфикс, без изменения API | patch (0.0.X) | | Сломан/изменён публичный API компонента | major (X.0.0) |

Установка пакета в приложении-потребителе

Пакет публичный и опубликован на npmjs.com — никакой дополнительной авторизации для установки не требуется.

pnpm add @tk-kit/design-system

/* globals.css приложения */
@import 'tailwindcss';
@import 'tw-animate-css';
@import '@tk-kit/design-system/tokens.css';

@source "../../../node_modules/@tk-kit/design-system/dist";

import { Button, TextField } from '@tk-kit/design-system'

Для CI/CD — тоже ничего настраивать не нужно, обычный pnpm install подтянет пакет с публичного registry:

script:
  - pnpm install