Структура каталогов

lh-ui-core/
├── tokens/       Единый источник токенов дизайна (нейтральные JSON, со схемой)
├── specs/        Контракты компонентов (props / перечисления / значения по умолчанию / события / слоты / поведение)
├── cases/        Золотые сценарии (переводимые между платформами поведенческие утверждения)
├── codegen/      Инструментарий codegen (TS/Node): src/ + templates/
├── dist/         Артефакты codegen (генерируются при сборке, изменять вручную запрещено)
├── scripts/      Скрипты проверки и публикации
├── tests/        Снапшот-тесты и мета-тесты токенов
└── docs/         Исходный код сайта документации разработчика (Astro Starlight, этот сайт)

Назначение каталогов

tokens/ — единый источник токенов

Платформенно-нейтральные JSON-источники, формат которых строго задан tokens/schema.json. Всего 9 файлов данных:

Файл	Пространство имён	Содержимое
color.json	color	Палитра: семантические цвета организованы по default/hover/active/bg/border
color-dark.json	color (то же имя, что у светлого)	Инкрементное переопределение тёмной темы (только ключи, отличающиеся от светлой)
components.json	"" (пустая строка)	Токены компонентного уровня: button.*, input.* и т. д.
typography.json	typography	Шрифтовые семейства / размеры шрифта / насыщенность / межстрочный интервал
spacing.json	spacing	Шкала отступов xs–xxl
radius.json	radius	Скругления
shadow.json	shadow	Тени
motion.json	motion	Длительности и easing (кривые Безье)
z-index.json	zIndex	Z-уровни

Точное количество листьев в каждом файле меняется от версии к версии — ориентируйтесь на страницу Справочник по токенам: фиксированные числа в тексте неизбежно устаревают.

См. также Формат токенов и Пространства имён и точечные пути.

specs/ — контракты компонентов

Один JSON на компонент: имена props / типы / перечисления / значения по умолчанию / события / слоты / описания поведения / список потребляемых токенов. Формат строго задан specs/schema.json. Подробнее: Формат контракта.

cases/ — золотые сценарии

Один JSON на компонент: переводимые между платформами поведенческие утверждения (given/when/then), которые каждая нативная платформа вручную переводит в свои локальные тесты. Формат строго задан cases/schema.json. Подробнее: Формат сценариев.

codegen/ — инструментарий генерации

codegen/
├── src/
│   ├── index.ts      Точка оркестрации CLI (выполняет pnpm codegen)
│   ├── types.ts      Все определения типов (не попадает в артефакты времени выполнения)
│   ├── load.ts       Загрузка JSON + валидация схемы Ajv + уплощение
│   ├── resolve.ts    Разрешение ref + слияние тёмной темы
│   ├── format.ts     Разбор нейтральных значений / форматирование для каждой платформы
│   ├── tree.ts       Плоский path → вложенное дерево
│   ├── render.ts     Обёртка над Handlebars
│   └── targets/      Пять target'ов: android / ios / harmony / windows / docs
└── templates/        Handlebars-шаблоны для каждой платформы (7 файлов .hbs)

Подробнее: Обзор конвейера.

dist/ — сгенерированные артефакты

Изменять вручную запрещено (каталог в .gitignore). Структура:

dist/
├── android/top/lhgb/ui/tokens/   LhTokens.kt, LhDarkTokens.kt
├── ios/Sources/LhUITokens/       LhTokens.swift, LhDarkTokens.swift, LhShadow.swift
├── harmony/tokens/               LhTokens.ets, LhDarkTokens.ets, LhShadow.ets
├── c/include/lh_ui/              lh_tokens.h, lh_dark_tokens.h
└── docs/                         tokens.md, tokens.light.json, tokens.dark.json

Подробнее: Артефакты.

scripts/ — скрипты проверки и публикации

verify-tokens.mts (проверка токенов: схема + целостность ссылок + отчёт о путях-сиротах тёмной темы), verify-specs.mts (согласованность specs и cases), resolve-local-tokens.mjs (защита локальной линковки). Публикация идёт через changesets (см. Список команд).

tests/ — снапшот-тесты

codegen-snapshot.spec.ts зеркалирует все артефакты dist/ (снапшоты хранятся в репозитории), tokens.spec.ts выполняет мета-тесты токенов.

docs/ — этот сайт

Исходный код сайта на Astro Starlight (конфигурация в docs/astro.config.mjs, содержимое в docs/src/content/docs/). Три справочные страницы (токены / контракты / сценарии) — это .astro-страницы в docs/src/pages/, которые на этапе сборки напрямую вызывают функции загрузки и разрешения codegen и рендерят данные из JSON-источника, поэтому таблицы не нужно поддерживать вручную. Сведения о развёртывании — Описание развёртывания.