Для ИИ-агентов

Как ИИ-агент может получить исходный код любого компонента Oracul DS через API с минимальными затратами токенов.

Если вы — ИИ-агент и вам нужно добавить компонент Oracul DS в проект пользователя, используйте registry API. Он возвращает полный исходный код компонентов и компактные метаданные, готовые для вставки в проект.

Стратегия минимизации токенов

Выбирайте endpoint в зависимости от задачи:

Задача	Endpoint	Размер ответа
Понять что есть в библиотеке	`GET /api/registry`	~1 КБ
Узнать API компонента (варианты, пропсы)	`GET /api/registry/[name]/meta`	~0.5 КБ
Скопировать компонент в проект	`GET /api/registry/[name]`	~5–30 КБ
Обзор всей библиотеки сразу	`GET /api/registry/cheatsheet`	~40 КБ

Рекомендуемый порядок:

Загрузи /api/registry/cheatsheet один раз в начале сессии — получишь API всех компонентов без исходников
Используй /api/registry/[name] только когда нужно скопировать файл в проект
Никогда не читай исходники только чтобы узнать пропсы — используй /meta

Эндпоинты

GET https://ds.oracul.co/ui/api/registry
GET https://ds.oracul.co/ui/api/registry/cheatsheet
GET https://ds.oracul.co/ui/api/registry/[component]
GET https://ds.oracul.co/ui/api/registry/[component]/meta

/api/registry — список компонентов

curl https://ds.oracul.co/ui/api/registry

{
  "components": ["accordion", "alert", "button", "card", ...],
  "total": 53,
  "baseUrl": "/api/registry"
}

/api/registry/cheatsheet — вся библиотека кратко

Один запрос вместо 53. Загружай в начале сессии.

curl https://ds.oracul.co/ui/api/registry/cheatsheet

{
  "total": 53,
  "hint": "Use /api/registry/[name] for full source",
  "components": [
    {
      "name": "button",
      "exports": ["Button", "buttonVariants"],
      "variants": {
        "variant": ["default", "outline", "ghost", "secondary", "destructive", "destructive-outline", "link"],
        "size": ["xs", "sm", "default", "lg", "xl", "icon", "icon-xs", "icon-sm", "icon-lg", "icon-xl"]
      },
      "props": ["variant", "size", "loading", "render"],
      "import": "import { Button, buttonVariants } from \"@oracul/ui/components/button\""
    },
    ...
  ]
}

/api/registry/[component]/meta — API компонента

Используй когда нужно знать варианты и пропсы, но не нужен исходник.

curl https://ds.oracul.co/ui/api/registry/button/meta

{
  "name": "button",
  "exports": ["Button", "buttonVariants"],
  "variants": {
    "variant": ["default", "outline", "ghost", "secondary", "destructive", "destructive-outline", "link"],
    "size": ["xs", "sm", "default", "lg", "xl", "icon", "icon-xs", "icon-sm", "icon-lg", "icon-xl"]
  },
  "props": ["variant", "size", "loading", "render"],
  "import": "import { Button } from \"@oracul/ui/components/button\""
}

/api/registry/[component] — полный исходник

Используй только когда нужно скопировать файл в проект.

curl https://ds.oracul.co/ui/api/registry/button

{
  "name": "button",
  "source": "\"use client\";\n\nimport { mergeProps } ...",
  "import": "import { } from \"@oracul/ui/components/button\""
}

Как добавить компонент в проект

Проверь что компонент существует и узнай его API через /meta
Получи исходник через /api/registry/[name]
Создай файл components/ui/[name].tsx и вставь source
Установи зависимости (указаны в импортах внутри source)
Импортируй компонент из этого файла

Пример: добавить Button в проект

// 1. Проверить API (дёшево — ~0.5 КБ)
const meta = await fetch("https://ds.oracul.co/ui/api/registry/button/meta").then(r => r.json());
// meta.variants.variant → ["default", "outline", "ghost", ...]
 
// 2. Получить исходник (только когда нужно скопировать)
const { source } = await fetch("https://ds.oracul.co/ui/api/registry/button").then(r => r.json());
 
// 3. Записать файл в проект
import { writeFile } from "node:fs/promises";
await writeFile("components/ui/button.tsx", source);

Зависимости

Все компоненты Oracul DS требуют:


pnpm add @base-ui/react class-variance-authority tailwind-merge clsx

Дополнительные зависимости компонентов видны в import-строках внутри source.

Альтернатива: shadcn CLI

Если в проекте настроен components.json с реестром Oracul DS, компоненты можно ставить через CLI без ручного копирования:


pnpm dlx shadcn@latest add @oracul/button

Подробнее о настройке CLI — в разделе Начало работы.

Particles — готовые композиции

В библиотеке есть 486 particles — готовые блоки (формы, карточки, диалоги, тулбары и т.д.), собранные из примитивов. Для большинства задач берите готовый particle вместо ручной композиции.

Задача	Endpoint	Размер
Найти particle по ключевому слову	`GET /api/particles/search?q=carousel`	~1–5 КБ
Все particles одной категории	`GET /api/particles/by-category/card`	~3–10 КБ
Обзор всех categories с описаниями	`GET /api/particles/cheatsheet`	~25 КБ
Полный индекс с тегами и deps	`GET /api/particles`	~120 КБ
Исходник одного particle	`GET /api/particles/[name]`	~2–10 КБ
Все particles inline в одном файле	`GET /llms-full.txt`	~640 КБ

Рекомендуемый порядок:

Используй /api/particles/search?q=<ключевое слово> — самый быстрый способ найти готовый блок (например, q=carousel, q=otp, q=pricing).
Если поиск не дал результата — открой /api/particles/cheatsheet и проверь категории.
Получи исходник через /api/particles/[name] или установи через npx shadcn@latest add @oracul/[name].

# Найти particles с каруселью
curl "https://ds.oracul.co/ui/api/particles/search?q=carousel"
 
# Все card-particles
curl https://ds.oracul.co/ui/api/particles/by-category/card
 
# Установить
npx shadcn@latest add @oracul/p-card-12

Что ищет search: имя файла, описание, категории, и автоматически извлечённые теги — импортированные lucide-иконки, имена примитивов, ключевые слова из описания.

Полный каталог в браузере: /ui/particles. Группированный список со ссылками на JSON — в llms.txt. Полный исходник всех 486 particles — в llms-full.txt.

На этой странице

Стратегия минимизации токенов Эндпоинты /api/registry — список компонентов /api/registry/cheatsheet — вся библиотека кратко /api/registry/[component]/meta — API компонента /api/registry/[component] — полный исходник Как добавить компонент в проект Пример: добавить Button в проект Зависимости Альтернатива: shadcn CLI Particles — готовые композиции