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
- Business screens — five complete business screens that run inside the docs.
- Pick a component by job — what the user does, and which component to use.
- App shell and page header —
AppShellandPageContainer. - List pages —
ProTablewith search, tabs, and bulk selection. - Dashboards — KPIs, to-do lists, charts.
- Forms — drawer forms, step forms, line items.
- Detail pages — view one record and approve it.
- Sign-in and sign-up —
LoginForm. - Page recipes — layouts for common pages.
- Diagrams, kanban, AI chat — libraries beyond tables and forms.
- APIs to know —
ProTable, form, andvalueTypeprops.
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
Tablewith 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: PageContainer (breadcrumb, tag, summary, key figure) + progress Steps + Info + Timeline + decision buttons pinned to the footer.
// No PageContainer onBack (it crashes the page on this runtime) — use the breadcrumb.
import { useState } from "react";
import { ModalForm, PageContainer, ProCard, ProDescriptions, ProFormTextArea } from "@ant-design/pro-components";
import { Alert, App, Button, Col, Flex, Row, Space, Steps, Tag, Timeline, Typography } from "antd";
import { CheckOutlined, CloseOutlined } from "@ant-design/icons";
export default function Page() {
const { message } = App.useApp();
const [status, setStatus] = useState<"pending" | "approved" | "rejected">("pending");
const [note, setNote] = useState<string | null>(null);
const events = [
{ color: "blue", text: <><b>Laura Bennett</b> created the request</>, at: "Nov 10, 2026 · 12:52 PM" },
...(status !== "pending" ? [{ color: status === "approved" ? "green" : "red", text: <><b>Hannah Reed</b> {status === "approved" ? "approved" : "rejected"}{note ? <> — <i>“{note}”</i></> : null}</>, at: "just now" }] : []),
];
const decide = (to: "approved" | "rejected") => async (v: { note?: string }) => {
setStatus(to); setNote(v.note ?? null);
message.success(to === "approved" ? "Approved" : "Rejected");
return true;
};
return (
<PageContainer
header={{
title: "Renew Microsoft 365 Business (12 months, 10 users)",
breadcrumb: { items: [{ title: <a>Requests</a> }, { title: "#9" }] },
tags: <Tag color={status === "pending" ? "processing" : status === "approved" ? "success" : "error"}>{status === "pending" ? "Pending" : status === "approved" ? "Approved" : "Rejected"}</Tag>,
}}
content={
<ProDescriptions column={{ xs: 1, sm: 2, lg: 3 }}>
<ProDescriptions.Item label="Requested by">Laura Bennett · Operations</ProDescriptions.Item>
<ProDescriptions.Item label="Category">Software</ProDescriptions.Item>
<ProDescriptions.Item label="Needed by">Nov 13, 2026</ProDescriptions.Item>
</ProDescriptions>
}
extraContent={
<Space orientation="vertical" size={0} style={{ textAlign: "right" }}>
<Typography.Text type="secondary">Requested amount</Typography.Text>
<Typography.Text strong style={{ fontSize: 28 }}>$1,500.00</Typography.Text>
</Space>
}
footer={status === "pending" ? [
<ModalForm key="r" title="Reject request" width={480} trigger={<Button danger icon={<CloseOutlined />}>Reject</Button>} onFinish={decide("rejected")} modalProps={{ okText: "Reject", okButtonProps: { danger: true } }}>
<ProFormTextArea name="note" label="Reason for rejection" rules={[{ required: true, whitespace: true, message: "Please add a reason" }]} />
</ModalForm>,
<ModalForm key="a" title="Approve request" width={480} trigger={<Button type="primary" icon={<CheckOutlined />}>Approve</Button>} onFinish={decide("approved")} modalProps={{ okText: "Approve" }}>
<ProFormTextArea name="note" label="Note (optional)" />
</ModalForm>,
] : undefined}
>
<Flex vertical gap={16}>
<ProCard title="Progress" headerBordered>
<Steps current={status === "pending" ? 1 : 2} status={status === "rejected" ? "error" : status === "approved" ? "finish" : "process"}
items={[{ title: "Submitted", content: "Laura Bennett · Nov 10, 12:52 PM" }, { title: status === "pending" ? "Manager approval" : status === "approved" ? "Approved" : "Rejected", content: status === "pending" ? "Needed by Nov 13" : "Hannah Reed" }]} />
</ProCard>
{status === "rejected" && <Alert type="error" showIcon title="Rejected by Hannah Reed" description={`Reason: ${note}`} />}
<Row gutter={[16, 16]}>
<Col xs={24} lg={15}>
<ProCard title="Details" headerBordered style={{ height: "100%" }}>
<Typography.Paragraph>The current plan expires at the end of the month. We need to renew it so email isn't interrupted.</Typography.Paragraph>
</ProCard>
</Col>
<Col xs={24} lg={9}>
<ProCard title="History" headerBordered style={{ height: "100%" }}>
<Timeline items={events.map((e) => ({ color: e.color, children: <><div>{e.text}</div><Typography.Text type="secondary" style={{ fontSize: 12 }}>{e.at}</Typography.Text></> }))} />
</ProCard>
</Col>
</Row>
</Flex>
</PageContainer>
);
}
Build the "Detail page + approval" screen for my app following the Manh UI playbook (framework_docs("pro")): Detail page: PageContainer (breadcrumb, tag, summary, key numbers) + progress Steps + info + Timeline + decision buttons fixed at the bottom. Data comes from the app's API through useApiClient(); labels and fields follow my spec.Six rules for every screen
- Pick the component by job. App shell →
AppShell; page header →PageContainer; list of records →ResourceListorProTable; 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. - Fill in the semantic props.
title,subTitle,tooltip,headerBordered,extra,content,extraContent,valueEnumwithstatus,valueType="money",showTotal, counts on tabs, and buttons infooterare what make a screen look finished. - 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 withRow gutter={[16, 16]}+Col, notProCard gutter. - Take colors only from tokens. Set the brand color once in
app/theme.tsxand read colors withtheme.useToken(). Don’t type hex codes. - Show status as a Badge. Tables, lists, and detail pages share one
valueEnummap:{ text, status: "Success" | "Error" | "Processing" | "Warning" | "Default" }. - Don’t use
onBackonPageContainerorPageHeader, because the page crashes. Useheader.breadcrumb.
Good to know
ProCard gutterinsets cards by about 8px from the full-width cards above and below.checkwarnscode.hardcoded-coloron typed color codes (white or black overlays on a background image are fine) and blockscode.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 inSteps, history inActivityLog, status buttons withFlowActions. - 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
- Pick a component by job — a quick lookup when you start a new screen.
- List pages — the most complete page in the playbook.
- Call the API from the UI — replace sample data with
useApiClient().