시작하기
manifest, provider, app shell, 첫 harness page까지 연결하는 빠른 시작 가이드
reopt designUpdated
1. 패키지 연결
opt-shell는 현재 internal-first 패키지입니다. 기존 앱이 이미 opt-ui를 사용하고 있다는 전제에서 그 위에 제품 shell과 state policy를 한 겹 더 얹습니다. 첫 도입에서는 화면 하나를 rollout 대상으로 잡고 시작하는 편이 안전합니다.
bun add @reopt-ai/opt-shell @reopt-ai/opt-palette
# adapter 데모까지 함께 쓸 경우
bun add @reopt-ai/opt-datagrid @reopt-ai/opt-editor2. manifest 정의
harness의 시작점은 component가 아니라 manifest입니다. 어떤 route group이 있는지, 화면 폭과 density는 무엇인지, loading/empty/error copy를 어떻게 통일할지 먼저 고정합니다.
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만 잡아도 차이가 큽니다.
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 하는 흐름입니다.
빠른 운영 루프
- Draft harness 생성
- Policy와 recipe 설정 편집
- Preview에서 demo/workspace live 비교
- Current draft 기준 fresh PASS proof 캡처
- Review note 작성 후 request review
- 승인 후 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에 정리했습니다.