TopxAI desktop uses this interface from 1.55.0; the design is called "Direction A: Paper". The grounds are warm white and warm charcoal, and brand blue appears only on primary buttons, focus, selection and running states. With less blue on the screen, the places that need pressing stand out more. The workspace uses the system font; serif type is kept for launch, sign-in and the Home greeting.

Colour, type sizes, spacing, corners, shadows and control sizes are in tokens.json; tokens.css holds the CSS variables and type classes generated from it. Component styles are in components/bundle.css, with the same class names as the design file. Every component has two previews, preview.html (light) and preview-dark.html (dark), which open straight in a browser with no network. Switching theme only changes data-theme on the html element; component code stays the same.

This is the English edition of version 1.1.1, which is version 1.1 with the addresses changed to api.topxai.xyz. Version 1.1 reviewed the 1.0 design for gaps; what it corrected, what it added and what still needs a design decision are in the last section. The English edition has the same tokens, components and rules, written for English interfaces: English copy rules, status words and button verbs, Instrument Serif display styles, and all nine screens drawn in English. The desktop client follows this spec. TopX Terminal is the spec for the trading terminal; its README section on custom apps no longer applies to the desktop client.

## Copy

The interface talks to people as "you", and says what happened and what they need to do. Count what the agent did: "Ran 1 command, read 2 files". When something needs confirming, ask directly: "Committing needs your OK", with the reason on the next line.

Status words come in two sets. A session has one of four: Running, Needs you, Unread, Idle. A step or a run ends in one of five: Running, Needs you, Done, Failed, Queued; failures give a count: "1 failed". Don't use synonyms such as "In progress", "Processing" or "Waiting".

Errors say what is wrong and how to fix it: "Missing https://. Add it and save again." A toast says only what happened and what you can do: "The Codex process exited", then "Exit code 1; the session stopped at step 3" and a Retry button. An empty state first says why it is empty, then gives a next step people can click.

Button labels are verbs: Allow, Deny, Retry, Update, View changes. When there is a shortcut, write it on the button: "Allow ↵", "Deny esc".

Use one name for each concept, and only where it belongs: "Providers", for example, appears only in navigation and in the page title. A model with no published price shows "Unknown", is left out of totals, and is never counted as 0. A model you can't switch away from says why: "GLM only after switching".

Write in sentence case everywhere: titles, buttons, menu items, tabs and section names ("Pinned", "Sub-sessions"), never Title Case or capitals. Spelling is British (colour, favourites, customise). Contractions are fine ("can't", "doesn't"). Quotation marks and apostrophes are typographic: “Allow”, Claude Code’s.

### Numbers, time and units

- Put a space between a number and its unit: "9.4 GB", "19k tokens", "42 min ago". Short durations are the exception: "8.1s".
- Clock times use 24 hours: "16:04". In the sidebar write "Just now" within the hour, "3h" earlier the same day, "Yesterday" for the day before, and a date such as "Oct 28" before that.
- Durations: under a minute, seconds with one decimal: "8.1s"; above a minute "1:12", "2:41"; above an hour "1:02:41". Waiting works the same way: "Waited 0:12".
- A countdown must never look like a clock time. Write "Expires in 14 min" or "Expires at 15:47", never "14:32 left".
- Tokens: whole numbers below 1,000; above that one decimal and k: "9.8k", "36.3k"; M above a million. Follow with "tokens" ("1 token").
- Money is in US dollars. Usually two decimals: "$0.37"; below a cent, three: "$0.002"; balances get thousands separators: "$1,076.28". A total that includes unknown prices reads "$0.37 + 1 unknown".
- Negative numbers and removed lines use the real minus sign "−" (U+2212), not a hyphen: "+18 −4".
- File sizes read "9.4 GB", progress "5.8 / 9.4 GB"; percentages are rounded: "22%".
- Numbers, durations and money in tables and meta use tabular figures (font-variant-numeric: tabular-nums).

## Colour

