Settings pages are the highest-volume authenticated surface in Cal.com. Almost every route under apps/web/app/(use-page-wrapper)/settings/ follows the same recipe: SettingsShell provides secondary navigation, then the page content column is AppHeader + stacked CardFrame (or list) sections.

Field wiring, validation, and save footers are covered in Forms. This Guide is the page chrome around those cards.

Copyimport {
  AppHeader,
  AppHeaderActions,
  AppHeaderContent,
  AppHeaderDescription,
} from "@coss/ui/shared/app-header";
import { Card, CardFrame, CardFrameFooter, CardPanel } from "@coss/ui/components/card";

Product UI detail for the header composite: App Header.

Anatomy

1. SettingsShell — route-group layout (settings/(settings-layout)/layout.tsx → SettingsShellServer). Secondary nav + content column. Do not re-implement this in a page.
2. AppHeader — page title (AppHeaderContent title=…), optional description, optional actions.
3. Body — one or more sections in a vertical stack (flex flex-col gap-4), usually CardFrame + form cards; sometimes a list or table under the header.
4. page.tsx contract — session, data fetching, and permission checks live in the App Router page. UI often lives in ~/modules/settings/.... Prefer fail-closed notFound() when the caller lacks permission (never invent a “no access” empty in layout.tsx).

Best practices

Header · title and description

Most settings views use title + description with no actions.

Copy<AppHeader>
  <AppHeaderContent title={t("general")}>
    <AppHeaderDescription>{t("general_description")}</AppHeaderDescription>
  </AppHeaderContent>
</AppHeader>

AppHeaderContent requires the title prop — do not put the heading only as children.

Header · with actions

Put primary create / add CTAs in AppHeaderActions. Hide the action when it does not apply (empty list CTAs often live in the empty state instead — see Empty states).

Copy<AppHeader>
  <AppHeaderContent title={t("out_of_office")}>
    <AppHeaderDescription>{headerDescription}</AppHeaderDescription>
  </AppHeaderContent>
  {showAddEntryAction ? (
    <AppHeaderActions>
      <CreateNewOutOfOfficeEntryButton onClick={handleOpenCreateDialog} />
    </AppHeaderActions>
  ) : null}
</AppHeader>

The same shape appears with the CTA gated by PBAC on org/team roles pages (canCreate → AppHeaderActions).

Full page recipe

Under the shell content column: header, then stacked cards. Forms use Form className="contents" so the card chrome owns the layout — details in Forms → Settings page card.

Copy<>
  <AppHeader>
    <AppHeaderContent title={t("general")}>
      <AppHeaderDescription>{t("general_description")}</AppHeaderDescription>
    </AppHeaderContent>
  </AppHeader>
 
  <div className="flex flex-col gap-4">
    <Form className="contents" onSubmit={formMethods.handleSubmit(onSubmit)}>
      <CardFrame>
        <Card>
          <CardPanel>{/* FieldGrid / fields */}</CardPanel>
        </Card>
        <CardFrameFooter className="flex justify-end">
          <Button type="submit" disabled={isDisabled} loading={isSubmitting}>
            {t("update")}
          </Button>
        </CardFrameFooter>
      </CardFrame>
    </Form>
    {/* Additional CardFrame sections as needed */}
  </div>
</>

Where AppHeader lives

Both placements ship today — pick one and keep the page thin:

Do not put permission checks in layout.tsx. Authorize in page.tsx, then render header + body (or notFound()).

Copyif (!canRead) {
  return notFound();
}
 
return (
  <>
    <AppHeader>
      <AppHeaderContent title={t("roles_and_permissions")}>
        <AppHeaderDescription>{t("roles_and_permissions_description")}</AppHeaderDescription>
      </AppHeaderContent>
      {canCreate ? (
        <AppHeaderActions>
          <CreateRoleCTA />
        </AppHeaderActions>
      ) : null}
    </AppHeader>
    <RolesList ... />
  </>
);

Not this Guide

Call sites

Example URLs

Not exhaustive — a few places you can open locally (e.g. http://localhost:3000) to see this in product.