Pattern Page Infrastructure Design
Overview
Extend the Naos Design System documentation site to support pattern pages alongside existing component pages. Patterns (e.g., empty states, form validation, dashboard layouts) use a folder-per-tab structure with the same visual treatment as components but with pattern-specific content sections.
This is also a rename/generalization pass — the project is early-stage (one component page exists: Avatar), so we rename component-specific infrastructure to generic names now while the cost is minimal.
Goals
- Pattern pages render with the same layout as component pages (full-width header, custom TOC, hidden breadcrumbs)
- The tab system supports both
docs/components/anddocs/patterns/directories - A new
contenttab is available for content guidelines - A
DoDontCardcomponent supports Usage do/don't pairs in pattern design tabs - A dummy pattern (
empty-states) validates the full pipeline end-to-end - The
/generate-pattern-docslash command is available for generating pattern docs from Figma
Non-Goals
- No visual differentiation between pattern and component page layouts (same treatment for now)
- No new Figma automation — the command file is saved as-is; Figma integration is tested separately
- No migration of existing pattern overview links (they already point to files that don't exist yet)
Section 1: Plugin Rename & Generalization
Current State
plugins/component-tabs-plugin.jsscans onlydocs/components/TAB_NAMES = ['overview', 'design', 'code', 'accessibility', 'status']- Plugin name:
'component-tabs-plugin' - Referenced in
docusaurus.config.tsline 62
Changes
Rename plugins/component-tabs-plugin.js → plugins/doc-tabs-plugin.js
Plugin becomes config-driven:
- Scan directories:
docs/components/anddocs/patterns/ TAB_NAMES = ['overview', 'design', 'code', 'accessibility', 'content', 'status']- Plugin name:
'doc-tabs-plugin' - Manifest entries include a
typefield so the tab component knows the import path
Manifest shape:
{
"avatar": { tabs: ["overview", "design"], path: "docs/components/avatar", type: "component" },
"empty-states": { tabs: ["overview", "design", "content"], path: "docs/patterns/empty-states", type: "pattern" }
}
Slug uniqueness constraint: Manifest entries are keyed by slug/name, so slugs must be globally unique across docs/components/ and docs/patterns/. A component and pattern must not share the same slug (for example, both using tabs), because the later entry would overwrite the earlier one in the generated manifest. In practice, collisions are unlikely since components and patterns have different naming domains.
getPathsToWatch() returns globs for both directories.
Update docusaurus.config.ts: Change plugin path from './plugins/component-tabs-plugin' to './plugins/doc-tabs-plugin'.
Section 2: Tab Component Rename & Dual-Path Imports
Current State
src/components/AutoComponentDocTabs/withindex.tsxandstyles.module.cssTAB_CONFIGhas 5 tabs (nocontent)createLazyTabhardcodes@site/docs/components/${slug}/${tab}.mdwith a single webpack include regexsrc/components/ComponentTabs/index.tsxhas matching 5-tabTAB_CONFIG
Changes
Rename src/components/AutoComponentDocTabs/ → src/components/AutoDocTabs/
Rename function AutoComponentDocTabs → AutoDocTabs
Add content tab to TAB_CONFIG in both:
src/components/AutoDocTabs/index.tsxsrc/components/ComponentTabs/index.tsx
Insert {value: 'content', label: 'Content'} between accessibility and status.
Dual webpack import factories (webpack requires partial literal paths):
function createComponentLazyTab(slug: string, tab: string) {
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) {
return React.lazy(() => import(
/* webpackInclude: /docs\/patterns\/[^/]+\/(overview|design|code|accessibility|content|status)\.md$/ */
`@site/docs/patterns/${slug}/${tab}.md`
));
}
The component reads type from the manifest and calls the corresponding factory.
Update src/theme/DocItem/Layout/index.tsx:
- Import renamed:
AutoDocTabsfrom@site/src/components/AutoDocTabs - Plugin data:
usePluginData('doc-tabs-plugin')
Section 3: Layout Extension
Current State
src/theme/DocItem/Layout/index.tsxrecognizes onlycomponent_page?: booleanandpreview_image?: stringin frontmatterisComponentPagedrives: custom header, hidden breadcrumbs, custom TOC
Changes
Add pattern_page?: boolean to the CustomFrontMatter type.
Change detection:
const isComponentPage = frontMatter.component_page === true || frontMatter.pattern_page === true;
No other layout changes. The variable name isComponentPage stays as-is internally — it means "uses custom page layout" and renaming it would touch many lines for no functional benefit.
Section 4: DoDontCard Component
New Files
src/components/DoDontCard/index.tsx
Props:
type: 'do' | 'dont'— determines label text and color accentchildren: ReactNode— contains<FigmaEmbed>and caption text
Rendering:
- Card container with a colored top border (green for
do, red fordont) - Label badge: "Do" (green) or "Don't" (red)
- Children rendered below the label
src/components/DoDontCard/styles.module.css
CSS module with:
.card— base card styling with border-radius, padding.do— green top border, green label color.dont— red top border, red label color.label— badge styling for the Do/Don't text
Register in src/theme/MDXComponents.tsx:
Add DoDontCard import and registration so it's available globally in MDX without imports.
Usage in MDX
<FigmaGrid columns={2}>
<DoDontCard type="do">
<FigmaEmbed url="..." title="..." height="250px" />
Provide a clear call-to-action.
</DoDontCard>
<DoDontCard type="dont">
<FigmaEmbed url="..." title="..." height="250px" />
Don't leave the screen blank.
</DoDontCard>
</FigmaGrid>
Section 5: Sidebar, Command File & Naming Config
sidebars.ts
Change the Patterns category from manual items to autogenerated:
{
type: 'category',
label: 'Patterns',
collapsed: true,
link: { type: 'doc', id: 'patterns/overview' },
items: [{ type: 'autogenerated', dirName: 'patterns' }],
},
.claude/commands/generate-pattern-doc.md
Save the provided file from /Users/harshitpurwar/Downloads/generate-pattern-doc.md to .claude/commands/generate-pattern-doc.md. No modifications needed.
.claude/figma-naming-config.md
Add a "Pattern-Specific Sections" section documenting:
| 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 |
Add DoDontCard to the constructing embeds section as a rendering option for Usage frames.
Section 6: Dummy Pattern Page (empty-states)
Validates the full pipeline end-to-end.
Files
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.
<ComponentDocTabs>
<TabContent tab="overview">
</TabContent>
<TabContent tab="design">
</TabContent>
<TabContent tab="content">
</TabContent>
<TabContent tab="accessibility">
</TabContent>
<TabContent tab="code">
</TabContent>
<TabContent tab="status">
</TabContent>
</ComponentDocTabs>
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
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>
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")
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)
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"
docs/patterns/empty-states/status.md
## Status
Draft — initial documentation.
## Changelog
| Date | Change |
|---|---|
| 2026-04-05 | Initial draft |
Section 7: AGENTS.md Updates
Update the following references in AGENTS.md:
component-tabs-plugin→doc-tabs-plugin(all occurrences)AutoComponentDocTabs→AutoDocTabs(all occurrences)- Add
DoDontCardto the "Available MDX Components" table:DoDontCard | Do/Don't comparison card for usage examples (type prop: "do" or "dont") - Add
contentto available tab values:overview | design | code | accessibility | content | status - Add
pattern_page: trueas a frontmatter flag in the "Component Page Layout" section (rename section to "Component & Pattern Page Layout") - Add pattern folder structure example alongside the component structure
- Document that the plugin scans both
docs/components/anddocs/patterns/
Files Changed Summary
| Action | File |
|---|---|
| Rename | plugins/component-tabs-plugin.js → plugins/doc-tabs-plugin.js |
| Rename | src/components/AutoComponentDocTabs/ → src/components/AutoDocTabs/ |
| Edit | docusaurus.config.ts (plugin path) |
| Edit | src/theme/DocItem/Layout/index.tsx (imports, frontmatter, plugin name) |
| Edit | src/components/ComponentTabs/index.tsx (add content tab) |
| Edit | src/theme/MDXComponents.tsx (register DoDontCard) |
| Edit | sidebars.ts (autogenerated patterns) |
| Edit | .claude/figma-naming-config.md (pattern sections) |
| Edit | AGENTS.md (renames and new capabilities) |
| Create | src/components/DoDontCard/index.tsx |
| Create | src/components/DoDontCard/styles.module.css |
| Create | .claude/commands/generate-pattern-doc.md |
| 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 |