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.

frontend/agent/src/App.tsx
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 to entry.js with 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.

Existing Vue apps

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.

Esc