Skip to content

CLAUDE.md

Latest commit

 

History

History
129 lines (106 loc) · 10 KB

CLAUDE.md

File metadata and controls

129 lines (106 loc) · 10 KB
Raw

CLAUDE.md — DesignSystemBuilder

dsbuilder-ios — единый macOS CLI дизайн-системы SDDS под iOS. Две задачи в одном бинаре:

  • themes (подкоманда по умолчанию) — берёт схему темы и палитру, декодирует JSON и по Stencil-шаблонам генерирует токены (цвета, типографику, тени, формы, отступы, градиенты) и вариации компонентов в Themes/<Name>Theme.
  • theme generate --sdds <dir> — токены, шрифты и мета токенов для одной темы, описанной локальной .sdds (её наполняет dsbuilder theme fetch). JSON-конфиг не нужен: имя темы, выход и схема компонентов выводятся из директории. Так команду вызывает делегат платформы.
  • components generate --sdds <dir> — вариации компонентов, код binding-API и config-info-ios.json. Отдельная команда: тема и компоненты независимы, как generateComposeTheme и generateComposeComponents на Android. Прежний совмещённый проход одной командой — theme generate --with-components; themes работает как раньше.
  • docs aggregate --sdds <dir> — собирает дерево документационного бандла целиком: сканирует // @DocSample, рендерит маркеры и раскладывает контент в <sdds>/temp/docs (см. ../docs/DOCS_BUNDLE.md). Прежняя пара docs extract + docs aggregate --theme осталась для ручных прогонов с нестандартными путями.

Не путать с внешним dsbuilder из salute-developers/design-system-builder (Kotlin/Native): тот выгружает .sdds/, вызывает наш бинарь как платформенный инструмент (theme generate, docs aggregate) и печёт готовый бандл из подготовленного нами дерева.

Структура

  • DesignSystemBuilderCLI/ — точка входа (main.swift) и подкоманды (GenerateThemes.swift, ThemeCommands.swift, ComponentsCommands.swift, DocsCommands.swift); общие опции генерации — SddsGeneration.swift.
  • DesignSystemBuilderCore/ — логика генерации тем (App.swift), Stencil-шаблоны.
  • DocsAggregatorCore/ — сканер сэмплов, рендер маркеров и раскладка докбандла.
  • SDDSThemeCore/ — рантайм-типы токенов (портируемое ядро) — см. SDDSThemeCore/CLAUDE.md.
  • SDDSThemeUtilities/ — вспомогательные утилиты.
  • DesignSystemBuilderCoreTests/, DocsAggregatorCoreTests/, SDDSThemeCoreTests/, SDDSThemeTests/ — тесты.
  • LocalSchemes/, Playground/ — локальные схемы и песочница для отладки.
  • DesignSystemBuilder.xcodeproj, build_cli.sh — сборка.

Тип: SwiftPM-пакет DesignSystemBuilder (Package.swift), продукт — executable dsbuilder. Зависимости: swift-argument-parser, Stencil, PathKit, swift-syntax. DesignSystemBuilder.xcodeproj остался только под то, чего SwiftPM не умеет: SDDSThemeCore.xcframework, SDDSTheme и SDDSDemo.

Сборка и запуск CLI

Из каталога DesignSystemBuilder/:

./build_cli.sh                 # Release (по умолчанию)
./build_cli.sh --debug         # Debug
./build_cli.sh --run           # собрать и запустить с default-конфигом
./build_cli.sh --run cfg.json  # запустить с внешним JSON-конфигом
./build_cli.sh --run docs extract --repo-root ..
./build_cli.sh --help

Результат: DesignSystemBuilder/build/dsbuilder-ios/dsbuilder-ios — самодостаточный бинарник, фреймворка рядом больше нет. build/ в .gitignore.

Напрямую через SwiftPM: swift build --package-path DesignSystemBuilder -c release --product dsbuilder-ios.

Кастомный выходной каталог — опция -o/--output.

Standalone-бандл и исходники с релиза

