@spark-web/design-system 5.0.99 → 5.1.0

package/CLAUDE.md

@@ -0,0 +1,274 @@
+# CLAUDE.md
+
+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 —
+always follow this sequence before writing any code. Do not skip steps. Do not
+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.
+
+### 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.
+
+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.
+
+### 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.
+
+### Step 5 — Read the component stories
+
+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.
+
+### Step 6 — Assemble, do not invent
+
+Use only components that exist in 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/:
+
+- Use the closest available Spark primitive as a placeholder
+- Add a comment in the generated code: // COMPONENT GAP: [ComponentName] needed
+  — not yet in Spark
+- Flag it clearly in your response as a gap to be formalised into the design
+  system before this feature ships
+
+### Step 7 — Validate before marking complete
+
+Run the validation checklist from the pattern file before marking the task
+complete. Fix all violations before responding. A task is not complete until all
+checklist items pass.
+
+---
+
+## Uplift protocol
+
+When uplifting an existing page to match a pattern, follow the same 7 steps but
+with these additions:
+
+Before Step 6, run the pattern's validation checklist against the existing file.
+Report every PASS and FAIL. This is mandatory — do not skip it.
+
+If any checklist failure requires changing the component tree structure — such
+as replacing a custom component with a Spark component, restructuring how
+columns are defined, or replacing a custom loading/empty pattern with a built-in
+prop — scaffold a new file using the structural skeleton from the pattern file
+and migrate data and logic into it. Do not patch the existing file
+incrementally.
+
+If all failures are prop-level or styling fixes that do not change the component
+tree, you may modify the existing file in place.
+
+In either case, the pattern file is authoritative. Do not preserve existing
+structure that conflicts with the pattern. Treat the current implementation as
+data input (what fields exist, what the page does), not as a structural
+reference.
+
+Before writing any code, state whether you are (a) rebuilding from the pattern's
+structural skeleton or (b) modifying in place, and justify your choice by
+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.
+
+### portal-table
+
+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.

package/ai-context/layer-1-root.md

@@ -0,0 +1,158 @@
+# Layer 1 — Root CLAUDE.md
+
+## What this layer is
+
+The root `CLAUDE.md` sits at the top of the repository. It is the first file an
+AI agent reads in any session. Its job is to orient the agent: what this repo
+is, how it is structured, and — most importantly — **what reading order to
+follow before writing any code**.
+
+Think of it as the agent's onboarding document. Without it, an agent has no
+contract to work from and will make assumptions. With it, every build task
+starts from the same controlled entry point.
+
+---
+
+## Where it lives
+
+```
+/CLAUDE.md          ← root of the repository
+```
+
+---
+
+## What it must contain
+
+### 1. Repo overview (2–4 sentences)
+
+A plain-language description of what the codebase is — the tech stack, the
+package structure, and the general purpose. This gives the agent enough context
+to interpret file paths and package names correctly.
+
+```markdown
+## 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.
+```
+
+### 2. Common commands
+
+Shell commands the agent can run for development, testing, building, and
+linting. These prevent the agent from guessing or inventing commands.
+
+```markdown
+## Common Commands
+
+yarn test:unit yarn check yarn build:packages
+```
+
+### 3. The build task reading order — the most critical section
+
+This is the mechanism that enforces layered reading. It is a numbered sequence
+of steps the agent **must** follow before writing any code. Each step references
+a specific file or layer. The agent is explicitly told never to skip steps.
+
+```markdown
+## How to approach any build task
+
+### Step 1 — Classify the surface
+
+Read docs/patterns/CLAUDE.md in full. Determine which surface type the task is
+for based on language in the PRD.
+
+### Step 2 — Read the surface rules
+
+Read the surface rules file for the classified surface.
+
+### Step 3 — Identify the feature type and read the pattern file
+
+Match the task to a pattern file in the surface folder.
+
+### Step 4 — Read the relevant component CLAUDE.md files
+
+Only read the components the pattern file tells you to use.
+
+### Step 5 — Read the component stories
+
+Read the Storybook story file for each component you will use.
+
+### Step 6 — Assemble, do not invent
+
+Use only components that exist in packages/. Do not build custom components.
+
+### Step 7 — Validate before marking complete
+
+Run the validation checklist from the pattern file before marking the task
+complete.
+```
+
+### 4. Architecture section
+
+A description of the monorepo structure, dependency layers, and key patterns
+(styling, accessibility, TypeScript conventions). This prevents the agent from
+making incorrect assumptions about how components relate to each other.
+
+### 5. New packages index
+
+A brief entry for each new or in-progress package — its purpose, its
+sub-components, and its key rules. This acts as a registry so the agent knows
+what exists without having to explore the filesystem.
+
+```markdown
+## New packages (in progress)
+
+### table
+
+Composable table component. See packages/table/CLAUDE.md before writing any
+code. Sub-components: Table, TableHeaderRow, TableHeaderCell, TableRow,
+TableCell, TablePagination.
+
+### status-badge
+
+Pill badge with a colored status dot and text label. See
+packages/status-badge/CLAUDE.md. Tones: positive, caution, critical, neutral,
+pending.
+```
+
+---
+
+## How it connects to the other layers
+
+The root file does not define _how_ to use any component. It only tells the
+agent **what order to read things in**. Every rule lives in the layer it belongs
+to:
+
+| Concern                      | Lives in                               |
+| ---------------------------- | -------------------------------------- |
+| Surface classification logic | `docs/patterns/CLAUDE.md`              |
+| Surface interaction rules    | `docs/patterns/[surface]/CLAUDE.md`    |
+| Feature assembly patterns    | `docs/patterns/[surface]/[pattern].md` |
+| Component-specific rules     | `packages/[component]/CLAUDE.md`       |
+
+The root file is the table of contents. The other layers are the chapters.
+
+---
+
+## What happens if this layer is missing or incomplete
+
+- The agent skips directly to component documentation and assembles UI without
+  understanding which surface it is building for.
+- Surface-level interaction rules (hover states, overflow menus, badge tones)
+  are ignored.
+- The agent invents components or custom styles that do not exist in the design
+  system.
+
+---
+
+## Implementation notes
+
+- Keep this file short. Its job is orientation and reading-order enforcement,
+  not documentation.
+- The build task steps should be imperatives, not suggestions: "Read X before Y.
+  Never skip steps."
+- The new packages index should stay in sync with `packages/` — add an entry
+  here whenever a new package is scaffolded, even if it is not yet published.
+- Do not duplicate rules here that already live in a lower layer. If a rule
+  belongs to a component, keep it in the component's CLAUDE.md.

