# Umbra by Aid Beisembin

> Дизайн-система продуктов Aid Beisembin (ShadeNotes, портфолио). Токены W3C DTCG, реестр shadcn с пространством имён @umbra, правила в DESIGN.md. Перед работой над интерфейсом прочитать DESIGN.md и описание нужного компонента

Подключение: в components.json продукта "registries": { "@umbra": "https://aid-design-lovat.vercel.app/r/{name}.json" }, затем npx shadcn@latest add @umbra/<имя>

## Правила

- [DESIGN.md](https://aid-design-lovat.vercel.app/DESIGN.md): ДНК, токены, правила, каталог компонентов в формате Google Stitch
- [Цвета и контраст](https://aid-design-lovat.vercel.app/colors): значения обеих тем, акценты продуктов, отчёт контраста

## Сайт

- [Что такое Umbra](https://aid-design-lovat.vercel.app/): Что это за система, из чего состоит и с чего начать
- [Быстрый старт](https://aid-design-lovat.vercel.app/start): Подключить реестр, тему продукта и первый компонент, проверить сборку
- [Пример экрана](https://aid-design-lovat.vercel.app/example): Готовый экран из компонентов Umbra: как части работают вместе
- [Цвета и контраст](https://aid-design-lovat.vercel.app/colors): Какие цвета есть, для чего каждый и как проверить читаемость
- [Типографика](https://aid-design-lovat.vercel.app/typography): Шкала текста: размеры, начертания и где какой брать
- [Отступы и сетка](https://aid-design-lovat.vercel.app/layout): Шкала отступов, радиусы и правило внутреннего и внешнего
- [Иконки](https://aid-design-lovat.vercel.app/docs/icon): Набор Phosphor: вес, размеры и что нельзя
- [Темы продуктов](https://aid-design-lovat.vercel.app/themes): База и слой продукта: как подключить тему ShadeNotes, портфолио или новую
- [Стекло и анимация](https://aid-design-lovat.vercel.app/glass-motion): Стекло для слоя управления, пружины, перетекание и появление
- [Окно](https://aid-design-lovat.vercel.app/docs/window-bar): Подложка кнопок окна macOS над сайдбаром
- [Страница](https://aid-design-lovat.vercel.app/docs/page): Колонка экрана: шапка, прокрутка и запас под док
- [Плитка](https://aid-design-lovat.vercel.app/docs/tile): Единица экрана бенто: когда плитка, когда вложенное
- [Сайдбар](https://aid-design-lovat.vercel.app/docs/sidebar): Узкая колонка навигации приложения
- [Кнопка](https://aid-design-lovat.vercel.app/docs/button): Таблетки 40, 48, 56 и круглые: варианты и состояния
- [Чип](https://aid-design-lovat.vercel.app/docs/chip): Фильтры и вкладки: выбор одного из нескольких
- [Поле](https://aid-design-lovat.vercel.app/docs/field): Поле ввода с подписью, подсказкой и ошибкой
- [Список выбора](https://aid-design-lovat.vercel.app/docs/select): Выбор одного значения из списка
- [Переключатель](https://aid-design-lovat.vercel.app/docs/toggle): Включить и выключить настройку
- [Поиск](https://aid-design-lovat.vercel.app/docs/search-toggle): Круглая кнопка поиска, которая раскрывается в поле
- [Счётчик](https://aid-design-lovat.vercel.app/docs/counter): Число, которое считается вверх при появлении
- [Строка списка](https://aid-design-lovat.vercel.app/docs/list-row): Строка без своей карточки: миниатюра, заголовок, мета
- [Спиннер](https://aid-design-lovat.vercel.app/docs/spinner): Дуга ожидания без подложки
- [Скелетон](https://aid-design-lovat.vercel.app/docs/skeleton): Заглушка содержимого, пока оно грузится
- [Тост](https://aid-design-lovat.vercel.app/docs/toast): Короткое уведомление о результате действия
- [Карточка итога](https://aid-design-lovat.vercel.app/docs/notice-card): Уведомление у дока: что случилось и одно действие
- [Капсула записи](https://aid-design-lovat.vercel.app/docs/dock): Капсула состояния записи поверх контента
- [Первый запуск](https://aid-design-lovat.vercel.app/docs/onboarding): Знакомство до трёх шагов, каждый в 1100 × 700
- [Обработка записи](https://aid-design-lovat.vercel.app/docs/process-screen): Экран процесса с настоящим статусом и содержимым
- [Витрина](https://aid-design-lovat.vercel.app/docs/showcase): Показ работы продукта на шаге знакомства
- [Как подключить агента](https://aid-design-lovat.vercel.app/agents): Что дать агенту в продукте: DESIGN.md, реестр через MCP, llms.txt и сниппет
- [Навык «Экран по Umbra»](https://aid-design-lovat.vercel.app/docs/skill-umbra-ui): Навык Claude Code: порядок сборки экрана и чек-лист отчёта
- [Знаки продуктов](https://aid-design-lovat.vercel.app/characters): Персонажи и логотипы продуктов, их размеры и как поставить знак
- [Живой персонаж портфолио](https://aid-design-lovat.vercel.app/characters/portfolio): Эмоции, движения и жесты живого персонажа портфолио
- [Проверка кода (ESLint)](https://aid-design-lovat.vercel.app/docs/eslint): Правила Umbra в ESLint: что ловят и как подключить
- [Склейка классов (cn)](https://aid-design-lovat.vercel.app/docs/cn): Функция cn: склейка классов Tailwind без конфликтов

## Основа

- [Тема: база](https://aid-design-lovat.vercel.app/themes#base): Токены и base.css Umbra: нейтрали двух тем, роли цвета, геометрия, типографика, движение, стекло, reduced-motion и reduced-transparency. Ставится первым в любой продукт, один раз. Без него компоненты @umbra не работают. Акцент продукта ставится отдельно: theme-shadenotes или theme-portfolio. Реестр: https://aid-design-lovat.vercel.app/r/theme-base.json
- [Тема: ShadeNotes](https://aid-design-lovat.vercel.app/themes#shadenotes): Слой продукта ShadeNotes: акцент лайм #E4FB77, текст на нём #111, чернила #576E00 в светлой теме. Ставится после theme-base в ShadeNotes. В другом продукте не брать: у каждого продукта свой акцент. Реестр: https://aid-design-lovat.vercel.app/r/theme-shadenotes.json
- [Тема: портфолио](https://aid-design-lovat.vercel.app/themes#portfolio): Слой продукта портфолио: акцент кобальт #3044D8, текст на нём белый, чернила в тёмной теме осветлены до #C4CBFF (Lc 77 на #0A0A0A). Ставится после theme-base в портфолио. В другом продукте не брать. Реестр: https://aid-design-lovat.vercel.app/r/theme-portfolio.json
- [Движение](https://aid-design-lovat.vercel.app/glass-motion#motion): Пружины --spring-snappy и --spring-smooth (CSS linear(), перелёт не больше 4 %), появление поверх из размытия, перетекающий индикатор выбора MorphIndicator, нажатие, смена страниц и темы через View Transitions. Брать для слоя управления: индикатор вкладок и сайдбара, бегунок, меню, тост, смена темы. Не брать для появления контента в потоке (это umbra-rise из theme-base). Реестр: https://aid-design-lovat.vercel.app/r/motion.json
- [Склейка классов (cn)](https://aid-design-lovat.vercel.app/docs/cn): Склейка классов для компонентов Umbra: clsx плюс tailwind-merge, которому объяснены классы токенов (text-display, text-muted, p-tile, rounded-tile). Ставится сам как зависимость компонентов. Отдельно брать, только если пишете свой компонент из классов Umbra и передаёте className снаружи. Реестр: https://aid-design-lovat.vercel.app/r/cn.json
- [Icon](https://aid-design-lovat.vercel.app/docs/icon): Иконка Umbra: обёртка над @phosphor-icons/react, вес fill по умолчанию, bold сам у всех шевронов Caret*, Check, X, MagnifyingGlass. Брать для любой иконки в интерфейсе. Не брать для логотипа и маскота (это SVG продукта) и для индикатора ожидания (это Spinner). Реестр: https://aid-design-lovat.vercel.app/r/icon.json
- [ESLint Umbra](https://aid-design-lovat.vercel.app/docs/eslint): Правила ESLint Umbra для продукта: запрет сырых цветов, произвольных значений Tailwind вне шкалы, радиусов вне шкалы, чужих наборов иконок и Phosphor без fill. Брать в каждый продукт вместе с theme-base: правила работают только если их проверяют. Реестр: https://aid-design-lovat.vercel.app/r/eslint.json

## Для агентов

- [Навык: экран по Umbra](https://aid-design-lovat.vercel.app/docs/skill-umbra-ui): Навык Claude Code «собрать экран по Umbra»: порядок работы (каркас, плитки, роли цвета, правило двух плиток, APCA, движение, проверка в 1100 × 700) и чек-лист отчёта. Ставится в .claude/skills/umbra-ui/ продукта. Брать в каждый продукт, где агент делает интерфейс. Не заменяет DESIGN.md: навык задаёт порядок, правила в DESIGN.md. Реестр: https://aid-design-lovat.vercel.app/r/skill-umbra-ui.json

## Компоненты

- [Tile](https://aid-design-lovat.vercel.app/docs/tile): Плитка бенто: --tile, радиус 24, отступ 20, без рамок и теней; вложенная: радиус 16, отступ 16. Одна плитка, одна задача. Брать для любого смыслового блока на окне и для вложенной поверхности внутри плитки (variant=nested). Не брать для того, что лежит поверх контента (это Glass, NoticeCard, Toast) и для строк списка (это ListRow без вложенной карточки). Реестр: https://aid-design-lovat.vercel.app/r/tile.json
- [Page](https://aid-design-lovat.vercel.app/docs/page): Колонка страницы одной плиткой: липкая шапка (Display, подпись, круглые действия 56, чипы-фильтры), при прокрутке шапка становится стеклом с растворённым краем, прокрутка обрезана по радиусу. Брать для основного экрана раздела рядом с Sidebar. Не брать для экрана-шага (онбординг, обработка: там Tile по центру) и для блока внутри экрана (это Tile). Реестр: https://aid-design-lovat.vercel.app/r/page.json
- [Button](https://aid-design-lovat.vercel.app/docs/button): Кнопка-таблетка: primary (акцент), secondary (--nested), ghost (текст), destructive; размеры 40 / 48 / 56; icon для круглой кнопки-иконки. Брать для действия, у которого есть подпись или понятная иконка. Не брать для фильтров и вкладок (это Chip), для навигации сайдбара (это Sidebar) и для поиска (это SearchToggle). Реестр: https://aid-design-lovat.vercel.app/r/button.json
- [Chip](https://aid-design-lovat.vercel.app/docs/chip): Фильтр и вкладка: таблетка 40 px на --nested, выбранный с рамкой 2 px --primary-edge, лёгким стеклом и font-medium, может нести счётчик. Брать для 2–6 видимых вариантов фильтра или вкладок. Не брать для действия (это Button), для длинного списка вариантов (это Select) и для «вкл / выкл» (это Toggle). Реестр: https://aid-design-lovat.vercel.app/r/chip.json
- [ListRow](https://aid-design-lovat.vercel.app/docs/list-row): Строка списка без вложенной карточки: круглая миниатюра состояния 48, заголовок Label 500, мета Caption, шеврон; List даёт две колонки от 1100 px. Брать для списков записей, встреч, кейсов внутри Page или Tile. Не брать для одиночного блока (это Tile) и для пунктов меню (это Select или стеклянное меню). Реестр: https://aid-design-lovat.vercel.app/r/list-row.json
- [NoticeCard](https://aid-design-lovat.vercel.app/docs/notice-card): Карточка-уведомление у дока: плотное стекло, радиус 24, знак в круге 44, заголовок одной строкой, одно главное действие и тихие второстепенные; появляется из размытия. Брать для статуса, который ждёт действия человека (нет доступа к микрофону, не распознано). Не брать для короткого подтверждения (это Toast) и для содержимого страницы (это Tile). Реестр: https://aid-design-lovat.vercel.app/r/notice-card.json
- [Glass](https://aid-design-lovat.vercel.app/glass-motion#glass): Стекло в духе Liquid Glass macOS 26 / iOS 26: материал .umbra-glass (обычное и плотное), индикатор выбора, преломление по краю в Chromium с фолбэками, нажатие. Брать только для слоя управления поверх контента: шапка при прокрутке, индикатор выбора, переключатели, меню, подсказки, тосты, диалоги, плавающие панели. Не брать для плиток и карточек в потоке: они плотные (это Tile). Реестр: https://aid-design-lovat.vercel.app/r/glass.json
- [Spinner](https://aid-design-lovat.vercel.app/docs/spinner): Индикатор ожидания: дуга без подложки цветом --loader, размеры 16 / 20 / 24. Брать, когда идёт настоящая работа без известного процента. Не брать для заглушки будущего содержимого (это Skeleton), для выдуманного прогресса и вместо иконки. Реестр: https://aid-design-lovat.vercel.app/r/spinner.json
- [Skeleton](https://aid-design-lovat.vercel.app/docs/skeleton): Скелетон: место будущего содержимого поверхностью --skeleton, формы block, text, circle; статичный, без бегущего блика. Брать, когда известна форма содержимого, которое загружается. Не брать, когда форма неизвестна или идёт долгая обработка (это Spinner). Реестр: https://aid-design-lovat.vercel.app/r/skeleton.json
- [Field](https://aid-design-lovat.vercel.app/docs/field): Поле ввода: Input таблеткой 48 px и Textarea на --nested с рамкой --border, фокус кольцом внутри; Field связывает подпись, подсказку и ошибку. Брать для ввода текста. Не брать для выбора из списка (это Select), для «вкл / выкл» (это Toggle) и для поиска в шапке (это SearchToggle). Реестр: https://aid-design-lovat.vercel.app/r/field.json
- [Toggle](https://aid-design-lovat.vercel.app/docs/toggle): Переключатель «вкл / выкл» на Radix Switch: таблетка, включённый цветом акцента, выключенный тоном --border. Брать для настройки, которая действует сразу. Не брать для выбора одного из нескольких (это Chip или Select) и для действия с подтверждением (это Button). Реестр: https://aid-design-lovat.vercel.app/r/toggle.json
- [Sidebar](https://aid-design-lovat.vercel.app/docs/sidebar): Сайдбар приложения: отдельная плитка 72 px слева, логотип сверху, пункты круглыми кнопками 48 с иконкой 24, служебное внизу, выбранный пункт таблеткой --nav-active. Брать для навигации между разделами приложения. Не брать для сайта (там сайдбар 320 с лентой), для действий на странице (это Button) и для фильтров (это Chip). Реестр: https://aid-design-lovat.vercel.app/r/sidebar.json
- [WindowBar](https://aid-design-lovat.vercel.app/docs/window-bar): Подложка под кнопки окна macOS 72 × 26 над сайдбаром, зона перетаскивания окна в Electron и Tauri. Брать только в настольном приложении на macOS. Не брать в браузере, на Windows и Linux и как декоративную шапку. Реестр: https://aid-design-lovat.vercel.app/r/window-bar.json
- [SearchToggle](https://aid-design-lovat.vercel.app/docs/search-toggle): Поиск в шапке: круглая кнопка 56 с лупой, поле выезжает влево до 280 px, лупа поворотом становится крестиком. Брать для поиска по списку страницы. Не брать для полей формы (это Field) и для постоянной строки поиска, если поиск главное действие экрана. Реестр: https://aid-design-lovat.vercel.app/r/search-toggle.json
- [Dock](https://aid-design-lovat.vercel.app/docs/dock): Док действия продукта внизу по центру поверх контента (запись в ShadeNotes): в покое круглая кнопка 88 цвета записи с иконкой 32, при записи стеклянная капсула с таймером, полосами сегментов, паузой 56 и красной кнопкой «Остановить». Брать для одного главного длительного действия продукта. Не брать для обычных действий (это Button) и для уведомлений (это NoticeCard). Реестр: https://aid-design-lovat.vercel.app/r/dock.json
- [Toast](https://aid-design-lovat.vercel.app/docs/toast): Короткое уведомление Sonner в стекле: радиус 24, ширина 380, виды success (галочка акцента), error, warning (знак Giants). Брать для короткого подтверждения или сбоя после действия. Не брать для статуса, который ждёт действия человека (это NoticeCard), и для ошибок поля (это Field). Реестр: https://aid-design-lovat.vercel.app/r/toast.json
- [Select](https://aid-design-lovat.vercel.app/docs/select): Выбор одного значения из списка на Radix Select: триггер таблеткой 48 px как поле, меню в стекле с появлением из размытия, галочка у выбранного. Брать для выбора из 6 и больше вариантов или длинных названий. Не брать для 2–5 видимых вариантов (это Chip) и для «вкл / выкл» (это Toggle). Реестр: https://aid-design-lovat.vercel.app/r/select.json
- [Counter](https://aid-design-lovat.vercel.app/docs/counter): Число, которое считается вверх от 0 при появлении за --t-slow (0,5 с) по кривой --ease-out; при reduced-motion сразу итог. Брать для крупных настоящих чисел в момент их появления (итоги, статистика). Не брать для прогресса, таймера (это Dock) и чисел, которые часто меняются. Реестр: https://aid-design-lovat.vercel.app/r/counter.json
- [Onboarding](https://aid-design-lovat.vercel.app/docs/onboarding): Первый запуск продукта: одна плитка до 600 px по центру окна, точки шага, шаги сменяются размытием и сдвигом; OnboardingTitle и OnboardingHint держат колонку текста. Брать для первого запуска и коротких мастеров до трёх шагов. Не брать для настроек (это Page), для одиночного уведомления (это NoticeCard) и для экрана обработки (это Showcase на плитке). Реестр: https://aid-design-lovat.vercel.app/r/onboarding.json
- [Showcase](https://aid-design-lovat.vercel.app/docs/showcase): Показ работы продукта на первом экране: обложка 8:3, сцены по очереди, итоговый кадр держится 1,7 с и гаснет перед повтором; содержимое 60–70 % обложки по оптическому центру. Брать только для шага знакомства в Onboarding. Не брать для экранов процесса с настоящим статусом (это ProcessScreen), для прогресса и для декоративной анимации в остальном интерфейсе. Реестр: https://aid-design-lovat.vercel.app/r/showcase.json
- [ProcessScreen](https://aid-design-lovat.vercel.app/docs/process-screen): Экран процесса: сверху текущий шаг 22/28 со спиннером строго по реальному статусу, ниже настоящее содержимое процесса (например, дописывающийся транскрипт), факты одной строкой; финал «Готово» с галочкой и явными действиями, автопереход не раньше 3 с без действий человека. Брать для обработки, импорта, сохранения, загрузки. Не брать для демо на первом экране (это Showcase) и для коротких действий до секунды (хватит Spinner в кнопке). Реестр: https://aid-design-lovat.vercel.app/r/process-screen.json

## Персонажи и логотипы

- [BrandMark](https://aid-design-lovat.vercel.app/characters#brand-mark): Статичный знак продукта: картинка персонажа продукта на плитке акцента нужного размера (16–128), с альтернативным текстом. Брать для логотипа в Sidebar, на заставке и в шапке. Не брать для живого маскота (он в портфолио) и для иконок интерфейса (это Icon). Реестр: https://aid-design-lovat.vercel.app/r/brand-mark.json
- [Знак ShadeNotes](https://aid-design-lovat.vercel.app/characters#brand-shadenotes): Знак ShadeNotes: персонаж ShadeNotes (острый силуэт #0A0A0A, глаза-полумесяцы, лаймовая искра) на лаймовой плитке с радиусом 52/256, SVG и PNG, и иконка приложения 512. Брать в ShadeNotes для логотипа в сайдбаре, заставки и иконок. Не брать в другом продукте и не анимировать: знак статичный. Реестр: https://aid-design-lovat.vercel.app/r/brand-shadenotes.json
- [Знак портфолио](https://aid-design-lovat.vercel.app/characters#brand-portfolio): Персонаж портфолио: статичный кадр живого маскота (круглая голова с ушами, вертикальные глаза #FFFEF5, тело с радиальными градиентами) и иконка сайта 180. Брать в портфолио для превью и иконки сайта. Не брать в других продуктах: у каждого продукта свой персонаж. Живой маскот (настроения и движения) остаётся компонентом портфолио и в реестр не входит. Реестр: https://aid-design-lovat.vercel.app/r/brand-portfolio.json

## Необязательно

- [Реестр целиком](https://aid-design-lovat.vercel.app/r/registry.json)
- [llms-full.txt](https://aid-design-lovat.vercel.app/llms-full.txt): всё одним текстом