85 lines
6.2 KiB
Markdown
85 lines
6.2 KiB
Markdown
# Архитектура дизайн-системы
|
||
|
||
## Цель
|
||
|
||
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; его физика находится в Core и используется React-компонентом и DOM-controller без расхождения формул. `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.
|