Skip to Content
BBRICKSv0.7.4
Foundations

Screen patterns

How to build any TRNDR screen the same way.

How to build any TRNDR screen the same way: the page frame and grid, the header, KPI rows, filtering, bulk actions, forms, overlays, feedback, the three data states, money, statuses, navigation, language and data. Each pattern says when to use it, which components draw it, a short example and the rules. The facts come from the two v3 mocks (reference/trndr-brand-dashboard-gui-v3.html, reference/trndr-pr-portal-gui-v3.html), the screen compositions in src/gallery/screens and the library source. Lists have their own page: Tables. Live examples: Tables and lists, Loading, error and empty states, Build an app frame and the dashboard screens.

Every example assumes this frame:

import { BricksProvider, DataProvider, createHttpClient, trndrPreset } from '@ergasti/bricks';

const client = createHttpClient({ baseUrl: '/api', onUnauthorized: () => window.location.assign('/login') });

<BricksProvider preset={trndrPreset} language={language} moneyNotes={NOTES[language]}>
  <DataProvider client={client}>
    <App />
  </DataProvider>
</BricksProvider>;

The PR Portal look is a theme, not other components: put data-bricks-theme="pr" on the app root (and on <html> when drawers and menus portal to the body).

1. Page anatomy and grid

When: every screen.

Anatomy, top to bottom (the mocks' .app › .side + .main):

  1. The sidebar: ink, fixed full height, 252px (Brand) / 248px (PR), brand block, nav, a card ("Need a hand?" + Contact TRNDR), the user row.
  2. The top bar: the page title (h1, 30/800) and its muted subtitle (max 620px); in the PR mock a breadcrumb above it ("Brands / Glow Lab"); the tools at the end (search pill, language circle, help, bell, user menu; screen tools such as "Record gifts for a brand" first).
  3. The main column: padding 24px 32px 56px (Brand) / 64px (PR). Inside <main> the blocks stack 16px apart (.kit-shell-main gap).
  4. Content blocks in order: banners, sub-page tabs, the KPI row, then cards on the grid.

The grid is the mocks' .grid.c12: 12 equal columns, 16px gaps, cards spanning s3 s4 s5 s6 s7 s8 s12. The kit ships components, not page grids: write the grid in the app's CSS.

SplitWhere
5 / 7Brand Home: wallet hero (s5) beside the 2 × 2 metric tiles (s7)
7 / 5Brand Home: To-do list (s7) + Seat usage (s5), Live challenge (s7) + Top creators (s5); Payouts: November payout (s7) + two tiles (s5); Wallet: hero (s7) + Wallet health (s5); Analytics: Best creators (s7) + Best-selling products (s5); Gifts: Gift rules (s5) + Gift stock (s7)
6 / 6Brand Invitations' two cards, Motivation bonuses and challenge cards, Settings cards; PR Tiers' two move lists
8 / 4PR Home (Needs you + side cards), brand page, challenge page, gift shipment page
3 × 4PR stat tiles (brand page, gift stock, challenge page)
12full-width cards: Grow your program, tables, Sales by challenge

Breakpoints (from the mocks' CSS and the library's):

WidthWhat changesSource
≤ 1240pxPR challenge cards 3 → 2 across; tier ladder 2 across; the PR search pill 190pxPR mock
≤ 1180pxevery s4–s8 span becomes 12: splits stackboth mocks, screens.css
≤ 1100pxKPI rows 4 → 2 across (KpiGrid); 3-up page grids stackBrand mock .kpis, v3.css, screens.css
≤ 1024pxthe sidebar becomes a 72px icon rail that expands over the content; touch targets grow to 44px (pager buttons, selects, row checkboxes)AppShell, kit.css, dataTable.css
< 860pxphone: no sidebar; a tab bar and a nav sheet; the header's tools take their own row; DataTable rows become stacked cardsAppShell, AppHeader, dataTable.css
≤ 760pxthe PR message composer and campaign card grids stackpr.css
≤ 600pxKPI rows 1 across (2 with phoneColumns={2}, down to 360px); ListToolbar can fold its filters (collapseFiltersBelow); the header search folds into a button; the subtitle can clamp (subtitleLines)v3.css, ListToolbar, AppHeader
// App CSS: the mock's grid.
// .grid { display: grid; gap: 16px; grid-template-columns: repeat(12, minmax(0, 1fr)); }
// .s5 { grid-column: span 5 } .s7 { grid-column: span 7 }
// @media (max-width: 1180px) { .s4, .s5, .s6, .s7, .s8 { grid-column: 1 / -1 } }
<div className="grid">
  <div className="s5"><HeroCard figures={wallet} compact deco={false} actions={<Button variant="white">Top up by card</Button>} /></div>
  <div className="s7 grid-2x2">{tiles}</div>
  <Card className="s7" title="To-do list" sub="4 things worth a look today">{todos}</Card>
  <div className="s5"><SeatUsage /></div>
</div>;

Do: keep the 16px gap everywhere; put the wider column on the side with the work (a list, a to-do) and the narrower on the summary. Don't: add page padding inside cards to fake a grid; nest a 12-column grid inside a card except for a row of facts (s4 × 3 inside a card is the mocks' own pattern).