--standalone [--components] собирает плоскую папку .swift (StandaloneBundle.swift). Вендоримые исходники и пакет темы берутся от sourcesRootURL (App.swift), приоритет:

  1. --sources-version <tag> — архив SDDSSources-<tag>.zip с GitHub Release; скачивает и распаковывает SourcesRelease/SourcesReleaseFetcher.swift в generationRootURL, то есть рядом со сгенерированными токенами (<output>/SDDSSources-<tag>). Требует --standalone, несовместим с --sources-root. --sources-url / --sources-repository — переопределения.
  2. --sources-root <dir> — распакованная копия исходников.
  3. корень репозитория.

Архив собирает ../scripts/package_sources.sh, публикует .github/workflows/publish-release.yml. Список путей в скрипте обязан совпадать с тем, что читает App.sourcesRootURL — иначе бандл соберётся молча неполным (на этот случай есть guard'ы StandaloneBundle.runGuards и проверка layout-маркера в фетчере).

Что откуда берётся

  • Состав компонентов темы и имена файлов конфигов — из индекса DS meta.json. Источник: сначала локальный пакет .sdds/components, который выгружает DS Builder CLI, затем theme-converter components/<theme>/meta.json. Генерятся только вариации, которые в теме есть; чего iOS не умеет — печатается в лог. Директория .sdds/components без meta.json — ошибка: это оборванная выгрузка, а не повод уйти в сеть.
  • Значения enum-свойств — из меты (valueEnum): case'ы, их id в конфиге и дефолт задаются аннотациями на самом enum'е, отдельного реестра в генераторе нет.
  • ios-api-meta.json описывает компоненты: одна запись — один компонент, как в uikit-compose-api-meta.json на Android. Какая вариация генерации какому компоненту принадлежит, объявлено в CodeGenerationComponent+MetaComponent.swift — из имён это не выводится (ListNumberedItem принадлежит ListItem, а не List).
  • Имена *Appearance/*SizeConfiguration — из .sdds/ios-api-meta.json (см. ../Tools/SDDSApiInfoGenerator/CLAUDE.md), руками в генераторе не дублируются.
  • Связка «компонент → тип стиля» объявлена в самой библиотеке — @ApiInfo(components: [...]) на *Appearance, как на Android — и приезжает в мету. Вывести её из данных нельзя: группировка по типам iOS не совпадает с группировкой DS (у DS basic-button/icon-button — разные компоненты, на iOS это один ButtonAppearance; bottom-sheet на iOS зовётся BottomSheetAppearance, а в мете обязан называться ModalBottomSheet, как на Android).

Источник темы

.sdds/ios-api-meta.json — продукт сборки, не коммитится: генерится scripts/generate_api_meta.sh, который вызывают build_cli.sh и run_tests.rb.

Приоритет: локальная .sdds/-директория DS Builder → удалённый/локальный zip-снапшот. .sdds/ наполняется scripts/fetch_sdds.sh (DS Builder CLI). Токены/палитра в .sdds/ под .gitignore; config.json — трекается. Если .sdds/ пуст — откат на zip (localSchemePath).

Тесты

swift test --package-path .    # DesignSystemBuilderCoreTests + DocsAggregatorCoreTests
ruby ../scripts/run_tests.rb   # то же самое из корня репозитория

Грабли

  • Генерация тем перезаписывает Themes/<Name>Theme/ — правь шаблоны/токены, не результат.
  • ios-api-meta.json нужна только генерации компонентов; theme generate работает без неё.
  • --format (swiftlint --fix) по умолчанию выключен: пакеты тем коммитятся как есть, и включение переформатировало бы их целиком — это отдельная регенерация всех тем.
  • Полный конвейер «токены → пакеты тем → Xcode-проекты» — scripts/generate_themes/ + scripts/create_project/ (см. ../scripts/CLAUDE.md).
  • Меняешь публичное appearance-API в SDDSComponents? Регенерируй темы и убедись, что шаблоны/типы совпадают.
  • Коммит-скоуп: sdds-icore/theme-builder.