---
name: blocks-mdx
description: Authors and edits Storybook MDX documentation for @chainlink/blocks components under libs/blocks. For internal maintainers. Triggers on libs/blocks/**/*.mdx, MDX structure, Canvas/Controls, When to use, or Storybook docs pages for the design system—not on app product pages.
---

# Blocks MDX (maintainers)

**Scope:** `libs/blocks/**/*.mdx`.

**Normative spec (read before substantive edits):** [reference/GUIDE_MDX.md](reference/GUIDE_MDX.md). All structure, rules, and checklist detail live there—**the guide wins** over any summary here or in chat.

**Out of scope:** app UI → **`blocks-ui-builder`**; `*.figma.tsx` → **`blocks-figma-connect`**.

## Prerequisites

1. `../../AGENTS.md`
2. [reference/GUIDE_MDX.md](reference/GUIDE_MDX.md)
3. Target **`.mdx`** with sibling **`.tsx`** and **`.stories.tsx`** for the same component.

## Workflow

```
- [ ] reference/GUIDE_MDX.md read end-to-end for this change
- [ ] Edits match guide; .mdx aligned with .tsx + .stories
- [ ] Package lint / Storybook docs (or nx target) when appropriate
```

### 1. Classify

New file vs section fix vs small tweak—smallest change that satisfies the guide.

### 2. Edit

Follow **[reference/GUIDE_MDX.md](reference/GUIDE_MDX.md)** only; keep snippets compile-ready.

### 3. Validate

Run the checks your change needs (package lint, typecheck, Storybook/docs build).

## Report

Paths touched; checks; deviations from the guide (and why).