Expandable Sidebar Nesting Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Add support for nested parent → child sidebar items in Docusaurus so component families (e.g., Input → Input text / Input number / Input date / Text area) render as expandable categories.
Architecture: Filesystem-driven detection — a folder with _category_.json is a parent (sidebar category, no own page); a folder with index.md is a leaf (existing pattern, unchanged). The doc-tabs-plugin walks recursively, emits a manifest keyed by slug paths and a list of parent-URL → first-child redirects. Docusaurus' autogenerated sidebar reads _category_.json natively, so sidebars.ts is unchanged. Slash commands (/generate-component-doc, /migrate-component-doc, /add-content-tab, /generate-pattern-doc) accept a unified Parent/Child path syntax.
Tech Stack: Docusaurus 3.10 (with Rspack faster flag), React 19, TypeScript 5.6, Node 20+. Tests use Node's built-in node:test runner (zero new test dependencies). Redirects use @docusaurus/plugin-client-redirects.
Spec: docs/superpowers/specs/2026-04-27-expandable-sidebar-nesting-design.md
File Structure
| File | Status | Responsibility |
|---|---|---|
plugins/doc-tabs-plugin.js | Modify | Recursively scan doc dirs; emit manifest, categories, redirects, warnings via setGlobalData; write redirects JSON to .docusaurus/ for the redirects plugin to read. |
plugins/__tests__/doc-tabs-plugin.test.js | Create | Unit tests for scanDocTabs, exposed as a named export from the plugin module. |
plugins/__tests__/fixtures/flat-only/ | Create | Fixture: only flat components (regression coverage). |
plugins/__tests__/fixtures/nested-family/ | Create | Fixture: parent _category_.json + 2 children. |
plugins/__tests__/fixtures/mixed/ | Create | Fixture: flat siblings alongside a nested family. |
plugins/__tests__/fixtures/ambiguous/ | Create | Fixture: folder with both index.md and _category_.json (warning case). |
plugins/__tests__/fixtures/empty-parent/ | Create | Fixture: _category_.json with no leaf descendants (warning case). |
src/components/AutoDocTabs/index.tsx | Modify | Update three webpackInclude regexes (component/pattern/foundation) to allow nested paths. |
src/theme/DocItem/Layout/index.tsx | Modify | Replace last-segment slug derivation with full sub-path derivation. Extract to a pure helper for testability. |
src/theme/DocItem/Layout/derive-slug.ts | Create | Pure helper deriveSlug(metadataId) with full unit-test coverage. |
src/theme/DocItem/Layout/__tests__/derive-slug.test.ts | Create | Unit tests for deriveSlug (run via node --test --experimental-strip-types). |
docusaurus.config.ts | Modify | (a) Update exclude patterns from components/*/... to components/**/... so nested tab files stay hidden. (b) Register @docusaurus/plugin-client-redirects plugin reading from the JSON the doc-tabs-plugin writes. |
package.json | Modify | Add @docusaurus/plugin-client-redirects dependency. Add test and test:plugin scripts. |
docs/.redirects.json | Create | Persistent migration redirects array (starts as []). Read by the redirects plugin alongside the plugin-emitted file. |
.claude/commands/generate-component-doc.md | Modify | Add Parent/Child path syntax; parent detection; first-child _category_.json creation; bug-fix the legacy <kebab>.md check. |
.claude/commands/add-content-tab.md | Modify | Add Parent/Child path syntax; resolve to nested folder. |
.claude/commands/generate-pattern-doc.md | Modify | Same as generate-component-doc.md but for patterns. |
.claude/commands/migrate-component-doc.md | Create | New skill for flat → nested migration. Two argument forms (same-name default, path-form rename). |
Task 1: Set up the Node test runner and a single passing fixture test
Files:
-
Modify:
package.json -
Create:
plugins/__tests__/fixtures/flat-only/components/avatar/index.md -
Create:
plugins/__tests__/fixtures/flat-only/components/avatar/overview.md -
Create:
plugins/__tests__/fixtures/flat-only/components/avatar/design.md -
Create:
plugins/__tests__/doc-tabs-plugin.test.js -
Modify:
plugins/doc-tabs-plugin.js(exportscanDocTabsfor testability) -
Step 1: Add test scripts to package.json
In package.json, add to scripts (preserve existing entries):
"test": "node --test plugins/__tests__/",
"test:plugin": "node --test plugins/__tests__/doc-tabs-plugin.test.js"
- Step 2: Create the flat-only fixture directory
Create three placeholder files. They mimic a real flat component but are tiny.
plugins/__tests__/fixtures/flat-only/components/avatar/index.md:
---
title: Avatar
component_page: true
---
# Avatar
plugins/__tests__/fixtures/flat-only/components/avatar/overview.md:
## Purpose
Test fixture.
plugins/__tests__/fixtures/flat-only/components/avatar/design.md:
## Anatomy
Test fixture.
(Minimum required to be recognised as a leaf with two tabs.)
- Step 3: Export
scanDocTabsfor testability
In plugins/doc-tabs-plugin.js, at the bottom of the file, add:
module.exports.scanDocTabs = scanDocTabs;
(Keep the default export module.exports = function docTabsPlugin(context) { ... } as-is.)
- Step 4: Write the first failing test
Create plugins/__tests__/doc-tabs-plugin.test.js:
const test = require('node:test');
const assert = require('node:assert/strict');
const path = require('node:path');
const {scanDocTabs} = require('../doc-tabs-plugin');
const FIXTURES = path.join(__dirname, 'fixtures');
test('flat-only fixture: avatar leaf is recognised with its tabs', () => {
const {manifest} = scanDocTabs(path.join(FIXTURES, 'flat-only'));
assert.ok(manifest.avatar, 'expected manifest entry for avatar');
assert.deepEqual(manifest.avatar.tabs, ['overview', 'design']);
assert.equal(manifest.avatar.type, 'component');
});
- Step 5: Run the test — expect it to FAIL
Run: npm run test:plugin
Expected: FAIL. Reason: today's scanDocTabs returns manifest directly (not {manifest, ...}); the test will fail on the destructuring.
- Step 6: Update
scanDocTabsto return a structured object
In plugins/doc-tabs-plugin.js, change the function to return an object:
function scanDocTabs(docsDir) {
const manifest = {};
// ... existing inner logic unchanged ...
return { manifest }; // was: return manifest;
}
Update the plugin's contentLoaded to consume the new shape:
async contentLoaded({actions}) {
const {setGlobalData} = actions;
const {manifest} = scanDocTabs(docsDir);
setGlobalData({manifest});
},
- Step 7: Run the test — expect it to PASS
Run: npm run test:plugin
Expected: 1 test passing.
- Step 8: Verify the production build still works
Run: npm run build
Expected: build succeeds; flat components render unchanged. (No nested folders exist yet.)
- Step 9: Commit
git add package.json plugins/doc-tabs-plugin.js plugins/__tests__
git commit -m "test: add node:test runner and flat-only plugin fixture"
Task 2: Recursive walker — handle nested leaf folders
Files:
-
Modify:
plugins/doc-tabs-plugin.js -
Create:
plugins/__tests__/fixtures/nested-family/components/input/_category_.json -
Create:
plugins/__tests__/fixtures/nested-family/components/input/input-text/index.md -
Create:
plugins/__tests__/fixtures/nested-family/components/input/input-text/overview.md -
Create:
plugins/__tests__/fixtures/nested-family/components/input/input-number/index.md -
Create:
plugins/__tests__/fixtures/nested-family/components/input/input-number/overview.md -
Modify:
plugins/__tests__/doc-tabs-plugin.test.js -
Step 1: Create the nested-family fixture
plugins/__tests__/fixtures/nested-family/components/input/_category_.json:
{
"label": "Input",
"position": 5,
"link": { "type": "doc", "id": "components/input/input-text" },
"collapsed": true
}
plugins/__tests__/fixtures/nested-family/components/input/input-text/index.md:
---
title: Input text
component_page: true
---
# Input text
plugins/__tests__/fixtures/nested-family/components/input/input-text/overview.md:
## Purpose
Fixture child.
plugins/__tests__/fixtures/nested-family/components/input/input-number/index.md:
---
title: Input number
component_page: true
---
# Input number
plugins/__tests__/fixtures/nested-family/components/input/input-number/overview.md:
## Purpose
Fixture child.
- Step 2: Add a failing test for the nested family
Append to plugins/__tests__/doc-tabs-plugin.test.js:
test('nested-family fixture: children are keyed by slash path', () => {
const {manifest} = scanDocTabs(path.join(FIXTURES, 'nested-family'));
assert.ok(manifest['input/input-text'], 'expected input/input-text in manifest');
assert.ok(manifest['input/input-number'], 'expected input/input-number in manifest');
assert.deepEqual(manifest['input/input-text'].tabs, ['overview']);
assert.equal(manifest['input/input-text'].type, 'component');
// The parent folder itself is NOT a manifest entry.
assert.equal(manifest.input, undefined);
});
- Step 3: Run the test — expect it to FAIL
Run: npm run test:plugin
Expected: FAIL. Today's scanDocTabs only walks one level deep and skips folders without index.md, so it ignores input/ entirely.
- Step 4: Refactor
scanDocTabsto use a recursive walker
Replace the body of scanDocTabs in plugins/doc-tabs-plugin.js with the walker pattern:
function walk(currentDir, relativeSlug, dir, type, manifest, categories, warnings) {
const indexFile = path.join(currentDir, 'index.md');
const categoryFile = path.join(currentDir, '_category_.json');
const hasIndex = fs.existsSync(indexFile);
const hasCategory = fs.existsSync(categoryFile);
if (hasIndex && hasCategory) {
warnings.push(`${currentDir}: both index.md and _category_.json present — treating as leaf`);
}
if (hasIndex) {
const tabs = TAB_NAMES.filter((tab) =>
fs.existsSync(path.join(currentDir, `${tab}.md`)),
);
if (tabs.length > 0) {
manifest[relativeSlug] = {
tabs,
path: `docs/${dir}/${relativeSlug}`,
type,
};
}
return;
}
if (hasCategory) {
let category;
try {
category = JSON.parse(fs.readFileSync(categoryFile, 'utf8'));
} catch (err) {
warnings.push(`${categoryFile}: could not parse — ${err.message}`);
return;
}
categories.push({slug: relativeSlug, dir, type, category, path: currentDir});
const children = fs.readdirSync(currentDir, {withFileTypes: true});
for (const child of children) {
if (!child.isDirectory()) continue;
walk(
path.join(currentDir, child.name),
`${relativeSlug}/${child.name}`,
dir,
type,
manifest,
categories,
warnings,
);
}
return;
}
// No marker — folder is skipped.
}
function scanDocTabs(docsDir) {
const manifest = {};
const categories = [];
const warnings = [];
for (const {dir, type} of DOC_DIRS) {
const fullDir = path.join(docsDir, dir);
if (!fs.existsSync(fullDir)) continue;
const entries = fs.readdirSync(fullDir, {withFileTypes: true});
for (const entry of entries) {
if (!entry.isDirectory()) continue;
walk(
path.join(fullDir, entry.name),
entry.name,
dir,
type,
manifest,
categories,
warnings,
);
}
}
return {manifest, categories, warnings};
}
- Step 5: Run the tests — expect both to PASS
Run: npm run test:plugin
Expected: 2 tests passing (flat-only + nested-family).
- Step 6: Verify build still works
Run: npm run build
Expected: build succeeds. Existing flat components render unchanged.
- Step 7: Commit
git add plugins/doc-tabs-plugin.js plugins/__tests__
git commit -m "feat(doc-tabs-plugin): recursive walker with nested-family fixture"
Task 3: Mixed fixture — flat and nested coexist
Files:
-
Create:
plugins/__tests__/fixtures/mixed/components/avatar/index.md -
Create:
plugins/__tests__/fixtures/mixed/components/avatar/overview.md -
Create:
plugins/__tests__/fixtures/mixed/components/input/_category_.json -
Create:
plugins/__tests__/fixtures/mixed/components/input/input-text/index.md -
Create:
plugins/__tests__/fixtures/mixed/components/input/input-text/overview.md -
Modify:
plugins/__tests__/doc-tabs-plugin.test.js -
Step 1: Create the mixed fixture
Mirror the structure: a flat avatar/ next to a nested input/ with one child.
plugins/__tests__/fixtures/mixed/components/avatar/index.md and overview.md — same content as Task 1.
plugins/__tests__/fixtures/mixed/components/input/_category_.json:
{
"label": "Input",
"position": 5,
"link": { "type": "doc", "id": "components/input/input-text" }
}
plugins/__tests__/fixtures/mixed/components/input/input-text/index.md and overview.md — same as Task 2.
- Step 2: Add a failing test
Append:
test('mixed fixture: flat and nested coexist in one manifest', () => {
const {manifest, categories} = scanDocTabs(path.join(FIXTURES, 'mixed'));
assert.ok(manifest.avatar, 'flat avatar present');
assert.ok(manifest['input/input-text'], 'nested input/input-text present');
assert.equal(categories.length, 1);
assert.equal(categories[0].slug, 'input');
assert.equal(categories[0].category.label, 'Input');
});
- Step 3: Run the test — expect it to PASS
Run: npm run test:plugin
Expected: 3 tests passing. (No code change needed; the walker from Task 2 already handles both shapes.)
- Step 4: Commit
git add plugins/__tests__
git commit -m "test(doc-tabs-plugin): mixed flat-and-nested fixture"
Task 4: Redirect emission from categories
Files:
-
Modify:
plugins/doc-tabs-plugin.js -
Modify:
plugins/__tests__/doc-tabs-plugin.test.js -
Step 1: Add a failing test for redirect emission
Append:
test('mixed fixture: emits redirect from parent URL to first child', () => {
const result = scanDocTabs(path.join(FIXTURES, 'mixed'));
assert.ok(Array.isArray(result.redirects), 'redirects is an array');
assert.deepEqual(result.redirects, [
{ from: '/docs/components/input', to: '/docs/components/input/input-text' },
]);
});
- Step 2: Run the test — expect it to FAIL
Run: npm run test:plugin
Expected: FAIL. result.redirects is undefined today.
- Step 3: Build redirects from categories in
scanDocTabs
In plugins/doc-tabs-plugin.js, just before return {manifest, categories, warnings} in scanDocTabs, add:
const redirects = categories
.filter((c) => c.category.link && c.category.link.type === 'doc' && c.category.link.id)
.map((c) => ({
from: `/docs/${c.dir}/${c.slug}`,
to: `/docs/${c.category.link.id}`,
}));
return {manifest, categories, warnings, redirects};
- Step 4: Run the test — expect it to PASS
Run: npm run test:plugin
Expected: 4 tests passing.
- Step 5: Commit
git add plugins/doc-tabs-plugin.js plugins/__tests__
git commit -m "feat(doc-tabs-plugin): emit parent-URL redirects from _category_.json"
Task 5: Build-time validation warnings
Files:
-
Create:
plugins/__tests__/fixtures/ambiguous/components/avatar/index.md -
Create:
plugins/__tests__/fixtures/ambiguous/components/avatar/_category_.json -
Create:
plugins/__tests__/fixtures/empty-parent/components/input/_category_.json -
Modify:
plugins/__tests__/doc-tabs-plugin.test.js -
Modify:
plugins/doc-tabs-plugin.js -
Step 1: Create the ambiguous fixture
plugins/__tests__/fixtures/ambiguous/components/avatar/index.md:
---
title: Avatar
---
# Avatar
plugins/__tests__/fixtures/ambiguous/components/avatar/_category_.json:
{ "label": "Avatar", "position": 1 }
- Step 2: Create the empty-parent fixture
plugins/__tests__/fixtures/empty-parent/components/input/_category_.json:
{
"label": "Input",
"position": 5,
"link": { "type": "doc", "id": "components/input/input-text" }
}
(No child folders. link.id points nowhere.)
- Step 2b: Create the out-of-subtree fixture
plugins/__tests__/fixtures/out-of-subtree/components/input/_category_.json:
{
"label": "Input",
"position": 5,
"link": { "type": "doc", "id": "components/tag" }
}
plugins/__tests__/fixtures/out-of-subtree/components/input/input-text/index.md:
---
title: Input text
---
# Input text
plugins/__tests__/fixtures/out-of-subtree/components/input/input-text/overview.md:
## Purpose
Fixture child.
plugins/__tests__/fixtures/out-of-subtree/components/tag/index.md:
---
title: Tag
---
# Tag
plugins/__tests__/fixtures/out-of-subtree/components/tag/overview.md:
## Purpose
Fixture leaf in a different subtree.
(The input parent's link.id points to components/tag — outside its own subtree.)
- Step 3: Add failing tests
Append:
test('ambiguous fixture: warns when both index.md and _category_.json exist', () => {
const {warnings, manifest} = scanDocTabs(path.join(FIXTURES, 'ambiguous'));
assert.ok(warnings.some((w) => w.includes('both index.md and _category_.json')));
// It is still treated as a leaf:
assert.ok(manifest.avatar);
});
test('empty-parent fixture: warns when category has no leaf descendants', () => {
const {warnings} = scanDocTabs(path.join(FIXTURES, 'empty-parent'));
assert.ok(warnings.some((w) => w.includes('has no leaf descendants')),
`expected empty-parent warning, got: ${warnings.join(' / ')}`);
});
test('empty-parent fixture: warns when link.id points to non-existent leaf', () => {
const {warnings} = scanDocTabs(path.join(FIXTURES, 'empty-parent'));
assert.ok(warnings.some((w) => w.includes('does not resolve')),
`expected unresolved-link warning, got: ${warnings.join(' / ')}`);
});
test('out-of-subtree fixture: warns when link.id points outside the parent subtree', () => {
const {warnings} = scanDocTabs(path.join(FIXTURES, 'out-of-subtree'));
assert.ok(warnings.some((w) => w.includes('points outside the parent')),
`expected out-of-subtree warning, got: ${warnings.join(' / ')}`);
});
- Step 4: Run the tests — expect FAIL
Run: npm run test:plugin
Expected: 3 of the 4 new tests fail. (The "both index.md and category.json" warning was added in Task 2 already, so that one passes. The other three — empty-parent, unresolved-link, out-of-subtree — require the validation pass added in Step 5.)
- Step 5: Add empty-parent, unresolved-link, and out-of-subtree validation
In plugins/doc-tabs-plugin.js, after building redirects and before returning, add:
// Validation pass over all categories.
for (const c of categories) {
// (a) Empty parent: no leaf in this parent's subtree.
const hasLeafInSubtree = Object.keys(manifest).some((k) =>
k === c.slug || k.startsWith(`${c.slug}/`),
);
if (!hasLeafInSubtree) {
warnings.push(`${c.path}: parent has no leaf descendants`);
}
if (c.category.link && c.category.link.type === 'doc' && c.category.link.id) {
// link.id is a doc ID like "components/input/input-text".
// Strip the doc-dir prefix to get the slug used in the manifest.
const linkSlug = c.category.link.id.replace(new RegExp(`^${c.dir}/`), '');
// (b) Unresolved link.id.
if (!manifest[linkSlug]) {
warnings.push(
`${c.path}: _category_.json link.id="${c.category.link.id}" does not resolve to a leaf`,
);
}
// (c) link.id outside the parent's subtree.
// The linkSlug must equal the parent's slug or start with `<parent-slug>/`.
if (linkSlug !== c.slug && !linkSlug.startsWith(`${c.slug}/`)) {
warnings.push(
`${c.path}: _category_.json link.id="${c.category.link.id}" points outside the parent's subtree`,
);
}
}
}
- Step 6: Run the tests — expect PASS
Run: npm run test:plugin
Expected: all 8 tests passing.
- Step 7: Surface warnings in the dev-server log
In the plugin's contentLoaded, after scanDocTabs:
async contentLoaded({actions}) {
const {setGlobalData} = actions;
const {manifest, categories, warnings, redirects} = scanDocTabs(docsDir);
for (const w of warnings) {
console.warn(`[doc-tabs-plugin] ${w}`);
}
setGlobalData({manifest, categories, redirects});
},
- Step 8: Verify build still works (no warnings expected)
Run: npm run build
Expected: build succeeds. No [doc-tabs-plugin] warnings (no nested families exist in the live docs yet).
- Step 9: Commit
git add plugins/doc-tabs-plugin.js plugins/__tests__
git commit -m "feat(doc-tabs-plugin): validate empty parents and unresolved link.ids"
Task 6: Update AutoDocTabs lazy-import regexes
Files:
- Modify:
src/components/AutoDocTabs/index.tsx
This is a runtime React change with no unit-test surface available in this repo. Verification is via build + visual smoke test.
- Step 1: Update the three
webpackIncluderegexes
In src/components/AutoDocTabs/index.tsx, line 31:
Before:
/* webpackInclude: /docs\/components\/[^/]+\/(overview|design|code|accessibility|content|status)\.md$/ */
After:
/* webpackInclude: /docs\/components\/(?:[^/]+\/)+(overview|design|code|accessibility|content|status)\.md$/ */
Apply the same change to the pattern variant (line 40) and the foundation variant (line 49). The replacement of [^/]+\/ with (?:[^/]+\/)+ permits any number of intermediate path segments.
- Step 2: Verify the production build succeeds
Run: npm run build
Expected: build succeeds with no new warnings. Existing flat component pages still bundle their tab modules correctly.
- Step 3: Manual smoke test
Run: npm run start
Open the dev server. Visit one existing flat component page (e.g., /docs/components/avatar/) and click through every tab. Confirm tabs still load.
- Step 4: Commit
git add src/components/AutoDocTabs/index.tsx
git commit -m "refactor(auto-doc-tabs): allow nested paths in webpackInclude regex"
Task 7: Layout slug derivation — extract pure helper with tests
Files:
- Create:
src/theme/DocItem/Layout/derive-slug.js - Create:
src/theme/DocItem/Layout/__tests__/derive-slug.test.js - Modify:
src/theme/DocItem/Layout/index.tsx - Modify:
package.json
The helper is intentionally plain JS (with JSDoc types) rather than .ts so the test runner doesn't need a TypeScript loader. The TypeScript layout file imports it directly; TypeScript reads the JSDoc for type info.
- Step 1: Create the helper file
src/theme/DocItem/Layout/derive-slug.js:
/**
* Convert a Docusaurus metadata.id (e.g., "components/avatar/index" or
* "components/input/input-text/index") into the slug used by the
* doc-tabs-plugin manifest (e.g., "avatar" or "input/input-text").
*
* Rules: drop the doc-dir prefix (first segment), drop a trailing
* "/index" segment, join the rest with "/".
*
* @param {string | undefined} metadataId
* @returns {string}
*/
function deriveSlug(metadataId) {
if (!metadataId) return '';
const parts = metadataId.split('/');
if (parts.length < 2) return '';
const withoutDocDir = parts.slice(1);
const last = withoutDocDir[withoutDocDir.length - 1];
const trimmed = last === 'index' ? withoutDocDir.slice(0, -1) : withoutDocDir;
return trimmed.join('/');
}
module.exports = {deriveSlug};
- Step 2: Add a failing test file
src/theme/DocItem/Layout/__tests__/derive-slug.test.js:
const test = require('node:test');
const assert = require('node:assert/strict');
const {deriveSlug} = require('../derive-slug');
test('flat leaf: components/avatar/index → avatar', () => {
assert.equal(deriveSlug('components/avatar/index'), 'avatar');
});
test('nested leaf: components/input/input-text/index → input/input-text', () => {
assert.equal(deriveSlug('components/input/input-text/index'), 'input/input-text');
});
test('flat leaf without trailing index: components/avatar → avatar', () => {
assert.equal(deriveSlug('components/avatar'), 'avatar');
});
test('nested 3-deep: components/forms/input/input-text/index → forms/input/input-text', () => {
assert.equal(deriveSlug('components/forms/input/input-text/index'), 'forms/input/input-text');
});
test('empty input returns empty string', () => {
assert.equal(deriveSlug(undefined), '');
assert.equal(deriveSlug(''), '');
});
test('single-segment id returns empty string', () => {
assert.equal(deriveSlug('components'), '');
});
- Step 3: Update the test script to also run the helper tests
In package.json, change the test script:
"test": "node --test plugins/__tests__/ src/theme/DocItem/Layout/__tests__/"
(No flags needed — both files are .js and run on Node 20+.)
- Step 4: Run the tests — expect PASS
Run: npm run test
Expected: 8 plugin tests + 6 derive-slug tests = 14 passing.
- Step 5: Replace the inline slug logic in the layout with the helper
In src/theme/DocItem/Layout/index.tsx, add the import at the top (alongside the other imports):
import {deriveSlug} from './derive-slug';
Replace lines 57–59 (the existing slug derivation):
Before:
const idParts = metadata.id?.split('/') ?? [];
const lastPart = idParts[idParts.length - 1];
const slug = lastPart === 'index' ? (idParts[idParts.length - 2] ?? '') : lastPart ?? '';
After:
const slug = deriveSlug(metadata.id);
- Step 6: Run typecheck to confirm JSDoc types resolve cleanly
Run: npm run typecheck
Expected: no errors. TypeScript reads derive-slug.js's JSDoc and infers deriveSlug: (metadataId: string | undefined) => string. The slug variable in index.tsx is correctly typed as string.
- Step 7: Verify build and dev server
Run: npm run build
Expected: build succeeds.
Run: npm run start and visit an existing flat component page. Confirm tabs render.
- Step 8: Commit
git add src/theme/DocItem/Layout package.json
git commit -m "refactor(doc-item-layout): extract deriveSlug helper with full coverage"
Task 8: Update docusaurus.config.ts exclude patterns for nested
Files:
- Modify:
docusaurus.config.ts
Today's exclude array uses single-* patterns (components/*/overview.md) which only match one path segment. Without this fix, nested children's tab files (e.g., components/input/input-text/overview.md) would leak into the autogenerated sidebar as standalone entries.
- Step 1: Replace
*with**in the exclude array
In docusaurus.config.ts, the existing exclude array (lines 46–58):
Before:
exclude: [
'components/*/overview.md',
'components/*/design.md',
'components/*/code.md',
'components/*/accessibility.md',
'components/*/content.md',
'components/*/status.md',
'patterns/*/overview.md',
'patterns/*/design.md',
'patterns/*/code.md',
'patterns/*/accessibility.md',
'patterns/*/content.md',
'patterns/*/status.md',
],
After:
exclude: [
'components/**/overview.md',
'components/**/design.md',
'components/**/code.md',
'components/**/accessibility.md',
'components/**/content.md',
'components/**/status.md',
'patterns/**/overview.md',
'patterns/**/design.md',
'patterns/**/code.md',
'patterns/**/accessibility.md',
'patterns/**/content.md',
'patterns/**/status.md',
'foundations/**/overview.md',
'foundations/**/design.md',
'foundations/**/code.md',
'foundations/**/accessibility.md',
'foundations/**/content.md',
'foundations/**/status.md',
],
(** is a globstar — matches across path segments, including zero segments. Foundations are added for completeness since the plugin already scans them.)
- Step 2: Verify build still works (regression check on existing components)
Run: npm run build
Expected: build succeeds. All existing flat components render unchanged. No tab files leak into the sidebar.
- Step 3: Manual smoke test
Run: npm run start. Open the sidebar — verify the components/patterns/foundations sections look identical to before.
- Step 4: Commit
git add docusaurus.config.ts
git commit -m "refactor(config): use globstar in docs exclude for nested-aware filtering"
Task 9: Install and wire @docusaurus/plugin-client-redirects
Files:
- Modify:
package.json - Modify:
plugins/doc-tabs-plugin.js - Modify:
docusaurus.config.ts - Create:
docs/.redirects.json
The doc-tabs-plugin will write its computed redirects to a JSON file at .docusaurus/doc-tabs-plugin/redirects.json during contentLoaded. The redirects plugin reads two sources: that file, plus a persistent docs/.redirects.json for migration redirects.
- Step 1: Install the redirects plugin
Run: npm install @docusaurus/plugin-client-redirects
Expected: dependency added to package.json at the same major version as the rest of @docusaurus/* (3.10.x).
- Step 2: Create the persistent migration manifest as an empty array
Create docs/.redirects.json:
[]
(Will be appended to by /migrate-component-doc over time.)
- Step 3: Make the doc-tabs-plugin write its computed redirects to disk
In plugins/doc-tabs-plugin.js, update contentLoaded:
async contentLoaded({actions}) {
const {setGlobalData} = actions;
const {manifest, categories, warnings, redirects} = scanDocTabs(docsDir);
for (const w of warnings) {
console.warn(`[doc-tabs-plugin] ${w}`);
}
setGlobalData({manifest, categories, redirects});
// Write redirects to disk so docusaurus.config.ts can read them
// synchronously when configuring plugin-client-redirects.
const outDir = path.join(context.siteDir, '.docusaurus', 'doc-tabs-plugin');
fs.mkdirSync(outDir, {recursive: true});
fs.writeFileSync(
path.join(outDir, 'redirects.json'),
JSON.stringify(redirects, null, 2),
);
},
(Note: context is the factory's argument; bind it via closure.)
- Step 4: Register the redirects plugin in
docusaurus.config.ts
In docusaurus.config.ts, replace the plugins array:
plugins: [
require.resolve('./plugins/doc-tabs-plugin'),
[
'@docusaurus/plugin-client-redirects',
{
createRedirects: () => {
const fs = require('node:fs');
const path = require('node:path');
const fromPlugin = (() => {
const file = path.join(__dirname, '.docusaurus', 'doc-tabs-plugin', 'redirects.json');
if (!fs.existsSync(file)) return [];
try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return []; }
})();
const fromManifest = (() => {
const file = path.join(__dirname, 'docs', '.redirects.json');
if (!fs.existsSync(file)) return [];
try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return []; }
})();
return [...fromPlugin, ...fromManifest];
},
},
],
],
(The createRedirects callback runs at build time, after doc-tabs-plugin has written the redirects file.)
- Step 5: Verify build succeeds with no redirects yet
Run: npm run build
Expected: build succeeds. Both redirects sources are empty arrays at this point, so no redirects are emitted.
- Step 6: Add a test for the redirects-file write
Append to plugins/__tests__/doc-tabs-plugin.test.js:
const fsp = require('node:fs/promises');
const os = require('node:os');
test('plugin contentLoaded writes redirects.json to .docusaurus dir', async () => {
// Create a tmp siteDir, copy the mixed fixture into <tmp>/docs/.
// The plugin factory does docsDir = path.join(siteDir, 'docs'), so the
// fixture content needs to land under <tmp>/docs/.
const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'doc-tabs-plugin-'));
const docsDest = path.join(tmp, 'docs');
await fsp.mkdir(docsDest, {recursive: true});
const fixture = path.join(FIXTURES, 'mixed');
await fsp.cp(fixture, docsDest, {recursive: true});
const docTabsPlugin = require('../doc-tabs-plugin');
const instance = docTabsPlugin({siteDir: tmp});
let captured;
await instance.contentLoaded({
actions: {setGlobalData: (data) => { captured = data; }},
});
const written = JSON.parse(
await fsp.readFile(
path.join(tmp, '.docusaurus', 'doc-tabs-plugin', 'redirects.json'),
'utf8',
),
);
assert.deepEqual(written, [
{from: '/docs/components/input', to: '/docs/components/input/input-text'},
]);
assert.equal(captured.redirects.length, 1);
});
- Step 7: Run the tests — expect PASS
Run: npm run test
Expected: 15 tests passing total (8 plugin + 6 derive-slug + 1 redirects-write).
- Step 8: Commit
git add package.json package-lock.json plugins/doc-tabs-plugin.js docusaurus.config.ts docs/.redirects.json plugins/__tests__
git commit -m "feat: wire client-redirects plugin reading from doc-tabs-plugin output"
Task 10: Smoke test — create a real nested family in live docs
Files:
- Create:
docs/components/input/_category_.json - Create:
docs/components/input/input-text/index.md - Create:
docs/components/input/input-text/overview.md - Create:
docs/components/input/input-text/design.md - Create:
docs/components/input/input-text/code.md - Create:
docs/components/input/input-text/accessibility.md - Create:
docs/components/input/input-text/status.md - Create:
docs/components/input/input-number/(same six files)
The infrastructure is now complete. Create one nested family by hand to verify end-to-end behavior before updating the slash commands.
- Step 1: Create the
_category_.jsonparent marker
docs/components/input/_category_.json:
{
"label": "Input",
"position": 99,
"link": { "type": "doc", "id": "components/input/input-text" },
"collapsed": true
}
- Step 2: Scaffold the
input-textchild
Use scripts/new-component.sh adapted (or copy from an existing component) to create docs/components/input/input-text/ with all six tab files. Each file uses the standard template — the existing bash scripts/new-component.sh input-text will create at docs/components/input-text/, so git mv it to the nested location:
bash scripts/new-component.sh input-text
git mv docs/components/input-text docs/components/input/input-text
(The shell script doesn't yet support nested paths — that comes in Task 11. This is the workaround for now.)
- Step 3: Scaffold the
input-numberchild the same way
bash scripts/new-component.sh input-number
git mv docs/components/input-number docs/components/input/input-number
- Step 4: Run the dev server and verify the sidebar
Run: npm run clear && npm run start
Expected:
-
Sidebar shows "Input" as a collapsed category under Components
-
Expanding "Input" reveals "Input text" and "Input number" as children
-
Clicking "Input" navigates to
/docs/components/input/input-text/ -
Both child pages render with the standard tab structure (Overview, Design, Code, Accessibility, Status)
-
All tabs load content (clicking each tab on a child shows the corresponding
.mdfile) -
Step 5: Verify the parent-URL redirect
Run: npm run build && npm run serve
Visit http://localhost:3000/docs/components/input/ (with trailing slash) and http://localhost:3000/docs/components/input (without).
Expected: both redirect to /docs/components/input/input-text/.
- Step 6: Verify regression on existing flat components
Visit /docs/components/avatar/ (or any existing flat component). Confirm tabs render and content matches main.
- Step 7: Commit
git add docs/components/input
git commit -m "feat(docs): add Input nested family as nesting smoke test"
Task 11: Update /generate-component-doc skill — path syntax + parent detection
Files:
- Modify:
.claude/commands/generate-component-doc.md
The existing skill checks docs/components/<kebab>.md (single-file convention, outdated) and creates flat-only scaffolds. Update to: (a) check the folder-based convention; (b) accept Parent/Child path syntax; (c) detect/create parents.
- Step 1: Read the existing skill to find anchors for the edits
Run: cat .claude/commands/generate-component-doc.md | head -120
(Skim to identify the specific section headings to modify — the structure already exists.)
- Step 2: Update Step 1 (Derive Name Variants) to handle
Parent/Child
In .claude/commands/generate-component-doc.md, find the "## Step 1: Derive Name Variants" section and replace it with:
## Step 1: Derive Name Variants
The argument may be a single name (`Avatar`) or a path (`Input/InputText`). Split on `/` first.
For each segment, derive:
- **kebab**: `date-picker` (filename, npm package)
- **pascal**: `DatePicker` (title, headings)
- **lower**: `datepicker` (Storybook URL slug, preview image filename)
Convert PascalCase → kebab by inserting hyphens before uppercase letters and lowercasing.
If the argument has 2+ segments, the last is the **leaf** (the new component being created); the rest is the **parent path** (one or more parent kebab segments joined by `/`).
- Step 3: Replace Step 3 (Ensure Scaffold Exists)
Find the "## Step 3: Ensure Scaffold Exists" section. Replace with:
## Step 3: Ensure Parent and Scaffold
The target folder is `docs/components/<parent-kebab-path>/<leaf-kebab>/` (or `docs/components/<leaf-kebab>/` for flat creation with no parent path).
### 3a: Resolve the parent (only when a parent path was given)
For each parent segment, walk down `docs/components/<parent-kebab-path>/`:
- If the folder doesn't exist:
- Ask the user: "Create new '[Parent-pascal]' parent category? (Y/n)"
- On Y: create the folder + `_category_.json` with:
```json
{
"label": "[Parent-pascal]",
"position": 99,
"link": { "type": "doc", "id": "components/[parent-kebab-path]/[leaf-kebab]" },
"collapsed": true
}
The new leaf becomes the first child (the parent's link.id points to it).
- If the folder exists and contains
_category_.json: continue (it's a valid parent). - If the folder exists and contains
index.md: STOP and report:"
[parent-kebab-path]is a leaf component. Cannot nest under it. Use/migrate-component-doc [parent] [NewParent]first to convert it into a child of a new parent, or pick a different parent path."
3b: Create the leaf folder
Check if docs/components/<parent-kebab-path>/<leaf-kebab>/ exists.
- If it does NOT exist: Create it with the standard six-tab scaffold (
index.md+overview.md+design.md+code.md+accessibility.md+status.md). Usesidebar_position: 99,component_page: true, all tabs with TODO placeholders. If a Storybook URL was provided in Step 2, use it instead of the TODO placeholder. - If it exists: Read it — you'll enrich it in the following steps. If a Storybook URL was provided, replace any existing Storybook URLs or TODO placeholders.
- [ ] **Step 4: Add a new Step 7b that updates `_category_.json` if needed**
After Step 7 (Write the Updated Markdown), add:
```markdown
## Step 7b: Update `_category_.json` (only when applicable)
If a parent path was given AND the parent's `_category_.json` was created in Step 3a, no update is needed (it already points to this leaf).
If a parent path was given AND the parent's `_category_.json` already existed before this run AND its `link.id` is missing, set `link.id` to the new leaf's doc ID. Otherwise leave it alone.
- Step 5: Update Step 8 (Report Results) summary content
In Step 8, add a bullet to the summary:
- Whether a parent `_category_.json` was created or updated, and where (path on disk)
- Step 6: Verify the skill renders correctly
Run the slash command in dry-run mode (or read the file end-to-end):
cat .claude/commands/generate-component-doc.md
Expected: all sections are present, no broken markdown. The "Reference" section still mentions .claude/figma-naming-config.md.
- Step 7: Commit
git add .claude/commands/generate-component-doc.md
git commit -m "feat(skills): generate-component-doc supports Parent/Child path syntax"
Task 12: Update /add-content-tab skill — path syntax
Files:
-
Modify:
.claude/commands/add-content-tab.md -
Step 1: Update Step 1 (Derive Name Variants)
In .claude/commands/add-content-tab.md, find Step 1. Add to the bottom of the section:
The argument may be a single name (`alert`) or a path (`Input/InputText`). Split on `/` first; derive kebab/pascal/lower for each segment.
- Step 2: Update Step 2 (Locate the Documentation Folder)
Replace with:
## Step 2: Locate the Documentation Folder
The folder path is `docs/components/<...kebab-segments>/` for components or `docs/patterns/<...kebab-segments>/` for patterns.
For a flat component, that's `docs/components/alert/`.
For a nested child, that's `docs/components/input/input-text/`.
Search for the folder + `index.md` in this order:
1. `docs/components/<kebab-path>/index.md` — if found, this is a **component**
2. `docs/patterns/<kebab-path>/index.md` — if found, this is a **pattern**
**If neither exists**, report:
> "No folder-based documentation found at `<kebab-path>`. For nested paths (e.g., `Input/InputText`), make sure the parent folder exists and the leaf is in place. Run `/generate-component-doc <Path>` first if needed."
- Step 3: Verify the skill markdown renders
Run: cat .claude/commands/add-content-tab.md | head -80
Expected: well-formed markdown, no orphan sections.
- Step 4: Commit
git add .claude/commands/add-content-tab.md
git commit -m "feat(skills): add-content-tab supports nested Parent/Child paths"
Task 13: Update /generate-pattern-doc skill — same nesting support
Files:
- Modify:
.claude/commands/generate-pattern-doc.md
The pattern skill needs the same nesting support as the component skill. Patterns use the folder-per-tab structure too (docs/patterns/wizard/, docs/patterns/form-pattern/).
- Step 1: Update the "Derive Name Variants" section
Find the "## Step 1: Derive Name Variants" section in .claude/commands/generate-pattern-doc.md and replace it with:
## Step 1: Derive Name Variants
The argument may be a single name (`Wizard`) or a path (`Forms/Wizard`). Split on `/` first.
For each segment, derive:
- **kebab**: `form-wizard` (filename)
- **pascal**: `FormWizard` (title, headings)
- **lower**: `formwizard` (Storybook URL slug, preview image filename)
Convert PascalCase → kebab by inserting hyphens before uppercase letters and lowercasing.
If the argument has 2+ segments, the last is the **leaf** (the new pattern being created); the rest is the **parent path** (one or more parent kebab segments joined by `/`).
- Step 2: Replace the "Ensure Scaffold Exists" section
Find the section that ensures the scaffold exists and replace it with:
## Step 3: Ensure Parent and Scaffold
The target folder is `docs/patterns/<parent-kebab-path>/<leaf-kebab>/` (or `docs/patterns/<leaf-kebab>/` for flat creation with no parent path).
### 3a: Resolve the parent (only when a parent path was given)
For each parent segment, walk down `docs/patterns/<parent-kebab-path>/`:
- If the folder doesn't exist:
- Ask the user: "Create new '[Parent-pascal]' parent category? (Y/n)"
- On Y: create the folder + `_category_.json` with:
```json
{
"label": "[Parent-pascal]",
"position": 99,
"link": { "type": "doc", "id": "patterns/[parent-kebab-path]/[leaf-kebab]" },
"collapsed": true
}
The new leaf becomes the first child (the parent's link.id points to it).
- If the folder exists and contains
_category_.json: continue (it's a valid parent). - If the folder exists and contains
index.md: STOP and report:"
[parent-kebab-path]is a leaf pattern. Cannot nest under it. Use/migrate-component-doc [parent] [NewParent]first to convert it into a child of a new parent, or pick a different parent path."
3b: Create the leaf folder
Check if docs/patterns/<parent-kebab-path>/<leaf-kebab>/ exists.
- If it does NOT exist: Create it with the standard six-tab scaffold (
index.md+overview.md+design.md+code.md+accessibility.md+status.md). Usesidebar_position: 99,pattern_page: true, all tabs with TODO placeholders. If a Storybook URL was provided in Step 2, use it instead of the TODO placeholder. - If it exists: Read it — you'll enrich it in the following steps. If a Storybook URL was provided, replace any existing Storybook URLs or TODO placeholders.
- [ ] **Step 3: Add a Step 7b that updates `_category_.json` if needed**
After the "Write the Updated Markdown" step, insert:
```markdown
## Step 7b: Update `_category_.json` (only when applicable)
If a parent path was given AND the parent's `_category_.json` was created in Step 3a, no update is needed (it already points to this leaf).
If a parent path was given AND the parent's `_category_.json` already existed before this run AND its `link.id` is missing, set `link.id` to the new leaf's doc ID. Otherwise leave it alone.
- Step 4: Update the summary in the final report step
Find the "Report Results" or equivalent final step and add this bullet to the summary list:
- Whether a parent `_category_.json` was created or updated, and where (path on disk)
- Step 5: Verify the skill markdown renders
Run: cat .claude/commands/generate-pattern-doc.md | head -100
Expected: well-formed markdown, no orphan sections.
- Step 6: Commit
git add .claude/commands/generate-pattern-doc.md
git commit -m "feat(skills): generate-pattern-doc supports Parent/Child path syntax"
Task 14: Create /migrate-component-doc skill (new)
Files:
-
Create:
.claude/commands/migrate-component-doc.md -
Step 1: Write the skill file
Create .claude/commands/migrate-component-doc.md:
# Migrate Component Documentation (Flat → Nested)
You are migrating an existing flat component documentation folder into a nested parent.
## Input
- **$ARGUMENTS** — expects: `<flat-name> <parent-or-target>`
- Two argument forms:
- **Same name (default):** `datepicker Input` → moves `docs/components/datepicker/` to `docs/components/input/datepicker/`
- **Rename (rare):** `datepicker Input/input-date` → moves `docs/components/datepicker/` to `docs/components/input/input-date/`
- The first argument is always the existing flat component's kebab name.
- The second argument is the target. If it contains `/`, it is the full target path (parent + new leaf name). If not, it is just the parent name (leaf name preserved).
If args are missing, ask: "Which component should I migrate, and to which parent?"
## Step 1: Parse Arguments
- Split the second argument on `/`. If it has 1 segment, target = `<arg2>/<arg1>`. If 2+ segments, target = the literal arg2.
- Derive kebab/pascal forms for the parent and target leaf.
## Step 2: Validate
- **Source exists:** `docs/components/<flat>/index.md` must exist. Otherwise STOP with: "No flat component found at `docs/components/<flat>/`."
- **Source is a leaf:** `docs/components/<flat>/_category_.json` must NOT exist. Otherwise STOP with: "`<flat>` is already a parent."
- **Target doesn't exist:** the full target path `docs/components/<target-kebab-path>/` must NOT exist. Otherwise STOP with: "Target already exists."
- **Parent compatibility:** if the parent folder exists, it must contain `_category_.json` (not `index.md`). If it exists with `index.md`, STOP with: "`<parent>` is a leaf component, not a parent."
## Step 3: Move the Folder (preserves git history)
Run:
```bash
git mv docs/components/<flat> docs/components/<target-kebab-path>
```
(For non-rename case, `<target-kebab-path>` = `<parent-kebab>/<flat>`.)
## Step 4: Create or Update Parent `_category_.json`
If the parent folder did NOT exist before this run:
- Create `docs/components/<parent-kebab>/` (already created by `git mv` since the target was nested into it).
- Write `docs/components/<parent-kebab>/_category_.json`:
```json
{
"label": "<Parent-pascal>",
"position": 99,
"link": { "type": "doc", "id": "components/<target-kebab-path>" },
"collapsed": true
}
```
If the parent folder DID exist with `_category_.json`: do NOT modify it. The first child stays whatever it was.
## Step 5: Append Migration Redirect
Open `docs/.redirects.json` (it always exists; starts as `[]`). Append:
```json
{
"from": "/docs/components/<flat>",
"to": "/docs/components/<target-kebab-path>"
}
```
(JSON syntax must remain valid — comma-separate entries inside the array.)
## Step 6: Update Internal References
Run a grep across the repo for hardcoded references to the old path:
```bash
grep -rn "/docs/components/<flat>" docs/ src/ | grep -v ".redirects.json"
```
For each match, present the file:line and ask the user: "Replace `/docs/components/<flat>` → `/docs/components/<target-kebab-path>` here? (Y/n)". On Y, update the line.
Targets that commonly contain these references:
- Markdown links: `](/docs/components/<flat>)`
- `RelatedComponents` arrays: `link: "/docs/components/<flat>"`
## Step 7: Verify Build
Run: `npm run build`
Expected: build succeeds. The redirects plugin should now have the new entry, so `/docs/components/<flat>` redirects to the new path.
## Step 8: Report
Print a summary:
- Files moved (count + paths)
- Internal references updated (file:line list)
- Redirect added to `docs/.redirects.json`
- Whether a new parent `_category_.json` was created
- Reminder: review the diff and commit (the skill does not commit on the user's behalf for migrations)
- Step 2: Verify the new skill is well-formed
Run: cat .claude/commands/migrate-component-doc.md | wc -l
Expected: a substantial file (~80 lines or more).
- Step 3: Commit
git add .claude/commands/migrate-component-doc.md
git commit -m "feat(skills): add /migrate-component-doc for flat→nested migration"
Task 15: End-to-end smoke test — migrate one existing flat component
Files:
-
The migration command in Task 14 will move files automatically. No manual file edits.
-
Step 1: Pick a candidate
Identify one existing flat component that fits an existing or new family. Recommended: datepicker → Input/datepicker (or Input/input-date if rename desired).
- Step 2: Run the migration command in dry-run mode (manual walkthrough)
Walk through /migrate-component-doc datepicker Input step-by-step against the real repo. Don't commit yet — review the diff first.
After Step 3 (git mv), expected file changes:
docs/components/datepicker/→docs/components/input/datepicker/(move detected)docs/components/input/_category_.jsonalready exists from Task 10 (no change needed)
After Step 5, expected docs/.redirects.json:
[
{ "from": "/docs/components/datepicker", "to": "/docs/components/input/datepicker" }
]
- Step 3: Verify build and dev server
Run: npm run clear && npm run build && npm run serve
Visit:
-
/docs/components/input/datepicker/— page renders with full tabs -
/docs/components/datepicker— redirects to/docs/components/input/datepicker/ -
/docs/components/input/— redirects to whateverlink.idpoints to (the existing first child from Task 10,input-text) -
Step 4: Manual visual check
Open the dev server. Sidebar shows:
- Input (collapsed by default; auto-expanded when on a child)
- Input text
- Input number
- Datepicker (newly migrated)
Click each. Each loads correctly. The date-picker page maintains its content; only its URL changed.
- Step 5: Commit the migration
git add docs/components docs/.redirects.json
git commit -m "feat(docs): migrate datepicker into Input family (smoke test)"
Done
The 15 tasks deliver:
- Plugin recursion + manifest path-keying + redirect emission + validation warnings (Tasks 2–5)
- Layout/AutoDocTabs nested-aware (Tasks 6–7)
- Build config nested-aware (Task 8)
- Redirects plugin wired (Task 9)
- One nested family + one migrated component as live smoke tests (Tasks 10, 15)
- All four slash commands updated/created (Tasks 11–14)
After Task 15, designers can:
- Create a new flat component with
/generate-component-doc Avatar - Create a nested family with
/generate-component-doc Input/InputText(auto-creates parent on first child) - Add a content tab to either with
/add-content-tab Input/InputText - Migrate an existing flat component into a family with
/migrate-component-doc datepicker Input
The infrastructure (Tasks 1–10) is independently shippable; the slash command updates (Tasks 11–14) are independently shippable; smoke tests (10, 15) are the final integration.