Neutrals have three layers. The window ground is bg-app, and the sidebar sits straight on it. The session area and the content of Settings are bg-canvas. Cards, inputs and menus are bg-raised. Recessed places (code blocks, the composer footer, the track of a segmented control) use bg-sunken. Hover uses bg-hover and selection bg-selected. Selection is shown by the ground alone, with no coloured bar on the left. Dialogs sit on an overlay, and selected text gets the selection ground.

Lines have four levels. border-subtle is for dividers inside cards and the outline of blocks in a conversation; border is for the outline of cards, menus, buttons and the composer; border-strong is only for the Idle dot. Form controls (text fields, checkboxes, radios and switches that are off) use control-border, which stays at 3:1 or more on all six grounds so the outline of a control can be seen.

Text has four levels: text for body and headings, text-2 for secondary text and sidebar rows, text-3 for meta, placeholders and help, and text-4 only for disabled states and decorative icons. The first three and accent-text reach at least 4.5:1 on bg-app, bg-canvas, bg-raised, bg-sunken, bg-hover and bg-selected, checked in both themes. text-4 does not, so it never carries text people need to read.

Brand blue (accent) is only for primary buttons, Send, a switch that is on, progress and running states, with on-accent for text on it. Blue text, file paths and links use accent-text. Selected menu items, info tags and info banners have an accent-soft ground; the halo of the Running dot uses accent-soft-2.

Keyboard focus is a 2px solid outline in focus (equal to accent-text), offset 2px, following the corners, and shown only for keyboard use (:focus-visible). The 3px translucent focus-ring glow reaches only 1.4:1 (light) / 1.7:1 (dark) on the ground, so it is decoration that goes with the field's edge colour change, never a focus signal on its own.

State colours come in sets. success, warning and danger each have three steps: the base colour for text and icons, -soft for the ground of tags and banners, and -dot for status dots, progress segments and banner edges. Needs you uses warning; failures and deletions use danger.

In a multi-agent run, members take agent-1 to agent-6 in the order they join, and a member keeps one colour for the whole run. These six colours only tell members apart; they never mean a state.

The sign-in poster and the launch art use the brand panel: brand-panel-1, brand-panel-2 and brand-panel-3 in a 160° gradient with stops at 0%, 46% and 100%. Text on it uses paper, secondary text paper-2, and decoration such as page numbers paper-3.

Code syntax uses syn-keyword, syn-fn, syn-string, syn-type and syn-comment, code text uses code-text, and inline code sits on code-bg.

In a diff, added lines sit on success-soft with a "+" in success at the start; removed lines sit on danger-soft with a "−" in danger; line numbers use text-3. Code text reaches at least 9:1 on both grounds.

ANSI colours in command output map to existing colours, with nothing new: red danger, green success, yellow warning, blue accent-text, magenta syn-keyword, cyan agent-2, white and bright white text, black and bright black text-3; bold is 600.

## Type

The workspace uses the system font font-ui (SF Pro, with PingFang for Chinese). Conversation text is 15/26 (fs-chat), interface text 13/20 (fs-ui), meta 12/18 (fs-small), and sidebar section names and table headers 11/16 at weight 600 (fs-label). Page titles are 20/28 at weight 600 across the app (fs-title); group and empty-state headings are 15/22 at weight 600 (fs-heading).

Serif type appears only on launch, sign-in, the device code and the Home greeting. Chinese interfaces use Noto Serif SC (font-display); English interfaces use Instrument Serif (font-latin), in the English display styles described under English interface. Sessions, Settings and menus never use serif type.

The bundled Noto Serif SC is a subset of 4,695 common characters that covers the brand copy. When the name in a Chinese greeting is Chinese, it stays in upright font-display rather than Instrument Serif italic; characters missing from the subset fall back to the system's serif, so dynamic text other than the greeting never uses font-display.

Code, commands and file paths use JetBrains Mono (font-mono) at 12.5/20 (fs-code) with ligatures off. JetBrains Mono ships with the app (fonts/ has its latin subset), so it doesn't depend on what people have installed. Numbers, durations and money in tables use tabular figures so they line up.

