Golden Image

프런트엔드와 디자인 시스템

새 앱은 React로 만들고, UI 킷(src/ui/)의 부품과 --ms-* 토큰으로 화면을 그려요. 호스트의 테마와 언어를 그대로 받아요.

진입점과 호스트

frontend/agent/src/entry.ts는 호스트의 mount/unmount ES 모듈 계약을 지키고 앱을 MothershipProvider로 감싸요. 그대로 둬요. 앱은 불투명 출처의 iframe에서 돌고, 세션·키는 호스트에 있고, 앱은 범위가 정해진 SDK 다리로만 API를 불러요. CSP가 앱의 네트워크 호출을 Mothership 출처로 묶어요.

시작하기

App.tsx의 맨 위를 UiFrame으로 감싸고, 페이지와 절은 Page, PageHeader, Section으로 만들어요.

frontend/agent/src/App.tsx
import { Button, EmptyState, Page, PageHeader, Section, UiFrame } from "./ui";

export default function App() {
  return (
    <UiFrame>
      <Page>
        <PageHeader title="계약 검토" description="검토할 계약을 고르세요." />
        <Section title="계약" actions={<Button variant="primary">계약 추가</Button>}>
          <EmptyState title="아직 계약이 없습니다">계약을 추가하면 여기에 표시됩니다.</EmptyState>
        </Section>
      </Page>
    </UiFrame>
  );
}

UiFrame이 없으면 Select와 Dialog가 열리지 않아요.

컴포넌트

필요한 것 컴포넌트 쓰는 법
동작 Button primary는 화면·절마다 하나. 기본 secondary, 보조 ghost, 되돌릴 수 없으면 danger
입력 Field + Input/TextArea 라벨, hint/error, aria-*를 이어 줘요
선택 Select options={[{ value, label }]}. 키보드와 검색 입력 포함
켜고 끄기 Checkbox label을 함께
파일 FileButton 브라우저 기본 파일 입력을 보이지 않아요
화면 전환 Tabs 패널은 role="tabpanel"
확인 ConfirmDialog 실패하면 대화상자 안에 이유를 보이고 다시 시도
대화상자 Dialog 포커스 가두기, Escape, 바깥 클릭
상태 Badge ok/warn/danger/info/accent, 진행 중이면 live
실패·안내 Alert 실패는 action으로 다시 시도
비어 있음, 불러오는 중 EmptyState, Loading 다음에 할 일을 한 문장으로

await를 건너 지금 값을 읽어야 하는 작업(저장 재시도, 스트리밍, 실행 복구)은 useLiveState를 써요.

토큰과 테마

화면은 범위가 정해진 --ms-* 토큰으로 그려요. 기본값은 갈피의 zinc 팔레트이고, 호스트가 보낸 토큰과 host:theme-changed 이벤트가 덮어써요. 그래서 Mothership의 밝게·어둡게가 앱에도 그대로 적용돼요. 하드코딩한 색, CDN 글꼴·스크립트는 쓰지 않아요.

  • 글꼴: Pretendard Variable(SIL OFL 1.1)이 src/ui/fonts/에 들어 있고, 빌드가 entry.js 옆에 라이선스와 함께 내보내요. 폐쇄망에서도 같은 빌드가 돌아요.
  • 언어: 화면 문구는 한국어로 쓰고(메시지 id), 영어는 i18n-en.ts에 둬요. 호스트가 알려 준 사람의 언어로 보여요.

시험

frontend/agent/test/는 운영 번들을 jsdom에 올리고 기록하는 호스트에 대고 실제 흐름을 돌려요. 두 프로필이 src/ui/ 사본을 따로 갖고 있어서 scripts/tests/test_ui_kit_sync.py가 두 사본이 같은지 확인해요.

기존 Vue 앱

예전 프로필로 만든 Vue 앱은 그대로 두고, React로 옮기는 것은 새로 쓰고 새로 검증하는 별도 작업이에요.

Esc