2. Page header

When: every screen has one title; detail pages add a breadcrumb; screen-wide actions go in the header.

Components: AppHeader (inside AppShell: title, subtitle, subtitleLines, breadcrumbs, leading, search, actions, userMenu, onToggleLanguage) with HeaderSearch, LanguageToggle, NotificationsMenu, TopbarMenu, UserMenu. PageHeader is the same title block without the tools, for a page outside the shell.

<AppHeader
  title="Glow Lab" breadcrumbs={<><a href="#brands">Brands</a> / Glow Lab</>}
  subtitle="Every PR action on every brand, newest first."
  leading={<Button><PrIcon name="eye" /> View as brand</Button>}
  search={<HeaderSearch placeholder="Search brands, creators…" onQueryChange={setTerm} results={results} onSelect={openResult} />}
  actions={<NotificationsMenu items={notifications} onOpenItem={open} onSeeAll={() => go('activity')} />}
  onToggleLanguage={toggleLanguage}
/>;

Do: write the subtitle as what the page is for, in the mock's words ("Creators waiting for a yes or no. Oldest first."); let the subtitle change with the scope ("The 3 brands you own…" / "All 6 brands on TRNDR…"). Don't: put filters in the header (they belong to the list's toolbar) or more than one primary action.

3. KPI rows

When: a screen that opens on figures (Creators, Coupons, Gifts, Challenges, Messages, Gift analytics) or a home page.

Components: KpiGrid + KpiCard (tones lime, rasp, butter, sky, lilac; icon, label, value, sub, progress, active, onClick, deco, size); Tile (size="metric" for Home and Analytics tiles with a Delta and a Spark; size="stat" for the PR stat tiles; size="short" for the payouts tiles; size="kpi" for View as brand).

Card kindPropsExample
Filteractive + onClick toggles the list's chipCreators › Active / Paused; Coupons › Active coupons / Stopped; Gifts › Shipped / Delivered; PR Creators (all four)
NavigateonClick, no activeGroups → Groups tab; Coupon uses → Analytics; Seats left → Raise limit
SortonClick sets the list's sortPR Challenges › Creators joined, Budget held
PlainneitherMessages (Messages sent, Opened on average, Creators reached)

Sizes: four across (columns={4}, default), three (columns={3}, PR Messages), five (Brand Gifts: the app's own 5-column grid), size="short" for the strip above a dense list (PR Creators).

<KpiGrid phoneColumns={2}>
  <KpiCard tone="lime" icon="user" label="Active" value={260} sub="86% of your creators · selling now" progress={86} active={chip === 'active'} onClick={() => toggle('active')} />
  <KpiCard tone="rasp" icon="seat" label="Seats left" value={79} sub="321 of 400 seats used" progress={80} onClick={openRaiseLimit} />
</KpiGrid>;

Do: say what the number means in sub ("Working in your store now", "Across live challenges"); keep the mocks' tone order for each component: Tile rows (Home, Analytics) run lime, rasp, butter, sky; KpiCard grids above a list run lime, butter, lilac, rasp (Coupons swaps lilac for sky: lime, sky, butter, rasp). Don't: make every card clickable for its own sake; show a progress bar without a sub that says the number.

When: any list longer than one page, or with states the viewer acts on.

Components: ListToolbar for any toolbar above a data list whose state lives in useListState; the slot-based Toolbar (search, chips, filters, sort, actions, reset as nodes) only for a filter or chart row that does not drive such a list (Analytics: period Segmented, challenge SelectBox, Export CSV; Motivation › Challenges: the hint and "+ Request a challenge"); SortSelect is deprecated, never in new code. With them: FilterChips, Segmented for a scope or view switch (size="sm" in a toolbar), PillTabs for sub-pages, KPI filter cards (above), useListState for the state.

The order is fixed: search (260px, fires after 300 ms) → status chips (one radiogroup; the first chip is "All …") → selects ("All tiers", "Any followers", "All platforms", "All groups": the first option is the label) → any other filter (a date, a Segmented) → Sort by + ⇅ → Reset filters (only while something is set) → Export CSV (pushed to the end) → extra (the PR My brands / All brands switch).

<ListToolbar
  search={{ value: q, onChange: (v) => list.set({ q: v }), placeholder: 'Search name, @handle or coupon' }}
  chips={{ label: 'Status', value: chip, onChange: (v) => list.set({ chip: v }), options: STATUS_CHIPS }}
  selects={[tierSelect, followerSelect, platformSelect, groupSelect]}
  sort={{ value: sort, dir, options: SORTS, onChange: (k, d) => list.set({ sort: k, dir: d ?? dir }), onFlip }}
  reset={{ active: isFiltered, onReset: list.reset }}
  actions={<ButtonLink size="sm" href={csvUrl} download>Export CSV</ButtonLink>}
  extra={<Segmented size="sm" label="Brands" value={scope} onChange={setScope} options={[['my', 'My brands'], ['all', 'All brands']]} />}
  collapseFiltersBelow={600}
/>;

Tabs vs chips vs selects: PillTabs change the sub-page and its columns (My creators / Groups / Join requests / Invitations; Live / Upcoming / Settling / Ended / Brand requests), with counts. Chips filter one status dimension. Selects filter the other dimensions. A filter change always returns to page 1.

Do: write the placeholder as what it searches ("Search order, creator or coupon"); keep every filter in the URL (useListState, useHashState). Don't: hide the only status filter in a select; filter on the client what the server pages; show Reset when nothing is set.

5. Bulk actions

When: the viewer decides many rows the same way. In the mocks: PR Approvals › Join requests only (Reject, Approve n).

Components: DataTable selection ({ selected, onChange, rowLabel }); PrBulkBar + BulkAction (approve lime, danger dark, plain) in the PR look, which replaces the toolbar's scope switch while rows are selected (ListToolbar.extra); BulkBar (the kit's accent bar between toolbar and table, persistent to show it with nothing selected, buttons disabled).

extra={selected.size ? (
  <PrBulkBar count={selected.size} onClear={() => setSelected(new Set())}>
    <BulkAction kind="danger" onClick={() => setRejecting(rowsSelected)}>Reject</BulkAction>
    <BulkAction kind="approve" onClick={() => approve(rowsSelected)}>{`Approve ${selected.size}`}</BulkAction>
  </PrBulkBar>
) : scopeSwitch}

Do: keep the selection across pages (the header checkbox toggles only this page's keys: togglePageSelection); put the count in the button ("Approve 3"); ask once for a bulk reason ("Same reason for all"); toast the result with Undo ("3 creators approved"). Don't: offer a bulk action without a single-row one; leave the selection set after the action ran.

6. Forms and validation

When: creating or requesting something short (a modal), or editing settings (a page or card with a save bar).

Components: FormField (label, the one control, hint, error; it sets id, aria-describedby, aria-invalid), native input / select / textarea (42px, radius 12, raspberry focus ring), Switch (iOS 51 × 31, rowLabelled in a KeyValue row), Segmented, ChoiceGroup, CommissionInput, NumberSetting, SaveBar; the data side useAction (fieldErrors, error, pending) and useServerErrors (blocks re-apply a 422 and focus the first invalid field). Ready-made forms: GroupForm, SpecialCommissionForm, ChallengeRequestForm, RecordGiftsDialog, MessageFields.

const [days, setDays] = useState('90');
const save = useAction<Settings>({ method: 'PATCH', url: '/gift-rules' }, { onDone: () => setToast({ message: 'Gift rules saved' }) });

<FormField label="Gift cooldown" hint="Default 90 days" error={local.days ?? save.fieldErrors.days}>
  <input type="number" min={1} max={365} value={days} onChange={(e) => setDays(e.target.value)} />
</FormField>
{save.error && !Object.keys(save.fieldErrors).length && <p role="alert" className="kit-field-err">{save.error}</p>}
<SaveBar dirty={dirty} saving={save.pending} saveDisabled={Boolean(local.days)} onSave={() => save.run(draft)} onDiscard={reset} />;

Rules: validate on send; show the error under its field in a sentence ("Give the challenge a title", "Cooldown must be a whole number from 1 to 365 days"); a 422 maps field by field (fieldErrorsOf); a refusal or a network failure is one alert line; the server's own words reach the viewer only for a 422 or a business refusal. The mocks toast validation errors; the library always puts them on the field.

Dates: show dates as the mocks write them, day and short month, with the year when it is not this year ("1 Nov", "13 Nov 2026", "15 Jul 2026"; a range "1 Nov → 30 Nov"), formatted by the app or the server, never toLocaleDateString defaults. A native <input type="date"> shows the browser's locale order ("12/10/2026" in a US browser) and sends YYYY-MM-DD: keep the native input for picking (it gives the platform picker and keyboard entry), send and store YYYY-MM-DD (ListToolbar.date takes the same), and repeat the chosen date in the mocks' format where it matters (a hint, the summary, the confirmation). In Arabic the month is Arabic and the digits stay Latin ("1 نوفمبر").

Do: mark optional fields in the label ("Dates (optional)"); accept Arabic digits and convert (toAsciiDigits); keep the action enabled so a press explains what is missing. Don't: disable Save with no explanation; clear what the viewer typed after a failed send; use placeholder text as the label.

7. Modals, drawers and details drawers

SizeUse forMock examples
Drawer400px floating sheet from the inline end (inset 12, radius 24); PR theme 420px; size="wide" 560pxone record's details and its actions, opened from a row or cardcreator, group, order, gift order, payout batch, product, challenge, message, PR creator
Modalcentred 660px, radius 26 (wide 760px; PR theme 480px)a short task that needs the viewer's attention: a form, a confirmation, a reason, an explainerRequest a challenge, Raise your creator limit, Choose gift products, New group, Reject …?, How the TRNDR score works
DetailsDrawerthe drawer with a hero, tiles and sections from datadeprecated since 0.5.0: compose Drawer + DrawerHead + KeyValue + RowItems (+ StepTimeline, RankList) instead—
A pagefull width, breadcrumba record with its own sub-lists or an editorPR brand page, challenge page, request page, gift shipment, program editor

Ready-made drawer bodies: MyCreatorPanel, CreatorProfilePanel, GroupPanel, ChallengeDetail, BonusDetail, PayoutBatchDetail, PrCreatorDrawer, FraudCaseDetail.

const [openRow, setOpenRow] = useState<{ id: number; name: string } | null>(null);
const drawer = useDrawerResource<CreatorDetail, { id: number; name: string }>(openRow ? `/creators/${openRow.id}` : null, openRow);

<Drawer open={drawer.open} loading={drawer.loading} onClose={() => setOpenRow(null)} title={drawer.seed?.name ?? ''}
  lead={drawer.seed && <Avatar name={drawer.seed.name} seed={drawer.seed.id} size="lg" />}>
  {drawer.error ? <AsyncBlock state={{ status: 'error', error: drawer.error, reload: drawer.retry }} skeleton={null}>{() => null}</AsyncBlock>
    : drawer.data && <MyCreatorPanel {...toPanel(drawer.data)} />}
</Drawer>;

The drawer opens on the click with what the row already knows (seed) and stays the same dialog while its body swaps from DialogSkeleton to the content. Keep the open row's id in the URL (useHashState with { history: 'push' }) so Back closes it; useOpenedRow reads the row from the current page so an action updates it.

Do: one drawer at a time; a modal may open over a drawer (a reject reason from the creator drawer). Don't: put a long editor in a drawer, or a record's details in a modal; nest modals.

8. Confirmation and reason dialogs

When: an action that is hard to undo or that the other side sees (remove, reject, pause, change a tier, adjust a wallet).

Components: Modal with Cancel + the action in footer for a plain confirmation (the kit story "Remove Mona Saeed?": "Their coupon stops at once. Commission they already earned is still paid."); ReasonDialog when a reason is required: mode="select" (reasons + an optional note "(optional, they'll see it)") for rejections, mode="text" (a required free-text reason) for pause and tier moves; tone="rasp" for a rejection or pause, ink for a neutral save; TierChangeDialog for a manual tier change.

<ReasonDialog open={Boolean(target)} onClose={close} mode="select" tone="rasp" confirmLabel="Reject"
  title={`Reject ${target.creator.name}?`}
  sub={`They won't join ${target.brand.name}. They can request again after 2 weeks (29 Nov 2026).`}
  reasons={[{ value: 'fit', label: 'Not a fit for this brand' }, { value: 'audience', label: "Audience doesn't match" }, { value: 'competitor', label: 'Already promoting a competitor' }, { value: 'other', label: 'Other' }]}
  busy={reject.pending} error={reject.error} onConfirm={({ reason, note }) => reject.run({ id: target.id, reason, note })} />;

Do: name the object in the title ("Reject Sara Ali?", "Pause Glow Lab?") and the consequence in sub; label the button with the verb. Don't: ask "Are you sure?"; confirm actions that Undo covers (approve: toast with Undo instead).

9. Toasts and inline feedback

FeedbackComponentWhen
ToastToastRegion ({ message, actionLabel?, onAction? }): an ink pill at the bottom centre, 5 s, the action in limethe outcome of an action the viewer just took: "Invite link copied", "CSV of this list downloaded", "Request sent to the TRNDR team", "Sara Ali approved into Glow Lab · Undo"
BannerBanner tones info (sky), warn (butter), lime, bad (rasp, an alert); iconSize="sm" for the one-line brand bannera standing fact about the page: "79 seats left…", "The TRNDR team reviews every join request…", "Low: 17% of your last top-up is left…", a brand below zero with "Remind brand"
Field errorFormField errorone field is wrong
Alert linerole="alert" text above the buttons (ReasonDialog error)the whole send failed
Copy feedbackCouponChip, CopyLink, CopyLinkField ("Copied")in place, no toast needed
Save barSaveBar ("Unsaved changes · Discard · Save")a page editor with a draft
const [toast, setToast] = useState<ToastMessage | null>(null);
// after a success:
setToast({ message: `${row.creator.name} rejected`, actionLabel: 'Undo', onAction: undoReject });
<ToastRegion toast={toast} onDismiss={() => setToast(null)} />; // keep it mounted: the live region must exist before its text

Do: write toasts as the concrete outcome, with the object ("Glow Lab paused · codes stopped"); offer Undo for decisions in the PR portal. Don't: toast errors that belong to a field; stack toasts; put a banner's warning only in a toast.

10. Empty, loading and error

When: every block that reads data. See the Loading, error and empty states card.

StateCard or blockListWhole view
LoadingAsyncBlock → your skeleton (Skeleton shape="line" | "rows" | "tile" | "hero")DataTable loading (skeleton rows; later pages keep rows, aria-busy)drawer: Drawer loading → DialogSkeleton
EmptyAsyncBlock empty + isEmpty"Nothing matches these filters. Clear filters" (onClearFilters) or your empty (PrEmpty: "No join requests", "Everyone is vetted")EmptyView (title, a sentence, tag, action)
ErrorAsyncBlock → message + RetryDataTable error + onRetry ("Try again")ScreenErrorBoundary ("This part could not load · Retry")
<AsyncBlock state={useResource<Summary>('/summary')} skeleton={<Skeleton shape="tile" count={4} />}>
  {(s) => <KpiGrid>{toCards(s)}</KpiGrid>}
</AsyncBlock>;

Do: shape skeletons like the content; keep old data while reloading; give every error a Retry. Don't: show a spinner alone; show raw HTTP errors (httpError gives the EN/AR copy: "We couldn't load this. Please try again.", "You don't have permission to do this.", "Your session expired. Sign in again.").

11. Money and the "?" notes

When: every money figure. Money arrives from the server as 2-dp strings ("184300.00"); the browser formats, never computes (a bar width from two figures is ratioWidth, the only arithmetic allowed).

Components: Money (value, compact for "EGP 184.3K", money display options, slot); MoneyFigure (label + "?" + amount, the one way to show a labelled figure); MoneyNote (the "?" or the dotted term for a money label; variant term / plain / icon, or moneyNoteStyle on the provider); DataColumn.figure, KeyValueItem.figure, RowItems.figure (the header's "?"); Term (a dotted word with a tip for anything that is not money: "Score", "Discount", "Gift cooldown", "Selected / Reserved / Remaining"). The notes are the app's: pass moneyNotes (figure → { label, includes, excludes }, already in the page language) to BricksProvider or MoneyNotesProvider.

<KeyValue items={[
  { label: <MoneyNote figure="wallet_available">Available</MoneyNote>, value: <Money value="43390.00" /> },
  { label: 'Held', value: <Money value="18450.00" />, figure: 'wallet_held' },
]} />;
const sales: DataColumn<Creator> = { key: 'sales', label: 'Sales', figure: 'creator_sales', align: 'end', render: (c) => <Money value={c.sales} compact /> };
const discount: DataColumn<Coupon> = { key: 'discount', label: 'Discount', tip: 'What the shopper saves with this coupon', render: () => '10% off' }; // a non-money term
<b><Term tip="Days a creator waits after a gift before picking another one">Gift cooldown</Term></b>; // the Gift rules row label

Formats: English "EGP 1,234.50", Arabic "1,234.50 ج.م" (TRNDR_CURRENCY); money and numbers stay LTR and tabular inside Arabic text. Signs in ledgers: "+ EGP …" green, "− EGP …" red.

Do: give every money label its note the first time it appears on a surface; use compact in dense tables and tiles, full in ledgers, payouts and drawers. Don't: add, subtract or round money in the browser; put a "?" button inside a sort button (DataTable places it beside); invent a figure key (the type allows only MONEY_FIGURES).

12. Statuses and tiers

When: a record's state (a pill) or a creator's level (a tier chip).

Components: StatusPill status="…" (the Brand table, statuses): ok active, live, accepted, approved, paid, delivered; warn paused, waiting ("Waiting for TRNDR"), waiting_reply, pending, with_trndr, on_hold, partial; sky shipped, scheduled; mute ended, removed; bad expired, stopped, declined, rejected, revoked. PrStatusPill reads statusTables.pr (programs, challenges, requests, creators, join sources, payouts, receipts, top-ups, gift states, audit areas). PrCountPill for a status with a number ("Pauses in 3 days", "5 waiting"). WalletHealthPill (Healthy, Low funds, "Below zero · day 4/7", Paused). TierChip / TierBadge: Rising (lime), Established (sky), Influential (teal), Elite (gold, a star); no tier yet = Rising. Pill tones: ok, warn, bad, mute, sky, lime, lilac.

<StatusPill status="with_trndr" />            // "With TRNDR"
<PrStatusPill status="brand_invite" />        // the join source
<PrCountPill status="pauses_in" count={3} />  // "Pauses in 3 days"
<TierChip tier="established" />

Do: add a status to the provider's table (statuses, statusTables) with EN and AR words and a tone, once, so it reads the same on every screen; let the word carry the meaning (the tone repeats it). Don't: colour a status by hand; use bad (red) for anything that is not a failure or a refusal; show an unknown key's raw name (it shows muted and is reported once, so add it).

13. Navigation

When: the app frame.

Components: AppShell (brand, nav groups as data, activeId, onNavigate, header, sidebarCard, sidebarFooter, sheetFooter, bottomNavIds), NavGroups, Sidebar, SidebarCard, SidebarUser, BottomNav, MobileNavSheet, PillTabs for sub-pages, AppHeader breadcrumbs for detail pages.

Nav items (NavItem): label as { en, ar }, icon, count (waiting work; nothing for 0; "999+"), hot (a red count: only late work), badge (new lime "NEW" or soon muted "LATER", instead of the count), disabled, indent, href. Groups (NavGroup): heading ("Campaigns", "Next sprint"), collapsible (a More group, open while one of its items is active).

TierWidthFrame
desktop> 1024pxfull sidebar
tablet860–1024px72px icon rail, labels as tooltips, counts as dots, expands over the content (Escape or the scrim closes it)
phone< 860pxa tab bar (bottomNavIds, default the first four items with an icon, plus More; no count badges) and a modal nav sheet with the whole nav
const NAV: NavGroup[] = [
  { id: 'top', items: [
    { id: 'home', label: { en: 'Home', ar: 'الرئيسية' }, icon: 'home' },
    { id: 'approvals', label: { en: 'Approvals', ar: 'الموافقات' }, icon: 'approvals', count: 9 },
    { id: 'brands', label: { en: 'Brands', ar: 'البراندات' }, icon: 'brands' },
  ] },
  { id: 'campaigns', heading: { en: 'Campaigns', ar: 'الحملات' }, items: [
    { id: 'programs', label: { en: 'Affiliate programs', ar: 'برامج الأفلييت' }, indent: true, count: 3 },
    { id: 'gifts', label: { en: 'Gift stock', ar: 'مخزون الهدايا' }, indent: true, count: 3 },
  ] },
  { id: 'next', heading: { en: 'Next sprint', ar: 'السبرنت الجاي' }, items: [
    { id: 'payouts', label: { en: 'Payouts', ar: 'المدفوعات' }, icon: 'payments', disabled: true, badge: { label: { en: 'LATER', ar: 'بعدين' }, tone: 'soon' } },
  ] },
];
const screenNode: ReactNode = <HomeScreen />;
<AppShell brand={brand} nav={NAV} activeId={route} onNavigate={(item) => go(item.id)} header={header} sidebarCard={needAHand}>{screenNode}</AppShell>;

The Brand nav is one group of nine (Home, Find creators NEW, Creators 304, Coupons 304, Motivation 2, Payments, Analytics, Activity log, Settings). Do: count only work waiting for the viewer; keep the URL the source of the route. Don't: put more than four items in the tab bar; use hot for a plain count.

14. Language and RTL

When: always: every screen ships in English and Egyptian Arabic.

How: BricksProvider language sets the language for everything below (a component's own language prop still wins); the shell sets dir. Labels that are data take { en, ar } (NavLabel); component words come from the kit and package copy tables and can be overridden with labels on the provider or a component's labels / copy prop. LanguageToggle shows the other language ("عربي" in English, "EN" in Arabic).

What mirrors: layout (logical properties throughout), the drawer (slides from the left), chevrons and pager arrows, the select chevron, switches' knob travel, the sort and flip buttons. What does not: money, numbers, dates, handles, codes and URLs stay LTR (isolated with bdi / dir); charts stay LTR. Mixed text keeps the page's direction when it has a letter of the page's script (bidiDir): "Kemet Home تحت الصفر" stays RTL. Arabic uses Cairo with a taller line height; English uses Inter and Plus Jakarta Sans for display.

<BricksProvider preset={trndrPreset} language="ar" moneyNotes={NOTES.ar}>
  <Banner tone="info" language="ar">فريق TRNDR بيراجع كل طلب انضمام.</Banner>
</BricksProvider>;

Do: test every screen in Arabic (each screen renders { language: 'ar' }); write Arabic copy in the mocks' Egyptian register ("جرّب تاني", "امسح الفلاتر"). Don't: hard-code left / right, or flip icons by hand; translate a brand, a coupon code or a handle.

15. Data fetching and URL state

When: any screen that reads or writes the server.

NeedHookGives
One client for the appcreateHttpClient + DataProviderJSON, same-origin cookies, CSRF on writes to trusted origins, onUnauthorized for 401/419, HttpError { status, message, errors, code }
A GETuseResource(url | null, { params, enabled, keepPrevious }){ status: 'idle' | 'loading' | 'ready' | 'error', data, error, reload, url }; race-safe; null = idle (no permission)
A paged GETusePaged(url, { params, perPage, adapter, page, onPageChange })rows, page, lastPage, total, summary, setPage; envelopes pagination, meta, paginator, array, auto
A whole list (search, chip, selects, sort, page) in the hashuseListState({ namespace, defaults, fetcher, enabled, inHash }) + listFetcher(client, url, { chipParam, params, adapter, toParams })query, rows, total, lastPage, loading, error, retry, set(patch), reset(); any change but the page goes back to page 1; an emptied last page steps back
A writeuseAction(spec | fn, { onDone, onError, codes })run(input) never rejects → { ok, data } or { ok: false, kind, message, fieldErrors }; pending, error, fieldErrors, reset; a double click sends once
A drawer's recorduseDrawerResource(url | null, seed)open, seed, data, loading, error, retry
Screen state in the URLuseHashState(namespace, defaults) / useQueryState, useUrlSort(keys, { fallback })[state, patch, reset]; a value equal to its default leaves the URL; { history: 'push' } for a step Back should undo
TypinguseDebouncedCallback, useDebouncedValuesearch after a pause (300 ms)
const client = useHttpClient();
const fetcher = useMemo(() => listFetcher<Creator>(client, '/creators', { chipParam: 'status' }), [client]);
const list = useListState<Creator>({ namespace: 'cr', defaults: { chip: 'all', sort: 'sales', dir: 'desc' }, fetcher });
// #creators?cr.q=sara&cr.status=paused&cr.sort=orders&cr.page=2  ← reload, Back and a shared link land here

const pause = useAction((id: number, http) => http.post(`/creators/${id}/pause`), {
  onDone: () => { list.retry(); setToast({ message: 'Coupon paused' }); },
  codes: { wallet_busy: { en: 'The wallet is busy. Try again in a minute.', ar: '…' } },
});

Do: create the client once (a module constant or the DataProvider); give each list on a screen its own namespace; pass null as the URL when the viewer may not read it. Don't: fetch in components below the screen (blocks take data as props and report actions through callbacks); keep list state in component state when it should survive a reload; show the server's English for a session, permission or server failure (the hooks map it to EN/AR copy).

On this page