Начало работы

Это руководство содержит основные сведения о добавлении компонентов Oracul DS в ваше React-приложение.

Предварительные требования

Наши компоненты построены с использованием Tailwind CSS v4. Прежде чем начать, убедитесь, что в вашем React-проекте настроен Tailwind CSS.

Добавление компонентов

Вы можете добавлять компоненты автоматически с помощью shadcn CLI или вручную, копируя файлы. Оба метода подходят для примитивов, частиц и атомов.

С помощью CLI

На странице каждого компонента есть команда для его автоматического добавления в ваш проект. CLI создаст необходимые файлы и установит все нужные зависимости.

Настройка нового проекта (рекомендуется)

[!IMPORTANT] Порядок шагов важен. Команда init @oracul/style работает только если в проекте уже есть components.json с описанным реестром @oracul. Иначе CLI выдаст Unknown registry "@oracul". Поэтому сначала создаём components.json, потом запускаем установку через add.

Шаг 1. Создайте components.json в корне проекта со ссылкой на реестр @oracul:

Copy{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "baseColor": "neutral",
    "css": "app/globals.css",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui"
  },
  "registries": {
    "@oracul": "https://ds.oracul.co/ui/r/{name}.json"
  }
}

Шаг 2. Установите всё одной командой (внизу можно переключиться между npm / pnpm / yarn / bun):

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @oracul/style
Копировать

Эта команда установит все UI-компоненты, систему нейтральных цветов, переменные боковой панели (sidebar) и базовые стили. Она также добавит шрифты Inter (--font-sans, --font-heading) и Geist Mono (--font-mono), автоматически настроив их в вашем layout.tsx.

[!TIP] Перезапись файлов. Если CLI спрашивает «overwrite?» даже при флаге --yes, используйте --force. Флаг --yes отвечает «да» на стандартные вопросы, но не подавляет промпт перезаписи существующих файлов — для этого нужен --force.

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @oracul/style --force
Копировать

Альтернатива: init напрямую с URL пресета

Если в проекте ещё нет components.json, можно инициализировать всё одной командой, передав CLI полный URL пресета (а не короткий @oracul/style):

bunnpmpnpmyarn
pnpm dlx shadcn@latest init https://ds.oracul.co/ui/r/style.json
Копировать

CLI сам создаст components.json и подтянет реестр @oracul. После этого короткие команды (add @oracul/button) начнут работать.

Существующие проекты

Если у вас уже настроен components.json (см. шаг 1 выше), просто выполните:

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @oracul/ui
Копировать

Это добавит все примитивы UI (Button, Card, Avatar, Dialog, Tabs и многое другое). Для установки полной темы, включая цвета, боковую панель и шрифты:

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @oracul/style
Копировать

Или добавьте только цветовые токены:

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @oracul/ui @oracul/colors-neutral
Копировать

Подробности можно найти в руководстве по Стилям.

Настройка реестра (детали components.json)

Чтобы короткие команды типа add @oracul/ui работали, файл components.json обязан содержать поле registries с реестром @oracul. Если вы только что создали проект, см. Шаг 1 выше — там уже валидный пример. Если правите существующий файл, добавьте секцию registries:

Copy{
  "registries": {
    "@oracul": "https://ds.oracul.co/ui/r/{name}.json"
  }
}

Проверить конфигурацию можно командой:

Copybun run validate:components

Подробнее — в Руководстве по components.json.

[!IMPORTANT]

1. Используйте именно ключ registries (во множественном числе).
2. URL должен заканчиваться на /{name}.json.
3. Если вы используете Tailwind v4, поле config в секции tailwind должно быть удалено.

После этого вы сможете устанавливать любые компоненты, используя короткий префикс:

bunnpmpnpmyarn
pnpm dlx shadcn@latest add @oracul/button
Копировать

Вручную

1. Найдите компонент на страницах Components или Particles.
2. Скопируйте код из вкладки Code.
3. Создайте новый файл в вашем проекте (например, components/ui/button.tsx) и вставьте код.
4. Установите все зависимости, указанные на странице компонента.
5. Импортируйте и используйте компонент в вашем приложении.

Стилизация

Компоненты стилизованы с использованием системы дизайн-токенов, которая определяется переменными CSS и реализуется с помощью Tailwind CSS.

Эти переменные аналогичны используемым в shadcn/ui и полностью настраиваемы. Вы можете изменить их в своем глобальном файле стилей (например, app/globals.css).

Мы ввели несколько дополнительных токенов для более тонкого контроля:

• --destructive-foreground: Используется для кнопок удаления с контуром, пунктов меню удаления, бейджей и ошибок полей.
• --info и --info-foreground: Для информационных бейджей, уведомлений (toast) и алертов.
• --success и --success-foreground: Для компонентов со статусом успеха.
• --warning и --warning-foreground: Для предупреждающих компонентов.

Важно: При ручном импорте компонентов вы должны также добавить эти токены в ваш CSS файл. При использовании CLI они будут настроены автоматически.

Шрифты

Компоненты Oracul DS используют три свойства CSS для типографики:

• --font-sans — Основной текст, кнопки, метки и большинство элементов интерфейса.
• --font-mono — Блоки кода, <kbd>, моноширинный текст.
• --font-heading — Заголовки диалогов (по умолчанию Inter, как и --font-sans).

При использовании @oracul/style шрифты устанавливаются и настраиваются в layout.tsx автоматически.

Экспорт примитивов

Компоненты, оборачивающие примитивы Base UI, повторно экспортируют базовый примитив. Используйте стилизованный компонент, когда подходят наши настройки, или примитив, когда вам нужна другая композиция или стилизация.

Copyimport { Slider, SliderValue, SliderPrimitive } from "@oracul/ui/components/slider";

Повторный экспорт Base UI

Когда вам нужны только useRender, mergeProps, CSPProvider или DirectionProvider, импортируйте их из @oracul/ui/base-ui/* вместо прямого добавления @base-ui/react:

• @oracul/ui/base-ui/use-render
• @oracul/ui/base-ui/merge-props
• @oracul/ui/base-ui/csp-provider
• @oracul/ui/base-ui/direction-provider

Это особенно полезно в монорепозиториях, чтобы избежать дублирования установок и держать версии синхронизированными.

Работа с LLM (ИИ-моделями)

Мы структурируем документацию так, чтобы компоненты были удобны для ИИ (AI-friendly). Для этого мы включили:

• Навыки агента (Agent Skills) — Установите знания о проекте прямо в ваш ИИ-ассистент с помощью npx skills add oracul-ds/oracul. Это охватывает все 53 примитива, конвенции стилизации и паттерны.
• Файл llms.txt, который предоставляет карту документации и структуры компонентов для вашего ИИ-агента.
• Кнопку Copy Markdown на каждой странице для удобной передачи контента в рабочие процессы ИИ.
• Registry API — Получайте исходный код любого компонента через GET /api/registry/[component]. Удобно для агентов, которые добавляют компоненты в проект программно.