package/ai-context/layer-2-surface-pattern.md

@@ -0,0 +1,236 @@
+# Layer 2 — Surface & Pattern files
+
+## What this layer is
+
+The surface and pattern layer sits between the root and individual component
+rules. It has two responsibilities:
+
+1. **Surface classifier** — determines _which product_ is being built before any
+   component is touched.
+2. **Surface rules** — defines interaction behaviour that applies globally
+   across all components on that surface.
+
+Together they answer: _"For this surface, what are the rules that override
+component defaults?"_
+
+---
+
+## Where these files live
+
+```
+docs/patterns/
+  CLAUDE.md                        ← surface classifier (always read first)
+  internal-admin/
+    CLAUDE.md                      ← surface rules for internal admin
+    list-page.md                   ← feature pattern: list of records
+    form-page.md                   ← feature pattern: create / edit (coming soon)
+    detail-page.md                 ← feature pattern: record detail (coming soon)
+  customer-portal/                 ← not yet defined
+  website/                         ← not yet defined
+```
+
+---
+
+## File 1 — The surface classifier (`docs/patterns/CLAUDE.md`)
+
+### What it does
+
+This is the agent's second read (after the root). Its only job is to map signals
+from a PRD or feature brief to a named surface, then point the agent at the
+correct surface rules file.
+
+### What it must contain
+
+**A signal-to-surface lookup table.** Words or phrases that appear in a PRD,
+mapped to the surface they indicate:
+
+| Signal in PRD                                                    | Surface         |
+| ---------------------------------------------------------------- | --------------- |
+| "admin", "internal", "back office", "ops", "manage", "dashboard" | Internal admin  |
+| "customer", "portal", "my account", "self-service"               | Customer portal |
+| "website", "marketing", "landing page", "public"                 | Website         |
+| "mobile", "app", "iOS", "Android"                                | Mobile app      |
+
+**A pointer to the surface rules file for each defined surface.** Undefined
+surfaces should be flagged explicitly so the agent stops and asks rather than
+guessing:
+
+```markdown
+| Surface         | Rules location                         |
+| --------------- | -------------------------------------- |
+| Internal admin  | docs/patterns/internal-admin/CLAUDE.md |
+| Customer portal | Not yet defined — flag to the team     |
+```
+
+**A pointer to feature pattern files** for each surface:
+
+```markdown
+| Feature type                 | Pattern file                              |
+| ---------------------------- | ----------------------------------------- |
+| List of records with actions | docs/patterns/internal-admin/list-page.md |
+| Create or edit a record      | docs/patterns/internal-admin/form-page.md |
+```
+
+**The canonical reading order** — a numbered list reinforcing the full sequence
+from root to component. This is intentional redundancy: the more times the agent
+sees the reading order, the less likely it is to skip steps.
+
+```markdown
+1. docs/patterns/CLAUDE.md ← surface classifier (this file)
+2. docs/patterns/[surface]/CLAUDE.md ← surface rules
+3. docs/patterns/[surface]/[pattern].md ← feature pattern (if exists)
+4. packages/[component]/CLAUDE.md ← component rules
+5. packages/[component]/src/[component].stories.tsx ← usage examples
+```
+
+---
+
+## File 2 — Surface rules (`docs/patterns/[surface]/CLAUDE.md`)
+
+### What it does
+
+Defines interaction and visual rules that apply across **all** components when
+building for this surface. These rules sit above component-level CLAUDE.md
+files. When a conflict exists between a surface rule and a component rule, the
+surface rule wins.
+
+### What it must contain
+
+Rules that are **cross-component** in nature — things that would otherwise be
+decided inconsistently component by component. Examples from the internal admin
+surface:
+
+**Row interaction rules**
+
+Whether a table row is clickable, and what that implies for hover state.
+Connecting row clickability to the data model (does a detail page exist?) rather
+than leaving it to the agent to infer:
+
+```markdown
+### Clickable rows
+
+- If the PRD describes a detail page, record view, or drill-down → row is
+  clickable
+- If the PRD describes a read-only display with no destination → row is not
+  clickable
+- If unsure, default to clickable
+
+### Hover state
+
+- Row is clickable → hover state always applied
+- Row is not clickable → hover state never applied, no exceptions
+```
+
+**Overflow menu rules**
+
+A decision tree for when a row gets an overflow menu vs. an inline button vs.
+nothing:
+
+```markdown
+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
+```
+
+**Badge and pill rules**
+
+When to use a status badge, and how to map status values to visual tones.
+Explicit tone definitions prevent the agent from inventing tones:
+
+```markdown
+- Positive / active / approved / complete → `positive`
+- Warning / approaching limit / expiring → `caution`
+- Critical / rejected / failed / overdue → `critical`
+- Neutral / inactive / archived / unknown → `neutral`
+- Pending / in review / awaiting approval → `pending`
+```
+
+### What it must NOT contain
+
+- Component-specific implementation rules (those live in component CLAUDE.md)
+- Rules that only apply to one feature type (those live in pattern files)
+- Duplication of anything that already lives in a lower layer
+
+---
+
+## File 3 — Feature pattern file (`[surface]/[pattern].md`)
+
+### What it does
+
+Describes how to assemble a specific type of page or feature — which components
+to use, in what order, with what configuration. It is a recipe, not a reference.
+
+The agent reads this _after_ the surface rules and _before_ component docs.
+
+### What it must contain
+
+- **Component list** — the exact packages to use for this feature type
+- **Assembly order** — the layout structure from outermost to innermost
+- **Per-component configuration** — which props to set, what to avoid
+- **A validation checklist** — the agent must run this before marking the task
+  complete
+
+Example structure for a list page:
+
+```markdown
+## Components required
+
+- @spark-web/header
+- @spark-web/table (Table, TableHeaderRow, TableHeaderCell, TableRow, TableCell)
+- @spark-web/status-badge (if status column present)
+- @spark-web/meatball (if row actions present)
+- @spark-web/table (TablePagination, outside Table)
+
+## Assembly order
+
+1. Header
+2. Table a. TableHeaderRow → TableHeaderCell (one per column) b. TableRow (one
+   per record) → TableCell
+3. TablePagination (sibling of Table, never inside it)
+
+## Validation checklist
+
+- [ ] Header has a title prop
+- [ ] Hover state matches row clickability (see surface rules)
+- [ ] Meatball only present when 2+ row actions exist
+- [ ] Status cells use StatusBadge — no inline styling
+- [ ] TablePagination is outside Table
+```
+
+---
+
+## How this layer connects to the others
+
+| Layer               | Reads from                      | Overrides                                |
+| ------------------- | ------------------------------- | ---------------------------------------- |
+| Root CLAUDE.md      | Nothing — entry point           | —                                        |
+| Surface classifier  | Root (via reading order)        | —                                        |
+| Surface rules       | Surface classifier              | Component defaults                       |
+| Feature pattern     | Surface rules                   | Nothing — it assembles, doesn't override |
+| Component CLAUDE.md | Feature pattern (per component) | Nothing for this surface                 |
+
+---
+
+## How to add a new surface
+
+1. Create a folder at `docs/patterns/[surface-name]/`.
+2. Create `CLAUDE.md` inside it with the surface rules (row behaviour, badge
+   rules, any globally applicable interaction patterns).
+3. Add a row to the signal table in `docs/patterns/CLAUDE.md` pointing to the
+   new file.
+4. Update the root `CLAUDE.md` if needed to note the new surface.
+5. Create pattern files (list, form, detail, etc.) as features are designed.
+
+Do not build for a surface until its rules file exists. An undefined surface
+means the agent has no contract and will make assumptions.
+
+---
+
+## What happens if this layer is missing or incomplete
+
+- The agent applies component defaults regardless of surface context — hover
+  states, overflow menus, and badge tones become inconsistent across pages.
+- Surface-level rules that conflict with component defaults are silently
+  ignored.
+- Two agents working on the same surface independently will produce different
+  interaction patterns.