Kernlift

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

Know the layers

LayerLives inUse it for
Tokenssrc/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 sourcepackages/beui (the @workspace/beui workspace package)The components themselves: buttons, inputs, select, tabs, table, surface, modal, popover, form layout
Motion componentssrc/components/motionWhat 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 patternssrc/components/adminWhole regions of a console page: record lists, metric rows, panels, config forms, save state
Public primitivessrc/components/marketing/ui/page-shell.tsxBands, headers and panels for public pages
Shellssrc/components/layoutAppShell (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:

PatternImportGives you
AdminRecords@/components/admin/admin-recordsA searchable, paginated record list from columns, rows and rowKey; a table on desktop and labelled records on a phone
AdminMetrics@/components/admin/admin-metricsA row of figures from items (label, value, optional detail)
AdminPanel, AdminFacts@/components/admin/admin-detailA 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-layoutThe layout of every /admin/config/* form
useAdminSave, AdminSaveFeedback@/components/admin/admin-savePermission-aware save state: allowed, pending, result, save() and the saved or failed message
AdminSectionWorkspace@/components/admin/admin-section-workspaceAn AppShell page with a title, header actions and links (tabs) to its sub-pages
adminRouteFeedback@/components/admin/admin-route-feedbackThe 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"]:

src/styles/app.css
: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

RuleEnforced by
No route under admin, app, auth or system may reach a module in src/components/ui (shadcn), directly or through its importspnpm validate:beui-console
Every admin and workspace page reaches AppShell or AppConsoleLayoutpnpm validate:beui-console
Console pages and their components add no <main> of their ownpnpm validate:beui-console
app.css declares no bare element rule (a, button, h1, table and so on) outside a cascade layerpnpm validate:beui-console
Tokens are not scoped to a surface attributepnpm validate:beui-console
The landing and pricing pages hard-code no colour, use no inline style and no ds-/mk- class prefixpnpm validate:example-landing
New files carry no !importantpnpm 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

  1. Check src/components/motion first; most controls are already there.
  2. If it is missing, install it from the beUI registry into packages/beui/src/components/, then add a thin file in src/components/motion that re-exports it, as src/components/motion/surface.tsx does. Your coding agent can fetch components through the beUI MCP server at https://mcp.beui.dev/mcp.
  3. 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 check

Open 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