Golden Image
Frontend and design system
New apps use React and draw screens with the UI kit (src/ui/) and --ms-* tokens. They follow the host's theme and language.
Entry point and host
frontend/agent/src/entry.ts keeps the host's mount/unmount ES-module contract and wraps the app in MothershipProvider. Leave it as it is. Apps run in an opaque-origin iframe; sessions and keys stay in the host, and apps reach the API only through the scoped SDK bridge. CSP restricts the app's network calls to the Mothership origin.
Getting started
Wrap the top of App.tsx in UiFrame, and build pages and sections from Page, PageHeader and Section.
import { Button, EmptyState, Page, PageHeader, Section, UiFrame } from "./ui";
export default function App() {
return (
<UiFrame>
<Page>
<PageHeader title="Contract review" description="Pick a contract to review." />
<Section title="Contracts" actions={<Button variant="primary">Add contract</Button>}>
<EmptyState title="No contracts yet">Contracts you add appear here.</EmptyState>
</Section>
</Page>
</UiFrame>
);
}
Without UiFrame, Select and Dialog don't open.
Components
| Need | Component | How |
|---|---|---|
| Action | Button |
One primary per screen or section. secondary by default, ghost for minor ones, danger for the irreversible |
| Input | Field + Input/TextArea |
Connects label, hint/error and aria-* |
| Choice | Select |
options={[{ value, label }]}; keyboard and search included |
| Toggle | Checkbox |
Pass a label |
| Files | FileButton |
Never shows the browser's raw file input |
| Switching views | Tabs |
Panels are role="tabpanel" |
| Confirmation | ConfirmDialog |
Shows failures inside the dialog and lets people retry |
| Dialog | Dialog |
Focus trap, Escape, outside click |
| Status | Badge |
ok/warn/danger/info/accent, live while in progress |
| Failure, notice | Alert |
Failures offer a retry action |
| Empty, loading | EmptyState, Loading |
One sentence saying what to do next |
For work that reads the current value across an await (save retries, streaming, run recovery), use useLiveState.
Tokens and theme
Screens are drawn with scoped --ms-* tokens. The defaults are Galpi's zinc palette, overridden by the tokens the host sends and its host:theme-changed events, so Mothership's light and dark apply to the app too. No hard-coded colours, no fonts or scripts from a CDN.
- Font: Pretendard Variable (SIL OFL 1.1) ships in
src/ui/fonts/, and the build emits it next toentry.jswith its licence. The same build works on a closed network. - Language: write UI text in Korean (the message id) and the English in
i18n-en.ts. It shows in the language the host says the person uses.
Tests
frontend/agent/test/ mounts the production bundle in jsdom and drives real workflows against a recording host. Both profiles carry their own copy of src/ui/; scripts/tests/test_ui_kit_sync.py keeps the copies identical.
Vue apps made from earlier profiles stay as they are. Moving one to React is a rewrite and a fresh validation, done as its own work.