Skip to Content

UI playbook

The UI playbook shows how to make Manh app screens look like real products: use the right Pro component for each job and follow six shared rules.

Each page covers one screen type: app shell, list, dashboard, form, detail page. Your agent reads the same content over MCP (framework_docs("pro")), so you and your agent build screens the same way. The reference app is the Duyệt mua sắm (purchase approval) template (templates/purchase-requests/, live at duyet-mua-sam.manh.run).

Read first

  1. Business screens — five complete business screens that run inside the docs.
  2. Pick a component by job — what the user does, and which component to use.
  3. App shell and page header — AppShell and PageContainer.
  4. List pages — ProTable with search, tabs, and bulk selection.
  5. Dashboards — KPIs, to-do lists, charts.
  6. Forms — drawer forms, step forms, line items.
  7. Detail pages — view one record and approve it.
  8. Sign-in and sign-up — LoginForm.
  9. Page recipes — layouts for common pages.
  10. Diagrams, kanban, AI chat — libraries beyond tables and forms.
  11. APIs to know — ProTable, form, and valueType props.

To edit an example and copy a prompt for your agent, open the Playground.

Why apps look like demos, and the fix

An app looks “plastic” when each part is hand-built from small pieces:

  • A shell assembled from Layout + Menu.
  • A dashboard of plain Card + Statistic, with numbers that have no secondary line.
  • A Table with no search, status tabs, or badges.
  • Forms inside a bare Modal.
  • Every screen the same grey box.

More CSS doesn’t fix this. The fix is to use the Pro component that already encodes the finished pattern, and to fill in its semantic props.

Detail page + approvalDetail page: PageContainer (breadcrumb, tag, summary, key numbers) + progress Steps + info + Timeline + decision buttons fixed at the bottom.
example.manh.run · sample dataOpen in editor ↗
The example runs when you scroll to it

Six rules for every screen

  1. Pick the component by job. App shell → AppShell; page header → PageContainer; list of records → ResourceList or ProTable; cards or a feed → ProList; KPIs → StatRow; history → ActivityLog; a read-only record → ProDescriptions; forms → ProForm, DrawerForm, ModalForm, StepsForm; sign-in → LoginForm; empty, done, or error states → Result.
  2. Fill in the semantic props. title, subTitle, tooltip, headerBordered, extra, content, extraContent, valueEnum with status, valueType="money", showTotal, counts on tabs, and buttons in footer are what make a screen look finished.
  3. Keep one spacing rhythm. Use 24px between sections (<Flex vertical gap={16|24}>) and 16px inside dense rows. Every card on a page shares one left edge and one right edge: build columns with Row gutter={[16, 16]} + Col, not ProCard gutter.
  4. Take colors only from tokens. Set the brand color once in app/theme.tsx and read colors with theme.useToken(). Don’t type hex codes.
  5. Show status as a Badge. Tables, lists, and detail pages share one valueEnum map: { text, status: "Success" | "Error" | "Processing" | "Warning" | "Default" }.
  6. Don’t use onBack on PageContainer or PageHeader, because the page crashes. Use header.breadcrumb.

Good to know

  • ProCard gutter insets cards by about 8px from the full-width cards above and below.
  • check warns code.hardcoded-color on typed color codes (white or black overlays on a background image are fine) and blocks code.no-pagecontainer-onback.

Checklist before you deploy

  • The shell is AppShell, the menu depends on the role, and the selected item stays highlighted on detail pages.
  • Every list: search fields chosen on purpose, status as a Badge, money right-aligned and formatted, a count on each main status tab, and empty text that names the next step.
  • Every dashboard number has a secondary line; the signed-in role’s to-do list comes first.
  • All cards line up on one left edge and one right edge down the page.
  • Detail page: summary in the header, key number in extraContent, progress in Steps, history in ActivityLog, status buttons with FlowActions.
  • Forms sit in a Drawer or Modal, button labels use the user’s language, unclear fields have a tooltip, and money and dates use local formats.
  • Walk each role’s main flow against the deployed API, then ask the owner to open each main screen on a phone and a desktop before calling it done.

Next steps

Last updated