Storybook addon

@component-anatomy/storybook — an "Anatomy" panel next to Controls and Actions, synced two-way with the story canvas.Open the live Storybook →

Compatibility

Storybook 9 and 10, any renderer (React, Vue, HTML, Web Components…). The canvas side is framework-agnostic — it only reads the rendered DOM.

Installation

npm install --save-dev @component-anatomy/storybook

// .storybook/main.ts
export default {
  addons: ['@component-anatomy/storybook'],
};

That's the whole setup — the addon registers its panel and a global decorator automatically.

Usage

Annotate the story's DOM with data-part and add the anatomy parameter:

export const Anatomy: Story = {
  parameters: {
    anatomy: {
      parts: [
        { id: 'icon',  name: 'Icon',  description: 'Optional leading glyph.' },
        { id: 'label', name: 'Label', description: 'The visible action text.' },
        { id: 'badge', name: 'Badge', description: 'Numeric counter.' },
      ],
    },
  },
};

Hover a part in the panel → the canvas element is highlighted. Hover the element in the canvas → the panel entry activates. Omit partsentirely and the panel lists what it finds in the DOM.

Parameters

Key	Type	Description
`parts`	`AnatomyPartDefinition[]`	Part list. Omit to auto-discover from `data-part`.
`preset`	`string`	`default` \| `minimal` \| `contrast` \| `blueprint`.
`theme`	`AnatomyTheme`	Token overrides for canvas overlays, e.g. `{ accent: "#0d9488" }`.
`overlayLabel`	`boolean`	Show the floating name chip. Default true.
`overlayPadding`	`number`	Inflate highlight boxes by N px.
`root`	`string`	CSS selector narrowing the anatomy root inside the canvas.
`disable`	`boolean`	Turn the addon off for a story.

Parameters follow Storybook's normal inheritance: set project-wide defaults in.storybook/preview.ts, per-component defaults in meta.parameters, and per-story overrides in story.parameters. Typed asAnatomyParameters:

import type { AnatomyParameters } from '@component-anatomy/storybook';

export const Anatomy: Story = {
  parameters: {
    anatomy: { preset: 'blueprint', overlayPadding: 2 } satisfies AnatomyParameters,
  },
};

In MDX docs pages

The same table renders inside an MDX page with the <Anatomy>block, so component anatomy can sit in the prose next to the preview rather than only in the panel. It needs@storybook/addon-docs, which is what renders MDX:

import { Canvas, Meta } from '@storybook/addon-docs/blocks';
import { Anatomy } from '@component-anatomy/storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

<Canvas of={ButtonStories.Anatomy} />
<Anatomy of={ButtonStories.Anatomy} />

Hover sync works both ways, exactly as it does in the panel. Pointof at a story to read its parameters.anatomy, at a whole CSF module to read the meta's, or omit it on an attached docs page to fall back to the page's current story.

Prop	Type	Description
`of`	`CSF export`	Story or meta to document. Omit on an attached page for the current story.
`parts`	`AnatomyPartDefinition[]`	Curated list, overriding the parameter and auto-discovery.
`sync`	`boolean`	Two-way hover sync with the canvas. Default true.

Auto-discovery reads the story as it renders, so a block relying on it needs the story on the same page — a <Canvas> or<Story> block above it. A block with an explicitparts list stands on its own. Several blocks can share one page: each talks only to the story it names.

Live examples

The deployed Storybook shows Button (default + blueprint theme), Slider (accent theme) and Tabs (auto-discovery + high-contrast preset), plus two MDX pages —Docs → Anatomy in MDX and the Button docs page — using the<Anatomy> block. Sources live inexamples/storybook in the repo.