# Blocks — MDX Documentation Guide

Canonical reference for writing `.mdx` files in `libs/blocks`.

This is the package-facing runtime guide for MDX in this package.

For runtime routing and source precedence, start with `AGENTS.md`.

The maintainer skill at `skills/blocks-mdx/SKILL.md` is **workflow only**. If anything in that skill (or in chat) disagrees with this guide, **this file wins**.

---

## Header order

Every component MDX file should keep this header order:

```
1. Imports
2. <Meta>
3. <Title>
4. <Subtitle>
5. <SourceLinks links={[{label, href}]}>   (if applicable — external primitive docs)
6. <LifecycleTag variant="Stable | In Development | Deprecated" />
7. **Component type:** Primitive | Abstraction over X | HTML wrapper
8. <Canvas of={Stories.Default} layout="padded" sourceState="shown" />
9. <Controls of={Stories.Default} />
```

## Section order

After the header, use this order:

1. `## When to use`
2. `## Import`
3. one primary structure section:
   - `## Recommended pattern` for simple components and higher-level abstractions
   - `## Anatomy` for composed primitives or components where structure is the
     main thing to teach
4. `## Subcomponents` when the component exports a public family
5. optional technical sections
6. `## Examples`
7. `## Related components`

Do not force both `Recommended pattern` and `Anatomy` into every doc. Use the
one that best teaches the default shape.

## Critical rules

- `<Controls />` is never inside `<Canvas>`. Always bind it:
  `<Controls of={Stories.Default} />`.
- The story bound to `<Controls of={...} />` must expose real controllable args.
- `sourceState="shown"` is required on every `<Canvas>` so agents can read code
  without clicking.
- `<SourceLinks>` uses `links={[{ label, href }]}`.
- `## Examples` should be the last major content section before
  `## Related components`.

## `## When to use`

This is the chooser section. It should answer:

- what the component is for
- when it is the right default
- which nearby component to use instead when relevant

Put primitive vs abstraction guidance here. Keep it direct.

## `## Import`

Always show the real public import path from `@chainlink/blocks`.

Do not use local imports in MDX docs.

## `## Recommended pattern`

Use this for simple components or default abstractions.

Purpose:

- give humans and AI the first snippet to copy
- show the normal product path, not every prop at once

Rules:

- one compile-ready snippet
- concise and realistic
- no MDX comments or partial fragments

## `## Anatomy`

Use this for composed primitives or components where the structure matters more
than a single prop example.

Purpose:

- show what goes inside what
- expose the minimum public composition shape

Rules:

- one compile-ready snippet
- show all required subcomponents
- omit optional parts unless they materially change the shape
- use realistic placeholder values

## `## Subcomponents`

Use this when the component exports a public family from the same module.

List each public subcomponent with a one-line role description and, when
relevant, the parent it belongs inside.

## Optional technical sections

Use only the sections that add real signal for the component. Common ones:

- `## Rendered Element`
- `## Styling Other Elements Like a Button`
- `## Responsive Behavior`
- `## Using asChild`
- `## Prop reference`

Do not force a fixed list across every component.

## `## Prop reference`

Use this only when the Controls surface needs clarification.

Typical case:

- the root Controls table is useful
- subcomponent tabs are present
- Storybook shows a broad type like `union`

In that case:

- keep the built-in Controls table
- add short prose underneath with the important concrete options
- derive those values from exported source constants when possible
- do not hardcode option lists when a component export already owns them

## `## Examples`

Keep one top-level examples section. Use `###` subheadings to label example
intent.

Common labels:

- `### Recommended`
- `### Variants`
- `### Sizes`
- `### States`
- `### Layout`
- `### Advanced composition`
- `### Content and states`
- `### State management`
- `### Edge cases`

Use only the labels that fit the component.

## `## Related components`

Use this for nearby family members or alternatives, not internal composition.

Examples:

- `ButtonIcon`
- `ButtonSet`
- `SimpleSelect`
- `Combobox`

## Quick checklist

- header order is correct
- Controls are bound and outside Canvas
- `When to use` is explicit
- import path uses `@chainlink/blocks`
- `Recommended pattern` or `Anatomy` matches the component
- public subcomponents are listed when relevant
- optional technical sections add real signal
- examples are backed by real stories where possible
- related components reflect real chooser alternatives