# Архитектура дизайн-системы

## Цель

NODE.DC состоит из самостоятельных репозиториев и разных frontend-стеков. Поэтому общий UI не может существовать как папка, которую вручную копируют из последнего приложения. Дизайн-система поставляется как версионируемые пакеты, а приложения сохраняют собственную доменную логику.

Репозиторий физически отделён от `NODEDC_PLATFORM`, но логически относится к платформенному слою. Пакеты дизайн-системы не владеют данными приложений. Living catalog имеет собственный минимальный runtime-store только для сохранения единого демонстрационного layout, загруженного stage-media и знака приложения между браузерными сессиями.

## Слои

### Tokens

`@nodedc/tokens` хранит геометрию, слои, motion и переменные темы. Геометрия не зависит от выбранного цвета приложения.

### Core

`@nodedc/ui-core` хранит:

- общий CSS-контракт;
- расчёт контрастного текста на акцентной заливке;
- расчёт позиции dropdown/popover относительно viewport;
- применение темы к DOM-контейнеру.

Core не зависит от React.

### React

`@nodedc/ui-react` предоставляет компоненты для Launcher/Hub, Engine, Ops и React-модулей. Компоненты контролируемые: бизнес-состояние остаётся у приложения, а визуальное и базовое интерактивное поведение принадлежит библиотеке.

`ApplicationShell` и `ApplicationPanel` образуют готовый launcher-style шаблон нового React-приложения. `useApplicationWorkspace` задаёт единую механику открытия navigation/content/expanded состояний. `MediaSourceField` отделяет стабильный UI выбора файла/URL от upload/storage API приложения. `Toolbar` фиксирует Engine/BIM dock, magnification, placement и autohide. `Icon` предоставляет ограниченный аудированный словарь glyph, чтобы приложения не импортировали vendor-наборы независимо.

### DOM

`@nodedc/ui-dom` предоставляет контроллеры для CMS, BIM Viewer и других приложений без React, включая те же workspace- и media-source state machines. DOM-слой не создаёт вторую стилизацию: он использует те же классы и токены `@nodedc/ui-core`.

### Catalog

Каталог является исполняемой документацией. Компонент не считается зафиксированным, если его состояния нельзя увидеть и проверить в каталоге.

Кнопка Save в `ApplicationPanel` записывает один server-side catalog layout: тему, обе material-схемы, Environment controls, Toolbar, stage-media и знак приложения. Browser localStorage не является источником истины.

## Граница shared/domain

В дизайн-системе живут элементы, значение которых не зависит от предметной области:

- поверхности;
- поля и действия;
- floating layers;
- окна;
- навигационная геометрия;
- application shell и фиксированная шапка;
- канонический набор иконок;
- inspector/settings layout;
- состояния загрузки, пустоты и ошибки.

В приложениях остаются:

- определение агентной ноды;
- схема SEO pipeline;
- BIM tree/model tools;
- модели задач и карточки с уникальной бизнес-логикой;
- запросы к API, права, маршруты и сохранение данных.

Если элемент встречается только в одном приложении, это ещё не причина переносить его сюда. Он переносится, когда имеет независимый UI-контракт или нужен новому приложению как готовый строительный блок.

## Зависимости

Направление зависимостей одностороннее:

1. tokens;
2. core;
3. React/DOM adapters;
4. applications.

Дизайн-система никогда не импортирует исходники приложения. Исторические реализации используются только как audit/reference и фиксируются в `registry/sources.json`.

## Версионирование

- `0.x` — baseline и первоначальная проверка API на реальных приложениях;
- minor — новый компонент или обратно совместимое расширение;
- patch — исправление поведения/стиля без изменения публичного контракта;
- major — удаление/переименование экспорта или несовместимая геометрия/семантика.

Приложение должно зависеть от опубликованной версии пакета, а не от копии файлов или произвольного commit URL.