@reopt-ai/opt-ui

접근성 우선 UI 컴포넌트 라이브러리. opt-ui-primitives 기반 Core, 비즈니스 Shells, Surface/block layout primitives를 제공합니다. 페이지 템플릿 Surface는 @reopt-ai/opt-cli registry로 설치하며, 차트와 데이터 시각화 컴포넌트는 @reopt-ai/opt-charts로 분리되었습니다.

에이전트 스킬로 설정하기 (권장)

소비자 프로젝트 루트에서 전용 스킬을 설치합니다.

npx skills add reopt-ai/reopt-skills/opt-ui-install

설치 후 에이전트에게 opt-ui-install 스킬로 이 프로젝트에 @reopt-ai/opt-ui를 설정하고 검증해줘라고 요청하세요. 스킬은 신규 설치와 업그레이드를 구분하고, AGENTS.md(없으면 CLAUDE.md)의 reopt marker 블록, Tailwind v4, OptThemeProvider, opt doctor, Surface 흐름을 멱등하게 설정합니다. 스킬 소스는 reopt-ai/reopt-skills가 단일 기준입니다.

아래 설치 명령은 스킬을 사용할 수 없거나 모든 단계를 직접 통제할 때의 수동 대안입니다.

설치

bun add @reopt-ai/opt-ui

Peer Dependencies

| 패키지 | 필수 | | ------------------- | ---- | | react ^19.0.0 | Yes | | react-dom ^19.0.0 | Yes |

Optional Peer Dependencies

| 패키지 | 용도 | | ---------------------------- | --------------------------------- | | next >=16.0.0 | SidebarNav, RouteFocusManager | | @codemirror/view | SqlEditor | | @codemirror/state | SqlEditor | | @codemirror/lang-sql | SqlEditor | | @codemirror/theme-one-dark | SqlEditor |

컴포넌트 계층

Core (55)  →  Shells (79)  →  Blocks via opt-cli
 primitives     비즈니스 조합     페이지 템플릿 설치

opt-charts (21) → 데이터 시각화와 chart-specific shells

Core (55개)

접근성 프리미티브 + Tailwind 스타일. 단일 책임 primitive 컴포넌트.

Button, Badge, Input, Textarea, Switch, Checkbox, CheckboxGroup, RadioGroup, Radio, Select, Combobox, Dialog, Disclosure, Accordion, Tabs, Menu, Menubar, Toolbar, Tooltip, Form (FormInput, FormTextarea, FormSelect, FormSwitch), Popover, DropdownMenu, Drawer, NumberInput, OtpField, Kbd, StatCard, Avatar, AvatarGroup, Progress, CircularProgress, Spinner, Alert, Skeleton, Separator, Breadcrumb, EmptyState, Card, DateRangePicker, TagInput, Toggle, ColorPicker, IconPicker, StepBuilder, ConditionBuilder, CompositeZone, SurfaceLayout, createSurface, PageHeader, ScrollArea, Container, Section, Resizable (PanelGroup/Panel/Handle), Logo

Charts / Visuals

차트 컴포넌트는 @reopt-ai/opt-charts에서 직접 import합니다. @reopt-ai/opt-ui/visuals는 기존 소비자를 위한 deprecated compatibility re-export입니다.

ChartContainer, ChartTooltip, ChartLegend, LineChart, BarChart, AreaChart, Sparkline, PieChart, ScatterChart, ComparisonChart, GaugeChart, FunnelChart, RetentionHeatmap, SankeyChart

Shells (79개)

Core 조합 + 비즈니스 로직.

대표 컴포넌트:

