@spark-web/design-system 5.1.3 → 5.1.5

package/CLAUDE.md

@@ -3,41 +3,6 @@
 This file provides guidance to Claude Code (claude.ai/code) when working with
 code in this repository.
 
-## Overview
-
-Spark Web is the Brighte Design System — a React component library organized as
-a Yarn monorepo (~50 packages). It uses Preconstruct for bundling, Emotion for
-CSS-in-JS, and Changesets for versioning.
-
-## Common Commands
-
-```bash
-# Development
-yarn dev                  # Run docs, playroom, and storybook concurrently
-yarn dev:storybook        # Storybook only (port 6006)
-yarn dev:docs             # Next.js docs site only
-yarn dev:playroom         # Playroom only
-
-# Testing
-yarn test:unit            # Run all Jest tests
-yarn test:unit -- --testPathPatterns=packages/alert  # Run tests for a specific package
-yarn check                # Run format + lint + package + type checks
-
-# Linting & Formatting
-yarn check:lint           # ESLint check
-yarn fix:lint             # ESLint autofix
-yarn check:format         # Prettier check
-yarn fix:format           # Prettier autoformat
-
-# Build
-yarn build:packages       # Build all packages via Preconstruct
-yarn build:docs           # Build docs site
-
-# Package management
-yarn new:package          # Scaffold a new component package via Plop
-yarn release              # Build + publish to npm (CI only)
-```
-
 ## How to approach any build task
 
 When given any build task — whether a PRD, a feature description, or a prompt —
@@ -46,68 +11,54 @@ ask for clarification before completing step 1.
 
 ### Step 1 — Classify the surface
 
-Read node_modules/@spark-web/design-system/patterns/CLAUDE.md in full. Determine
-which surface type the task is for based on language in the PRD:
-
-- "admin portal", "admin", "internal", "back office", "manage", "ops" → Internal
-  admin
-- "vendor portal", "vendor", "accreditation", "installer" → Vendor portal (not
-  yet defined — flag to team)
-- "website", "marketing", "landing page", "public" → Website (not yet defined —
-  flag to team)
-- "mobile", "app", "iOS", "Android" → Mobile app (not yet defined — flag to
-  team)
-
-If the surface cannot be determined from the PRD, flag it and ask before
-proceeding. Do not assume.
+Read `node_modules/@spark-web/design-system/patterns/CLAUDE.md` in full and
+classify the surface using its signal table. That file is the single source of
+truth for which surfaces exist. If the surface cannot be determined, flag it and
+ask before proceeding. Do not assume.
 
 ### Step 2 — Read the surface rules
 
-Read the surface rules file for the classified surface. For internal admin: read
-node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md in full.
-Surface rules take precedence over all component rules.
+Read the surface rules file for the classified surface. Read, in full, the rules
+file at the location given in the registry's Step 2 table
+(`node_modules/@spark-web/design-system/patterns/CLAUDE.md`). Surface rules take
+precedence over all component rules.
 
 If the surface is not yet defined, flag it to the team and do not proceed with
 building until the surface rules exist.
 
 ### Step 3 — Identify the feature type and read the pattern file
 
-Match the task to a pattern file in the surface folder:
-
-- List of records, manage, view all, search, filter →
-  node_modules/@spark-web/design-system/patterns/internal-admin/list-page.md
-- Create or edit a record, form →
-  node_modules/@spark-web/design-system/patterns/internal-admin/form-page.md
-  (not yet defined)
-- Record detail, view details, drill down →
-  node_modules/@spark-web/design-system/patterns/internal-admin/detail-page.md
-  (not yet defined)
-
-Read the pattern file in full. It defines which components to assemble, in what
-order, and with what rules. Follow it exactly.
-
-If no pattern file exists for the feature type, use the surface rules and
-component documentation to make the best decision, then flag that a pattern file
-should be created for this feature type before the next similar build.
+Match the task to a pattern file using the feature-type table in
+`node_modules/@spark-web/design-system/patterns/CLAUDE.md` (Step 3). Read the
+pattern file in full and follow it exactly. If no pattern exists for the feature
+type, use the surface rules and component documentation to make the best
+decision, then flag that a pattern file should be created.
 
 ### Step 4 — Read the relevant component CLAUDE.md files
 
 Only read the components the pattern file tells you to use. Do not read all
