From 1534fb75521b0c4e7cad979c41ad21ad3fa073ee Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 1 Jul 2026 02:04:38 +0000 Subject: [PATCH] Charts docs skill: document Source-block indentation convention Storybook's blocks dedent the template literal before rendering, so authoring the JSX body at column 0 causes props to render flat against the component tag. This surfaced on CHARTS-218 (HeatmapChart PR #50065) where every heatmap doc example rendered with flat props until the blocks were re-indented to match the other chart docs. Add an 'Authoring example blocks' section to the charts-docs skill (.agents/skills/charts-docs.md) capturing the dedent gotcha, the tabs-only body-indentation convention, an example matching the existing bar-chart doc pattern, and a quick self-check for future authors. Also cross-reference the convention from the in-package AI documentation guide so authors landing there see the same guidance. Co-authored-by: Adam Wood --- .agents/skills/charts-docs.md | 41 +++++++++++++++++-- .../changelog/charts-docs-source-indent | 5 +++ .../charts/docs/ai-documentation-guide.md | 1 + 3 files changed, 43 insertions(+), 4 deletions(-) create mode 100644 projects/js-packages/charts/changelog/charts-docs-source-indent diff --git a/.agents/skills/charts-docs.md b/.agents/skills/charts-docs.md index b26882f0adcf..c4704df43411 100644 --- a/.agents/skills/charts-docs.md +++ b/.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 `` example blocks so the rendered snippet is indented correctly (see "Authoring `` 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 `` example blocks + +Storybook's `` 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 (`` (or closing ``) 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 +` } +/> +``` + +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 ``, 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. diff --git a/projects/js-packages/charts/changelog/charts-docs-source-indent b/projects/js-packages/charts/changelog/charts-docs-source-indent new file mode 100644 index 000000000000..23277b615f43 --- /dev/null +++ b/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. + + diff --git a/projects/js-packages/charts/docs/ai-documentation-guide.md b/projects/js-packages/charts/docs/ai-documentation-guide.md index 078e331e3733..7c96debbe1f0 100644 --- a/projects/js-packages/charts/docs/ai-documentation-guide.md +++ b/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 `` 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 `` blocks must use tabs, not spaces, for indentation +- **Author `` templates for the dedent**: Storybook dedents `` 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 `` 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