@spark-web/design-system 5.1.3 → 5.1.5

package/patterns/vendor-admin/dashboard.md

@@ -0,0 +1,681 @@
+# Vendor admin — dashboard / overview page pattern
+
+## Before using this pattern
+
+Read `node_modules/@spark-web/design-system/patterns/vendor-admin/CLAUDE.md`
+fully before implementing this pattern. The layout-shell rule, the page-title
+rule (and its **documented dashboard exception** — see "Page titling" below),
+the spacing/density rule, the role/feature-flag gating rule, and the badge tone
+mapping defined there all apply to this pattern and take precedence over
+component-level rules.
+
+Working in vendor-portal? Apply the substitutions in
+`node_modules/@spark-web/design-system/patterns/vendor-admin/vendor-portal.md`.
+
+## What this pattern is
+
+The vendor landing / overview / home screen — the first screen a vendor /
+installer / partner sees after signing in. It summarises the account at a
+glance: a **metrics summary** (stat cards that click through to the underlying
+list), a **resources section** (downloadable assets, links, promo cards), and an
+optional, often flag-gated **announcements / news feed** ("What's New"). On a
+vendor's first visit it may also raise a **first-run consent modal** that must
+be acknowledged before the screen is usable.
+
+It renders inside the vendor-admin shell (fixed Header + left NavBar) like every
+other vendor-admin page, but its **page shell differs** from both the list page
+and the form page: it is a responsive **multi-panel layout** — a primary content
+panel plus an optional secondary feed panel — not the full-height single scroll
+region of the list page and not the `Container`-centered column of the form
+page.
+
+## When to use this pattern
+
+Use this pattern when the PRD describes any of the following:
+
+- A "dashboard", "home", "overview", "landing", or "welcome" screen for a vendor
+- A screen that summarises counts / totals across the account (applications
+  under review, approved, paid) as headline stats the user can click into
+- A screen that bundles resources, downloads, promo cards, and/or a product
+  announcements / news feed
+- A screen with a first-run consent / onboarding acknowledgement gate
+
+If the screen is primarily a searchable, filterable table of records, use the
+list-page pattern; if it is a settings / edit form, use the form-page pattern:
+
+- `node_modules/@spark-web/design-system/patterns/vendor-admin/list-page.md`
+- `node_modules/@spark-web/design-system/patterns/vendor-admin/form-page.md`
+
+---
+
+## Component docs to read
+
+Read these before implementing — they own the component-level rules. Only read
+the ones the screen actually uses:
+
+- `node_modules/@spark-web/row/CLAUDE.md` — Row API; the primary/secondary panel
+  layout (and its `flexDirection` collapse on mobile)
+- `node_modules/@spark-web/columns/CLAUDE.md` — Columns API; `collapseBelow`,
+  `gap`, `template` — the metrics and resources grids
+- `node_modules/@spark-web/box/CLAUDE.md` — Box layout utilities (panels, card
+  placeholders, banner)
+- `node_modules/@spark-web/stack/CLAUDE.md` — vertical stacking, gap
+- `node_modules/@spark-web/heading/CLAUDE.md` — section headings (`level="2"`),
+  card sub-headings (`level="3"`)
+- `node_modules/@spark-web/text/CLAUDE.md` — Text API (stat numbers, labels,
+  card copy)
+- `node_modules/@spark-web/icon/CLAUDE.md` — icon sizing / tones
+  (`ArrowRightIcon`, `ArrowNarrowRightIcon`, `PhoneIcon`)
+- `node_modules/@spark-web/button/CLAUDE.md` — `Button` / `ButtonLink` (resource
+  card actions, "Load More", consent Continue), `loading` prop
+- `node_modules/@spark-web/text-link/README.md` — `TextLink` (in-prose links,
+  e.g. the consent modal's requirements link)
+- `node_modules/@spark-web/modal-dialog/CLAUDE.md` — `ContentDialog` (the
+  first-run consent modal and any document dialog)
+- `node_modules/@spark-web/alert/CLAUDE.md` — sanitized announcement banner /
+  page-level feedback
+
+---
+
+## Page structure
+
+```
+Page (renders into the vendor-admin shell content region — no Header/NavBar here)
+  Row (panel frame)                      — flexDirection row; collapses to column on mobile (responsive prop)
+    Primary panel (Box)                  — flexGrow={1}; padding responsive; the metrics + resources content
+      Banner (conditional)               — sanitized announcement Alert/Text — NEVER dangerouslySetInnerHTML
+      Metrics section
+        Heading level="2"                — section heading (dashboard exception: no single page title)
+        Columns                          — MetricCard placeholders (COMPONENT GAP) — collapseBelow, gap
+      Resources section
+        Heading level="2"                — section heading
+        Columns                          — resource / promo cards (primitives — Box/Stack/Button/icon)
+      Help / contact banner (optional)   — Box with PhoneIcon + Text (+ TextLink/Link)
+    Secondary panel (conditional)        — announcements feed; rendered only when the feed flag is on
+      AnnouncementsFeed                  — "What's New" timeline + "Load More" (COMPONENT GAP placeholder)
+  ContentDialog (conditional)            — first-run consent modal; showCloseButton={false}, Continue persists flag
+```
+
+The primary panel and the secondary feed panel sit side by side on tablet and up
+and **stack vertically on mobile**. The feed panel is optional and frequently
+behind a feature flag (consumer logic — see the surface gating rule).
+
+---
+
+## Page shell — multi-panel layout
+
+The dashboard shell is a responsive two-panel frame, **not** the list page's
+`Stack height="full"` scroll region and **not** the form page's
+`Container size="medium"`. Use `Row` from `@spark-web/row` for the panel frame:
+a primary content panel (`flexGrow={1}`) and an optional secondary feed panel.
+
+`Row` renders a non-wrapping flex row and **locks `flexDirection`** (it is a
+removed Box prop on `Row`). To flip the panels to a vertical stack on mobile,
+Row alone cannot do it — so the canonical shell uses a `Box display="flex"` with
+a **responsive `flexDirection`** prop, which is the supported Spark way to
+express the collapse without raw CSS:
+
+```tsx
+import { Box } from '@spark-web/box';
+
+<Box display="flex" flexDirection={{ mobile: 'column', tablet: 'row' }}>
+  <Box
+    flexGrow={1}
+    padding={{ mobile: 'medium', tablet: 'xlarge' }}
+    width={{ mobile: 'full' }}
+  >
+    {/* primary panel — metrics + resources */}
+  </Box>
+
+  {feedEnabled && (
+    <Box
+      padding={{ mobile: 'medium', tablet: 'xlarge' }}
+      width={{ mobile: 'full' }}
+    >
+      {/* secondary panel — announcements feed */}
+    </Box>
+  )}
+</Box>;
+```
+
+Rules:
+
+- The shell is a `Box display="flex"` with
+  `flexDirection={{ mobile: 'column', tablet: 'row' }}` — primary panel
+  side-by-side with the optional feed on tablet+, stacked on mobile. This is the
+  Spark-native responsive collapse; **do not** reach for a raw
+  `@media (max-width: …)` `flexDirection` flip (the vendor-portal source does
+  this with `css`/`className`; the canonical pattern does not — see the
+  Documented exceptions table).
+- `Row` from `@spark-web/row` is the correct primitive **only when the layout
+  never needs to flip axis** (e.g. an action bar). Because the dashboard panels
+  must stack on mobile and `Row` locks `flexDirection`, use the responsive `Box`
+  above for the panel frame. (You may still use `Row` for inner left/right rows
+  such as a card's value-plus-arrow line.)
+- Each panel sets its own responsive `padding`
+  (`{ mobile: 'medium', tablet: 'xlarge' }`) and `width={{ mobile: 'full' }}` —
+  spacing comes from tokens, never raw pixels.
+- The page does **not** reproduce the shell Header / NavBar — the shell wraps
+  the page (surface rule); the page starts at the panel frame.
+- A fixed secondary-panel width (e.g. the feed taking ~40% on tablet+) is a
+  product-design decision: prefer `Columns template={[…]}` or a panel `width`
+  token. If a precise non-token width is genuinely required it goes in the
+  Documented exceptions table — do not inline a raw width silently.
+
+---
+
+## Page titling — documented dashboard exception
+
+**The dashboard is a documented exception to the surface page-title rule** (see
+the surface rules' "Page title rule"): it leads with **section-level
+`Heading level="2"` headings** ("Summary", "Support & resources", "What's New")
+standing in for the page title, with **no separate page title**.
+
+Rationale: (1) the fixed shell Header already carries the product identity
+("Brighte Partner Portal"), so a redundant in-page "Dashboard" title adds
+nothing; (2) a dashboard is inherently multi-panel with several co-equal
+sections, none of which is "the page"; (3) it matches the observed
+implementation. The surface rules note this exception and point here.
+
+Rules:
+
+- Headings **within** a section (e.g. a card title, the document-dialog title)
+  step down to `Heading level="3"` (or `level="4"` for a dialog sub-title where
+  the dialog itself owns the `level="3"`).
+- Do **not** add a single `Heading level="2">Dashboard</Heading>` above the
+  sections and then push the section headings to `level="3"` — that is the
+  rejected alternative. Lead with section-level `level="2"` headings directly.
+- `Heading`'s `level` union is `'1' | '2' | '3' | '4'`; its `tone` may be
+  `neutral` (the observed section-heading tone), `primary`, `primaryActive`, or
+  `muted`.
+
+---
+
+## Section 1 — Metrics summary
+
+A row of metric / stat cards in a `Columns` grid: a headline number, a label, a
+subtitle (e.g. a financed total), and a click-through that opens the underlying
+list filtered to that status.
+
+There is **no `@spark-web` stat / metric / KPI card component** (verified — no
+package under `packages/` provides one). The metric card is therefore a
+**COMPONENT GAP**. **COMPONENT GAP protocol** (this applies to every gap in this
+file): build the placeholder from primitives, mark the first use with a
+`// COMPONENT GAP: <Name> needed — not yet in Spark` comment, and flag it for
+**product design review before production — the placeholder is a stop-gap; do
+not ship as-is**.
+
+```tsx
+import { Box } from '@spark-web/box';
+import { Heading } from '@spark-web/heading';
+import { Columns } from '@spark-web/columns';
+import { Stack } from '@spark-web/stack';
+import { Text } from '@spark-web/text';
+import { ArrowRightIcon } from '@spark-web/icon';
+
+<Box marginTop="small">
+  <Heading level="2" tone="neutral">
+    Summary
+  </Heading>
+
+  <Columns
+    marginTop="xlarge"
+    gap={{ mobile: 'small', tablet: 'large' }}
+    collapseBelow="wide"
+  >
+    {metrics.map(metric => (
+      /* COMPONENT GAP: MetricCard needed — not yet in Spark — protocol: see
+         the Section 1 intro; prop contract: see the rules below. */
+      <Box
+        key={metric.id}
+        background="surface"
+        border="standard"
+        borderRadius="large"
+        padding="large"
+        cursor="pointer"
+        onClick={() => onMetricClick(metric)}
+      >
+        <Stack gap="medium">
+          <Text size="xxlarge" weight="bold" tone="neutral">
+            {metric.value}
+          </Text>
+          <Text weight="semibold" tone="primary">
+            {metric.label}
+          </Text>
+          <Box display="flex" justifyContent="spaceBetween" alignItems="center">
+            {metric.subtitle && (
+              <Text size="xsmall" tone="muted">
+                {metric.subtitle}
+              </Text>
+            )}
+            <ArrowRightIcon size="xsmall" tone="primary" />
+          </Box>
+        </Stack>
+      </Box>
+    ))}
+  </Columns>
+</Box>;
+```
+
+Rules:
+
+- **MetricCard is a COMPONENT GAP** — mark the first use with
+  `// COMPONENT GAP: MetricCard needed — not yet in Spark` (protocol: see the
+  Section 1 intro). Prop contract: `value` (string — the headline number, e.g. a
+  `toLocaleString()`'d count), `label` (string), `subtitle` (string, optional),
+  and exactly one of `href` / `onClick` for the click-through.
+- Lay cards out with `Columns` (`collapseBelow="wide"`, responsive `gap`) — one
+  card per column, equal width. Do not hand-roll a flex grid.
+- The headline number is a `Text` with a large size/weight — **never** a raw
+  `style={{ fontSize: '34px' }}` (the vendor-portal source does this; use a Text
+  size token such as `xxlarge` — 35px, the closest token to the raw 34px —
+  instead). Status counts are plain numbers here, not `Badge`s — the badge tone
+  mapping applies to status _labels_ in tables, not to dashboard headline
+  figures.
+- The click-through navigates to the underlying list filtered to that metric
+  (e.g. `/applications?status=approved`); wire it via `onClick`/`href`. Role /
+  flag visibility of individual metrics (e.g. hiding "Paid" for non-vendor
+  roles) is consumer gating logic, not a design-system rule.
+- Working in vendor-portal? The overlay substitutes the consumer's
+  `DashboardMetrics` / `MetricCard` — see the overlay.
+
+---
+
+## Section 2 — Resources
+
+A `Columns` grid of resource / promo cards — a media image, a heading, body
+copy, and an action (`Button` / `ButtonLink` / link), and/or a link list that
+opens in a document dialog. Resource cards are **lighter than a component gap**:
+they compose cleanly from primitives (`Box`/`Stack`/`Text`/`Button`/`Icon`/
+`Image`), so build them from primitives directly — no `// COMPONENT GAP` flag is
+required. (They are a reusable _consumer_ card, not a missing Spark primitive;
+if a repo wants to factor the repeated card chrome into a local component, that
+is a consumer convenience, noted in the overlay — not a Spark gap.)
+
+```tsx
+import { Box } from '@spark-web/box';
+import { Heading } from '@spark-web/heading';
+import { Columns } from '@spark-web/columns';
+import { Button, ButtonLink } from '@spark-web/button';
+import { Stack } from '@spark-web/stack';
+import { Text } from '@spark-web/text';
+import { ArrowNarrowRightIcon } from '@spark-web/icon';
+
+<Box marginTop="xxlarge">
+  <Heading level="2" tone="neutral">
+    Support &amp; resources
+  </Heading>
+
+  <Columns
+    marginTop="xlarge"
+    gap={{ mobile: 'medium', tablet: 'medium', desktop: 'large' }}
+    collapseBelow="wide"
+  >
+    {resources.map(resource => (
+      <Box
+        key={resource.id}
+        background="surface"
+        border="standard"
+        borderRadius="large"
+        padding="large"
+        display="flex"
+        flexDirection="column"
+        height="full"
+      >
+        <Stack gap="large">
+          <Text size="large" weight="semibold" tone="neutral">
+            {resource.heading}
+          </Text>
+          <Box>
+            <ButtonLink href={resource.href} target="_blank">
+              {resource.actionLabel}
+              <ArrowNarrowRightIcon size="xxsmall" tone="primary" />
+            </ButtonLink>
+          </Box>
+        </Stack>
+      </Box>
+    ))}
+  </Columns>
+</Box>;
+```
+
+Rules:
+
+- Build resource / promo cards from primitives (`Box` card chrome —
+  `background="surface" border="standard" borderRadius="large" padding="large"`
+  — plus `Stack`/`Text`/`Button`). No COMPONENT GAP flag — these are not a
+  missing Spark primitive.
+- Card actions are `Button` (`onClick`) or `ButtonLink` (`href`, opens in a new
+  tab with `target="_blank"`) from `@spark-web/button` — never a raw `<a>`
+  styled as a button.
+- A long list of downloadable documents that opens in a modal is a
+  `ContentDialog` from `@spark-web/modal-dialog` (see Section 4 — same component
+  family as the consent modal): a `size="small"` dialog whose body is a `Stack`
+  of `TextLink`s. Working in vendor-portal? The overlay maps its
+  `DashboardAds`/`AdCard` and `DocumentsDialog`.
+
+---
+
+## Section 3 — Announcements / news feed (optional, flag-gated)
+
+An optional secondary-panel "What's New" feed: a vertical timeline of article
+items (date, image, heading, intro, "Learn more" link), with incremental **"Load
+More"** loading. The feed is usually behind a feature flag (consumer gating) and
+renders only when enabled.
+
+There is **no `@spark-web` feed / timeline / article-list component** — the feed
+container is a **COMPONENT GAP** (protocol: see Section 1); the placeholder is
+`Box as="article"` items in a `Stack`, plus a "Load More" `Button`.
+
+```tsx
+import { Box } from '@spark-web/box';
+import { Heading } from '@spark-web/heading';
+import { Stack } from '@spark-web/stack';
+import { Text } from '@spark-web/text';
+import { Button } from '@spark-web/button';
+import { TextLink } from '@spark-web/text-link';
+
+{
+  /* COMPONENT GAP: AnnouncementsFeed needed — not yet in Spark — protocol: see
+     Section 1; prop contract: see the rules below. */
+}
+{
+  feedEnabled && (
+    <Stack gap="xlarge" width={{ mobile: 'full' }}>
+      <Heading level="2" tone="neutral">
+        What&apos;s New
+      </Heading>
+
+      <Stack gap="xlarge">
+        {items.map(item => (
+          <Box as="article" key={item.id}>
+            <Stack gap="small">
+              <Text size="small" tone="muted">
+                {item.date}
+              </Text>
+              <Text weight="bold" tone="neutral">
+                {item.heading}
+              </Text>
+              <Text size="small" tone="neutral">
+                {item.intro}
+              </Text>
+              <TextLink href={item.href} target="_blank">
+                Learn more
+              </TextLink>
+            </Stack>
+          </Box>
+        ))}
+      </Stack>
+
+      {hasNextPage && (
+        <Button tone="neutral" loading={isLoading} onClick={onLoadMore}>
+          Load More
+        </Button>
+      )}
+    </Stack>
+  );
+}
+```
+
+Rules:
+
+- **AnnouncementsFeed is a COMPONENT GAP** — mark the first use with
+  `// COMPONENT GAP: AnnouncementsFeed needed — not yet in Spark` (protocol: see
+  Section 1). Prop contract: `items`
+  (`Array<{ id, date, heading, intro, href, imageUrl? }>`), `hasNextPage`
+  (boolean), `isLoading` (boolean), `onLoadMore` (`() => void`).
+- Each feed entry is a `Box as="article"` for correct semantics; the date is a
+  muted `Text`, the heading a bold `Text`, and "Learn more" a `TextLink` (in
+  body copy) or `ButtonLink` (as a button).
+- **"Load More" is a THIRD list-loading mode.** The list-page pattern recognises
+  infinite scroll and pagination; this feed uses **button-triggered incremental
+  loading** — a "Load More" `Button` that fetches and appends the next page on
+  click, with the Button's `loading` prop bound to the in-flight fetch. It is
+  distinct from auto-fetch-on-scroll (infinite scroll) and from page controls
+  (pagination). Use "Load More" for a short, browse-occasionally feed where the
+  user opts in to more rather than paging or endlessly scrolling. The surface
+  rules list it as the third recognised mode.
+- The feed panel renders only when its feature flag is on (consumer gating) —
+  when off, omit the secondary panel entirely (the primary panel then fills the
+  shell). Flag gating is consumer logic, not a design-system rule.
+- The vertical connector line / image styling in the observed implementation is
+  consumer chrome; keep the canonical placeholder to the semantic structure
+  above. Working in vendor-portal? The overlay maps its
+  `DashboardProductAnnouncements`.
+
+---
+
+## Section 4 — First-run consent / onboarding modal
+
+On first visit a vendor may need to acknowledge a consent / requirements
+statement before using the dashboard. This is a **real** `@spark-web` component
+— `ContentDialog` from `@spark-web/modal-dialog` — **not** a component gap.
+
+```tsx
+import { Button } from '@spark-web/button';
+import { ContentDialog } from '@spark-web/modal-dialog';
+import { Text } from '@spark-web/text';
+import { TextLink } from '@spark-web/text-link';
+
+<ContentDialog
+  isOpen={showConsent}
+  title="Vendor requirements"
+  showCloseButton={false}
+  footer={
+    <Button tone="primary" onClick={handleConsent}>
+      Continue
+    </Button>
+  }
+  onToggle={onConsentToggle}
+>
+  <Text>
+    By clicking Continue, you confirm your understanding and acceptance of the{' '}
+    <TextLink href={requirementsUrl} target="_blank">
+      vendor requirements
+    </TextLink>{' '}
+    document.
+  </Text>
+</ContentDialog>;
+```
+
+Rules:
+
+- Build it on `ContentDialog` (`@spark-web/modal-dialog`) — the controlled form
+  (`isOpen` + `onToggle`). Read the modal-dialog doc for the full API.
+- **`showCloseButton={false}`** — the gate must be acknowledged; do not give the
+  user an X to dismiss it.
+- The single footer action is a `Button tone="primary"` labelled "Continue" (or
+  similar). Its handler **persists the acknowledgement flag** (e.g. POSTs
+  `initialized: true` to the profile) so the modal does not reappear on the next
+  visit, then closes the modal.
+- **Gate placement:** drive `isOpen` from the persisted profile/initialised flag
+  — open the modal in an effect when the profile has loaded **and** the flag is
+  not yet set (`profile && !profile.initialized`), not unconditionally on mount.
+  Render the `ContentDialog` once, at the page root (a sibling of the panel
+  frame), with its open state as a prop — not conditionally mounted — so the
+  close transition runs. Keep the gate at the page level, not buried inside a
+  panel.
+- In-prose links inside the modal body are `TextLink` from
+  `@spark-web/text-link` (with `target="_blank"` for external docs) — never a
+  raw `<a>`.
+- A document-list dialog (Section 2) uses the **same** `ContentDialog` component
+  with `size="small"`; it differs only in that it may be dismissable.
+
+---
+
+## Security — NEVER use `dangerouslySetInnerHTML`
+
+The observed implementation renders an announcement banner via
+`<Text … dangerouslySetInnerHTML={{ __html: title + content }} />`. **Never do
+this.** Injecting server- or CMS-supplied HTML straight into the DOM is an XSS
+vector (the source even flags it `// this one may cause security issue (XSS)`).
+
+Render banner content as **sanitized text**, not HTML:
+
+```tsx
+import { Alert } from '@spark-web/alert';
+import { Text } from '@spark-web/text';
+
+{
+  banner && (
+    <Alert tone="info">
+      <Text>{banner.message}</Text>
+    </Alert>
+  );
+}
+```
+
+Rules:
+
+- A dashboard banner is an `Alert` from `@spark-web/alert` (or a `Box` +
+  `Text`), with its message rendered as **plain text children** — `Alert`'s
+  `tone` union is `caution | critical | info | positive` (use `info` for a
+  neutral announcement, `caution` for a time-sensitive notice).
+- If the banner genuinely needs rich content (a link), compose it from `Text` +
+  `TextLink` as React children — never pass an HTML string.
+- **NEVER** pass `dangerouslySetInnerHTML` to `Text`, `Box`, or any element on a
+  vendor-admin page. If the source HTML cannot be expressed as React children,
+  sanitize it server-side and render the sanitized text — do not inject raw
+  HTML.
+
+---
+
+## Structural skeleton
+
+Use this skeleton as the starting point for new builds and uplifts. Do not use
+existing page implementations as a structural reference.
+
+```tsx
+import { Box } from '@spark-web/box';
+
+<>
+  <Box display="flex" flexDirection={{ mobile: 'column', tablet: 'row' }}>
+    {/* Primary panel — metrics + resources */}
+    <Box
+      flexGrow={1}
+      padding={{ mobile: 'medium', tablet: 'xlarge' }}
+      width={{ mobile: 'full' }}
+    >
+      {/* Sanitized banner Alert (conditional) — NEVER dangerouslySetInnerHTML
+          — see the Security section above */}
+
+      {/* Section 1 — metrics: Heading level="2" + Columns of MetricCard
+          placeholders (COMPONENT GAP) — see above */}
+
+      {/* Section 2 — resources: Heading level="2" + Columns of primitive
+          resource / promo cards — see above */}
+    </Box>
+
+    {/* Secondary panel — Section 3: AnnouncementsFeed placeholder
+        (flag-gated, optional; COMPONENT GAP) — see above */}
+  </Box>
+
+  {/* Section 4 — first-run consent ContentDialog (real component, NOT a gap;
+      showCloseButton={false}, Continue persists the flag) — see above */}
+</>;
+```
+
+---
+
+## Documented exceptions summary
+
+No raw CSS is required by this pattern's canonical snippets; if you add any,
+list it here with a justification and apply it via the `css` prop — never via
+`className` (`Stack` omits `className`; do not use `className` on `Box` either —
+the styling escape hatch on both is the `css` prop).
+
+| Value | Property | Reason        |
+| ----- | -------- | ------------- |
+| —     | —        | none required |
+
+---
+
+## Do NOTs
+
+- NEVER add a single `Heading level="2"` page title above the sections — the
+  dashboard is a documented exception: it leads with section-level `level="2"`
+  headings and has no separate page title (sub-headings within a section step to
+  `level="3"`).
+- NEVER use the list page's `Stack height="full"` scroll region or the form
+  page's `Container size="medium"` as the dashboard shell — the dashboard shell
+  is a multi-panel `Box display="flex"` with a responsive `flexDirection`.
+- NEVER use a raw `@media (max-width: …)` `flexDirection` flip (via `css` or
+  `className`) for the panel collapse — use the responsive
+  `flexDirection={{ mobile: 'column', tablet: 'row' }}` prop.
+- NEVER set `className` on `Stack` or `Box` — `Stack` omits `className`, and
+  `className` must not be used on `Box` either; the styling escape hatch on both
+  is the `css` prop, and only for a Documented exception.
+- NEVER reproduce the shell Header or NavBar inside the page — the shell wraps
+  the page (surface rule); the page starts at the panel frame.
+- NEVER render a metric headline number with a raw `style={{ fontSize: … }}` —
+  use a `Text` size token (e.g. `size="xxlarge"`).
+- NEVER use a `Badge` for a dashboard headline figure — badges map _status
+  labels_ in tables; dashboard stats are plain `Text` numbers.
+- NEVER import a metric card, stat card, or announcements feed from `@spark-web`
+  — they are COMPONENT GAPs. Build each as a primitives placeholder
+  (`Box`/`Stack`/`Text`/`Icon`/`Button`), mark it with a `// COMPONENT GAP:`
+  comment, and flag it for product design review before production — do not ship
+  the placeholder as-is. (In vendor-portal, the overlay's local components
+  remain the canonical substitution.)
+- NEVER flag the consent modal as a component gap or hand-roll a custom overlay
+  — it is a real `ContentDialog` from `@spark-web/modal-dialog`.
+- NEVER give the first-run consent modal a close button — use
+  `showCloseButton={false}`; the Continue action persists the flag and closes
+  it.
+- NEVER open the consent modal unconditionally on mount — gate it on the
+  persisted profile/initialised flag (`profile && !profile.initialized`).
+- NEVER use `dangerouslySetInnerHTML` on `Text`, `Box`, or any element to render
+  a banner / announcement — render sanitized content via `Text` / `Alert` (XSS
+  risk).
+- NEVER treat "Load More" as pagination or infinite scroll — it is a distinct
+  third loading mode (button-triggered incremental append); bind the Button's
+  `loading` prop to the in-flight fetch.
+
+---
+
+## Validation checklist
+
+Run this checklist before marking any vendor-admin dashboard task complete. Fix
+every violation first. The uplift protocol in
+`node_modules/@spark-web/design-system/CLAUDE.md` also runs this checklist
+against existing pages and reports PASS/FAIL per item.
+
+1. The page leads with **section-level `Heading level="2"`** headings (e.g.
+   "Summary", "Support & resources", "What's New") and has **no single page
+   title** — the documented dashboard exception; sub-headings within a section
+   are `level="3"` (or `level="4"` inside a dialog). No `PageHeader`, no
+   `level="1"`.
+2. The shell is a multi-panel `Box display="flex"` with
+   `flexDirection={{ mobile: 'column', tablet: 'row' }}` — a primary panel
+   (`flexGrow={1}`) plus an optional secondary feed panel — **not**
+   `Stack height="full"` (list page) and **not** `Container size="medium"` (form
+   page); the page does not reproduce the shell Header / NavBar.
+3. The responsive panel collapse uses the `flexDirection` responsive prop —
+   there is no raw `@media` `flexDirection` flip and no `className` on any
+   `Stack` / `Box`; spacing is all tokens.
+4. Metrics render in a `Columns` grid (`collapseBelow`, responsive `gap`); each
+   metric card is a primitives placeholder (`Box`/`Stack`/`Text`/`Icon`) flagged
+   `// COMPONENT GAP: MetricCard needed — not yet in Spark`, with the headline
+   number a `Text` size token (not a raw `fontSize`) and a click-through
+   (`onClick`/`href`) to the filtered list; no `Badge` for the headline figure.
+5. Resource / promo cards are composed from primitives (`Box` card chrome +
+   `Stack`/`Text`/`Button`/`ButtonLink`) with actions as `Button`/`ButtonLink`
+   (not raw `<a>`); no `// COMPONENT GAP` flag is required for them.
+6. If an announcements / news feed is present: it is in the secondary panel,
+   rendered only when its feature flag is on, built as a primitives placeholder
+   (`Box as="article"` items + "Load More" `Button`) flagged
+   `// COMPONENT GAP: AnnouncementsFeed needed — not yet in Spark`, and uses
+   **"Load More"** (button-triggered incremental, `Button loading` bound to the
+   fetch) — not infinite scroll, not pagination.
+7. The first-run consent modal (if present) is a real `ContentDialog` from
+   `@spark-web/modal-dialog` with `showCloseButton={false}`, a single
+   `Button tone="primary"` Continue footer whose handler persists the
+   profile/initialised flag, gated open on `profile && !profile.initialized`,
+   rendered once at page root with open state as a prop — not flagged as a
+   component gap, not a custom overlay.
+8. No element uses `dangerouslySetInnerHTML`; banner / announcement content is
+   sanitized text rendered via `Text` / `Alert` (XSS rule).
+9. No raw CSS values beyond the Documented exceptions table (which is empty by
+   default); every component is `@spark-web/*` or an explicit consumer-overlay
+   substitute, and anything missing (MetricCard, AnnouncementsFeed) is flagged
+   with a `// COMPONENT GAP:` comment and called out for product design review.