NODEDC_DESIGN_GUIDELINE/docs/ARCHITECTURE.md

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

Цель

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 и media source. 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.