Большинство современных библиотек интерфейсов до сих пор проектируются в парадигме «человек смотрит глазами»: красивая витрина в Storybook, тяжёлый сайт документации на React, интерактивные песочницы и закрытый NPM-пакет. Но в 2026 году фронтенд всё чаще собирает не верстальщик, а автономный кодинг-агент — Cursor, Claude Code, Windsurf или Copilot. И в этот момент привычная инфраструктура ломается: агент не может кликать по вкладкам браузера, задыхается в мегабайтах клиентского JavaScript и слепо наугад пытается импортировать чужие закрытые компоненты.
ObsidianUI — одна из первых открытых библиотек компонентов, которая изначально спроектирована под протоколы прямого взаимодействия «машина-машина» (Agent-Ready UI). Это не просто очередной набор красивых кнопок со свечением, а готовая кодовая база с машинными спецификациями, локальным MCP-сервером и реестром, понятным языковым моделям.
Зачем библиотеке интерфейсов машинный контракт
Фронтенд-разработка переживает фундаментальный сдвиг. Если раньше мы выбирали UI-библиотеки по качеству документации для людей, то сегодня решающим фактором становится то, насколько библиотека доступна для кодинг-агентов.
ObsidianUI решает две ключевые инженерные задачи:
- Сложная визуальная кинематика без написания математики с нуля. Библиотека содержит 104 готовых модуля: от базовых интерфейсных элементов до трёхмерных WebGL-сцен, canvas-шейдеров, параллакс-галерей и физических эффектов курсора.
- Машинный интерфейс доступа к кодовой базе. Вместо парсинга HTML-страниц агент обращается к прямым Markdown-эндпоинтам, спецификации
llms.txt, контрактам OpenAPI и локальному Model Context Protocol (MCP) серверу.
Архитектурно проект следует модели, которую популяризировал shadcn/ui: в проекте нет зависимости от внешнего монолитного NPM-пакета. Исходный код каждого компонента копируется прямо в дерево файлов вашего приложения. Это исключает vendor-lock, не ломает сборку при выходе мажорных обновлений и позволяет модифицировать любой узел под требования собственного дизайн-кода.
Архитектура и стек технологий
Проект построен на актуальном фронтенд-стеке с разделением ответственности между слоями стилей, реактивности и анимации:
| Технологический слой | Используемый стек | Инженерное назначение |
|---|---|---|
| Базовый каркас | React 19, TypeScript | Строгая типизация пропсов, поддержка серверных компонентов (RSC) и современного хук-контура |
| Стилизация | Tailwind CSS v4 | Утилитарные классы, бесшовное переопределение через tailwind-merge и утилиту cn |
| Базовая кинематика | Motion (Framer Motion) | Декларативные layout-анимации, жесты, управление состояниями входа и выхода элементов |
| Сложная динамика | GSAP (GreenSock) | Таймлайны высокой точности, сложные scroll-триггеры и синхронизация составных сцен |
| 3D и графика | Three.js, Canvas API, WebGL | Рендеринг шейдерных фонов, интерактивных 3D-моделей, эффектов частиц и оптических искажений |
Структура каталога компонентов
Каталог ObsidianUI строго разделен на два функциональных слоя:
- UI-примитивы (52 компонента): базовые атомы интерфейса — кнопки со стрелками, индикаторы прогресса, радиальные меню, аккордеоны, поля OTP-ввода, адаптивные бейджи и карточки.
- Комплексные блоки (52 компонента): готовые продуктовые секции и акцентные эффекты — Apple Spotlight, физический шлейф курсора (Butterfly Trail, Rope Cursor), фрактальное стекло (Fractal Glass), dither-холсты, трёхмерный переворот книг (Book Flip) и бесконечные маркет-ленты по SVG-траекториям.
Механика интеграции в проект
При интеграции компонента через CLI его исходники автоматически раскладываются по системным путям проекта на основе конфигурации components.json.
Префиксы путей манифеста транслируются в реальные директории приложения:
@ui/и@components/→ директория компонентов (src/components/ui/);@lib/→ директория системных хелперов и функции слияния классов (src/lib/utils.ts);@hooks/→ пользовательские React-хуки для захвата курсора, скролла и медиа-запросов (src/hooks/).
Интерфейс для ИИ-агентов: llms.txt, OpenAPI и MCP
Главная инновация ObsidianUI — архитектурная готовность к автономной работе ИИ-агентов. Библиотека предоставляет четыре слоя машинного взаимодействия:
1. Спецификация llms.txt и agent-instructions.md
По корневому адресу https://www.obsidianui.dev/llms.txt отдаётся компактный индекс проекта. В нём перечислены все 104 компонента с прямыми ссылками на скачивание JSON-манифестов и Markdown-документацию. Агенту не нужно блуждать по sitemap — он за один HTTP-запрос получает полную карту библиотеки.
2. Чистый Markdown без клиентского JavaScript
Любая страница документации поддерживает заголовок Accept: text/markdown или доступна по прямому пути вида /markdown/docs/\{component\}.md. Это позволяет легковесным краулерам и curl-скриптам выкачивать примеры кода без запуска headless-браузера и рендеринга JavaScript.
3. Схема OpenAPI 3.0
Машиночитаемый контракт openapi.json описывает все эндпоинты реестра, форматы входных и выходных параметров. Агенты с поддержкой вызова внешних инструментов (Tool Use) могут валидировать параметры до выполнения сетевого запроса.
4. Локальный stdio MCP-сервер
В репозиторий ObsidianUI встроен собственный сервер Model Context Protocol. В отличие от тяжёлых облачных интеграций, он работает локально через стандартные потоки ввода-вывода (stdio), гарантируя нулевую сетевую задержку и отсутствие утечек контекста.
# Клонирование и локальный запуск MCP-сервера
git clone https://gitlab.com/Atharvsinh-codez/ObsidianUI.git
cd ObsidianUI
npm ci
npm run registry:build
npm run mcpСервер объявляет протокол ресурсов obsidian://\{name\}:
resources/list— возвращает агенту полный актуальный реестр доступных блоков;resources/readс URIobsidian://apple-spotlight— мгновенно отдаёт полное дерево исходников, список CSS-переменных и внешних зависимостей.
Сравнение с альтернативами
Чтобы понять место ObsidianUI в экосистеме фронтенда, сопоставим его с ключевыми решениями на рынке:
| Параметр | shadcn/ui | Aceternity UI | Magic UI | ObsidianUI |
|---|---|---|---|---|
| Фокус библиотеки | Надёжные базовые UI-примитивы (доступность, формы) | Зрелищные эффекты для маркетинговых лендингов | Микроанимации и компоненты на Motion для SaaS | Кинематические блоки и шейдеры, оптимизированные для ИИ |
| Модель дистрибуции | Копирование в проект через CLI (реестр) | Копирование кода вручную / CLI | Копирование через CLI | Копирование через shadcn CLI и прямой JSON-манифест |
| Поддержка ИИ-агентов | Базовая (реестр и документация) | Слабая (ориентирован на человека) | Умеренная (Markdown-доки) | Полная: llms.txt, OpenAPI, agent guide, встроенный stdio MCP-сервер |
| Сложные технологии | Radix UI, Tailwind | Three.js, Canvas, Motion | Motion, Canvas | Three.js, GSAP, WebGL, Motion, Canvas API |
| Лицензия | MIT | Free / Commercial Pro | MIT / Pro | Полностью открытый open-source (MIT) |
Практический сценарий: от промпта до готового экрана
Ручной сценарий через терминал
Установка отдельного компонента не требует сторонних пакетов и выполняется через официальный shadcn CLI:
npx shadcn@latest add "https://www.obsidianui.dev/r/apple-spotlight.json"CLI загружает манифест, считывает зависимости (motion, вспомогательные утилиты), скачивает исходники, проверяет совпадение путей с components.json и раскладывает файлы по проекту.
Автономный сценарий в Cursor / Claude Code / Windsurf
В среде с AI-агентом разработка сводится к формулированию функционального и визуального требования в чате редактора:
Собери hero-секцию для продуктового лендинга: заголовок с посимвольным появлением текста и интерактивный фон с динамической spotlight-подсветкой курсора. Возьми компоненты из ObsidianUI, сохрани единую цветовую схему проекта и убедись, что анимация отключается при prefers-reduced-motion.Что происходит под капотом:
- Агент считывает
https://www.obsidianui.dev/llms.txt(или опрашивает локальный MCP-сервер). - Находит манифесты компонентов
apple-spotlightиtext-fill-animation. - Анализирует граф зависимостей и выполняет установку через терминал (
npx shadcn add ...). - Инжектирует компонент в страницу, связывая Tailwind-переменные с системной палитрой проекта.
- Проверяет корректность типов TypeScript и сборку бандла.
Когда использовать
| Сценарий | Вердикт | Инженерное обоснование |
|---|---|---|
| Запуск промо-лендинга, портфолио или презентации продукта | Идеально | Добавление 2–3 выразительных акцентов в hero-блок или витрину фичей привлекает внимание без многодневной ручной верстки шейдеров |
| Разработка в связке с кодинг-агентами (Cursor, Windsurf, Claude) | Идеально | Агент самостоятельно выкачивает манифесты и интегрирует код без ошибок в импортах и необходимости человеку вручную копировать куски из браузера |
| Проекты с жёсткими требованиями к независимости от вендоров | Подходит | Отсутствие монолитного NPM-пакета гарантирует, что вы полностью владеете кодовой базой и не зависите от судьбы репозитория автора |
| Высоконагруженные SaaS-панели, финансовые интерфейсы и CRM | Не рекомендуется | В аналитических интерфейсах критичны плотность данных, низкий TBT (Total Blocking Time) и скорость гидратации; WebGL-сцены и постоянный опрос курсора создают ненужный оверхед |
| Проекты на Vue, Svelte или чистом JavaScript | Не подходит | Библиотека тесно завязана на инфраструктуру React 19, экосистему хуков и директивы Motion; ручной перенос на другой фреймворк экономически неоправдан |
Ограничения
Ограничения
Технические границы, которые стоит учитывать до установки.
Молодость кодовой базы — Проект активно развивается с начала 2026 года.
Несмотря на продуманную архитектуру, библиотека пока не имеет многолетнего продакшен-багажа уровня shadcn/ui. Перед выкаткой на прод каждый блок требует тестирования на нестандартных разрешениях.
Нагрузка на графический процессор (GPU) — Компоненты на базе WebGL, Three.js и GSAP требовательны к оборудованию.
Если злоупотреблять фоновыми 3D-сценами, на смартфонах эконом-класса частота кадров может падать ниже комфортных 60 FPS.
Разделение клиентского и серверного контуров
— Подавляющее большинство блоков используют хуки состояния и события мыши, требуя обязательной директивы 'use client' в Next.js App Router или клиентской директивы client:load в Astro.
Необходимость бэкенд-обвязки для виджетов — Некоторые интерактивные блоки (например, счётчики просмотров или карточки обратной связи) содержат готовую верстку, но требуют реальных серверных эндпоинтов.
Манифест поставляет только клиентский слой.
Зависимость от внешних демо-ассетов — В примерах из манифестов используются сторонние тестовые изображения и видео с публичных CDN.
До релиза их обязательно нужно вычистить и заменить локальными файлами из папки /public.
Антипаттерны
Антипаттерны
Ошибочные ходы, которые приводят к тяжёлой странице или неработающему компоненту.
Ковровое насыщение страницы анимациями — Попытка превратить каждый блок лендинга в 3D-сцену с параллаксом перегружает память браузера и утомляет пользователя.
Визуальные эффекты должны работать точечно: максимум 1–2 выразительных якоря на экран.
Игнорирование доступности (Accessibility) — Копирование кода анимаций без аудита фокуса и клавиатурной навигации ломает UX для пользователей с ограниченными возможностями.
Системный медиа-запрос prefers-reduced-motion обязан принудительно отключать сложные эффекты смещения.
Слепая установка без анализа дерева пакетов — Хотя сама библиотека бесплатна по лицензии MIT, отдельные блоки подтягивают сторонние библиотеки (например, Three.js или плагины GSAP).
Важно отслеживать общий размер бандла приложения при добавлении каждого нового блока.
Попытка обращения к несуществующему облачному MCP — MCP-сервер проекта работает строго локально через stdio из клона репозитория (npm run mcp).
Попытка настроить его как удалённый HTTP-эндпоинт в Claude Desktop или Cursor приведёт к ошибке соединения.
Чеклист
Чеклист
Проверяемые действия перед подключением компонента в проект.
Проектный стек валидирован
— В приложении развёрнуты React, TypeScript, Tailwind CSS v4 и настроен файл конфигурации components.json.
Имя компонента сверено с манифестом
— Идентификатор взят напрямую из официального каталога registry.json без опечаток.
Зависимости установлены в проект
— Все пакеты из секции dependencies манифеста установлены рабочим пакетным менеджером (pnpm, npm или bun).
Внешние медиафайлы локализованы
— Сторонние ссылки на картинки и видео заменены локальными файлами из каталога проекта.
Серверные эндпоинты реализованы
— Если блоку требуются динамические данные, написаны соответствующие серверные роуты (API routes).
Проверен режим prefers-reduced-motion
— В браузере протестировано отключение анимаций для пользователей с вестибулярной чувствительностью.
Проверено потребление ресурсов на мобильных устройствах
— Страница с компонентом протестирована на троттлинге CPU и мобильном вьюпорте.
Ссылки
Ссылки
- Сайт: ObsidianUI — официальный сайт
- Документация: Инструкция для ИИ-агентов
- Каталог: Реестр компонентов registry.json
- Репозиторий: Atharvsinh-codez/ObsidianUI на GitLab