CommandPalette, CommandPaletteTrigger, DashboardGrid, SearchCombobox, StatusSelect, AppMenubar, SidebarNav, EditorToolbar, ContentTabs, FaqAccordion, SettingsForm, AuthForm, DynamicFieldForm, FileUploadForm, WizardForm, DeploymentTimeline, ProjectSwitcher, EnvPanel, BranchSelect, DomainTable, DataTable, NotificationToast, TaskList, ActivityFeed, FilterBar, QuickActions, TeamMemberList, EventIcon, ConnectionIndicator, FloatingActionBar, TemplatePicker, CodeSnippetViewer, PropertyExplorer, QueryResultsTable, AlertBuilder, SqlEditor, EventMetaEditor, WidgetGrid, ReportBuilder, SegmentBuilder, InsightsPanel, TimeRangeSelector, ExportButton, LoadingOverlay, SummaryRow, ComparisonSelector, ThemeSwitcher, PromptTemplate, Sidebar, AppShell, DesignGuidePanel

전체 목록은 COMPONENT_CATALOG.md 또는 generated docs의 02-components/03-shells.md를 기준으로 확인합니다.

Surface / Block templates

Shells 조합 페이지 템플릿은 runtime export가 아니라 copy-paste block registry로 제공합니다. 템플릿 내부에서는 SurfaceLayout/createSurface로 구조적 일관성을 유지합니다.

전체 Surface 레지스트리는 npx @reopt-ai/opt-cli surface add <slug> 으로 프로젝트에 설치합니다.

사용법

// 전체 패키지에서 import
import { Button, Badge, Input } from "@reopt-ai/opt-ui";
import { DataTable, FilterBar } from "@reopt-ai/opt-ui";
import { LineChart, BarChart } from "@reopt-ai/opt-charts";

// 또는 계층별 서브패스로 import
import { Button, Badge } from "@reopt-ai/opt-ui/core";
import { LineChart, BarChart } from "@reopt-ai/opt-charts/visuals";
import { DataTable, FilterBar } from "@reopt-ai/opt-ui/shells";

기본 예시

import {
  Card,
  CardHeader,
  CardTitle,
  CardContent,
  Button,
  Badge,
} from "@reopt-ai/opt-ui";

function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Dashboard</CardTitle>
      </CardHeader>
      <CardContent>
        <Badge variant="success">Active</Badge>
        <Button onClick={() => console.log("clicked")}>Action</Button>
      </CardContent>
    </Card>
  );
}

차트 예시

import { LineChart, ChartContainer } from "@reopt-ai/opt-charts";

const data = [
  { name: "Jan", revenue: 4000, users: 2400 },
  { name: "Feb", revenue: 3000, users: 1398 },
];

const series = [
  { dataKey: "revenue", name: "Revenue", color: "#8884d8" },
  { dataKey: "users", name: "Users", color: "#82ca9d" },
];

<ChartContainer height={300}>
  <LineChart data={data} series={series} />
</ChartContainer>;

Block template 설치

npx @reopt-ai/opt-cli surface add data-explorer

테마 프리셋

5개 시그니처 프리셋 CSS를 제공합니다. 각 프리셋은 [data-theme] 셀렉터 기반 CSS 변수를 정의합니다.

/* 원하는 프리셋을 import */
@import "@reopt-ai/opt-ui/theme/presets/default.css";
@import "@reopt-ai/opt-ui/theme/presets/minimal.css";
@import "@reopt-ai/opt-ui/theme/presets/natural.css";
@import "@reopt-ai/opt-ui/theme/presets/pro.css";
@import "@reopt-ai/opt-ui/theme/presets/mono-dark.css";

| 프리셋 | 특징 | | ----------- | -------------------------------------------- | | default | 뉴트럴 블루 계열, 범용 | | minimal | 모노톤, 미니멀, 샤프 엣지 | | natural | Playfair Display + Lora, force-light | | pro | Geist Mono 헤딩, 네온 블루, 고밀도 | | mono-dark | OLED 친화 블랙, 네온 시안, 신택스 하이라이트 |

이전 버전의 corporate/playful 프리셋은 제거되었습니다. localStorage에 남은 값은 default로 자동 마이그레이션됩니다. 기존 시각적 톤을 유지하려면 OptThemeProvider의 generated 모드 또는 ThemeBuilder로 직접 시드를 정의해 재현할 수 있습니다.

