Establish NODE.DC design system baseline

2026-07-10 02:34:36 +03:00
commit 73629d68c3
63 changed files with 6701 additions and 0 deletions
@@ -0,0 +1,79 @@
+# Архитектура дизайн-системы
+
+## Цель
+
+NODE.DC состоит из самостоятельных репозиториев и разных frontend-стеков. Поэтому общий UI не может существовать как папка, которую вручную копируют из последнего приложения. Дизайн-система поставляется как версионируемые пакеты, а приложения сохраняют собственную доменную логику.
+
+Репозиторий физически отделён от `NODEDC_PLATFORM`, но логически относится к платформенному слою. Он не является backend-сервисом и не владеет данными приложений.
+
+## Слои
+
+### Tokens
+
+`@nodedc/tokens` хранит геометрию, слои, motion и переменные темы. Геометрия не зависит от выбранного цвета приложения.
+
+### Core
+
+`@nodedc/ui-core` хранит:
+
+- общий CSS-контракт;
+- расчёт контрастного текста на акцентной заливке;
+- расчёт позиции dropdown/popover относительно viewport;
+- применение темы к DOM-контейнеру.
+
+Core не зависит от React.
+
+### React
+
+`@nodedc/ui-react` предоставляет компоненты для Launcher/Hub, Engine, Ops и React-модулей. Компоненты контролируемые: бизнес-состояние остаётся у приложения, а визуальное и базовое интерактивное поведение принадлежит библиотеке.
+
+### DOM
+
+`@nodedc/ui-dom` предоставляет контроллеры для CMS, BIM Viewer и других приложений без React. DOM-слой не создаёт вторую стилизацию: он использует те же классы и токены `@nodedc/ui-core`.
+
+### Catalog
+
+Каталог является исполняемой документацией. Компонент не считается зафиксированным, если его состояния нельзя увидеть и проверить в каталоге.
+
+## Граница shared/domain
+
+В дизайн-системе живут элементы, значение которых не зависит от предметной области:
+
+- поверхности;
+- поля и действия;
+- floating layers;
+- окна;
+- навигационная геометрия;
+- 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.
+