Use the design system
Build or restyle a screen with beUI, the motion components and the product tokens, change the theme, and avoid the imports the validators reject.
Every page in the project uses one design system: the admin console, the workspace, the auth and system pages and the public site. It has three layers: tokens on :root, components from @workspace/beui re-exported through src/components/motion, and a small set of page patterns. Every page uses the design system by default. You add no wrapper and set no attribute.
Before you begin
- A project that runs with
pnpm dev. - The screen you want to build or restyle, and whether it is a console page (
/admin,/app) or a public page. - For a new page, read Add an admin or workspace page or Replace the landing and pricing pages first. This guide covers the visual layer they both use.
Know the layers
| Layer | Lives in | Use it for |
|---|---|---|
| Tokens | src/styles/app.css, on :root and :root[data-theme="dark"] | Colours, radius and fonts. Tailwind utilities such as bg-background, text-muted-foreground and border-border read them |
| beUI source | packages/beui (the @workspace/beui workspace package) | The components themselves: buttons, inputs, select, tabs, table, surface, modal, popover, form layout |
| Motion components | src/components/motion | What pages import. Each file re-exports or adapts a beUI component for this app (button, input, select, switch, checkbox, tabs, surface, table, morphing-modal, drawer, tooltip, toast, empty-state, status-tag, skeleton, loader, theme-toggle) |
| Admin patterns | src/components/admin | Whole regions of a console page: record lists, metric rows, panels, config forms, save state |
| Public primitives | src/components/marketing/ui/page-shell.tsx | Bands, headers and panels for public pages |
| Shells | src/components/layout | AppShell (admin, setup) and AppConsoleLayout (workspace): sidebar, header and the page's single <main> |
Build a screen
Pick the frame
A console page renders inside AppShell (admin) or AppConsoleLayout (workspace). A public page renders inside PublicMarketingShell. The shell renders the <main> element. Use <section> and <div> inside it, and do not add a second <main>.
Compose a pattern before writing markup
For a console page, start from the patterns in src/components/admin:
| Pattern | Import | Gives you |
|---|---|---|
AdminRecords | @/components/admin/admin-records | A searchable, paginated record list from columns, rows and rowKey; a table on desktop and labelled records on a phone |
AdminMetrics | @/components/admin/admin-metrics | A row of figures from items (label, value, optional detail) |
AdminPanel, AdminFacts | @/components/admin/admin-detail | A titled panel with optional actions, and a label/value grid for detail pages |
ConfigShell, ConfigPanel, ConfigPanelGrid, ConfigField, ConfigFormFields, ConfigSelect, ConfigSwitch, ConfigTextarea, ConfigMessage, ConfigDetailsTable | @/components/admin/config-layout | The layout of every /admin/config/* form |
useAdminSave, AdminSaveFeedback | @/components/admin/admin-save | Permission-aware save state: allowed, pending, result, save() and the saved or failed message |
AdminSectionWorkspace | @/components/admin/admin-section-workspace | An AppShell page with a title, header actions and links (tabs) to its sub-pages |
adminRouteFeedback | @/components/admin/admin-route-feedback | The pending and error components to spread into an admin route |
useAdminSave("config.write") reads the signed-in user's permissions from the layout snapshot. When allowed is false, disable the form and show the read-only message. The server function still checks the permission.
Fill in with motion components
Import controls from src/components/motion, and form layout from the beUI package:
import { FieldLegend, FieldSet } from "@workspace/beui/form-layout";
import { Button } from "@/components/motion/button";
import { Input } from "@/components/motion/input";
import { Surface, SurfaceContent } from "@/components/motion/surface";Button and ButtonLink take variant="primary" | "secondary" | "ghost" | "outline" | "danger". @workspace/beui has no index export. Import the subpath you need (@workspace/beui/form-layout, @workspace/beui/components/motion/*), or the app's wrapper in src/components/motion when one exists.
Style with utilities on tokens
Use Tailwind utilities that resolve to tokens: bg-background, bg-card, bg-muted, text-foreground, text-muted-foreground, text-primary, border-border, ring-ring, rounded-lg. Do not write hex colours, rgb() values or inline style colours in a page, because a hard-coded colour does not follow the dark theme.
Use the dark: variant only when a token cannot express the difference. The variant follows data-theme="dark" on the root element.
Change the theme
Edit the tokens in both themes
Open src/styles/app.css. The product tokens are the block at the end of :root, under the comment that begins "beUI: one set of tokens for the whole product", and the same names in :root[data-theme="dark"]:
:root {
--background: #f6f5f1;
--foreground: #20231f;
--card: #ffffff;
--primary: #3859d6;
--primary-foreground: #ffffff;
--muted: #eeede8;
--muted-foreground: #62666e;
--accent: #e8edf9;
--border: #ddded8;
--ring: #3859d6;
--radius: 0.625rem;
}Change a value in both blocks. To change the brand colour, set --primary, --ring and --brand-accent together, and pick a --primary-foreground that stays readable on it. --radius scales every rounded corner. The sidebar has its own --sidebar-* set.
Leave the Tailwind mapping alone
The @theme inline block maps each token to a utility colour (--color-primary: var(--primary)). Edit it only when you add a new token and want a utility for it.
Keep fonts in the stylesheet
Fonts are imported at the top of app.css (Geist, Geist Mono and Noto Sans SC) and named in the font-family on :root and --font-sans in @theme inline. Replace the import and both names to change the typeface.
Bring the validator and the site config along
pnpm validate:beui-console asserts that the six core tokens are hex values in both themes and pins the page background to #f6f5f1 (light) and #101114 (dark). When you change --background, update those two values in scripts/validate/beui-console.ts in the same change. Then set themeColor and backgroundColor in src/config/site.ts to match; see Rebrand the project.
Avoid what the validators reject
| Rule | Enforced by |
|---|---|
No route under admin, app, auth or system may reach a module in src/components/ui (shadcn), directly or through its imports | pnpm validate:beui-console |
Every admin and workspace page reaches AppShell or AppConsoleLayout | pnpm validate:beui-console |
Console pages and their components add no <main> of their own | pnpm validate:beui-console |
app.css declares no bare element rule (a, button, h1, table and so on) outside a cascade layer | pnpm validate:beui-console |
| Tokens are not scoped to a surface attribute | pnpm validate:beui-console |
The landing and pricing pages hard-code no colour, use no inline style and no ds-/mk- class prefix | pnpm validate:example-landing |
New files carry no !important | pnpm check |
src/styles/app.css carries historical !important and specificity debt, and biome.json exempts that one file. Do not widen the exemption, and do not run biome check --write --unsafe across the repository. That command strips !important from the stylesheet and rewrites React hook dependency arrays.
A page also declares no class-name prefix of its own. If a design tool produced the screen, rebuild it with the components and utilities above. Do not paste its class names.
Add a component beUI does not have yet
- Check
src/components/motionfirst; most controls are already there. - If it is missing, install it from the beUI registry into
packages/beui/src/components/, then add a thin file insrc/components/motionthat re-exports it, assrc/components/motion/surface.tsxdoes. Your coding agent can fetch components through the beUI MCP server athttps://mcp.beui.dev/mcp. - Supply labels through the app's dictionaries. beUI components that render text read it from
BeuiLocaleProvider, which the layouts already mount.
Verify
pnpm validate:beui-console
pnpm validate:example-landing
pnpm validate:mobile
pnpm checkOpen the screen in both themes (the toggle is in the public header and in the console's account menu) and in both locales, at phone width and desktop width. An area that keeps a light background in the dark theme is using a hard-coded colour.
Next steps
Replace the landing and pricing pages
Rewrite the example home page, add public pages from the page-shell primitives, and know what /pricing reads and what the validators enforce.
Add and change copy
Edit copy in English and Chinese, add a locale-aware route, and understand the optional locale segment and the i18n validators.