## English interface

English runs wider than Chinese and Instrument Serif is narrower and lighter in colour than Noto Serif SC, so the English interface has its own display styles and a few layout rules. The nine screens in screens/ are drawn with them.

Display type, all in Instrument Serif (font-latin), with tokens in the "Brand, English interface" group of tokens.json:

| Style | Size | Where |
| --- | --- | --- |
| fs-poster-en | 92/92 | The sign-in poster: "Begin anew," then "from here." on a second line, indented 64px and set in italic. |
| fs-greet-en | 48/54 | The Home greeting: "Good afternoon, *alex*", with the name in italic. |
| fs-display-en | 38/44 | Titles of the sign-in and device-code screens. |
| fs-tagline-en | 19/24 italic | "Begin anew, from here." under the wordmark on the launch screen. |

The greeting follows the time of day: "Good morning" until 12:00, "Good afternoon" until 18:00, then "Good evening".

Fitting English into the same layout:

- The composer toolbar is nearly full at 700px (with the side panel open), so its chips keep short labels: "Medium", "Ask when risky". Don't widen chips or wrap the toolbar.
- Session titles in the sidebar truncate with an ellipsis; they never wrap.
- The model menu grows from 478px to 500px in English, and the description under each model fits on one line ("Everyday coding and long chats"). A model with a warning tag may take two.
- Page subtitles in Settings stay on one line next to the page's button.

Words the English interface uses:

- Session status: Running, Needs you, Unread, Idle. Results: Running, Needs you, Done, Failed, Queued.
- Modes: Plan and Run. Reasoning effort: Low, Medium, High. Permissions: Always ask, Ask when risky, Full access.
- Roles in a multi-agent run: Lead, Worker, Errands, Triage. A member's own conversation is a sub-session.
- Sidebar: New session, Search, Customise, Create, Scheduled, On duty, Pinned, Projects, Groups.
- The composer: Context for context use, This computer for the machine, "2 queued" and Send now for the queue.
- Model menu: Favourites, Subagents (Auto, Same model, Local agent), Manage providers.
- Settings: Back to sessions, Providers, Agents, Projects, Memory, Advanced, Prompts, Keyboard, Permissions, Storage, Computer, General.

## Spacing, corners and shadows

Spacing uses multiples of 4 only (sp-1 to sp-12). Controls in one group sit close and groups sit apart; don't use the same gap everywhere. The common steps: 4 between an icon and its text, 8 inside controls, 12 for card padding, 16 between cards, 20 from the composer to the bottom of the window, 24 for the side margins of the session area, 32 between groups in Settings.

Multiples of 4 govern the distance between elements. Sizes inside a component follow that component's guide, such as 9px between icon and label in a sidebar row or a banner's 9px 10px 9px 12px padding; don't round them. Control heights, icon sizes and stroke width are in the size table of tokens.json.

Corners follow size: inline code 4 (r-xs), small buttons and menu items 6 (r-sm), buttons, text fields and sidebar rows 8 (r-md), the 40px button 10 (r-btn-lg, the only value off the scale), cards, menus and the approval card 12 (r-lg), the composer 16 (r-xl), dialogs and large popovers 20 (r-2xl), and tags, avatars and the Send button fully round (r-full).

Shadows have three levels: shadow-1 for secondary buttons and the New session button, shadow-2 for the composer and the approval card, shadow-3 for menus, toasts and dialogs. Dark-theme shadows are heavier and add a 1px inner highlight so cards separate from the ground.

## Layout

The window is designed at 1440×900. The sidebar is 264px (sidebar-w) and the header 52px (header-h), with the centres of the window's traffic lights on the header's midline. Sidebar rows are 32px (row-h); menu items and session rows under a project are 30px (menu-item-h, row-sub-h). The conversation column is 720px (chat-w) and the composer 760px (composer-w); with the 380px side panel open (panel-w) the column narrows to 680px and the composer to 700px.

