Pattern Page Infrastructure 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: Extend the Naos Design System docs site to support pattern pages alongside component pages, including a full rename of component-specific infrastructure to generic names.
Architecture: Generalize the existing component-tabs-plugin → doc-tabs-plugin to scan both docs/components/ and docs/patterns/. Rename AutoComponentDocTabs → AutoDocTabs. Extend the DocItem Layout to recognize pattern_page: true. Add a DoDontCard component for usage examples. Create a dummy empty-states pattern to validate end-to-end.
Tech Stack: Docusaurus 3.9.2, React 19, TypeScript 5.6, CSS Modules
File Structure
| Action | File | Responsibility |
|---|---|---|
| Rename + rewrite | plugins/doc-tabs-plugin.js (from component-tabs-plugin.js) | Scan docs/components/ and docs/patterns/ for tab files, expose manifest via globalData |
| Rename + rewrite | src/components/AutoDocTabs/index.tsx (from AutoComponentDocTabs/) | Lazy-load tab MDX files for both component and pattern pages |
| Move | src/components/AutoDocTabs/styles.module.css (from AutoComponentDocTabs/) | Skeleton loading styles (unchanged content) |
| Edit | src/components/ComponentTabs/index.tsx | Add content tab to TAB_CONFIG |
| Edit | src/theme/DocItem/Layout/index.tsx | Support pattern_page frontmatter, use renamed imports |
| Edit | src/theme/MDXComponents.tsx | Register DoDontCard |
| Edit | docusaurus.config.ts | Update plugin path, add pattern tab file exclusions |
| Edit | sidebars.ts | Autogenerated sidebar for patterns |
| Create | src/components/DoDontCard/index.tsx | Do/Don't comparison card |
| Create | src/components/DoDontCard/styles.module.css | Card styles |
| Create | .claude/commands/generate-pattern-doc.md | Slash command for pattern doc generation |
| Edit | .claude/figma-naming-config.md | Add pattern-specific sections |
| Create | docs/patterns/empty-states/index.md | Dummy pattern entry point |
| Create | docs/patterns/empty-states/overview.md | Dummy overview tab |
| Create | docs/patterns/empty-states/design.md | Dummy design tab with DoDontCard usage |
| Create | docs/patterns/empty-states/accessibility.md | Dummy accessibility tab |
| Create | docs/patterns/empty-states/code.md | Dummy code tab |
| Create | docs/patterns/empty-states/content.md | Dummy content tab |
| Create | docs/patterns/empty-states/status.md | Dummy status tab |
| Edit | AGENTS.md | Update all renamed references and add new capabilities |
Task 1: Rename and generalize the plugin
Files:
-
Delete:
plugins/component-tabs-plugin.js -
Create:
plugins/doc-tabs-plugin.js -
Modify:
docusaurus.config.ts:41-63 -
Step 1: Create the new plugin file
Create plugins/doc-tabs-plugin.js with the following content:
// Docusaurus plugin: scans docs/components/*/ and docs/patterns/*/ for tab
// files and exposes a manifest via globalData.
// Consumers: usePluginData('doc-tabs-plugin')
const fs = require('fs');
const path = require('path');
// Must match TAB_CONFIG in src/components/ComponentTabs/index.tsx
const TAB_NAMES = ['overview', 'design', 'code', 'accessibility', 'content', 'status'];
// Directories to scan for folder-per-tab doc pages
const DOC_DIRS = [
{dir: 'components', type: 'component'},
{dir: 'patterns', type: 'pattern'},
];
function scanDocTabs(docsDir) {
const manifest = {};
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;
const entryDir = path.join(fullDir, entry.name);
const indexFile = path.join(entryDir, 'index.md');
if (!fs.existsSync(indexFile)) continue;
const tabs = TAB_NAMES.filter((tab) =>
fs.existsSync(path.join(entryDir, `${tab}.md`)),
);
// Entries with zero tab files are excluded — AutoDocTabs
// returns null for them, so they don't need a manifest entry.
if (tabs.length > 0) {
manifest[entry.name] = {
tabs,
path: `docs/${dir}/${entry.name}`,
type,
};
}
}
}
return manifest;
}
module.exports = function docTabsPlugin(context) {
const docsDir = path.join(context.siteDir, 'docs');
return {
name: 'doc-tabs-plugin',
async contentLoaded({actions}) {
const {setGlobalData} = actions;
const manifest = scanDocTabs(docsDir);
setGlobalData({manifest});
},
getPathsToWatch() {
return DOC_DIRS.map(({dir}) =>
path.join(docsDir, dir, '*/*.md'),
);
},
};
};
- Step 2: Delete the old plugin file
rm plugins/component-tabs-plugin.js
- Step 3: Update docusaurus.config.ts
In docusaurus.config.ts, make two changes:
- Update the plugin path (line 62):
plugins: [
require.resolve('./plugins/doc-tabs-plugin'),
],
- Add pattern tab file exclusions to the
docs.excludearray (lines 45-51):
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',
],
- Step 4: Verify the build compiles
Run: npm run build 2>&1 | tail -20
Expected: Build succeeds (may have broken link warnings — that's OK). No plugin errors.
- Step 5: Commit
git add plugins/doc-tabs-plugin.js docusaurus.config.ts
git rm plugins/component-tabs-plugin.js
git commit -m "refactor: rename component-tabs-plugin to doc-tabs-plugin
Generalize the plugin to scan both docs/components/ and docs/patterns/.
Add 'content' to TAB_NAMES. Manifest entries now include a 'type' field."
Task 2: Add content tab to ComponentTabs
Files:
-
Modify:
src/components/ComponentTabs/index.tsx:12-18 -
Step 1: Add content to TAB_CONFIG
In src/components/ComponentTabs/index.tsx, replace the TAB_CONFIG array:
const TAB_CONFIG = [
{ value: 'overview', label: 'Overview' },
{ value: 'design', label: 'Design' },
{ value: 'code', label: 'Code' },
{ value: 'accessibility', label: 'Accessibility' },
{ value: 'content', label: 'Content' },
{ value: 'status', label: 'Status' },
] as const;
- Step 2: Verify typecheck passes
Run: npx tsc --noEmit 2>&1 | tail -10
Expected: No new errors.
- Step 3: Commit
git add src/components/ComponentTabs/index.tsx
git commit -m "feat: add content tab to ComponentTabs TAB_CONFIG"
Task 3: Rename AutoComponentDocTabs to AutoDocTabs
Files:
-
Delete:
src/components/AutoComponentDocTabs/index.tsx -
Delete:
src/components/AutoComponentDocTabs/styles.module.css -
Create:
src/components/AutoDocTabs/index.tsx -
Create:
src/components/AutoDocTabs/styles.module.css -
Step 1: Create the new directory and copy styles
mkdir -p src/components/AutoDocTabs
cp src/components/AutoComponentDocTabs/styles.module.css src/components/AutoDocTabs/styles.module.css
- Step 2: Create the renamed and updated component
Create src/components/AutoDocTabs/index.tsx:
import React, {
type ReactNode,
useState,
useRef,
useEffect,
useCallback,
Suspense,
} from 'react';
import {usePluginData} from '@docusaurus/useGlobalData';
import MDXContent from '@theme/MDXContent';
import {useActiveTab} from '@site/src/components/ComponentTabs/ActiveTabContext';
import tabStyles from '@site/src/components/ComponentTabs/styles.module.css';
import styles from './styles.module.css';
const TAB_CONFIG = [
{value: 'overview', label: 'Overview'},
{value: 'design', label: 'Design'},
{value: 'code', label: 'Code'},
{value: 'accessibility', label: 'Accessibility'},
{value: 'content', label: 'Content'},
{value: 'status', label: 'Status'},
] as const;
interface DocTabsManifest {
manifest: Record<string, {tabs: string[]; path: string; type: string}>;
}
// Webpack requires partial literal paths for dynamic imports.
// We need separate factories for each directory because the path prefix must be a literal.
function createComponentLazyTab(slug: string, tab: string): React.LazyExoticComponent<React.ComponentType> {
return React.lazy(
() => import(
/* webpackInclude: /docs\/components\/[^/]+\/(overview|design|code|accessibility|content|status)\.md$/ */
`@site/docs/components/${slug}/${tab}.md`
),
);
}
function createPatternLazyTab(slug: string, tab: string): React.LazyExoticComponent<React.ComponentType> {
return React.lazy(
() => import(
/* webpackInclude: /docs\/patterns\/[^/]+\/(overview|design|code|accessibility|content|status)\.md$/ */
`@site/docs/patterns/${slug}/${tab}.md`
),
);
}
function TabSkeleton(): ReactNode {
return (
<div className={styles.skeleton}>
<div className={styles.skeletonLine} />
<div className={styles.skeletonLine} />
<div className={styles.skeletonLine} />
</div>
);
}
interface AutoDocTabsProps {
slug: string;
}
export default function AutoDocTabs({slug}: AutoDocTabsProps): ReactNode {
const {manifest} = usePluginData('doc-tabs-plugin') as DocTabsManifest;
const docData = manifest[slug];
if (!docData || docData.tabs.length === 0) {
return null;
}
const createLazyTab = docData.type === 'pattern' ? createPatternLazyTab : createComponentLazyTab;
const availableTabs = TAB_CONFIG.filter((t) =>
docData.tabs.includes(t.value),
);
const {setActiveTab: setContextTab} = useActiveTab();
const [activeTab, setActiveTabLocal] = useState<string>(availableTabs[0]?.value ?? 'overview');
const setActiveTab = useCallback(
(tab: string) => {
setActiveTabLocal(tab);
setContextTab(tab);
},
[setContextTab],
);
// Reset active tab when slug changes (client-side navigation between pages)
useEffect(() => {
const firstTab = availableTabs[0]?.value ?? 'overview';
setActiveTabLocal(firstTab);
setContextTab(firstTab);
}, [slug]); // eslint-disable-line react-hooks/exhaustive-deps
const [indicatorStyle, setIndicatorStyle] = useState<React.CSSProperties>({});
const tabsRef = useRef<HTMLDivElement>(null);
const tabRefs = useRef<Map<string, HTMLButtonElement>>(new Map());
// Cache of lazy components so we don't recreate on every render
const lazyTabsRef = useRef<Map<string, React.LazyExoticComponent<React.ComponentType>>>(new Map());
function getLazyTab(tab: string): React.LazyExoticComponent<React.ComponentType> {
let cached = lazyTabsRef.current.get(tab);
if (!cached) {
cached = createLazyTab(slug, tab);
lazyTabsRef.current.set(tab, cached);
}
return cached;
}
const updateIndicator = useCallback(() => {
const el = tabRefs.current.get(activeTab);
const container = tabsRef.current;
if (el && container) {
const containerRect = container.getBoundingClientRect();
const elRect = el.getBoundingClientRect();
setIndicatorStyle({
width: elRect.width,
transform: `translateX(${elRect.left - containerRect.left}px)`,
});
}
}, [activeTab]);
useEffect(() => {
updateIndicator();
}, [updateIndicator]);
useEffect(() => {
window.addEventListener('resize', updateIndicator);
return () => window.removeEventListener('resize', updateIndicator);
}, [updateIndicator]);
const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
let nextIndex: number | null = null;
if (e.key === 'ArrowRight') {
nextIndex = (index + 1) % availableTabs.length;
} else if (e.key === 'ArrowLeft') {
nextIndex = (index - 1 + availableTabs.length) % availableTabs.length;
} else if (e.key === 'Home') {
nextIndex = 0;
} else if (e.key === 'End') {
nextIndex = availableTabs.length - 1;
}
if (nextIndex !== null) {
e.preventDefault();
const nextTab = availableTabs[nextIndex];
setActiveTab(nextTab.value);
tabRefs.current.get(nextTab.value)?.focus();
}
};
const tabId = (value: string) => `tab-${value}`;
const panelId = (value: string) => `tabpanel-${value}`;
const LazyContent = getLazyTab(activeTab);
return (
<div className={tabStyles.componentTabs}>
<div
className={tabStyles.tabsBar}
ref={tabsRef}
role="tablist"
aria-label="Documentation tabs"
>
{availableTabs.map((tab, index) => (
<button
key={tab.value}
id={tabId(tab.value)}
ref={(el) => {
if (el) tabRefs.current.set(tab.value, el);
}}
role="tab"
aria-selected={activeTab === tab.value}
aria-controls={panelId(tab.value)}
tabIndex={activeTab === tab.value ? 0 : -1}
className={`${tabStyles.tabButton} ${activeTab === tab.value ? tabStyles.tabButtonActive : ''}`}
onClick={() => setActiveTab(tab.value)}
onKeyDown={(e) => handleKeyDown(e, index)}
>
{tab.label}
</button>
))}
<div className={tabStyles.indicator} style={indicatorStyle} />
</div>
<div
role="tabpanel"
id={panelId(activeTab)}
aria-labelledby={tabId(activeTab)}
>
<Suspense fallback={<TabSkeleton />}>
<MDXContent>
<LazyContent />
</MDXContent>
</Suspense>
</div>
</div>
);
}
- Step 3: Delete the old directory
rm -rf src/components/AutoComponentDocTabs
- Step 4: Commit
git add src/components/AutoDocTabs/
git rm -r src/components/AutoComponentDocTabs/
git commit -m "refactor: rename AutoComponentDocTabs to AutoDocTabs
Support dual import paths for components and patterns.
Add content tab to TAB_CONFIG. Read type from manifest
to select the correct webpack import factory."
Task 4: Update DocItem Layout
Files:
-
Modify:
src/theme/DocItem/Layout/index.tsx -
Step 1: Update imports and frontmatter type
In src/theme/DocItem/Layout/index.tsx, make these changes:
- Replace the import on line 18:
import AutoDocTabs from '@site/src/components/AutoDocTabs';
- Add
pattern_pageto theCustomFrontMattertype (lines 22-26):
type CustomFrontMatter = {
component_page?: boolean;
pattern_page?: boolean;
preview_image?: string;
[key: string]: unknown;
};
- Update the detection line (line 48):
const isComponentPage = frontMatter.component_page === true || frontMatter.pattern_page === true;
- Update the plugin data call (line 53):
const pluginData = usePluginData('doc-tabs-plugin') as {manifest: Record<string, {tabs: string[]}>} | undefined;
- Update the JSX that renders the tabs (line 98):
{() => <AutoDocTabs slug={slug} />}
- Step 2: Verify typecheck passes
Run: npx tsc --noEmit 2>&1 | tail -10
Expected: No new errors.
- Step 3: Commit
git add src/theme/DocItem/Layout/index.tsx
git commit -m "feat: extend DocItem Layout for pattern pages
Add pattern_page frontmatter support. Update imports to use
renamed AutoDocTabs and doc-tabs-plugin."
Task 5: Create DoDontCard component
Files:
-
Create:
src/components/DoDontCard/index.tsx -
Create:
src/components/DoDontCard/styles.module.css -
Modify:
src/theme/MDXComponents.tsx -
Step 1: Create the component
Create src/components/DoDontCard/index.tsx:
import React, {type ReactNode, type ReactElement} from 'react';
import styles from './styles.module.css';
interface DoDontCardProps {
type: 'do' | 'dont';
children: ReactNode;
}
export default function DoDontCard({type, children}: DoDontCardProps): ReactElement {
const label = type === 'do' ? 'Do' : "Don't";
return (
<div className={`${styles.card} ${styles[type]}`}>
<span className={styles.label}>{label}</span>
<div className={styles.content}>{children}</div>
</div>
);
}
- Step 2: Create the styles
Create src/components/DoDontCard/styles.module.css:
.card {
border-radius: 8px;
border-top: 3px solid;
background: var(--ifm-card-background-color);
padding: 16px;
display: flex;
flex-direction: column;
gap: 12px;
}
.do {
border-top-color: var(--ifm-color-success);
}
.dont {
border-top-color: var(--ifm-color-danger);
}
.label {
font-size: 13px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.do .label {
color: var(--ifm-color-success);
}
.dont .label {
color: var(--ifm-color-danger);
}
.content {
font-size: 14px;
line-height: 1.6;
color: var(--ifm-color-content-secondary);
}
.content p {
margin: 0;
}
.content p:not(:last-child) {
margin-bottom: 8px;
}
- Step 3: Register in MDXComponents
In src/theme/MDXComponents.tsx, add the import and registration:
Add after line 15 (import FigmaGridItem ...):
import DoDontCard from '@site/src/components/DoDontCard';
Add DoDontCard, after FigmaGridItem, in the export (after line 31):
FigmaGridItem,
DoDontCard,
- Step 4: Verify typecheck passes
Run: npx tsc --noEmit 2>&1 | tail -10
Expected: No new errors.
- Step 5: Commit
git add src/components/DoDontCard/ src/theme/MDXComponents.tsx
git commit -m "feat: add DoDontCard component for usage do/dont pairs
Register in MDXComponents for global MDX availability."
Task 6: Update sidebars and docusaurus config exclusions
Files:
-
Modify:
sidebars.ts:38-45 -
Step 1: Update the Patterns sidebar category
In sidebars.ts, replace lines 38-45:
{
type: 'category',
label: 'Patterns',
collapsed: true,
link: { type: 'doc', id: 'patterns/overview' },
items: [{ type: 'autogenerated', dirName: 'patterns' }],
},
- Step 2: Commit
git add sidebars.ts
git commit -m "feat: use autogenerated sidebar for patterns section"
Task 7: Create dummy empty-states pattern
Files:
-
Create:
docs/patterns/empty-states/index.md -
Create:
docs/patterns/empty-states/overview.md -
Create:
docs/patterns/empty-states/design.md -
Create:
docs/patterns/empty-states/accessibility.md -
Create:
docs/patterns/empty-states/code.md -
Create:
docs/patterns/empty-states/content.md -
Create:
docs/patterns/empty-states/status.md -
Step 1: Create the pattern directory
mkdir -p docs/patterns/empty-states
- Step 2: Create index.md
Create docs/patterns/empty-states/index.md:
---
sidebar_position: 1
title: Empty States
description: Guide users when there is no content to display by providing clear messaging and actionable next steps.
pattern_page: true
---
# Empty States
Guide users when there is no content to display by providing clear messaging and actionable next steps.
- Step 3: Create overview.md
Create docs/patterns/empty-states/overview.md:
## Description
Empty states appear when a screen, container, or section has no data to display. They communicate the absence of content and guide users toward productive next steps.
## When to use
- A list, table, or feed has no items yet
- Search or filter results return zero matches
- A feature requires setup before it can show content
- Data has been deleted or archived
## When not to use
- When content is loading (use a loading state instead)
- When an error prevented data from loading (use an error state instead)
## Related patterns
- [Error States](../error-states) — when data fails to load
- [Loading States](../loading-states) — when data is in transit
- Step 4: Create design.md
Create docs/patterns/empty-states/design.md:
## Anatomy
An empty state consists of an illustration or icon, a headline, a body message, and an optional call-to-action button.
## Elements
| Element | Required | Description |
|---|---|---|
| Illustration / Icon | Optional | Visual that reinforces the message |
| Headline | Required | Short, clear title explaining the state |
| Body text | Required | Brief explanation with guidance |
| Action button | Optional | Primary action to resolve the empty state |
## Layout
The empty state content is centered both vertically and horizontally within its container. Maximum content width is 400px to maintain readability.
## Spacing
- 16px between illustration and headline
- 8px between headline and body text
- 24px between body text and action button
## Behavior
- Empty states update immediately when content becomes available
- Action buttons navigate to the relevant creation flow
- If the container is resized, the empty state remains centered
## Guidelines
- Keep the headline under 5 words
- Body text should be 1-2 sentences maximum
- Always provide at least one actionable next step
- Use illustrations sparingly — simple icons work for small containers
## Usage
<FigmaGrid columns={2}>
<DoDontCard type="do">
Provide a clear headline and an action button so users know what to do next.
</DoDontCard>
<DoDontCard type="dont">
Don't show a completely blank screen with no explanation or guidance.
</DoDontCard>
</FigmaGrid>
- Step 5: Create accessibility.md
Create docs/patterns/empty-states/accessibility.md:
## Keyboard navigation
- The action button (if present) must be focusable via Tab
- Focus order: headline → body → action button
## ARIA requirements
- The empty state container should use `role="status"` to announce content changes to screen readers
- Action buttons must have descriptive labels (avoid generic "Click here")
- Step 6: Create code.md
Create docs/patterns/empty-states/code.md:
## Components used
- `Illustration` or `Icon` — visual element
- `Text` — headline and body
- `Button` — call-to-action
## Implementation notes
- Render the empty state conditionally when the data array is empty
- Avoid flash of empty state while data is loading — check loading state first
## Technical constraints
- The empty state component should accept custom illustrations and actions as props
- Must work within any container size (responsive)
- Step 7: Create content.md
Create docs/patterns/empty-states/content.md:
## Tone
Use a helpful, encouraging tone. Avoid blaming the user or using negative language.
## Headline guidelines
- State what's missing, not what went wrong
- Example: "No campaigns yet" (not "You haven't created anything")
## Body text guidelines
- Explain what the user can do next
- Keep it to 1-2 sentences
- Example: "Create your first email campaign to start reaching your audience."
## Action button labels
- Use specific verbs: "Create campaign", "Import contacts", "Add product"
- Avoid vague labels: "Get started", "Click here", "Learn more"
- Step 8: Create status.md
Create docs/patterns/empty-states/status.md:
## Status
Draft — initial documentation.
## Changelog
| Date | Change |
|---|---|
| 2026-04-05 | Initial draft |
- Step 9: Verify build succeeds
Run: npm run build 2>&1 | tail -20
Expected: Build succeeds. The empty-states pattern page should be generated. Broken link warnings for error-states and loading-states are expected (those pages don't exist yet).
- Step 10: Commit
git add docs/patterns/empty-states/
git commit -m "feat: add empty-states dummy pattern page
Validates end-to-end: plugin scanning, tab rendering,
DoDontCard usage, content tab, pattern_page layout."
Task 8: Save the generate-pattern-doc command
Files:
-
Create:
.claude/commands/generate-pattern-doc.md -
Step 1: Copy the command file
cp /Users/harshitpurwar/Downloads/generate-pattern-doc.md .claude/commands/generate-pattern-doc.md
- Step 2: Commit
git add .claude/commands/generate-pattern-doc.md
git commit -m "feat: add /generate-pattern-doc slash command"
Task 9: Update figma-naming-config.md
Files:
-
Modify:
.claude/figma-naming-config.md -
Step 1: Add pattern-specific sections
Append the following after the "Validation Rules" section at the end of .claude/figma-naming-config.md:
## Pattern-Specific Sections
Patterns use the same `DOC_` prefix and parsing rules as components, with these additional reserved section values:
| Section | Tab | Markdown Heading |
|---|---|---|
| Elements | design | `## Elements` |
| Layout | design | `## Layout` |
| Guidelines | design | `## Guidelines` |
| Usage_Do | design | `DoDontCard type="do"` inside `## Usage` |
| Usage_Dont | design | `DoDontCard type="dont"` inside `## Usage` |
### Pattern Grid & Height Defaults
| Section | Default Columns | Default Embed Height |
|---|---|---|
| Anatomy | 1 | 400px |
| Elements | 1 | 350px |
| Layout | 1 | 400px |
| Spacing | 2 | 300px |
| Responsive | 1 | 500px |
| Behavior | 2 | 300px |
| Guidelines | 1 | 350px |
| Usage | 2 | 250px |
### Usage Do/Don't Rendering
Usage frames in patterns render as `DoDontCard` pairs instead of plain `FigmaGridItem`:
```md
<FigmaGrid columns={2}>
<DoDontCard type="do">
<FigmaEmbed url="..." title="..." height="250px" />
Caption text from DOC_TEXT frame.
</DoDontCard>
<DoDontCard type="dont">
<FigmaEmbed url="..." title="..." height="250px" />
Caption text from DOC_TEXT frame.
</DoDontCard>
</FigmaGrid>
- [ ] **Step 2: Commit**
```bash
git add .claude/figma-naming-config.md
git commit -m "docs: add pattern-specific sections to figma-naming-config"
Task 10: Update AGENTS.md
Files:
-
Modify:
AGENTS.md -
Step 1: Update all renamed references
In AGENTS.md, make these changes:
- Project Structure (lines 42-61): Add
AutoDocTabsandDoDontCardto the components list. Remove any reference toAutoComponentDocTabs. Thesrc/components/section should include:
│ ├── AutoDocTabs/ # Auto-assembled tabs from folder-per-tab structure
│ ├── DoDontCard/ # Do/Don't comparison card for usage examples
-
Section title (line 70): Rename from "Component Page Layout (Required for all component docs)" to "Component & Pattern Page Layout (Required for all component and pattern docs)"
-
Layout description (line 72): Update to mention both flags:
This layout is activated when the page's frontmatter includes `component_page: true` or `pattern_page: true`.
- Tab values (line 182): Already has
content— verify it reads:
`overview` | `design` | `code` | `accessibility` | `content` | `status`
- Available MDX Components table (lines 193-205): Add row:
| `DoDontCard` | Do/Don't comparison card for usage examples (`type` prop: `"do"` or `"dont"`) |
-
Plugin references: Replace all occurrences of
component-tabs-pluginwithdoc-tabs-pluginandAutoComponentDocTabswithAutoDocTabs. -
Add a pattern folder structure example after the component folder structure, showing:
docs/patterns/<kebab>/
├── index.md (frontmatter with pattern_page: true)
├── overview.md
├── design.md
├── accessibility.md
├── code.md
├── content.md (optional — for content guidelines)
└── status.md
- Step 2: Commit
git add AGENTS.md
git commit -m "docs: update AGENTS.md with pattern page infrastructure
Rename component-tabs-plugin → doc-tabs-plugin, AutoComponentDocTabs → AutoDocTabs.
Add DoDontCard, pattern_page flag, pattern folder structure."
Task 11: End-to-end verification
Files: None (verification only)
- Step 1: Run full build
Run: npm run build 2>&1 | tail -30
Expected: Build succeeds. No plugin errors. Broken link warnings for error-states and loading-states are expected.
- Step 2: Run typecheck
Run: npx tsc --noEmit 2>&1 | tail -10
Expected: No errors.
- Step 3: Start dev server and verify visually
Run: npm start
Then verify:
- Navigate to
/docs/components/avatar— existing component page still works, tabs load - Navigate to
/docs/patterns/empty-states— pattern page renders with custom header, tabs load (overview, design, code, accessibility, content, status) - On the design tab, the
DoDontCardrenders with green "Do" and red "Don't" labels - Sidebar shows "Patterns" category with "Empty States" listed
- Step 4: Verify Avatar page is not broken
Navigate to /docs/components/avatar and confirm:
- Page header renders with title and description
- Tabs load and switch correctly
- No console errors