# Подключение дизайн-системы

## Главный принцип

Новый проект не копирует исходники компонентов из Launcher, CMS или этого репозитория. Он устанавливает версию пакетов NODE.DC, импортирует общий CSS и собирает интерфейс из публичных exports. Обновление пакета должно исправлять геометрию во всех подключённых приложениях без повторной ручной вёрстки.

`control-c / control-v` допустим только для короткой композиции приложения: какие routes и данные переданы готовым компонентам. CSS, DOM-анатомия header, оконные переходы, media control и accessibility не копируются.

## React consumer

Минимальный состав нового оконного приложения:

1. `@nodedc/tokens`, `@nodedc/ui-core` и `@nodedc/ui-react` фиксируются одной версией.
2. Один раз подключаются `tokens.css`, `themes.css` и `@nodedc/ui-core/styles.css`.
3. Theme/accent задаются через `applyNodedcTheme`.
4. Приложение собирает `ApplicationShell` из `AppHeader`, `AdminNavigationPanel` и `ApplicationPanel`.
5. Все состояния shell берутся из `useApplicationWorkspace`.
6. Routes, profile, stage content и бизнес-данные передаются props.

Нельзя добавлять local CSS к `AppHeader`, `HeaderNavigation`, `HeaderWorkspace`, `HeaderProfile` и `HeaderAvatar`. Если production Launcher изменяет канон, исправляется preset здесь и выпускается новая версия.

## DOM consumer

CMS/BIM подключают те же tokens/core styles и `@nodedc/ui-dom`. `createApplicationWorkspaceController`, `createMediaSourceController`, `createShareLinkController`, `createFloatingLayer` и `createModalController` связывают стабильную DOM-анатомию с тем же поведением, не вводя React в приложение.

## Adapter boundary

Общие компоненты не импортируют API конкретного проекта.

| Библиотека владеет | Приложение владеет |
| --- | --- |
| размеры, радиусы, поверхности | маршруты и тексты |
| header/window/media DOM anatomy | API, auth и permissions |
| open/close/expand state machine | получение и сохранение данных |
| file/URL selector и preview | file picker/media library/storage upload |
| focus, Escape, portal, responsive flow | доменная валидация и ошибки backend |

Например, `MediaSourceField` получает `onFileChange`. Consumer загружает файл, получает URL и возвращает его в контролируемое состояние. Компонент не знает S3, локальный диск, CMS media library или endpoint Launcher.

## Definition of done для нового общего компонента

- экспортируется из React или DOM package;
- использует tokens/core styles без screen-local geometry;
- показан в живом каталоге в ключевых состояниях;
- записан в `registry/components.json`;
- имеет документированную adapter boundary;
- проходит desktop/mobile visual QA;
- версия пакета зафиксирована consumer-ом.