The smallest window is 1040×640 (window-min-w, window-min-h): just enough for the sidebar, the 720px column and 24px on each side. Below 1372px wide (sidebar 264 + column 680 + margins 48 + panel 380), the side panel covers the session area with shadow-3 instead of squeezing the column. Below 1040px the sidebar hides, and the button at the top left of the header brings it back.

The header is the window's drag area; its buttons, breadcrumbs and fields don't drag. Stacking from bottom to top: the conversation, the Dock and the composer, menus and the model menu, dialogs and their overlay, toasts, tooltips.

Approvals, questions and the queue above the composer share one card (Dock), with what needs you most at the top and only one primary button per card. Tool calls fold into one line by default and open by themselves when a step fails (ToolGroup). Settings has two columns: navigation on the left, and on the right one row per provider that opens in place, with no cards inside cards.

1.55.0 ships for macOS only. When a Windows version comes, the window buttons move to the top right of the header and ⌘ in shortcuts becomes Ctrl, written "Ctrl+N".

## States

Loading uses only a brand-blue spinner or progress bar, with a sentence beside it saying what is happening (see Progress). While a button waits for a result, the icon before its label becomes a spinner, the label stays the same and the button is disabled; don't change the label to "Loading…".

When the network drops, a warning banner at the top of the session says "Connection lost. Reconnecting…" with Retry; Send is disabled and the text in the composer is kept. The banner goes away by itself once the connection is back.

When the TopxAI provider runs out of balance, a failure banner above the composer says "Not enough balance; this turn wasn't sent", with the current balance as its explanation and Top up as its action, which opens the top-up page on api.topxai.xyz. The unsent message stays in the composer.

Upstream errors (rate limits, overload, timeouts) are written under that turn's reply: one line of reason plus Retry, such as "Claude is busy right now. Try again in 20s.", never a toast. When you stop a turn or the process exits, the end of the turn says "Stopped" or "Interrupted", and what was already generated stays.

When the window is in the background, only Needs you and a finished run send system notifications. The Dock icon badge counts the sessions that need you.

## Accessibility

Contrast: text people read is at least 4.5:1; control outlines, focus outlines and icons people need to recognise are at least 3:1. Both themes must meet this. Values that can't are explained in tokens.json (agent-*, paper-2, paper-3, text-4).

Never colour alone: status dots have a status word beside them, line counts carry "+" and "−", failed steps carry an icon and an exit code, and a member's name is always next to their avatar.

Keyboard: everything that can be clicked can be reached with Tab; for the focus outline see Colour. Menus, the model menu and tab bars move with the arrow keys; ↵ picks and esc closes and returns focus to the button that opened them. Focus stays inside an open dialog.

Screen readers: an icon-only button has an aria-label with the same words as its Tooltip. Changes in session state and toasts are announced with aria-live="polite", and the approval card with assertive. Streaming text is not read out word by word; it is read once when the turn ends.

With Increase contrast on, border and border-subtle switch to control-border. For Reduce motion see Motion.

## Shortcuts

Shortcuts that appear in the design are written with Kbd in buttons, menus and tooltips:

| Key | Does |
| --- | --- |
| ⌘N | New session |
| ⌘K | Search sessions |
| ⌘M | Open the model menu |
| ⌘1 to ⌘4 | Switch to favourite model 1 to 4 |
| F2 | Rename the session |
| ↵ | Send; on the approval card, Allow |
| esc | Close a menu; on the approval card, Deny |

## Motion

Three durations: dur-fast (120ms) for hover, press and switches; dur-base (180ms) for menus opening, tab changes, and the approval card and dialogs appearing; dur-slow (280ms) for the side panel sliding in and toasts coming and going. Entrances use ease-out and exits ease-in, taking two thirds of the entrance time.

