reopt designreopt design
DocsExploreToolsPricingBuilder
Start
Overview
Start
Mission
Core Concepts
Core Concepts
Recipes
Adapters
Build & Operate
Agent Contract
Builder Rollout
Builder Manager
Rollout Playbook
Components · Workspaces
ShellPage
ListWorkspace
DetailWorkspace
EditorWorkspace
DashboardWorkspace
LandingWorkspace
Components · Layout
ShellProvider
ShellAppShell
ShellLandingPage
ShellFullscreenToolSurface
Components · Navigation
ShellCollapsibleNav
ShellNavItem
ShellNavGroup
ShellNavAccordion
Components · Panels
ShellResizableLayout
ShellResizeHandle
ShellBottomBar
ShellFlyoutAside
ShellHeaderStackProvider
Components · Helpers
ShellSection
ShellStateBoundary
ShellSpacing
ShellPolicyToggler
Components · Adapters
ShellDataGridAdapter
ShellEditorAdapter
Oopt-shell
reopt designreopt design

A design system for the AI era

  • Docs
  • Pricing
  • Releases
  • GitHub
  • Terms of Service
  • Privacy Policy

© 2026 reopt-ai. All rights reserved.

Start
  1. Docs
  2. /
  3. Start
  4. /
  5. Start

시작하기

manifest, provider, app shell, 첫 harness page까지 연결하는 빠른 시작 가이드

reopt design · Updated Jun 26, 2026

개요시작하기Mission핵심 개념RecipesAdaptersAgent ContractBuilder RolloutBuilder ManagerRollout Playbook

1. 패키지 연결

opt-shell는 현재 internal-first 패키지입니다. 기존 앱이 이미 opt-ui를 사용하고 있다는 전제에서 그 위에 제품 shell과 state policy를 한 겹 더 얹습니다. 첫 도입에서는 화면 하나를 rollout 대상으로 잡고 시작하는 편이 안전합니다.

bash
bun add @reopt-ai/opt-shell @reopt-ai/opt-palette

# adapter 데모까지 함께 쓸 경우
bun add @reopt-ai/opt-datagrid @reopt-ai/opt-editor

2. manifest 정의

harness의 시작점은 component가 아니라 manifest입니다. 어떤 route group이 있는지, 화면 폭과 density는 무엇인지, loading/empty/error copy를 어떻게 통일할지 먼저 고정합니다.

tsx
import { createShellApp } from "@reopt-ai/opt-shell/core";

export const builderHarness = createShellApp({
  id: "reopt-builder",
  label: "reopt design Builder",
  description:
    "Internal-first harness for the Builder experience, page rhythm, and shared state UX.",
  audience: "internal",
  routeGroups: [
    {
      id: "projects",
      label: "Projects",
      href: "/builder/projects",
    },
    {
      id: "templates",
      label: "Templates",
      href: "/builder/starters",
    },
  ],
  defaults: {
    density: "comfortable",
    contentWidth: "wide",
    navigationMode: "sidebar",
    motionPolicy: "reduced",
    stateLabels: {
      loading: "Builder 화면을 불러오는 중입니다.",
      emptyTitle: "표시할 항목이 없습니다",
      emptyDescription: "새 항목을 만들거나 현재 필터를 조정해 보세요.",
      errorTitle: "Builder 화면을 표시하지 못했습니다",
    },
    adapters: {
      datagrid: { chrome: "card" },
      editor: { chrome: "card" },
    },
  },
});

3. provider와 page shell 연결

`ShellProvider`는 policy를 주입하고, `ShellAppShell`은 앱 수준 frame을, `ShellPage`는 개별 화면의 rhythm을 담당합니다. 첫 적용에서는 header, toolbar, aside만 잡아도 차이가 큽니다.

tsx
import {
  DashboardWorkspace,
  ShellAppShell,
  ShellCollapsibleNav,
  ShellProvider,
  ShellSection,
  ShellStateBoundary,
} from "@reopt-ai/opt-shell";
import { builderHarness } from "@/lib/harness";
import type { ReactNode } from "react";

export function BuilderFrame({
  nav,
  children,
}: {
  nav: ReactNode;
  children: ReactNode;
}) {
  return (
    <ShellProvider manifest={builderHarness}>
      <ShellAppShell nav={<ShellCollapsibleNav>{nav}</ShellCollapsibleNav>}>
        <DashboardWorkspace
          header={<div>Builder Header</div>}
          toolbar={<div>Primary Actions</div>}
          aside={<div>Inspector</div>}
        >
          <ShellStateBoundary loading={false}>
            <ShellSection
              title="Overview"
              description="핵심 지표와 작업 상태를 한 리듬으로 묶습니다."
              frame="card"
            >
              {children}
            </ShellSection>
          </ShellStateBoundary>
        </DashboardWorkspace>
      </ShellAppShell>
    </ShellProvider>
  );
}

4. 운영 surface로 시작하기

지금 Builder에는 `/builder/harnesses`가 붙어 있습니다. 새 harness를 blank draft로 만들고, policy와 recipe 설정을 바꾼 뒤, preview에서 candidate vs active 결과를 비교하고, current draft 기준 fresh design proof를 캡처하고, review note를 남겨 APPROVED가 된 후에만 activation 하는 흐름입니다.

빠른 운영 루프

  1. Draft harness 생성
  2. Policy와 recipe 설정 편집
  3. Preview에서 demo/workspace live 비교
  4. Current draft 기준 fresh PASS proof 캡처
  5. Review note 작성 후 request review
  6. 승인 후 activate, Activity intelligence 확인

중요한 제약

  • draft를 수정하면 기존 approval은 다시 무효가 됩니다.
  • APPROVED 상태가 아니면 active runtime으로 승격할 수 없습니다.
  • current draft에 연결된 fresh PASS proof가 없으면 activate할 수 없습니다.
  • approval 이후 수정하면 이전 proof도 stale이 되어 다시 캡처해야 합니다.
  • activity feed는 searchable timeline/learnings와 exportable intelligence snapshot까지 남겨야 합니다.

새 route를 추가할 때는 `opt-shell scaffold`로 page, fixture, guard-matrix sidecar를 함께 만들고 `check`로 generated docs와 scaffold bundle drift를 먼저 확인하는 편이 안전합니다.

5. 첫 번째 적용 대상을 고르는 기준

좋은 첫 타깃

  • 페이지 골격은 반복되는데 주변 chrome이 흔들리는 화면
  • loading / empty / error 표현이 자주 달라지는 화면
  • DataGrid나 Editor 주위에 toolbar, inspector가 붙는 화면

첫 타깃으로 피할 것

  • 도메인 로직과 레이아웃 개편이 동시에 필요한 화면
  • 아직 정보 구조 자체가 정리되지 않은 실험 화면
  • 엔진 교체까지 같이 진행해야 하는 복합 마이그레이션

실제 적용 순서는 Rollout Playbook에 정리했습니다.

PreviousOverviewopt-ui 위에서 제품 shell, page rhythm, 상태 UX, adapter 경계를 고정하는 harness layer 개요Start
Go to Overview
NextMissionopt-shell를 design harness engineering layer로 정의하고 소유 경계를 정리합니다.Start