Charts docs skill: document <Source> code-block indentation convention

.agents/skills/charts-docs.md

@@ -26,9 +26,42 @@ Instructions:
    - Prop names/types match implementation and stories.
    - Cross-links resolve to the expected Storybook docs entries.
    - Examples reflect current API, not legacy patterns.
-9. Run relevant checks from `projects/js-packages/charts`:
-   - `pnpm run typecheck`
-   - `pnpm run test` (if behavior or stories were updated)
-10. Summarize what was documented, what API surface changed (if any), and any known limitations noted in docs.
+9. Author `<Source>` example blocks so the rendered snippet is indented correctly (see "Authoring `<Source>` example blocks" below).
+10. Run relevant checks from `projects/js-packages/charts`:
+    - `pnpm run typecheck`
+    - `pnpm run test` (if behavior or stories were updated)
+11. Summarize what was documented, what API surface changed (if any), and any known limitations noted in docs.
+
+## Authoring `<Source>` example blocks
+
+Storybook's `<Source code={ \`...\` } />` blocks run their template-literal contents through a **dedent** that strips one leading indentation level before rendering. Author blocks by hand and match the convention already used across the chart docs — otherwise the rendered example ends up with every prop flush against the component tag (looks broken), or with a mixed tab/space indent.
+
+Convention for the string inside `` code={ `...` } ``:
+
+- Keep the **leading imports / setup paragraph** (everything before the first blank line inside the template literal) flush at column 0.
+- Indent the **JSX body** one level: opening tag (`<Tag`) at one tab, its props at two tabs, self-closing `/>` (or closing `</Tag>`) back at one tab. Nested children go one tab deeper as usual.
+- **Use tabs only.** Do not mix tabs and spaces inside the template literal.
+- **Do not run Prettier over `.mdx` files.** Prettier will rewrite the block with mixed tabs/spaces and break the dedent. The repo's pre-commit hook only formats JS/TS/JSON, so leaving `.mdx` alone is the intended workflow.
+
+Example (matches `bar-chart/stories/index.docs.mdx`):
+
+```mdx
+<Source
+	language="jsx"
+	code={ `import { BarChart } from '@automattic/charts';
+import '@automattic/charts/style.css';
+
+	<BarChart
+		data={ data }
+		withTooltips={ true }
+	/>` }
+/>
+```
+
+Quick self-check before committing new or edited chart docs:
+
+- Open the story in Storybook (or the built docs) and confirm props render on their own indented lines rather than flat against the component tag.
+- If props render flat, the JSX body inside the template literal is under-indented by one level — add one tab to `<Tag>`, two tabs to each prop, and one tab to the closing tag.
+- If indentation looks ragged, check for a tab/space mix (often the result of an editor auto-format or a Prettier pass) and re-tab the block.
 
 Do not invent unsupported behaviors. When uncertain, prefer what is already implemented in chart code and stories.

projects/js-packages/charts/changelog/charts-docs-source-indent

@@ -0,0 +1,5 @@
+Significance: patch
+Type: changed
+Comment: Docs-tooling only: internal AI documentation guide note on Source-block indentation convention. No user-facing change.
+
+

projects/js-packages/charts/docs/ai-documentation-guide.md

@@ -315,6 +315,7 @@ If applicable, provide migration examples:
 - **Follow TypeScript patterns**: Include proper typing in examples
 - **Use `tsx` for component code**: All `<Source>` blocks with tsx/component code should use `language="tsx"`, use `language="typescript"` only for pure type definitions or imports
 - **Use tabs for indentation**: All code examples in `<Source>` blocks must use tabs, not spaces, for indentation
+- **Author `<Source>` templates for the dedent**: Storybook dedents `<Source code={ \`...\` } />` blocks by one level before rendering. Keep the leading imports/setup paragraph flush at column 0, then indent the JSX body one level (opening tag at one tab, props at two tabs, closing tag back at one tab). Do not run Prettier over `.mdx` — it will mix tabs and spaces and break the dedent. See the "Authoring `<Source>` example blocks" section of the `charts-docs` skill for the full convention and a self-check.
 - **Use consistent naming**: `data`, `dataPoint`, `sampleData` for chart data
 - **Show progressive complexity**: Start simple, build up to advanced usage