@spark-web/design-system 5.1.4 → 5.1.5

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

@@ -1,236 +0,0 @@
-# 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.

package/ai-context/layer-3-component.md

@@ -1,271 +0,0 @@
-# Layer 3 — Component CLAUDE.md files
-
-## What this layer is
-
-Every component package that an agent is expected to use gets its own
-`CLAUDE.md` inside `packages/[component]/`. This file is the agent's contract
-for that component: what it does, how its pieces fit together, what tokens to
-use, and what it must never do.
-
-This is the most granular layer. It is read last — only after the surface
-classifier, surface rules, and feature pattern have already been read. By the
-time the agent reaches this file it already knows _which_ components to use and
-_why_. This file tells it _how_.
-
----
-
-## Where these files live
-
-```
-packages/
-  table/
-    CLAUDE.md        ← component rules for @spark-web/table
-    src/
-      Table.tsx
-      table.stories.tsx
-      table.test.tsx
-  status-badge/
-    CLAUDE.md
-  meatball/
-    CLAUDE.md
-  header/
-    CLAUDE.md
-  ...
-```
-
-One `CLAUDE.md` per package. Not one per sub-component — one per package.
-
----
-
-## Anatomy of a component CLAUDE.md
-
-The sections below are the standard structure. Every component file should
-follow this shape. Use `@spark-web/table` as the reference example.
-
----
-
-### Section 1 — What this package is
-
-One short paragraph. Plain language. States the component's purpose and its
-compositional structure (sub-components, if any).
-
-```markdown
-## What this package is
-
-A composable table component for displaying tabular data. Five sub-components
-used together: Table, TableHeaderRow, TableHeaderCell, TableRow, TableCell.
-Optional TablePagination is a separate compositional layer used OUTSIDE Table.
-```
-
----
-
-### Section 2 — What this package is NOT
-
-Equally important. Explicitly rules out common misuses. This prevents the agent
-from reaching for this component when a different one is needed, and prevents it
-from adding features the component was never designed to have.
-
-```markdown
-## What this package is NOT
-
-- Not a data-grid. No virtual scrolling, column reordering, or column resizing.
-- Not a standalone component. TableRow and TableCell are meaningless outside
-  Table.
-- Not responsible for data fetching, sorting, or filtering.
-```
-
----
-
-### Section 3 — Component hierarchy
-
-Shows the parent/child relationship between sub-components. For simple single-
-component packages this can be omitted. For composable packages it is essential.
-
-```markdown
-## Component hierarchy
-
-Table ← scroll container, layout owner TableHeaderRow ← always first child of
-Table TableHeaderCell ← one per column, owns sort state TableRow (× n) ← one per
-data row, owns row state TableCell (× n) ← one per column per row
-TableRow[state=loading] ← replaces data rows during fetch, no children
-
-TablePagination is always OUTSIDE and BELOW Table — never inside it.
-```
-
----
-
-### Section 4 — Token usage
-
-All design token values the component uses, grouped by category. This is the
-most mechanical section and must be exhaustive — if a token is omitted the agent
-will either guess or use a raw value.
-
-Every token must reference `useTheme()` from `@spark-web/theme`. Raw hex values,
-pixel values, and Tailwind classes are never acceptable.
-
-```markdown
-## Token usage
-
-All values from useTheme() from @spark-web/theme.
-
-### Spacing tokens
-
-Cell padding all sides: theme.spacing.large Header cell padding horizontal:
-theme.spacing.large Pagination gap between buttons: theme.spacing.small
-
-### Color tokens
-
-Cell background default: theme.color.background.surface Cell background hover:
-theme.color.background.inputPressed Cell text default:
-theme.color.foreground.neutral Header cell background:
-theme.color.background.surface
-
-### Typography
-
-Use @spark-web/text for all text. Never raw <p> or <span>. Cell content:
-<Text tone="neutral"> using Body/Small scale Header cell label:
-<Text weight="semibold"> using xSmall scale
-```
-
----
-
-### Section 5 — States (if applicable)
-
-For components with visual states, list every valid state, the prop that
-controls it, and the tokens that apply. Be specific about which states interact
-(e.g. hover must not apply when state is disabled).
-
-```markdown
-## Row states
-
-state prop on TableRow: 'default' | 'selected' | 'disabled' | 'loading' Hover is
-CSS :hover only — not a state prop.
-
-default: theme.color.background.surface, text theme.color.foreground.neutral
-hover: theme.color.background.inputPressed, text theme.color.foreground.neutral
-selected: theme.color.background.primarySoft, text
-theme.color.foreground.neutral disabled: theme.color.background.inputDisabled,
-text theme.color.foreground.disabled, pointer-events none loading:
-theme.color.background.surface, renders "Loading" + spinner, ignores children
-
-Hover must NOT apply when state is disabled or loading.
-```
-
----
-
-### Section 6 — Composition rules
-
-Numbered constraints on how sub-components must be assembled. These prevent
-structural errors that would silently render incorrectly or break at runtime.
-
-```markdown
-## Composition rules
-
-1. Table must always contain exactly one TableHeaderRow as its first child.
-2. TableHeaderRow must contain one TableHeaderCell per column.
-3. TableRow must contain the same number of TableCell children as header
-   columns.
-4. A loading TableRow ignores all children.
-5. TablePagination is always a sibling of Table, never a child.
-```
-
----
-
-### Section 7 — Do NOTs
-
-A bulleted list of the most common agent mistakes for this component, stated as
-explicit prohibitions. These should cover the things an agent would most likely
-get wrong if it had only read the component source code without this file.
-
-```markdown
-## Do NOTs
-
-- NEVER raw hex values e.g. #1a2a3a — always use theme color tokens
-- NEVER raw pixel values e.g. 16px — always use theme spacing/sizing tokens
-- NEVER Tailwind classes — use Emotion CSS-in-JS via useTheme()
-- NEVER TableCell state prop — state on TableRow only
-- NEVER TablePagination inside Table
-- NEVER raw <table> <tr> <th> <td> HTML elements
-- NEVER omit forwardRef
-- NEVER re-implement the status dot/pill inline — use StatusBadge
-```
-
----
-
-## How this layer defers to surface rules
-
-A component CLAUDE.md defines _default_ behaviour. Surface rules override those
-defaults for a specific product context.
-
-Example: the table component has a hover state. The component CLAUDE.md defines
-the token to use for that hover state. The internal admin surface rules define
-_when_ hover is applied at all (only on clickable rows). The component file does
-not repeat the surface rule — it only documents what the hover state looks like
-when it is applied.
-
-If you find yourself writing a rule in a component CLAUDE.md that says "on admin
-pages, do X" — stop. That rule belongs in the surface rules file, not here.
-
----
-
-## When to create a component CLAUDE.md
-
-Create one when any of the following are true:
-
-- The component has sub-components that must be assembled in a specific order
-- The component uses design tokens that an agent would otherwise guess at
-- There are common misuses that would be hard to catch from the component's
-  TypeScript types alone
-- The component has states or variants with non-obvious visual behaviour
-- The component depends on another package that must always be used alongside it
-
-Do NOT create one for simple, single-element components with no configuration
-surface. If the TypeScript types and stories are sufficient, a CLAUDE.md adds no
-value.
-
----
-
-## Relationship to Storybook stories
-
-The component CLAUDE.md defines rules. The `.stories.tsx` file shows correct
-usage in real-world context. Both are required reading for the agent — the
-CLAUDE.md alone may not cover every prop combination, and stories alone do not
-explain why constraints exist.
-
-The reading order from the root file enforces this:
-
-```
-4. packages/[component]/CLAUDE.md          ← rules
-5. packages/[component]/src/[component].stories.tsx ← usage examples
-```
-
-Never reference a story in the CLAUDE.md and say "see stories for examples" as a
-substitute for writing out the composition rules. The rules must be explicit in
-this file.
-
----
-
-## What happens if this layer is missing or incomplete
-
-- The agent uses raw values (`#1a2a3a`, `16px`) instead of theme tokens,
-  breaking dark mode support and responsive scaling.
-- Sub-components are assembled in the wrong order or at the wrong nesting level
-  (e.g. `TablePagination` inside `Table`).
-- State props are applied to the wrong sub-component.
-- The agent re-implements functionality that already exists in a dependency
-  (e.g. builds a custom status pill instead of using `@spark-web/status-badge`).
-
----
-
-## Installed component context
-
-When `@spark-web/design-system` is installed, component-level CLAUDE.md files
-are available at `node_modules/@spark-web/{name}/CLAUDE.md`. Read the relevant
-file before working with any of the following components:
-
-- `node_modules/@spark-web/description-list/CLAUDE.md`
-- `node_modules/@spark-web/highlight-card/CLAUDE.md`
-- `node_modules/@spark-web/overflow-menu/CLAUDE.md`
-- `node_modules/@spark-web/section-card/CLAUDE.md`
-- `node_modules/@spark-web/section-header/CLAUDE.md`
-- `node_modules/@spark-web/tag/CLAUDE.md`