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,108 @@
+# Канонические компоненты
+
+Машинный список находится в `registry/components.json`. Ниже зафиксирован смысл компонентов и границы их использования.
+
+## GlassSurface
+
+Базовая поверхность для карточки, панели и большого окна. Варианты меняют плотность материала, но не создают отдельный дизайн.
+
+- `default` — обычная карточка/панель;
+- `strong` — dropdown, modal и поверхность над сложным фоном;
+- `soft` — вложенная или вторичная область.
+
+Material rim допустим только как часть стекла. Жёсткая цветная рамка, случайный browser outline или debug border не являются rim.
+
+## Button и IconButton
+
+Button используется для всех текстовых действий. IconButton — для действия без текста.
+
+- primary/accent — главное действие текущего контекста;
+- secondary — обычное действие на glass surface;
+- ghost — малозаметное действие без собственной подложки;
+- danger — разрушительное действие, обычно в окне подтверждения.
+
+Icon-only action по умолчанию круглый. Квадратная кнопка с маленьким радиусом допустима только как кнопка закрытия окна или плотный инструмент, где это зафиксировано контрактом.
+
+## Field
+
+FieldFrame объединяет label, control, hint и description. TextField/TextAreaField реализуют стандартные текстовые поля.
+
+Приложение не должно вручную собирать label и input, если подходит Field. Ошибка и validation state будут расширением этого контракта, а не локальным классом приложения.
+
+## Checker
+
+Круглый бинарный контрол из нового Engine settings/agent inspector. Он использует checkbox semantics, но не копирует квадратный системный checkbox.
+
+## RangeControl
+
+Pill-range с заполнением акцентным цветом, встроенной подписью и значением. Домен определяет min/max/step и формат числа.
+
+## ColorField
+
+Связка круглого color picker и текстового значения. Валидация конкретного формата остаётся у формы приложения.
+
+## Dropdown
+
+Dropdown владеет floating-layer поведением:
+
+- рендерится в `document.body`;
+- позиционируется относительно viewport;
+- переворачивается вверх при недостатке места;
+- ограничивает размеры viewport;
+- обновляется при resize и scroll;
+- закрывается по outside pointer и Escape;
+- закрывает другой открытый dropdown.
+
+Содержимое меню передаётся приложением. Selection, action menu и filter menu используют один engine.
+
+## Select
+
+Select добавляет к Dropdown контролируемое значение, options и необязательный поиск. Native select не используется как видимый runtime UI, но может использоваться как fallback только в специально оговорённом legacy-контуре.
+
+## Window
+
+Window — единая механика открытия modal и правой panel:
+
+- приложение контролирует `open`;
+- библиотека управляет portal, focus entry/trap/restore, Escape, backdrop и scroll lock;
+- `center` — modal;
+- `end` — inspector/settings/detail panel.
+
+Содержание, сохранение и запросы принадлежат приложению.
+
+## ConfirmationModal
+
+ConfirmationModal оборачивает Window и защищает async-confirm от повторного запуска. До завершения операции закрытие можно заблокировать.
+
+## SegmentedControl
+
+Pill navigation для верхней панели и компактного переключения режимов. Active segment использует активную поверхность темы; это не обязательно основной accent приложения.
+
+## AppHeader
+
+Трёхосевая верхняя панель:
+
+- слева фиксированная область логотипа и optional context;
+- по центру workspace/navigation;
+- справа actions/profile.
+
+Компонент фиксирует положение логотипа, высоту и выравнивание, но не знает маршруты конкретного приложения.
+
+## StatusBadge
+
+Статус использует semantic tone: neutral, success, warning, danger или accent. Бизнес-статус приложения маппится на tone в самом приложении.
+
+## Inspector и ControlRow
+
+Единая accordion-панель для settings и definition controls. Источник — только новый Environment Settings и NDC Agent Inspector.
+
+Inspector владеет:
+
+- заголовками разделов;
+- открытием/закрытием секций;
+- active state;
+- вертикальным ритмом;
+- раскладкой label/control.
+
+Engine продолжает владеть определениями полей, типами нод и сохранением значений.
+