@spark-web/design-system 5.0.99 → 5.1.0

package/patterns/CLAUDE.md

@@ -0,0 +1,67 @@
+# Pattern library — surface classifier
+
+When an agent receives a PRD or feature brief, it must read this file first
+before reading any component or pattern documentation.
+
+---
+
+## Step 1 — Identify the surface
+
+Determine which surface is being built by reading the PRD for these signals:
+
+| Signal in PRD                                                    | Surface                           |
+| ---------------------------------------------------------------- | --------------------------------- |
+| "admin", "internal", "back office", "ops", "manage", "dashboard" | Internal admin                    |
+| "customer", "portal", "my account", "self-service"               | Customer portal (not yet defined) |
+| "website", "marketing", "landing page", "public"                 | Website (not yet defined)         |
+| "mobile", "app", "iOS", "Android"                                | Mobile app (not yet defined)      |
+
+If the surface cannot be determined from the PRD, ask for clarification before
+proceeding. Do not assume.
+
+---
+
+## Step 2 — Read the rules for that surface
+
+| Surface         | Rules location                                                            |
+| --------------- | ------------------------------------------------------------------------- |
+| Internal admin  | `node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md` |
+| Customer portal | Not yet defined — flag to the team                                        |
+| Website         | Not yet defined — flag to the team                                        |
+| Mobile app      | Not yet defined — flag to the team                                        |
+
+Read the surface rules file in full before reading any component documentation.
+Surface rules take precedence over component rules.
+
+---
+
+## Step 3 — Read the pattern for the feature type
+
+After reading surface rules, identify the feature type and read the
+corresponding pattern file:
+
+| Feature type                 | Pattern file                                                                                 |
+| ---------------------------- | -------------------------------------------------------------------------------------------- |
+| List of records with actions | `node_modules/@spark-web/design-system/patterns/internal-admin/list-page.md`                 |
+| Create or edit a record      | `node_modules/@spark-web/design-system/patterns/internal-admin/form-page.md` (coming soon)   |
+| Record detail view           | `node_modules/@spark-web/design-system/patterns/internal-admin/detail-page.md` (coming soon) |
+
+If no pattern file exists yet for the feature type, use the surface rules and
+component documentation to make the best decision, and flag that a pattern file
+should be created for this feature type.
+
+---
+
+## Reading order for any build task
+
+1. `node_modules/@spark-web/design-system/patterns/CLAUDE.md` ← this file
+   (surface classifier)
+2. `node_modules/@spark-web/design-system/patterns/[surface]/CLAUDE.md` ←
+   surface interaction rules
+3. `node_modules/@spark-web/design-system/patterns/[surface]/[pattern].md` ←
+   feature pattern (if exists)
+4. `node_modules/@spark-web/[component]/CLAUDE.md` ← component rules
+5. `node_modules/@spark-web/[component]/src/[component].stories.tsx` ← usage
+   examples
+
+Never skip steps. Never read component documentation before surface rules.

package/patterns/internal-admin/CLAUDE.md

@@ -0,0 +1,126 @@
+# Internal admin — interaction and pattern rules
+
+These rules apply to all components and patterns built for internal 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 admin surfaces.
+
+---
+
+## Row interaction rules
+
+### Clickable rows
+
+A row is clickable when the data model has a record-level detail view or
+destination page. The agent must determine this from the PRD:
+
+- If the PRD describes a detail page, record view, or drill-down → row is
+  clickable
+- If the PRD describes a read-only data display with no record destination → row
+  is not clickable
+- If unsure, default to clickable
+
+### Hover state
+
+Hover state is determined entirely by whether the row is clickable:
+
+- Row is clickable → hover state is applied when the cursor is over the row,
+  **except** when hovering a button within the row (e.g. the MeatballMenu
+  trigger)
+- Row is not clickable → hover state is never applied, no exceptions
+
+Never apply a hover state to a non-clickable row. It implies interactivity that
+does not exist and misleads the user.
+
+When a clickable row contains a MeatballMenu, the row hover must be suppressed
+while the cursor is over the meatball button. Two competing hover targets (row
+and menu trigger) confuse the user about what will happen on click. Implement
+using CSS `:has()` on the `<tr>` — see `@spark-web/data-table` CLAUDE.md for the
+exact pattern.
+
+---
+
+## Overflow menu rules
+
+An overflow menu on a row is used only when ALL of the following are true:
+
+- There are 2 or more actions that apply to the row record
+- The actions relate only to that specific record, not to the page or table
+
+Use this decision tree:
+
+```
+Does the row have actions?
+  No  → no overflow menu, no action column
+  Yes → how many actions?
+          1 action + row is NOT clickable → inline button or icon
+          1 action + row IS clickable     → overflow menu
+          2+ actions                      → always overflow menu
+```
+
+Never place inline action buttons alongside a clickable row. A clickable row and
+inline buttons create two competing interaction targets and confuse the user
+about what clicking does.
+
+---
+
+## Badge and pill rules
+
+A badge or pill is used only when:
+
+- The field represents a status with 2 or more distinct values
+- The status values have meaningful visual distinction (e.g. active vs inactive,
+  pending vs approved vs rejected)
+
+Do not use a badge when:
+
+- The field is free-form text
+- The field is a boolean with no meaningful status distinction
+- There is only one possible value
+
+### Badge tone mapping
+
+This mapping is authoritative for the internal-admin surface. If a component
+CLAUDE.md defines tone guidance, the mapping below takes precedence.
+
+Map status values to tones using this logic derived from the PRD:
+
+- Positive / active / approved / complete → `positive` tone
+- Warning / approaching limit / expiring → `caution` tone
+- Critical / rejected / failed / overdue / suspended → `critical` tone
+- Neutral / inactive / archived / unknown → `neutral` tone
+- Pending / in review / awaiting approval → `info` tone
+
+**Caution vs info (pending):** Use `caution` for warnings that are
+time-sensitive or approaching a limit. Use `info` for states where a record is
+waiting on a human decision or review (e.g. "Pending approval", "Under review").
+
+Component choice:
+
+- Always use `<Badge>` (dot + label) for status columns in list-page tables —
+  never `<StatusBadge>`
+- Use `<StatusBadge>` (colored pill, no dot) only in page headers and section
+  headers via their `statusBadge` prop — never in table status columns
+
+Available tones for both components:
+`accent | caution | critical | info | neutral | positive`. There is no `pending`
+tone — always use `info` for pending/awaiting states.
+
+When in doubt, use `neutral`. Never invent a tone that does not exist in the
+Spark Web theme.
+
+---
+
+## Rules that update as the system grows
+
+When a new pattern or component is added to the internal 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.
+
+Then open the root CLAUDE.md and append this line to the Architecture section:
+
+## Pattern library
+
+Agent pattern and surface rules live in
+node_modules/@spark-web/design-system/patterns/. Always read
+node_modules/@spark-web/design-system/patterns/CLAUDE.md before any build task.