# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## 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 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. 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 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. 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 — Usage examples 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 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 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 — 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 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. ## Component quick-reference 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.