@spark-web/design-system 5.1.3 → 5.1.5

package/patterns/vendor-admin/CLAUDE.md

@@ -0,0 +1,216 @@
+# Vendor admin — interaction and pattern rules
+
+These rules apply to all components and patterns built for vendor admin
+surfaces. They sit above individual component rules. When a conflict exists
+between these rules and a component-level CLAUDE.md, these rules take precedence
+for vendor-admin surfaces.
+
+Vendor-admin is the surface used by external vendors, installers, and partners
+signing in to manage their own work (leads, applications, settings). It is a
+distinct surface from internal-admin and has different chrome — do not apply
+internal-admin rules here, and do not "correct" vendor-admin choices to match
+internal-admin where they intentionally diverge (see Page title rule below).
+
+---
+
+## Layout shell and content region
+
+Vendor-admin screens render inside a fixed application shell:
+
+- A **fixed, sticky Header** pinned to the top, full width
+  (`position: fixed; top: 0`). It is `72px` tall on mobile and `90px` on tablet
+  and up.
+- A **fixed left NavBar sidebar** on tablet and up
+  (`position: fixed; left: 0; width: 270px`, full height). On mobile the sidebar
+  collapses behind a hamburger (`MenuIcon`) toggle in the Header.
+- A **main content region** that is offset to clear the shell and owns a
+  full-height scroll area:
+  - top offset `72px` on mobile, `90px` on tablet and up (clears the Header),
+  - left offset `0` on mobile, `270px` on tablet and up (clears the sidebar),
+  - height `calc(100svh - 90px)` so the region — not the document — scrolls.
+
+The shell frame (Header + sidebar + offset content region) is the surface rule:
+every vendor-admin page renders into this region and must not reproduce the
+Header or sidebar itself. The **shell implementation is consumer-owned** — the
+Header, NavBar, and the `_app`-level wrapper are local components, not published
+`@spark-web/*` components. The concrete substitutions (component names, props)
+live in the consumer overlay (a sibling file):
+
+`node_modules/@spark-web/design-system/patterns/vendor-admin/vendor-portal.md`
+
+The region and offsets above are the rule; the implementation is the overlay's.
+
+A page authored for vendor-admin therefore starts at the page-content level (the
+page title row, filters, content) and assumes the shell already exists around
+it.
+
+---
+
+## Page title rule
+
+Vendor-admin uses `Heading level="2"` for the page title — **not**
+internal-admin's `PageHeader` / `H1`.
+
+This is the clearest divergence from internal-admin and is intentional: the two
+surfaces have different chrome. On vendor-admin the fixed Header already carries
+the product identity and primary navigation, so the in-page title is a section
+heading within the shell, expressed as `<Heading level="2">`. Do not replace it
+with `PageHeader` or promote it to `level="1"`. Within a page, sub-section
+titles step down to `<Heading level="3">`.
+
+**Dashboard exception.** The dashboard / overview screen type is a documented
+exception to this single-page-title rule: an overview page has no single
+dominant subject, so it leads with **section-level `Heading level="2"`**
+headings (e.g. "Summary", "Support & resources", "What's New") and **no separate
+page title**. Sub-headings within a dashboard section step down to `level="3"`.
+This exception applies only to the dashboard/overview shell — see
+`node_modules/@spark-web/design-system/patterns/vendor-admin/dashboard.md`. All
+other screen types keep the single `Heading level="2"` page title above.
+
+Page-level actions (e.g. an "Export" `Button`) sit on the same row as the title,
+right-aligned, in a flex row that stacks to a column on mobile. A count or limit
+indicator (`Badge`) may sit next to the title on the left.
+
+---
+
+## Spacing and density
+
+Vendor-admin pages use a generous rhythm. The observed page-level pattern across
+screens:
+
+- List pages wrap their content in a `Stack` with `gap="large"` and
+  `margin="xxlarge"` (often `marginBottom="none"` so the scroll region reaches
+  the viewport edge), `height="full"`.
+- Form / settings pages center content in a `Container size="medium"` and use a
+  `Stack` with `gap="xxlarge"` between sections, with `marginY="xxlarge"`.
+- Filter rows within a list page use `gap="medium"`.
+
+Use these spacing tokens — never raw pixel gaps or margins. When in doubt for a
+new vendor-admin page, default to `Stack gap="large"` for the page body and
+`gap="xxlarge"` to separate major form sections.
+
+---
+
+## Detail interaction rule — side panel vs full page
+
+Vendor-admin opens a record's detail in a **slide-in side panel**, not by
+navigating to a separate detail page.
+
+- The side panel is a right-anchored slide-in within the content region
+  (`position: absolute; right: 0`): **~`90vw` on mobile, up to `500px`
+  (`maxWidth`) from tablet** (vendor-portal's current panel also offsets below
+  the header — see the overlay). It overlays the list rather than reflowing it.
+- Opening a row's detail sets the selected record (typically via a URL query
+  param so the panel is deep-linkable) and renders the panel alongside the still
+  visible list.
+
+**When to use a side panel vs a full page:**
+
+- **Side panel** — the default for inspecting / lightly acting on a single
+  record while staying in the list context (viewing a lead, an application
+  summary, quick status changes). Use it whenever the user benefits from
+  remaining anchored to the list and the detail is bounded.
+- **Full page** — reserve for heavyweight, standalone flows that do not belong
+  beside a list: multi-step forms, a dedicated settings screen, or a legacy /
+  embedded screen. Settings is a full page (`Container`-centered), not a panel.
+
+The side panel itself is **consumer-supplied** and is a **COMPONENT GAP**: there
+is no `@spark-web` drawer or side-panel component (verification note: see the
+overlay). Until a Spark drawer exists, mark its use with
+`// COMPONENT GAP: SidePanel/Drawer needed — not yet in Spark` and use the
+consumer's `SidePanel`; see the overlay (a sibling file):
+
+`node_modules/@spark-web/design-system/patterns/vendor-admin/vendor-portal.md`
+
+---
+
+## List loading rule — infinite scroll vs pagination
+
+Choose the list-loading strategy by the shape of the dataset:
+
+- **Infinite scroll** — use for large or streamed datasets where the total is
+  unbounded or expensive to count, and the natural interaction is "keep
+  scrolling" (e.g. leads). Implement by fetching the next page when the bottom
+  of the scroll region is reached and appending rows.
+- **Pagination** — use for bounded result sets where the user benefits from
+  jumping to a known page and seeing the total (e.g. applications, with an "X of
+  Y results" summary and page controls).
+
+Default: if the PRD describes an open-ended, continuously growing list →
+infinite scroll; if it describes a finite, countable list the user pages through
+→ pagination.
+
+- **Load More** (button-triggered incremental) — a THIRD list-loading mode: a
+  "Load More" `Button` fetches and appends the next page on click (the Button's
+  `loading` prop bound to the in-flight fetch), rather than auto-fetching on
+  scroll (infinite scroll) or exposing page controls (pagination). Use it for a
+  short, browse-occasionally feed where the user opts in to more — e.g. the
+  dashboard announcements / "What's New" feed (see
+  `node_modules/@spark-web/design-system/patterns/vendor-admin/dashboard.md`).
+
+The **pagination control is consumer-supplied** and is a **COMPONENT GAP**:
+there is no `@spark-web` pagination component. Mark its use with
+`// COMPONENT GAP: TablePagination needed — not yet in Spark` and use the
+consumer's pagination component; see the overlay.
+
+---
+
+## Bulk actions rule
+
+When a list supports selecting multiple rows, selecting one or more rows reveals
+a **bottom-anchored bulk-action toast** pinned to the content region
+(`position: absolute; bottom: 0; left: 0`). It exposes the actions that apply to
+the current selection (e.g. assign, close) and a way to clear the selection.
+
+Rules:
+
+- The bulk-action toast appears **only when** the list is multi-select **and**
+  at least one row is selected; it is hidden when the selection is empty.
+- A bulk-action toast and a record side panel are mutually exclusive in
+  practice: show the detail panel only when the selection is a single record,
+  and the bulk toast only when one or more rows are selected for a bulk
+  operation.
+- Disable the toast's actions while a bulk mutation is in flight.
+
+---
+
+## Badge and pill rules — tone mapping
+
+Vendor-admin reuses the internal-admin badge tone mapping verbatim. Do not
+re-derive it here. Read and apply the authoritative mapping at:
+
+`node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md` (see
+"Badge and pill rules" / "Badge tone mapping").
+
+If a vendor-admin screen has status vocabulary not covered by the internal-admin
+mapping (e.g. lead intents, vendor lead statuses, accreditation states), map
+each new value with that same logic and record the new vocabulary in the
+relevant pattern file rather than redefining tones here.
+
+---
+
+## Role and feature-flag gating
+
+Vendor-admin screens and individual nav items / actions may be gated by role
+(e.g. vendor-admin-only screens) or by feature flags. This gating is **consumer
+logic, not a design-system rule** — it lives in the consuming app (the shell's
+nav config, route guards, and flag checks), not in `@spark-web` components or in
+these surface rules.
+
+Where it sits: gating wraps the page or nav entry at the shell / routing layer
+and conditionally renders flag-guarded sections. A pattern or component doc
+should never encode a specific role name or flag key. When a PRD specifies that
+a screen is admin-only or behind a flag, treat that as the consumer's
+responsibility and note it; build the screen's component tree per the pattern
+regardless.
+
+---
+
+## Rules that update as the system grows
+
+When a new pattern or component is added to the vendor-admin surface, update
+this file with any new interaction rules that apply globally. Do not duplicate
+rules that already exist here in component-level CLAUDE.md files. If a new
+pattern file is added under `patterns/vendor-admin/`, also update the
+feature-type table in `node_modules/@spark-web/design-system/patterns/CLAUDE.md`
+in the same commit.