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

Требования к окружению

• Node.js >= 22.12 (сайт документации использует Astro 7, это жёсткое требование)
• pnpm 10.x (репозиторий зафиксирован на pnpm@10.34.5)

Установка

pnpm install

В этом репозитории нет зависимостей времени выполнения (dependencies пуст), всё установленное — это инструментарий сборки (tsx, ajv, handlebars, vitest, astro и т. д.).

Первый запуск codegen

pnpm codegen

Эта команда выполняет tsx codegen/src/index.ts; полный процесс:

1. Чтение версии из package.json
2. Загрузка и валидация tokens/*.json (структурная валидация Ajv)
3. Разрешение ref и слияние тёмной темы (семантическая валидация: соответствие типов, целостность ссылок, обнаружение циклов)
4. Загрузка и валидация specs/*.json и cases/*.json
5. Удаление всего dist/ и его пересоздание
6. Последовательное выполнение 5 target’ов (android → ios → harmony → c → docs)

Вывод в dist/:

  [android] android/top/lhgb/ui/tokens/LhTokens.kt
  [android] android/top/lhgb/ui/tokens/LhDarkTokens.kt
  ...
codegen завершён: 5 target'ов, N файлов, версия v0.0.1

Количество файлов зависит от содержимого токенов (при наличии токенов теней ios / harmony получают дополнительный файл-носитель тени), поэтому ориентируйтесь на фактический вывод.

Проверка

pnpm verify          # = pnpm verify:tokens && pnpm verify:specs

• verify:tokens: схема токенов + целостность ссылок + контрастность ключевого текста/фона >= 4.5:1 (WCAG AA) + инспекция платформо-специфичного синтаксиса (var() / rem / sp / dp), а также отчёт о путях-сиротах тёмной темы (ключах, объявленных в тёмном файле, но отсутствующих в светлой теме) и тёмных ключах без типа.
• verify:specs: согласованность specs и cases (существует ли prop / event, на которые ссылается case, в spec, и т. д.).

Тесты

pnpm test

Снапшот-тесты зеркалируют все артефакты dist/. После изменения токенов или шаблонов снапшоты упадут; убедившись, что всё верно, обновите их командой pnpm test -- -u.

Сайт документации

pnpm docs:dev        # Локальный предпросмотр http://localhost:5185/lhui/core/
pnpm docs:build      # Продакшен-сборка (base — /lhui/core/)
pnpm docs:preview    # Предпросмотр продакшен-сборки

Три справочные страницы сайта (токены / контракты / сценарии) на этапе сборки читают исходники tokens/, specs/, cases/ напрямую — запускать codegen предварительно не нужно.

Частые комбинации

Сценарий	Команда
Изменили токены, нужны артефакты	pnpm codegen
Изменили токены, нужны артефакты + проверка	pnpm build (= codegen + verify)
Изменили шаблоны, нужны артефакты + снапшоты	pnpm codegen && pnpm test -- -u
Только посмотреть таблицу токенов	После pnpm codegen открыть dist/docs/tokens.md

Где потребляются артефакты

Каждая нативная платформа потребляет артефакты своей платформы из dist/:

• Android: Kotlin-файлы в dist/android/
• iOS: Swift-файлы в dist/ios/
• HarmonyOS: ArkTS-файлы в dist/harmony/
• Windows: C#-файлы в dist/windows/

Механизм локальной линковки (мгновенное применение изменённых токенов без выпуска релиза) описан в Локальная линковка.