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으로 만들어요.
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 앱은 그대로 두고, React로 옮기는 것은 새로 쓰고 새로 검증하는 별도 작업이에요.