Animate only transform and opacity, never width, height or layout; colours may transition. The switch knob moves with transform. A spinner turns once every 0.8s at a steady speed; the sweep along the composer's top edge takes 1.6s each way. With Reduce motion on, the composer sweep and the launch glow stand still, a spinner stops as a still arc, and the sign-in poster stays on its first slide.

Brand moments enter with ease-expo and may add blur and masks. Launch to Home takes about 5.2 seconds: at 0.3s the glow and icon enter, at 0.9s the wordmark wipes in from left to right, at 1.5s the progress bar starts, at 3.7s the launch layer fades out over 0.6s, and then the Home greeting, text, composer, quick tasks and list rise in turn, 70ms apart. The sign-in poster rotates through four slides, 7 seconds each: the outline X draws in thin lines over 2.8s and each line of text rises out of a mask, 120ms apart; on change the current text moves up and fades over 0.8s, the page number turns, and one segment of the bottom progress fills; the two glows in the background drift on 26s and 34s cycles. On the device-code screen the eight character cells enter 55ms apart; once the browser confirms, the three steps tick in turn, the cells get a green edge, and the status line becomes "Confirmed. Opening TopxAI…". In the app these are driven by real events.

## Brand moments

The launch screen centres the 88px rounded icon (the same one as in the Dock), then the wordmark, the tagline, a progress bar and one line of status. In English the tagline is "Begin anew, from here." in fs-tagline-en; the web placeholder and OnboardingGuard share this screen and change only the status line, without restarting the progress bar.

Sign-in has two halves. The left is a rotating poster. Its first slide is the brand line, "Begin anew, from here.", set in fs-poster-en over two lines, the second indented and italic. The other three slides are quotations; in English, use published English translations and credit them. The right half has only one primary button, "Sign in with your browser", with the language picker at the top right. In both themes the primary button is blue with white text; in the dark theme the poster turns a deeper ink blue.

The device-code screen shows the eight characters in separate cells, with Copy code and Reopen browser beside them; three steps below say what to do in the browser, and the last line shows the waiting state and when the code expires.

Home opens with the serif greeting and the person's name, a sentence and the composer, then four quick tasks and the Continue list, so there is always something to click.

## Icons

Icons are lucide line icons, 16px by default, 14px in tight places and 18px for emphasis, with a 1.6 stroke and round caps and joins; their colour follows the text. The design uses 94 of them. Every icon-only button has a Tooltip saying what it does. Interface text never uses emoji.

Provider marks (in the model menu and the provider rows in Settings) are each provider's own logo, never recoloured or outlined. TopxAI's own models use the rounded version of topxai-square.

The logo is an X made of three pieces; see assets/logos. The Dock icon is a rounded square with a blue gradient and a white X; the single-colour mark is black on light grounds and white on dark grounds and the brand panel. When the app draws the launch icon, the gradient matches the icon file: vertical, from #3175f7 to #1f4ed6.

## Screens

screens/ has nine screens in light and dark, 1440×900, drawn in English: launch, sign-in, device code, Home, a session, a running session, the model menu, a multi-agent run and the Providers page in Settings. Prices, balances, token counts and durations are illustrative; names of people and projects are examples; version 1.54.1 was current when the screens were drawn. screens/html/ has the HTML each picture was taken from, built on tokens.css and bundle.css; open one in a browser, and add #dark to the address for the dark theme.

## Files

- tokens.json: every token; tokens.css: the CSS variables, type classes and font faces generated from it.
- components/bundle.css: component styles; components/<Name>/README.md is the guide, and preview.html and preview-dark.html are the light and dark previews.
- assets/logos/: logo files and notes.
- fonts/: the Noto Serif SC subset, Instrument Serif and the JetBrains Mono latin subset, each with its SIL Open Font License.
- screens/: the nine screens in light and dark, and the HTML they were taken from.
- Online: https://api.topxai.xyz/labs/topxai-paper

## What 1.1 changes

### Corrections