-component files — only the ones needed for this specific feature.
+component files — only the ones needed for this specific feature. For each named
+component doc you MUST read its **props/API**, **composition rules**, **usage
+examples**, and **anti-patterns (Do NOTs)** — these hold the load-bearing rules
+and the canonical code to copy. You MAY defer the narrative overview ('What this
+is' / 'What this is NOT') and the 'Token usage' prose, reading them only if a
+prop value or example is unclear. Component docs are short — when in doubt, read
+the whole file.
 
-### Step 5 — Read the component stories
+### Step 5 — Usage examples
 
-Read the Storybook story file for each component you will use. Stories show
-correct real-world usage examples that the CLAUDE.md documentation alone may not
-fully cover.
+The usage examples in each component CLAUDE.md are canonical. If (and only if)
+you are working inside the spark-web monorepo itself, you may also read
+`packages/[component]/src/*.stories.tsx` — stories are not published to npm and
+do not exist in consumer repos.
 
 ### Step 6 — Assemble, do not invent
 
-Use only components that exist in packages/. Do not build custom components or
+Use only published `@spark-web/*` packages. Do not build custom components or
 apply custom styling outside of the documented exceptions in each component
 CLAUDE.md.
 
-If a feature requires something that does not exist in packages/:
+If a feature requires something that has no published `@spark-web/*` package:
 
 - Use the closest available Spark primitive as a placeholder
 - Add a comment in the generated code: // COMPONENT GAP: [ComponentName] needed
@@ -154,121 +105,16 @@ listing which failures are structural versus prop-level.
 
 ## Architecture
 
-The agent reading order for any build task is defined in "How to approach any
-build task" above. Always follow that sequence. Never jump directly to component
-documentation without first reading the surface classifier and pattern files.
-
-### Monorepo Structure
-
-- `packages/` — ~50 component packages, each published as `@spark-web/{name}`
-- `docs/` — Next.js documentation site with Storybook, Playroom, and
-  Contentlayer
-- `examples/` — Reference Next.js apps (example-site, preapprovals)
-- `scripts/` + `plop-templates/` — Package scaffolding
-
-### Dependency Layers
-
-**Foundation** (no internal deps): `utils`, `theme`, `ssr`
-
-**Core components**: `a11y`, `box`, `text`, `icon` — depend on foundation
-
-**Composition layer**: Layout (`stack`, `row`, `columns`, `container`,
-`inline`), form inputs, complex components — compose from core
-
-**Integration**: `next-utils`, `design-system` (barrel re-export of all
-packages)
-
-### Component Package Structure
-
-Each package under `packages/{name}/src/` typically contains:
-
-- `{ComponentName}.tsx` — Main component
-- `{component-name}.stories.tsx` — Storybook stories
-- `{component-name}.test.tsx` — Jest + Testing Library unit tests
-- `types.ts` — Shared type definitions
-- `index.ts` — Public exports
-
-Preconstruct generates dual CJS/ESM bundles in `dist/`.
-
-### Styling
-
-All styling uses Emotion (CSS-in-JS). Components access the design token system
-via `useTheme()` from `@spark-web/theme`. The theme provides color tones
-(primary, secondary, positive, caution, critical, info), typography scales, and
-spacing utilities. Never use raw CSS values — always use theme tokens.
-
-### Key Patterns
-
-- **Composition**: Components are built by composing smaller components (Box,
-  Text, Icon, Row, Stack)
-- **Responsive**: Use theme utilities and Facepaint for responsive styles — not
-  media query literals
-- **Accessibility**: All components include proper ARIA attributes; use
-  `@spark-web/a11y` utilities
-- **`data` prop**: Components support a `data` prop for test selectors and
-  analytics
-- **TypeScript discriminated unions**: Used for related props that must appear
-  together (e.g., `onClose` requires `closeLabel`)
-- **`forwardRef`**: Used on all interactive/DOM-exposed components
-
-### Releases
-
-Changesets manages versioning. To add a changeset for your PR: `yarn changeset`.
-Snapshot releases can be triggered on a PR by commenting `/snapit`.
-
-### 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.
-
-## New packages (in progress)
-
-### data-table
-
-TanStack Table v8-based table. See node_modules/@spark-web/data-table/CLAUDE.md
-before writing any code using this package. Exports a single `DataTable`
-component — not composable sub-components.
-
-Key rules:
-
-- Single `DataTable` component, not composable sub-components
-- Use `createColumnHelper` from this package for type-safe column defs
-- Pagination handled externally — never put pagination inside DataTable
-- All values from useTheme() tokens — never raw hex, px, or Tailwind
-
-### meatball-menu
-
-Three-dot dropdown for 2+ record-level actions. See
-node_modules/@spark-web/meatball-menu/CLAUDE.md. Usage rules:
-node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md.
-
-### section-header
-
-Section-level heading bar with optional action. See
-node_modules/@spark-web/section-header/CLAUDE.md. Depends on:
-@spark-web/status-badge, @spark-web/meatball-menu.
-
-### status-badge
-
-Standalone label pill with colored background and optional icon. No dot. See
-node_modules/@spark-web/status-badge/CLAUDE.md. Tones: accent, positive,
-caution, critical, info, neutral. Only used in PageHeader and SectionHeader via
-their `statusBadge` prop — never in table status columns. Use @spark-web/badge
-for table status columns and any dot+label pattern.
-
-### base-edit-modal
-
-Reusable modal shell for all edit and action modals. Pinned header + scrollable
-body + pinned footer. Depends on: @spark-web/modal-dialog. Never pass
-scrollable={false}. Never use control as a prop.
+Repo architecture, dependency layers, styling tokens, and key patterns live in
+the repo-root CLAUDE.md. Pattern and surface rules live under
+`node_modules/@spark-web/design-system/patterns/` — reached via "How to approach
+any build task" above; always follow that sequence, never jump straight to
+component docs.
 
-### portal-table
+## Component quick-reference
 
-Label/value display component for structured record data in admin interfaces.
-Not a data table — use @spark-web/data-table for sortable paginated lists.
-Depends on: @spark-web/stack, @spark-web/box, @spark-web/row,
-@spark-web/heading, @spark-web/button, @spark-web/text-link, @spark-web/text,
-@spark-web/meatball-menu, @spark-web/inline. rows prop is a typed array — never
-JSX children.
+Component rules live in each package's own CLAUDE.md (component-level docs).
+Read them via `node_modules/@spark-web/[name]/CLAUDE.md`. Notable packages whose
+rules are frequently needed on admin surfaces: data-table, meatball-menu,
+section-header, status-badge, page-header, action-dropdown, portal-table, badge.
+Never rely on this file for component-level rules.

package/package.json

@@ -1,67 +1,66 @@
 {
   "name": "@spark-web/design-system",
-  "version": "5.1.3",
+  "version": "5.1.5",
   "license": "MIT",
   "main": "dist/spark-web-design-system.cjs.js",
   "module": "dist/spark-web-design-system.esm.js",
   "files": [
     "CLAUDE.md",
-    "ai-context",
     "patterns",
     "dist"
   ],
   "dependencies": {
-    "@spark-web/a11y": "5.3.0",
+    "@spark-web/a11y": "5.3.1",
     "@spark-web/accordion": "5.2.0",
-    "@spark-web/action-dropdown": "2.0.1",
-    "@spark-web/alert": "5.2.0",
+    "@spark-web/action-dropdown": "2.0.2",
+    "@spark-web/alert": "5.2.1",
     "@spark-web/analytics": "5.1.0",
     "@spark-web/badge": "^5.1.1",
     "@spark-web/box": "6.0.1",
     "@spark-web/button": "5.6.1",
-    "@spark-web/checkbox": "5.1.1",
+    "@spark-web/checkbox": "5.1.2",
     "@spark-web/columns": "5.1.1",
-    "@spark-web/combobox": "6.0.0",
-    "@spark-web/container": "5.1.0",
+    "@spark-web/combobox": "6.1.0",
+    "@spark-web/container": "5.1.1",
     "@spark-web/control-label": "5.1.0",
     "@spark-web/core": "5.2.0",
-    "@spark-web/currency-input": "6.0.0",
-    "@spark-web/data-table": "5.2.2",
-    "@spark-web/date-picker": "5.2.0",
+    "@spark-web/currency-input": "6.0.1",
+    "@spark-web/data-table": "5.2.3",
+    "@spark-web/date-picker": "5.2.1",
     "@spark-web/description-list": "0.1.0",
-    "@spark-web/divider": "5.1.0",
+    "@spark-web/divider": "5.1.1",
     "@spark-web/dropzone": "6.0.0",
     "@spark-web/field": "5.3.2",
     "@spark-web/fieldset": "5.1.0",
     "@spark-web/float-input": "6.0.0",
-    "@spark-web/heading": "5.2.0",
+    "@spark-web/heading": "5.2.1",
     "@spark-web/hidden": "5.1.0",
     "@spark-web/highlight-card": "0.1.0",
-    "@spark-web/icon": "5.1.0",
+    "@spark-web/icon": "5.1.1",
     "@spark-web/inline": "5.1.0",
     "@spark-web/link": "5.1.0",
     "@spark-web/meatball-menu": "0.1.0",
-    "@spark-web/modal-dialog": "6.0.2",
-    "@spark-web/multi-select": "6.0.1",
+    "@spark-web/modal-dialog": "6.0.3",
+    "@spark-web/multi-select": "6.0.2",
     "@spark-web/nav-link": "5.1.0",
     "@spark-web/next-utils": "5.1.0",
     "@spark-web/page-header": "1.0.0",
     "@spark-web/password-input": "6.0.0",
-    "@spark-web/portal-table": "^1.0.0",
+    "@spark-web/portal-table": "^1.0.1",
     "@spark-web/radio": "5.3.1",
     "@spark-web/row": "5.1.1",
     "@spark-web/section-card": "0.1.0",
-    "@spark-web/section-header": "0.1.0",
+    "@spark-web/section-header": "0.1.1",
     "@spark-web/select": "6.0.2",
     "@spark-web/spinner": "5.1.1",
     "@spark-web/ssr": "5.0.0",
     "@spark-web/stack": "5.1.1",
     "@spark-web/status-badge": "0.1.0",
     "@spark-web/switch": "5.0.3",
-    "@spark-web/tabs": "5.2.1",
+    "@spark-web/tabs": "5.2.2",
     "@spark-web/text": "5.3.1",
-    "@spark-web/text-area": "6.0.1",
-    "@spark-web/text-input": "6.0.2",
+    "@spark-web/text-area": "6.0.2",
+    "@spark-web/text-input": "6.0.3",
     "@spark-web/text-link": "5.4.0",
     "@spark-web/text-list": "5.1.0",
     "@spark-web/theme": "5.13.2",

package/patterns/CLAUDE.md

@@ -1,34 +1,44 @@
-# Pattern library — surface classifier
+# Pattern library — surface registry and classifier
 
-When an agent receives a PRD or feature brief, it must read this file first
-before reading any component or pattern documentation.
+This file is the SINGLE SOURCE OF TRUTH for which surfaces exist, how to
+classify a task into a surface, and which pattern file to read for a feature
+type. Other documents must link here — never copy these tables.
+
+When an agent receives a PRD or feature brief, it must read this file first,
+before any component or pattern documentation.
 
 ---
 
 ## Step 1 — Identify the surface
 
-Determine which surface is being built by reading the PRD for these signals:
+The design system supports exactly three surfaces:
+
+| Signal in PRD                                                                    | Surface        | Status    |
+| -------------------------------------------------------------------------------- | -------------- | --------- |
+| "admin", "admin portal", "internal", "back office", "ops", "manage", "dashboard" | internal-admin | Defined   |
+| "vendor", "vendor portal", "accreditation", "installer", "partner"               | vendor-admin   | Defined   |
+| "website", "marketing", "landing page", "public", "brighte.com.au"               | website        | (planned) |
 
-| 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)      |
+Classify by who uses the screen, not by which words appear most: internal
+Brighte staff operating the business → internal-admin; vendors/installers
+signing in to manage their own work → vendor-admin; unauthenticated public
+visitors → website. If signals from more than one row match and the audience is
+unclear, ask for clarification — never pick a surface by signal count.
 
 If the surface cannot be determined from the PRD, ask for clarification before
-proceeding. Do not assume.
+proceeding. Do not assume. If a PRD matches a surface marked (planned), flag to
+the team that the surface rules do not exist yet and do not proceed with
+building until they do.
 
 ---
 
 ## 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                                        |
+| Surface        | Rules location                                                            |
+| -------------- | ------------------------------------------------------------------------- |
+| internal-admin | `node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md` |
+| vendor-admin   | `node_modules/@spark-web/design-system/patterns/vendor-admin/CLAUDE.md`   |
+| website        | (planned) — flag to the team                                              |
 
 Read the surface rules file in full before reading any component documentation.
 Surface rules take precedence over component rules.
@@ -37,14 +47,25 @@ 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:
+Use the table for the surface you classified in Step 1.
+
+### internal-admin
+
+| Feature type                 | Pattern file                                                                           |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
+| List of records with actions | `node_modules/@spark-web/design-system/patterns/internal-admin/list-page.md`           |
+| Record detail view           | `node_modules/@spark-web/design-system/patterns/internal-admin/detail-page.md`         |
+| Create or edit a record      | `node_modules/@spark-web/design-system/patterns/internal-admin/form-page.md` (planned) |
 
-| 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) |
+### vendor-admin
+
+| Feature type                         | Pattern file                                                               |
+| ------------------------------------ | -------------------------------------------------------------------------- |
+| Vendor list of records with actions  | `node_modules/@spark-web/design-system/patterns/vendor-admin/list-page.md` |
+| Vendor create / edit / settings form | `node_modules/@spark-web/design-system/patterns/vendor-admin/form-page.md` |
+| Vendor record detail view            | (planned)                                                                  |
+| Vendor dashboard                     | `node_modules/@spark-web/design-system/patterns/vendor-admin/dashboard.md` |
+| Vendor tabbed screen                 | (planned)                                                                  |
 
 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
@@ -52,16 +73,35 @@ should be created for this feature type.
 
 ---
 
+## Consumer overlays
+
+Pattern files describe the design-system-canonical implementation using
+`@spark-web/*` components only. Where a specific consuming repo must substitute
+a local component (legacy constraints), that substitution lives in a
+per-consumer overlay file in the surface directory, named after the consumer —
+e.g.
+`node_modules/@spark-web/design-system/patterns/internal-admin/portal-hub.md`
+for portal-hub on internal-admin, and
+`node_modules/@spark-web/design-system/patterns/vendor-admin/vendor-portal.md`
+for vendor-portal on vendor-admin.
+
+Reading rule: after reading a pattern file, check the surface directory for an
+overlay matching the repo you are working in and apply its substitutions. An
+overlay overrides the pattern only where it explicitly says so.
+
+---
+
 ## 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.
+Full reading order (including how to read component docs): see
+`node_modules/@spark-web/design-system/CLAUDE.md`. This file owns the Step 1-3
+classification tables above. Pattern files are decision trees — always read them
+in full.
+
+---
+
+## Maintaining this file
+
+When a surface or pattern file is added, renamed, or removed under `patterns/`,
+update the tables above in the same commit. `yarn check:agent-docs` fails CI if
+these tables and the filesystem disagree.

package/patterns/internal-admin/CLAUDE.md

@@ -29,14 +29,10 @@ Hover state is determined entirely by whether the row is clickable:
   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.
+while the cursor is over the meatball button. DataTable implements this
+automatically when `enableClickableRow` is set — see `@spark-web/data-table`
+CLAUDE.md.
 
 ---
 
@@ -58,9 +54,7 @@ Does the row have actions?
           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.
+Never place inline action buttons alongside a clickable row.
 
 ---
 
@@ -115,12 +109,6 @@ Spark Web theme.
 
 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.
+rules that already exist here in component-level CLAUDE.md files. If a new
+pattern file is added, also update the feature-type table in
+`node_modules/@spark-web/design-system/patterns/CLAUDE.md` in the same commit.