Page UX guidelines
How to lay out information and actions in pages embedded in openmax.com, so they feel like part of the platform.
Page UX guidelines
Your page appears inside an OpenMax frame, used side by side with the platform's own pages. Below is how to make it look like part of the family and feel natural to use, each with a small example. For the technical side of embedding and theming, see Sign-in ("In practice: embedding and sign-in").
Laying out information
- One entry point per action. Each action appears on the page only once; if the same object appears in several places and each can be edited in place, that counts as one entry point. Example: put "Disable" only on the object itself, not once each in the list, the details, and a menu.
- At first glance, show only "what's the state, and what do I need to do". Put IDs, paths, API URLs, JSON, status keys, and version numbers in details, expanded on demand. Example: the card says "Expense claim is waiting for your manager's approval, due tomorrow 18:00", with the claim number under "Details".
- Use human words. Not system words.
Example: write "No one has picked this up yet", not
status=UNASSIGNED. - One primary action per screen. The primary button stands out most, and secondary ones carry less visual weight; but actions that can already be done in place on an object do not go into a collapsed menu. Example: on an approval page the primary button is "Approve", and "Reassign" sits next to it in a secondary style.
- Always show status: where it is, who it's waiting on, when it's due. Example: a line under the progress bar reads "Step 2 of 4 · Waiting on Finance · Due today 17:00".
- No permanent explanatory text. Do not leave rule explanations or "how the system works" on screen. Replace them, in this order: let the design speak for itself → say one line at the relevant moment → have the software do it for the person → tuck it under ⓘ → leave it to the conversation to explain. Only two kinds may stay visible: consequences that cannot be undone or will cause an immediate error, and next steps in empty states. Example: the delete dialog says "This cannot be undone after deletion"; the page does not say so the rest of the time.
Designing actions
- Prevent errors rather than report them. Actions without permission do not appear (information like names and status still shows); actions that are permitted but not allowed in the current state are grayed out, and hovering or clicking explains why and how to unblock it, without a separate "unblock" button; warn at the moment it matters, not with an error on submit. Example: hovering a grayed-out "Edit" shows "Can't edit while running. Disable it first", and clicking jumps to where you can disable it.
- If permitted, edit in place without leaving the page. If it's visible, permitted, and the state allows it, edit in place without leaving the current context; irreversible actions (delete, revoke, reassign) are also confirmed in place. Example: click the title and it turns into an input box; press Enter to save.
- Don't make people fill in or look up what the software can work out. Prefill what can be prefilled, show where the value came from, and let people change it. Example: the owner defaults to "the current project's owner", with small text beside it: "Filled from the project, can be changed".
- When people need to pick something, show all candidates right in the picker. Don't require them to create things in another settings page first; list candidates that are missing prerequisites too, and guide people to fix them in place after picking. Example: the agent dropdown lists the organization's agents directly; picking one without the skill installed prompts to install it on the spot.
For people and for agents
- Everything that can be done can be done through conversation; forms are a helper. Every feature can be started, changed, and queried through conversation; forms and buttons help people state their intent precisely and confirm the AI understood it, but they are not the only entry point. Agreement in a conversation does not take effect directly: first list exactly what will change, have someone with permission confirm it, and go through the same approval and records as the form.
Example: a user says in chat "Change step 2 to finance approval", and the agent replies with a confirmation card "Will change: Step 2 approver → Finance" (card buttons in chat need the Chat SDK
{ adapter }form; see Chat SDK integration). - If you can see an agent, you can click to chat with it. Clicking an agent name or avatar shown on the page opens a DM with it in place and carries over "what I'm looking at now"; the server checks the carried context and only includes what this person can see. If the person has no permission to DM, the name still shows but is not clickable.
Example: click the agent avatar next to step 3 of a run; the DM opens with the first context line "This run · Step 3".
Technically: clicking an avatar to open a DM in place works today (Chat SDK
openConversation({ memberId })); "with context" is coming soon, and your server must generate the first context message or card itself and check whether the person can see it; neither the SDK nor the platform checks this for you. To have the shell open OpenMax's own DM window, use "App requests to open a conversation" (navigate; coming soon; see Open modes and URLs). - Agent-friendly: anything people can do in the UI, agents can do through the API, with the same permissions and approvals; IDs, error codes, and request IDs belong in the API layer, not piled into the UI people see. Example: the UI says "You don't have permission", and the API returns 403 with an error code and request ID.
Narrow screens and embedding
- Usable on a 390-wide phone, with no horizontal scrolling when embedded. For acceptance, besides desktop width, also take a 390×844 screenshot embedded in openmax.com. Example: tables turn into stacked cards on narrow screens; sidebars move below the page or into a drawer instead of pushing the main content off screen.
