---
name: blocks-ui-builder
description: Builds product UIs in an existing app with @chainlink/blocks. Triggers on screens, pages, panels, or flows from natural language, specs, screenshots, or Figma—even without the word Blocks; also when Blocks, Chainlink Blocks, or @chainlink/blocks is named. Uses Storybook Blocks MCP (list-all-documentation, get-documentation, get-documentation-for-story) when connected; else reads mdx, stories, tsx on disk.
---

# Blocks UI builder

Ship UI in an **existing app** with `@chainlink/blocks`. **`.tsx` = API truth**; **MDX `## When to use`** + stories drive fit and patterns.

## Prerequisites

1. `../../../../AGENTS.md` when it exists (Explorer layout); else skip.
2. `../../AGENTS.md` — skills router.
3. Run **§2**, then **Storybook MCP** or **Without MCP**.

## Storybook MCP

Browse/compare the library when MCP is connected (typical `http://localhost:6006/mcp`, or whatever the session exposes). **MCP summary vs checked-in `*.mdx` → trust MDX**; reconcile in `.tsx`.

```
list-all-documentation
get-documentation(<id>)
get-documentation-for-story(<id>, <storyName>)
```

`list-all-documentation` → `get-documentation` on finalists → `get-documentation-for-story` if needed → reconcile in `../../src/components/<Name>/<Name>.tsx`. Use **`ServerName:tool_name`** with multiple servers. MCP missing or failing → note once, use **Without MCP**.

## Without MCP

Per component, in order: **`../../src/components/<Name>/<Name>.mdx`** (`## When to use`) → **`.stories.tsx`** → **`.tsx`**.

## Figma (app work)

Take from Figma: **copy, hierarchy, layout, states**—not props or subcomponents from the canvas alone.

**With a Code Connect snippet:** use it **first** (rough component + skeleton; **not** production-ready). Then **MDX `## When to use`**, optional [chooser-table.md](reference/chooser-table.md) (**MDX wins vs table**), Storybook MCP or stories, then **`.tsx`**. Do not use the package Code Connect **authoring** doc here—[reference/figma-branch.md](reference/figma-branch.md) expands this path.

## Precedence

Conflicts at ship time, highest first: **`.tsx`**, **`.stories.tsx`**, **`.mdx`**, Code Connect snippet, Figma—the last two never outrank the first three. **Choosing:** optional chooser yields to that component’s **MDX**; with Figma, snippet can precede a deep MDX read, but **MDX + stories override the snippet** when they disagree.

## Workflow

```
- [ ] MCP used or absence noted
- [ ] App + route
- [ ] §2 done; choice verified in .tsx
- [ ] Checks on touched app
```

### 1. Target surface

App and route from user or repo. No new apps unless asked. Mocks stay in the route unless the app already defines otherwise.

### 2. Choose components

1. **`../../src/components/<Name>/<Name>.mdx`** — **`## When to use`** (+ related); **`.stories.tsx`** for copy targets.
2. Optional [chooser-table.md](reference/chooser-table.md); **MDX overrides table** on conflict.
3. **Storybook MCP** or **Without MCP** to compare; on conflict, **on-disk MDX** beats MCP blurbs.
4. Confirm in **`.tsx`**.

### 3. Implement

Import from `@chainlink/blocks` only; prefer Blocks primitives; respect RSC/client and app styling. Figma-led work: **Figma** § + `reference/figma-branch.md`. No unrelated refactors or forbidden template copies.

### 4. Verify

Smallest useful typecheck/lint/build for the touched app; fix regressions you caused. Note MCP gaps and blocked externals.

## Report

Files changed; checks and results; MCP or reference blockers.