Design and code conventions

One way to build each kind of screen, one set of tokens, and one folder layout, so every page looks and reads the same. New pages follow this; existing pages move to it as they're touched.

Principles

• Content first. The sidebar recedes (a touch darker, muted labels); the work area gets the contrast.
• Structure felt, not seen. Separate with spacing and surface tone; keep only the borders that carry meaning.
• Dense but calm. App text 13–14 px, steady row heights, one accent, status colors only for status.
• Warm neutral grays in light and dark. The brand gradient (indigo → coral) is for marketing and moments (checkout success, empty states), never working UI.
• Keyboard first. ⌘K everywhere; shortcuts shown with Kbd.
• Small motion. 150–200 ms ease-out; prefers-reduced-motion respected.

Tokens (src/app/globals.css)

Status badges come from one map, StatusBadge (src/components/status): the same word always gets the same tone (success, warning, info, destructive, secondary, outline).

Route files (Next 16)

forbidden() / unauthorized() need experimental.authInterrupts (on in next.config.ts).

Cache Components

cacheComponents and partialPrefetching are on. Every segment starts with export const instant = false (allowed to block), data pages and layouts call await connection() before reading the database, and the session check (authenticationCheck) is request-time. To make a route instant: move its session/cookie/params reads into a component inside <Suspense>, then remove instant = false. Note that page state (inputs, open menus) now survives navigating away and back.

Route groups

Folder map

Every folder mirrors src/app:

• src/app/[locale]/… — routes only.
• src/views/<route> — the page's UI (ViewAppWorkspaceStudio, ViewAdminWorkspaceDetail…). A page's own pieces live beside it (views/app/[workspace]/studio/[id]/window/canvas/node.tsx).
• src/components/<domain> — pieces reused by several pages (components/ui from shadcn, components/state, components/status, components/dataset/access, components/account, components/dialog, components/flow).
• src/actions/<route> — mutations ('use server', a prefix, [true, data] | [false, message]): actions/app/[workspace]/studio, actions/admin/workspace, actions/(public)/invite.
• src/forms/<route> — react-hook-form/zod schemas reused by forms and actions.
• src/controllers/<domain>/<sub> — reads and business logic (no 'use server').
• src/lib/<domain>/<sub> — modules with a static list each (flow/node, flow/template, workspace/permission, secret, configuration, i18n, database/schema/<domain>/<sub>).
• src/types/<mirror> — shared types (TCamelCase).

Naming and data shapes

• Files and folders kebab-case; domain scope is nested folders (browser/live/create.ts), never dashes.
• Functions and variables domainSubdomain (workspaceAccess, flowNodeDot).
• Data shapes nest by domain: { tax: { isInclusive } }, not { isTaxInclusive }. Suffix fields stay flat: xxxAt, xxxId, xxxMs, xxxBy. Booleans are is + one word; a compound becomes an object or an enum.

Screen patterns

• Page header: h1 title, one-line description, actions on the right (primary last).
• List: toolbar (search, filters, view switch) → Table on md+, item rows on phones → Empty with one action → pagination. Row: icon, name, meta, status badge, time, a menu.
• Detail: header + route-based tabs from the layout + content.
• Settings: FieldGroup / Field (label and description, control); a section Card only where an action belongs to it (Delete workspace).
• Dialogs: AlertDialog / DialogConfirmation for confirmations (dangerous ones repeat the name), Dialog for short forms, Sheet / Drawer on phones.
• Forms: every <form> has method="post". Submitted before the page hydrates, the browser would otherwise send the fields as a GET query (passwords and keys in the URL, history and server logs); a POST only re-renders the page. After hydration onSubmit (react-hook-form) handles it as usual.
• States: loading, error, forbidden, unauthorized, not found — the components/state pieces, never hand-made per page.

Less DOM, same design

• Layout with flex/grid + gap on the parent; no wrapper div for spacing or around a single child.
• Semantic elements carry the layout (main, header, section, nav, ul/li, dl); Fragment, never <></>.
• shadcn's composed parts (Field, Empty, InputGroup, ButtonGroup, Kbd) instead of hand-built stacks; Card only when grouping means something (never card in card).
• State styling through data-* / aria-* / group-* / has-* variants; container queries for cards that change shape.

FAQ

Where does a new page's UI go?

In src/views/ at the same path as its route, named View + the path ([workspace] → Workspace, [id] → Detail).

When is something a component instead of part of a view?

When two or more pages use it. Then it goes to src/components/<domain>.

Can I add a color?

Use the tokens. A new meaning gets a token pair in globals.css (light and dark), never a literal color in a page.

How is a database model declared?

const Thing: Model<IDatabaseThingDocument> = mongoose.model<IDatabaseThingDocument>("Thing", ThingSchema, undefined, { overwriteModels: true }); in src/lib/database/schema/<domain>, and a discriminator with { overwriteModels: true } too. The dev server's hot reload then compiles a changed schema again (a new field and its default apply at once), instead of keeping the model it compiled first until a restart.