---
name: blocks-stories
description: Authors and edits Storybook stories and related JSDoc for @chainlink/blocks under libs/blocks. For internal maintainers. Triggers on libs/blocks/**/*.stories.tsx, argTypes, meta, docs-critical stories, tags, or component JSDoc for the design system—not on app product UI.
---

# Blocks stories (maintainers)

**Scope:** `libs/blocks/**/*.stories.tsx` and related component JSDoc.

**Normative spec:** [reference/GUIDE_STORIES.md](reference/GUIDE_STORIES.md). All rules live there—**the guide wins** over any summary here or in chat.

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

## Prerequisites

1. `../../AGENTS.md`
2. [reference/GUIDE_STORIES.md](reference/GUIDE_STORIES.md)
3. Target **`.stories.tsx`** with sibling **`.tsx`** and **`.mdx`**.

## Workflow

```
- [ ] reference/GUIDE_STORIES.md read for this change
- [ ] Stories + JSDoc match guide vs .tsx; aligned with .mdx where Controls bind
- [ ] Package lint / typecheck / Storybook when appropriate
```

### 1. Classify

New story vs Controls vs JSDoc—smallest change that satisfies the guide.

### 2. Edit

Follow **[reference/GUIDE_STORIES.md](reference/GUIDE_STORIES.md)** only.

### 3. Validate

Run the checks your change needs.

## Report

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