1. success's light value #2b7349 reached only 4.45:1 on bg-selected; it is now #2a7047 (at least 4.64:1 on all six grounds). The lowest contrast given for success, warning and danger used to be the value on their tag ground; it is now the lowest measured on the six grounds.
2. Form controls used border (1.38:1) and border-strong (1.74:1) for their edges, below 3:1. The new control-border (light #847f75, dark #7c7870, at least 3.08:1 on all six grounds) is used for text fields, checkboxes, radios and switches that are off.
3. Focus was only the translucent focus-ring glow, 1.4:1 / 1.7:1 on the ground. The new focus colour makes keyboard focus a 2px solid outline; the glow stays as decoration.
4. row-h said "sidebar rows and menu items 32px", but the Menu guide and bundle.css use 30px. The 30px menu and session rows are now in the size table, and row-h covers only sidebar rows.
5. "Spacing uses multiples of 4 only" clashed with the 9, 10, 6 and 14px inside components. The rule now covers distances between elements; the 10px corner of the 40px button is recorded as r-btn-lg.
6. The .appicon gradient in bundle.css (160°, #3a6cf6 → #2458ef → #1b44c4) didn't match the icon file (vertical #3175f7 → #1f4ed6); it now matches the file.
7. The multi-agent screen labelled a run with a synonym of "Running". Status words are now split into session statuses and results, each listed in full.
8. The device-code screen's expiry line could be read as either a clock time or a countdown; rules for times and countdowns were added.
9. bundle.css had only the preview helpers .hover, .focus and .dis, with no real :hover, :focus-visible or :disabled and no motion. 1.1 adds them at the end of the file and respects Reduce motion; the switch knob now moves with transform.
10. Previews loaded JetBrains Mono from Google Fonts, so they failed offline and often failed in mainland China. The fonts now ship in the kit.

### Additions

- Copy: how to write numbers, times and units; status words split into session statuses and results.
- States: waiting buttons, reconnecting, low balance, upstream errors, stopped and interrupted turns, system notifications.
- Accessibility: contrast floor, never colour alone, keyboard, screen-reader announcements, Increase contrast.
- A shortcut table.
- Layout: the 1040×640 minimum window, how the side panel and sidebar give way in narrow windows, stacking order, the drag area, a future Windows version.
- Tokens: control-border, focus, overlay, selection; a size table (control heights, icon sizes, stroke width, disabled opacity, minimum window); r-btn-lg.
- Components: Dialog, Message (your messages and the agent's replies, including Markdown headings, lists, quotes, tables, links and images) and Tabs (the side panel's tabs). Message and Tabs already had some styles in 1.0's bundle.css (.msg-user, .prose, .tabs); 1.1 adds their guides, previews and missing styles.
- Diff line colours and command output (ANSI) colours.
- Fonts: JetBrains Mono ships in the kit; the coverage of the Noto Serif SC subset and how to write Chinese names.
- A dark preview, preview-dark.html, for every component.
- The English edition: English copy rules, status words, button verbs and number formats; Instrument Serif display styles (fs-poster-en, fs-greet-en, fs-display-en, fs-tagline-en); rules for fitting English into the layout; all nine screens drawn in English, with their HTML.

### Still to decide

- When the approval card appears, does ↵ mean Allow or Send? The two clash while focus is in the composer. Suggestion: move focus to Allow when the approval card appears; ↵ in the composer still sends.
- agent-1 to agent-6 differ mostly in hue and are close in lightness (0.16 to 0.24 in the light theme), and white avatar letters reach only 2.2 to 2.8:1 in the dark theme. Members' names cover it for now; should the set change to colours further apart in lightness?
- border-subtle and bg-hover are nearly equal (light #ebe8e1 / #ebe8e2; both #282724 in dark), so dividers inside a card vanish under a hovered row.
- paper-3 is used for the poster page number at 2.4:1. Is the page number decoration, or information people need to read?
- The copy for reconnecting, low balance and upstream errors under States follows this spec's copy rules; it needs checking with product before release.
- The other three poster slides in English: which translations of the quotations to use and how to credit them.