OptThemeProvider와 ThemeSwitcher로 런타임 프리셋 + 라이트/다크 모드 전환을 지원합니다.

디자인 토큰

CSS 변수 기반 시맨틱 토큰 — dark: 프리픽스 없이 자동 전환:

| 토큰 | 용도 | | -------------------- | -------------- | | OPT_INPUT | 입력 필드 | | OPT_FOCUS_VISIBLE | 포커스 링 | | OPT_SURFACE | 카드/패널 배경 | | OPT_BORDER | 테두리 | | OPT_TEXT_PRIMARY | 주요 텍스트 | | OPT_TEXT_SECONDARY | 보조 텍스트 |

시맨틱 스페이싱

| CSS 변수 | Tailwind | 값 | | --------------------- | -------------------------- | ------------- | | --opt-space-section | gap-section, p-section | 1.5rem (24px) | | --opt-space-group | gap-group, p-group | 1rem (16px) | | --opt-space-element | gap-element, p-element | 0.5rem (8px) |

Block 루트는 반드시 BlockLayout을 사용합니다. 페이지 콘텐츠 경계를 Block이 직접 맡을 때는 inset="section"을 지정하고, 카드나 Shell이 이미 여백을 제공하는 embedded Block에서는 inset을 생략합니다. PageHeader는 재사용 가능한 콘텐츠 헤더이므로 바깥 여백을 소유하지 않습니다.

접근성

• opt-ui-primitives 기반 ARIA 역할/상태 관리
• 모든 인터랙티브 요소에 포커스 링
• Roving tabindex (CompositeZone, DataTable, SidebarNav)
• Focus trap (Dialog)
• Spatial Navigation 엔진 (SpatialNavProvider)
• 키보드: Tab, Arrow, Enter, Space, Escape

빌드

# 빌드만
bun run build

# 타입 체크
bun run typecheck

# 린트
bun run lint

배포

이 패키지는 npmjs.org에 public으로 배포됩니다. 유지보수자 배포는 직접 npm publish 또는 bun run release*를 사용하지 않고 design-publish 워크플로우만 사용합니다.

/design-publish opt-ui

• npm registry publish 권한과 2FA 또는 automation token이 필요합니다.
• Surface 또는 registry 입력이 바뀌면 @reopt-ai/opt-cli와 함께 배포합니다.
• @reopt-ai/opt-ui-primitives는 런타임 의존성이므로 publish-safe 버전으로 함께 검증합니다.
• CI는 publish snapshot과 generated artifact(registry.json, COMPONENT_CATALOG.md) freshness를 확인합니다.

테스트

bun run test
bun run validate:test-coverage
bun run test:coverage

bun run test는 Vitest 실행 후 scripts/validate-test-coverage.ts를 이어서 실행합니다. 이 검증은 src/*/_meta.ts의 158개 ComponentMeta가 모두 testDescribe를 갖고, 해당 이름의 describe(...) 블록이 테스트 파일에 존재하는지 확인합니다.

Design Decisions

• Layer metaphor: Core → Shells는 opt-ui가 맡고, 페이지 템플릿 Surface는 opt-cli block registry로 설치
• BlockLayout 강제: block template은 반드시 BlockLayout 또는 createBlock을 사용하고, 페이지 경계는 inset="section"으로 명시
• Subpath exports: ./core, ./visuals, ./shells — 필요한 계층만 import 가능
• Dual format: ESM + CJS — 모든 번들러/런타임 호환
• Source maps: 디버깅을 위한 소스맵 포함
• Tree-shakeable: splitting: true + ESM — 사용하는 컴포넌트만 번들에 포함
• "use client" 배너: 모든 빌드 출력에 "use client" 지시문 자동 주입
• External all: 런타임 의존성 전부 external — 모노레포 앱에서 중복 번들 방지
• Optional heavy deps: CodeMirror, Next.js는 optional peer — 사용하지 않으면 설치 불필요
• CSS variable theming: 5개 프리셋 × light/dark compound themes, dark: 없이 CSS 변수로 자동 전환

License

MIT