Skip to content

LedgerHQ/lumen / .claude/skills/component-mdx

component-mdx

Verified

Use when writing or editing Storybook MDX docs (*.mdx) — the two-tab Overview/Implementation structure, story-backed `<Source>` examples, and doc table guidelines.

FileKindSize
SKILL.mdskill md3.9 KB
references/tables.mdmarkdown1.4 KB
---
name: component-mdx
description: >-
  Use when writing or editing Storybook MDX docs (*.mdx) — the two-tab
  Overview/Implementation structure, story-backed `<Source>` examples, and doc
  table guidelines.
paths: "**/*.mdx"
---

# Documentation Guidelines

## MDX Documentation Structure

Component documentation MUST use the two-tab structure with Overview and Implementation tabs.

### Overview Tab

**Intent**: Provide designers and developers with a comprehensive understanding of the component's purpose, behavior, and usage patterns.

**Include**:

- Introduction and Figma link
- Anatomy with visual breakdown
- Properties (appearance, size, states, etc.)
- Responsive behavior
- Accessibility considerations
- Interactive examples

### Implementation Tab

**Intent**: Give developers practical, copy-paste ready code examples and integration patterns.

**Include**:

- Installation instructions (`<SetupNote />` where applicable)
- Code examples via `<Source of={ComponentStories.StoryName} />` — not hand-written fenced code blocks when a matching story exists
- Advanced patterns (icons, routing, custom styling) — prefer `<Source>` linked to the relevant story; use fenced blocks only when no story covers the snippet (e.g. one-off prop combinations)

**Use `<Source>` for story-backed examples:**

```tsx
import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
import * as ComponentStories from './Component.stories';

<Tab label='Implementation'>
  <SetupNote />

  ### Basic Usage

  <Source of={ComponentStories.Base} />

  ### With icon

  <Source of={ComponentStories.WithIcon} />
</Tab>
```

- Pair each `<Source>` with a real story export.
- Do not duplicate story code as manual ` ```tsx ` blocks in the Implementation tab.

See the `component-stories` skill for story setup (`Base` + `args`, naming conventions).

### Required Structure

```tsx
import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
import * as ComponentStories from './Component.stories';
import { CustomTabs, Tab, SetupNote } from '../../../../.storybook/components';

<Meta title='Core/Component' of={ComponentStories} />

# Component Name

<CustomTabs>
  <Tab label='Overview'>
    ## Introduction
    <Canvas of={ComponentStories.Base} />
    <Controls of={ComponentStories.Base} />
  </Tab>

  <Tab label='Implementation'>
    <SetupNote />
    ### Basic Usage
    <Source of={ComponentStories.Base} />
    ### Advanced Patterns
    <Source of={ComponentStories.WithFeature} />
  </Tab>
</CustomTabs>
```

- Every component page has `<Controls of={ComponentStories.Base} />` in the Overview tab (under "Properties"), and `Base` must have `args` that its `render` applies, so the controls are live (see `component-stories`, "Controls"). Do not replace it with `<ArgTypes />`. Subcomponent tabs inside the Controls block always show "Setup controls"; that is expected.

**Example**: See `Button.mdx` in ui-react or ui-rnative for reference implementation.

# Tables in docs

When a doc needs a table, use the copy-paste markup template in
`references/tables.md` — it carries the container/header/body classnames and the
design-system typography, colour, spacing and border tokens to use.

## Review checks

Rules verifiable from a diff.

| Check | Applies to | Detect | Skip |
| --- | --- | --- | --- |
| Doc doesn't use the two-tab Overview / Implementation structure | `.mdx` | missing `<Tab label='Overview'>` / `'Implementation'` | RN charts under `Components/visualization/` (no `.mdx`) |
| Implementation example is a hand-written ` ```tsx ` block where a story exists | `.mdx` | fenced code duplicating a story instead of `<Source of={…} />` | snippets no story covers |
| Doc references a removed/renamed prop or a stale default | `.mdx` | prop names vs current `types.ts` | — |
| Table uses raw Tailwind palette instead of tokens | `.mdx` | `text-gray-`, arbitrary sizes in table markup | — |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall