Skip to main content

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​

ActionFileResponsibility
Rename + rewriteplugins/doc-tabs-plugin.js (from component-tabs-plugin.js)Scan docs/components/ and docs/patterns/ for tab files, expose manifest via globalData
Rename + rewritesrc/components/AutoDocTabs/index.tsx (from AutoComponentDocTabs/)Lazy-load tab MDX files for both component and pattern pages
Movesrc/components/AutoDocTabs/styles.module.css (from AutoComponentDocTabs/)Skeleton loading styles (unchanged content)
Editsrc/components/ComponentTabs/index.tsxAdd content tab to TAB_CONFIG
Editsrc/theme/DocItem/Layout/index.tsxSupport pattern_page frontmatter, use renamed imports
Editsrc/theme/MDXComponents.tsxRegister DoDontCard
Editdocusaurus.config.tsUpdate plugin path, add pattern tab file exclusions
Editsidebars.tsAutogenerated sidebar for patterns
Createsrc/components/DoDontCard/index.tsxDo/Don't comparison card
Createsrc/components/DoDontCard/styles.module.cssCard styles
Create.claude/commands/generate-pattern-doc.mdSlash command for pattern doc generation
Edit.claude/figma-naming-config.mdAdd pattern-specific sections
Createdocs/patterns/empty-states/index.mdDummy pattern entry point
Createdocs/patterns/empty-states/overview.mdDummy overview tab
Createdocs/patterns/empty-states/design.mdDummy design tab with DoDontCard usage
Createdocs/patterns/empty-states/accessibility.mdDummy accessibility tab
Createdocs/patterns/empty-states/code.mdDummy code tab
Createdocs/patterns/empty-states/content.mdDummy content tab
Createdocs/patterns/empty-states/status.mdDummy status tab
EditAGENTS.mdUpdate 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:

  1. Update the plugin path (line 62):
plugins: [
require.resolve('./plugins/doc-tabs-plugin'),
],
  1. Add pattern tab file exclusions to the docs.exclude array (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:

  1. Replace the import on line 18:
import AutoDocTabs from '@site/src/components/AutoDocTabs';
  1. Add pattern_page to the CustomFrontMatter type (lines 22-26):
type CustomFrontMatter = {
component_page?: boolean;
pattern_page?: boolean;
preview_image?: string;
[key: string]: unknown;
};
  1. Update the detection line (line 48):
const isComponentPage = frontMatter.component_page === true || frontMatter.pattern_page === true;
  1. Update the plugin data call (line 53):
const pluginData = usePluginData('doc-tabs-plugin') as {manifest: Record<string, {tabs: string[]}>} | undefined;
  1. 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:

  1. Project Structure (lines 42-61): Add AutoDocTabs and DoDontCard to the components list. Remove any reference to AutoComponentDocTabs. The src/components/ section should include:
│ ├── AutoDocTabs/ # Auto-assembled tabs from folder-per-tab structure
│ ├── DoDontCard/ # Do/Don't comparison card for usage examples
  1. 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)"

  2. 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`.
  1. Tab values (line 182): Already has content — verify it reads:
`overview` | `design` | `code` | `accessibility` | `content` | `status`
  1. Available MDX Components table (lines 193-205): Add row:
| `DoDontCard` | Do/Don't comparison card for usage examples (`type` prop: `"do"` or `"dont"`) |
  1. Plugin references: Replace all occurrences of component-tabs-plugin with doc-tabs-plugin and AutoComponentDocTabs with AutoDocTabs.

  2. 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:

  1. Navigate to /docs/components/avatar — existing component page still works, tabs load
  2. Navigate to /docs/patterns/empty-states — pattern page renders with custom header, tabs load (overview, design, code, accessibility, content, status)
  3. On the design tab, the DoDontCard renders with green "Do" and red "Don't" labels
  4. 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