Дизайн система для продуктов Смарт-Сервиса

Навигация:

• Соглашения о комитах
• Именование веток
• Сборка пакета
• Алиасы
• Проверка пакета локально
• Публикация пакета
• Управление токенами
• Управление иконками
• Тестирование
• Быстрый старт для новых компонентов

Набор компонентов для использования в продуктах HubEx и myQrCards для приложений, написанных на React.

Соглашения о комитах

Для того, чтобы заполнять changelog необходимо пользоваться дополнительными ключевыми словами в тексте комита.

Например, если мы пофиксили баг в компоненте A:

git commit -m "fix: Пофиксил баг в компоненте A"

Будут полезны следующие ключевые слова:

• chore — изменение конфигурации, обновление зависимостей и так далее
• docs — изменения только в документации
• feat — новая функция, модуль и так далее
• fix — исправление ошибки
• refactor — изменение кода, которое не исправляет ошибку и не добавляет новую функцию
• test — добавление отсутствующих тестов или исправление существующих тестов

Правило для всех коммитов: сообщение должно строго соответствовать формату
<type>: <краткое описание>
где <type> — одно из ключевых слов выше. Пример: feat: добавлен компонент Tooltip. Любые другие форматы (без двоеточия, с несколькими типами, с произвольным текстом до типа и т.п.) запрещены.

Эти требования автоматически проверяет Husky commit-msg хук. Он устанавливается после npm install (скрипт npm run prepare запускает husky install). Если по какой-то причине хуки не сработали, выполните npm run prepare.

Именование веток

Используйте только строчные буквы (a-z), цифры и допустимые разделители (-, /, _). Примеры корректных названий: feat/tooltip, fix-input-placeholder.
Husky pre-commit хук запрещает заглавные буквы (например, bugFix, Bugfix). Чтобы обойти проблему, переименуйте ветку командой git branch -m <новое-имя> и повторите коммит.

Перед каждым коммитом автоматически запускается lint-staged: для JS/TS файлов выполняется eslint --fix и prettier --write, для остальных текстовых файлов — prettier --write. Поэтому после git add убедитесь, что форматирование корректно и изменения перезаписаны.

В секции scripts доступно 2 скрипта dryrealease и release.

Команду dryrelease удобно использовать в случае, когда вы еще не готовы поднимать версию пакета, но хотите проверить какие изменения войдут в релиз. После запуска этой команды в консоли будет выведен отчёт, схожий с тем, что вы получите после релиза.

Удостоверившись, что всё так, как нам нужно, мы можем выпустить релиз командой release.

В результате мы получим следующее:

• в package.json будет автоматически поднята версия до той, которая соответствует вашим правкам
• будет создан CHANGELOG.md, если его нет, а в его контент будут добавлены логи по коммитам с ключевыми словами (подобно тому, что мы видели в консоли после выполнения dryrelease).
• Все изменения будут закомичены и готовы к публикации.

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

Сборка пакета осуществляется командой npm build. Собранный пакет будет сохранен в папке dist в корне проекта.

Алиасы

• Все алиасы хранятся в alias.config.mjs (aliases, rollupAliasEntries).
• Rollup и Storybook читают их напрямую из этого файла.
• При изменении алиасов в alias.config.mjs не забудьте обновить вручную tsconfig.json (секция compilerOptions.paths).
• Основные пути: @ → src, @components → src/components, @icons → src/icons, @theme → src/theme.

Проверка пакета локально

Для проверки пакета локально, необходимо воспользоваться командой npm pack и поместить полученный файл в корень проекта, где необходимо его проверить.

Далее выполнить команду npm add file:./hubex-ds-1.0.0.tgz, обратить внимание на версию

Публикация пакета

Для публикации пакета необходимо воспользоватся командами npm login и npm publish

Конфигурация npm

- echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc

Если публикация пакета падает (401/403/404)

1. Проверь, что токен для npm актуальный (не отозван и не истёк).
2. При необходимости перевыпусти токен в npmjs.
3. Обнови токен в Azure DevOps: Pipelines → Library → Variable groups → HubEx.Frontend.DS → NPM_TOKEN.

Управление токенами

При обновлении токенов дизайн-системы дизайнерами, необходимо спулить изменения и выполнить скрипт npm run transform-tokens

Управление иконками

При обновлении иконок дизайнерами, необходимо выполнить скрипт npm run load-icons.

Если кто-то очень любопытный и залез глянуть код скрипта, то увидит странный массив iconsFramesIDs с только одной раскоменченноый строчкой. Объясняю это полный набор айдишников фреймов с иконками, но обновляется тольуо один (пока что). Менять ТОЛЬКО при согласовании с дизайнерами и техлидом фронта.

Тестирование

Дизайн-система использует комплексный подход к тестированию компонентов:

• Юнит-тесты (Jest) - для логики, хуков, хелперов
• Интерактивные тесты (Storybook Test Runner) - для взаимодействия пользователя с компонентами
• Визуальные тесты (Chromatic) - для обнаружения визуальных регрессий
• Тесты доступности (a11y) - для соответствия стандартам доступности

Быстрый старт

# Юнит-тесты
npm run test:unit              # Запуск всех юнит-тестов
npm run test:unit:watch        # Запуск в watch режиме
npm run test:unit:coverage     # С coverage отчетом

# Интерактивные тесты (требует запущенный Storybook)
npm run playwright:install     # Установить Playwright Chromium (нужно 1 раз / после очистки кеша)
npm run storybook              # Запустить Storybook в отдельном терминале
npm run test:interaction       # Запустить интерактивные тесты

# Тесты доступности
npm run test:a11y              # Запустить a11y тесты

# Все тесты
npm run test:all

Автоматический запуск

Все тесты автоматически запускаются перед git push через husky pre-push хук.

Пропуск тестов:

• Для экстренных случаев: git push --no-verify
• Для пропуска визуальных тестов: SKIP_VISUAL_TESTS=true git push

Документация

Подробная информация о стратегии тестирования и примерах:

• Стратегия тестирования
• Примеры тестов

Быстрый старт для новых компонентов

В репозитории есть общий промпт для генерации компонентов дизайн-системы: docs/component-prompt.md.
Как пользоваться:

1. Перед началом задачи открой docs/component-prompt.md и скопируй текст промпта.
2. Вставь его в Cursor (например, в Preset или System Instructions) и подставь реальные значения:
   • \[ComponentName] → имя компонента, например Tooltip;
   • \[Figma URL] → ссылка на соответствующий макет.
3. Включи этот пресет на время работы над компонентом. После завершения выключи, чтобы правило не влияло на другие задачи.

Промпт описывает обязательные файлы, требования к API, работу со стильными токенами, Storybook и a11y — его достаточно соблюдать, чтобы компонент был готов с первой попытки.