Skip to main content

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/ and docs/patterns/ directories
  • A new content tab is available for content guidelines
  • A DoDontCard component 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-doc slash 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.js scans only docs/components/
  • TAB_NAMES = ['overview', 'design', 'code', 'accessibility', 'status']
  • Plugin name: 'component-tabs-plugin'
  • Referenced in docusaurus.config.ts line 62

Changes​

Rename plugins/component-tabs-plugin.js → plugins/doc-tabs-plugin.js

Plugin becomes config-driven:

  • Scan directories: docs/components/ and docs/patterns/
  • TAB_NAMES = ['overview', 'design', 'code', 'accessibility', 'content', 'status']
  • Plugin name: 'doc-tabs-plugin'
  • Manifest entries include a type field 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/ with index.tsx and styles.module.css
  • TAB_CONFIG has 5 tabs (no content)
  • createLazyTab hardcodes @site/docs/components/${slug}/${tab}.md with a single webpack include regex
  • src/components/ComponentTabs/index.tsx has matching 5-tab TAB_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.tsx
  • src/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: AutoDocTabs from @site/src/components/AutoDocTabs
  • Plugin data: usePluginData('doc-tabs-plugin')

Section 3: Layout Extension​

Current State​

  • src/theme/DocItem/Layout/index.tsx recognizes only component_page?: boolean and preview_image?: string in frontmatter
  • isComponentPage drives: 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 accent
  • children: ReactNode — contains <FigmaEmbed> and caption text

Rendering:

  • Card container with a colored top border (green for do, red for dont)
  • 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:

SectionTabMarkdown Heading
Elementsdesign## Elements
Layoutdesign## Layout
Guidelinesdesign## Guidelines
Usage_DodesignDoDontCard type="do" inside ## Usage
Usage_DontdesignDoDontCard 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 DoDontCard to the "Available MDX Components" table: DoDontCard | Do/Don't comparison card for usage examples (type prop: "do" or "dont")
  • Add content to available tab values: overview | design | code | accessibility | content | status
  • Add pattern_page: true as 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/ and docs/patterns/

Files Changed Summary​

ActionFile
Renameplugins/component-tabs-plugin.js → plugins/doc-tabs-plugin.js
Renamesrc/components/AutoComponentDocTabs/ → src/components/AutoDocTabs/
Editdocusaurus.config.ts (plugin path)
Editsrc/theme/DocItem/Layout/index.tsx (imports, frontmatter, plugin name)
Editsrc/components/ComponentTabs/index.tsx (add content tab)
Editsrc/theme/MDXComponents.tsx (register DoDontCard)
Editsidebars.ts (autogenerated patterns)
Edit.claude/figma-naming-config.md (pattern sections)
EditAGENTS.md (renames and new capabilities)
Createsrc/components/DoDontCard/index.tsx
Createsrc/components/DoDontCard/styles.module.css
Create.claude/commands/generate-pattern-doc.md
Createdocs/patterns/empty-states/index.md
Createdocs/patterns/empty-states/overview.md
Createdocs/patterns/empty-states/design.md
Createdocs/patterns/empty-states/accessibility.md
Createdocs/patterns/empty-states/code.md
Createdocs/patterns/empty-states/content.md
Createdocs/patterns/empty-states/status.md