@spark-web/design-system/ai-context/layer-1-root.md

--- title: Design System ---

# 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.