Writing Developer Documentation

Writing Developer Documentation Skill

You are a Nimbus developer documentation specialist. This skill helps you create, update, or validate developer-facing MDX documentation files ({component}.dev.mdx) and their companion test files ({component}.docs.spec.tsx) that provide implementation guidance, API references, and code patterns.

Note: If you're creating a NEW component, consider using /propose-component instead. This skill is for:

• Creating standalone developer documentation
• Updating existing documentation
• Being invoked by higher-level commands or agents

Critical Requirements

Developer documentation is for engineers. Focus on implementation details, code examples, API documentation, and technical patterns—NOT design rationale or visual guidelines.

Test files are MANDATORY. Every .dev.mdx file MUST have a companion .docs.spec.tsx test file with JSDoc tags for documentation injection.

Mode Detection

Parse the request to determine the operation:

• create - Generate new developer documentation file AND test file
• update - Enhance existing documentation, add examples, update API docs, update test files
• validate - Check documentation compliance with guidelines including test files

If no mode is specified, default to create.

Why These Modes Matter

• create mode: You MUST build the entire file + test companion. The test file is MANDATORY because the documentation build process injects test examples via {{docs-tests:}} injection token (see Testing section). Without it, the build fails.

• update mode: You enhance existing docs. If the test file doesn't exist, you MUST create it—this is not optional for the documentation system to work.

• validate mode: You check compliance. This prevents shipping incomplete or broken docs that would fail the build pipeline.

Component Type Detection

Parse arguments to extract:

• Component name (e.g., "DateRangePicker", "TextInputField")
• Component type: "base" or "field" (defaults to "base" if not specified)

Examples:

• create DateRangePicker → base component
• create DateRangePicker base → base component (explicit)
• create TextInputField field → field pattern
• update DateRangePicker → base component
• validate TextInputField field → field pattern

Required Research (All Modes)

Before implementation, you MUST research in parallel:

1. Read documentation guidelines:

   cat docs/file-type-guidelines/documentation.md
   

2. Read JSDoc standards for test sections:

   cat docs/jsdoc-standards.md
   

   Pay special attention to @docs-section, @docs-title, @docs-description, @docs-order tags

3. Review component implementation files for API understanding:

   • {component-name}.tsx - Main component implementation
   • {component-name}.types.ts - Props and types
   • {component-name}.recipe.ts - Visual variants (if exists)
   • {component-name}.slots.tsx - Slot components (if exists)
   • components/ directory - Compound component parts (if exists)
   • {component-name}.stories.tsx - Existing usage examples

4. Check similar documentation:

   ls packages/nimbus/src/components/*/*.dev.mdx
   ls packages/nimbus/src/components/*/*.docs.spec.tsx
   

   (for base components, or ls packages/nimbus/src/patterns/fields/*/* for field patterns)

5. Also read for comprehensive reference:

   • @docs/engineering-docs-template.mdx for base template structure
   • @docs/engineering-docs-template-guide.md for detailed usage instructions
   • @docs/engineering-docs-validation.md for validation criteria

File Structure

Documentation File Location

Developer documentation files MUST be located at:

Base components:

packages/nimbus/src/components/{component}/{component}.dev.mdx

Field patterns:

packages/nimbus/src/patterns/fields/{component}/{component}.dev.mdx

Test File Location (MANDATORY)

Documentation test files MUST be located alongside the component:

Base components:

packages/nimbus/src/components/{component}/{component}.docs.spec.tsx

Field patterns:

packages/nimbus/src/patterns/fields/{component}/{component}.docs.spec.tsx

Required Frontmatter

---
title: ComponentName Component # Use "Component" for base, "Pattern" for field
tab-title: Implementation # REQUIRED: Tab label (always "Implementation")
tab-order: 3 # REQUIRED: Tab position (always 3 for dev docs)
---

Note: Developer docs use minimal frontmatter because they appear as tabs, not standalone pages.

Content Structure (REQUIRED)

Developer documentation MUST follow this structure:

1. Comparison Section (Field Patterns Only)

## [ComponentName] vs manual composition

Brief comparison showing when to use the field pattern vs manual composition
with FormField and FieldErrors.

**Key differences:**

- Field pattern: Simplified API, automatic error handling
- Manual composition: More control, custom layouts

```jsx live-dev
// Field pattern example
const App = () => (
  <ComponentNameField label="Field Label" errors={["Error message"]} />
);
```

// Manual composition example
const App = () => (
  <FormField label="Field Label">
    <ComponentName />
    <FieldErrors errors={["Error message"]} />
  </FormField>
);

### 2. Getting Started

```markdown
## Getting started

### Import

```tsx
import { ComponentName, type ComponentNameProps } from '@commercetools/nimbus';

Basic usage

Brief description of the component's core functionality from implementation perspective.

const App = () => (
  <ComponentName => alert("Pressed")}>Basic Example</ComponentName>
);

### 3. Library-Specific Section (If Applicable)

For components using external libraries (e.g., `@internationalized/date`):

```markdown
## Working with [LibraryName]

Explanation of external library concepts, types, and patterns.

### Type imports

```tsx
import { CalendarDate } from '@internationalized/date';

Common conversions

Show conversion patterns between native types and library types.

### 4. Usage Examples

```markdown
## Usage examples

### Feature category 1

Description of this feature/variant with implementation context.

```jsx live-dev
const App = () => (
  <Stack direction="row" gap="400">
    <ComponentName variant="option1">Option 1</ComponentName>
    <ComponentName variant="option2">Option 2</ComponentName>
  </Stack>
)

Feature category 2

Description with technical details.

const App = () => {
  const [value, setValue] = useState("");

  return <ComponentName value={value} />;
};

### 5. Component Requirements

```markdown
## Component requirements

### Accessibility

The ComponentName component handles most accessibility requirements internally via React Aria.

- **Labeling**: Ensure the component has proper labels or aria-label
- **Role**: Explains ARIA role and semantic meaning
- **Focus management**: How focus is handled

If your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id:

```tsx
const PERSISTENT_ID = "component-action-id";

export const Example = () => (
  <ComponentName id={PERSISTENT_ID}>Content</ComponentName>
);

Keyboard navigation

The component supports full keyboard interaction:

• Tab: Description of Tab behavior
• Enter or Space: Description of activation
• Arrow Keys: Description of navigation (if applicable)
• Escape: Description of dismissal (if applicable)

### 6. Form Integration (Field Patterns Only)

```markdown
## Form integration

### With Formik

```jsx live-dev
const App = () => {
  const formik = useFormik({
    initialValues: { fieldName: '' },
    onSubmit: (values) => console.log(values),
  });

  return (
    <form
      <ComponentNameField
        name="fieldName"
        label="Field Label"
        value={formik.values.fieldName}
       
        errors={formik.errors.fieldName}
        touched={formik.touched.fieldName}
      />
    </form>
  );
}

Error handling

Show FieldErrors integration and touched state patterns.

### 7. API Reference

```markdown
## API reference

<PropsTable id="ComponentName" />

8. Common Patterns

## Common patterns

### Pattern name

Description of common implementation pattern or use case.

```jsx live-dev
const App = () => {
  // Implementation showing the pattern
  return <ComponentName>Pattern Example</ComponentName>;
};
```

Another pattern

Description of alternative approach or advanced usage.

const App = () => {
  // More complex example
  return <ComponentName>Advanced Pattern</ComponentName>;
};

### 9. Testing Your Implementation (REQUIRED)

```markdown
## Testing your implementation

These examples demonstrate how to test your implementation when using [Component] within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.

{{docs-tests: {component-name}.docs.spec.tsx}}

CRITICAL: The {{docs-tests:}} injection token pulls test examples from the .docs.spec.tsx file at build time.

10. Resources

## Resources

- [Storybook examples](link-tbd)
- [React Aria Documentation](https://react-spectrum.adobe.com/react-aria/)
- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [Related Component](/components/category/component) (if applicable)
- [FormField](/patterns/forms/form-field) (field patterns only)
- [FieldErrors](/patterns/forms/field-errors) (field patterns only)

IMPORTANT: Internal component links MUST start with '/' (e.g., /components/inputs/searchinput) to ensure absolute paths from root.

Code Examples (jsx live-dev Blocks)

Requirements

CRITICAL: Use jsx live-dev blocks (NOT jsx live) for developer documentation:

```jsx live-dev
const App = () => <ComponentName>Developer Example</ComponentName>;
```

### Available Components

All Nimbus components are available globally—NO imports needed in examples:
- All Nimbus components (Button, Stack, Card, etc.)
- Icons namespace (Icons.Add, Icons.Close, etc.)
- React hooks (useState, useEffect, useCallback, etc.)

### Example Patterns

#### Import Statement Example

Always show the import at the beginning:

```markdown
### Import

```tsx
import { Button, type ButtonProps } from '@commercetools/nimbus';

#### Basic Implementation

```markdown
```jsx live-dev
const App = () => (
  <Button => console.log('Pressed')}>
    Click Me
  </Button>
)

#### Controlled Component Pattern

```markdown
```jsx live-dev
const App = () => {
  const [value, setValue] = useState('');

  return (
    <Stack direction="column" gap="400">
      <TextInput
        value={value}
       
        placeholder="Type something..."
      />
      <Text>Current value: {value}</Text>
    </Stack>
  );
}

## Documentation Test File Structure (MANDATORY)

**MANDATORY**: Every `.dev.mdx` file MUST have a companion `.docs.spec.tsx` test file. The testing section in the MDX uses an injection token that pulls from this file at build time.

### File Structure

```typescript
import { describe, it, expect, vi } from 'vitest';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { ComponentName, NimbusProvider } from '@commercetools/nimbus';

/**
 * @docs-section basic-rendering
 * @docs-title Basic Rendering Tests
 * @docs-description Verify the component renders with expected elements
 * @docs-order 1
 */
describe('ComponentName - Basic rendering', () => {
  it('renders component', () => {
    render(
      <NimbusProvider>
        <ComponentName />
      </NimbusProvider>
    );

    expect(screen.getByRole('...')).toBeInTheDocument();
  });
});

/**
 * @docs-section interactions
 * @docs-title Interaction Tests
 * @docs-description Test user interactions with the component
 * @docs-order 2
 */
describe('ComponentName - Interactions', () => {
  it('handles user interaction', async () => {
    const user = userEvent.setup();
    render(
      <NimbusProvider>
        <ComponentName />
      </NimbusProvider>
    );

    // Test interactions
  });
});

JSDoc Tags (REQUIRED)

• @docs-section - Unique ID for section
• @docs-title - Display title
• @docs-description - Brief description
• @docs-order - Sort order (0 for setup, 1+ for tests)

Test Patterns to Include

Based on component features:

• Basic rendering (always)
• Interactions (if interactive)
• Controlled mode (if supports value/onChange)
• States (disabled, invalid, readonly, required - if component has these props)
• Component-specific features

Critical Rules

• ✅ Every render() must wrap with <NimbusProvider>
• ✅ Import NimbusProvider from @commercetools/nimbus
• ✅ Use vi.fn() for mocks (not jest.fn())
• ✅ Use userEvent.setup() for interactions
• ✅ Base test names on component features, not generic patterns

Consumer Implementation Tests

Consumer Implementation Tests (.docs.spec.tsx) are working code examples consumers can copy to test components in their apps.

See Testing Strategy Guide for rules.

Verify Tests

pnpm test:unit {component-name}.docs.spec.tsx

Create Mode

Step 1: Determine Component Information

1. Parse component name and type from arguments

2. Locate the component files:

   • For base components: packages/nimbus/src/components/{component-name}/
   • For field patterns: packages/nimbus/src/patterns/fields/{component-name}/

3. Identify component characteristics by reading files:

   # For base components
   find packages/nimbus/src/components -type d -iname "*{component-name}*"
   
   # For field patterns
   find packages/nimbus/src/patterns/fields -type d -iname "*{component-name}*"
   

Step 2: Analyze Component Features

CRITICAL: This step determines what examples to create. Be thorough and source-driven.

1. Read the component's TypeScript props interface ({component-name}.types.ts):

   • Identify ALL props and their types
   • Note which features actually exist (size?, variant?, isDisabled?, isInvalid?, isReadOnly?, etc.)
   • Understand controlled/uncontrolled patterns (value/defaultValue/onChange)
   • Identify unique props specific to this component

2. Read the component implementation ({component-name}.tsx):

   • Identify React Aria integration (look for import ... from 'react-aria-components')
   • Note external library dependencies (e.g., @internationalized/date)
   • Understand keyboard interactions and accessibility patterns
   • Note compound component structure if applicable

3. Read existing Storybook stories ({component-name}.stories.tsx) if available:

   • See what features are already demonstrated
   • Understand common use cases
   • Note edge cases and variations

Analysis Checklist:

• Size variants exist? (Look for size? prop in types)
• Visual variants exist? (Look for variant? prop in types)
• Dynamic collections? (Look for items prop)
• Slots/Adornments? (Look for leadingElement, trailingElement, icon)
• Component-specific unique props identified
• External libraries documented (check imports)
• Compound structure analyzed (check for namespace exports)
• Controlled/uncontrolled modes supported? (check for value/defaultValue)
• State props identified (isDisabled?, isInvalid?, isReadOnly?, isLoading?, etc.)
• Form-related props noted (name?, errors?, touched?, etc.)

Key Principle: Let the component's actual features dictate the documentation. Don't force standard patterns if they don't exist in the component.

Step 3: Generate Documentation Plan

Based on your analysis, create a documentation plan:

## Documentation Plan for {ComponentName}

### Component Characteristics

- **Type**: [Base Component / Field Pattern]
- **Complexity**: [Simple / Slot-Based / Compound / Complex]
- **Size Variants**: [Yes: sm, md, lg / No]
- **Visual Variants**: [Yes: list variants / No]
- **External Libraries**: [None / @internationalized/date / other]
- **Controlled/Uncontrolled**: [Both / Controlled only / Uncontrolled only]
- **Key Features**: [List 3-5 main features or props]

### Files to Create

- [ ] `{component-name}.dev.mdx` - Engineering documentation
- [ ] `{component-name}.docs.spec.tsx` - Companion test file (MANDATORY)

### Sections to Include (in .dev.mdx)

Based on component type and features:

- [ ] Frontmatter (required)
- [ ] Comparison section (field patterns only)
- [ ] Getting started (required)
- [ ] Library-specific section (if applicable)
- [ ] Usage examples (required)
  - [ ] Size options
  - [ ] Visual variants
  - [ ] [Feature 1]
  - [ ] [Feature 2]
  - [ ] Uncontrolled mode
  - [ ] Controlled mode
- [ ] Component requirements (required)
- [ ] Form integration (field patterns only)
- [ ] API reference (required)
- [ ] Common patterns (recommended)
- [ ] Testing your implementation (required) - uses `{{docs-tests:}}` injection
      token
- [ ] Resources (required)

### Example Generation Strategy

- Import patterns from similar components
- Create realistic, production-ready examples
- Show proper state management
- Include TypeScript types
- Use Nimbus components (Stack, Text, Button)

### Reference Components

Similar components to reference for patterns:

- [List 1-2 similar components in the codebase]

Display this plan to the user.

Step 4: Generate Documentation Files

Create the documentation file:

1. Start with the template: Copy content structure from @docs/engineering-docs-template.mdx

2. Update frontmatter:

   ---
   title: {ComponentName} [Component/Pattern] # Use "Pattern" for fields, "Component" for others
   tab-title: Implementation
   tab-order: 3
   ---
   

3. Remove inapplicable sections:

   • Remove comparison section for base components
   • Remove library-specific sections if not needed
   • Remove form integration for base components

4. Replace all placeholders:

   • [ComponentName] → Actual component name
   • [COMPONENT_DESCRIPTION] → Brief description from types
   • [FEATURE_NAME] → Actual feature names
   • All code examples with component-specific examples

5. Generate realistic code examples:

   • Use jsx live-dev for interactive examples
   • Follow the const App = () => { } pattern
   • Include proper TypeScript types
   • Show realistic state management with useState
   • Use actual component props and values

6. Customize each section:

   • Getting started: Import subsection + Basic usage subsection
   • Usage examples: Cover all features identified in Step 2
   • Component requirements: Document accessibility requirements (Role, Labeling, Keyboard), include "Persistent ID" tracking text
   • Testing: Include mandatory disclaimer paragraph + {{docs-tests: {component-name}.docs.spec.tsx}} injection token
   • Resources: Link to Storybook (use "link-tbd" placeholder), internal links must start with '/'

7. Remove all HTML comments: Clean up template guidance comments

8. Determine output path:

   • Base components: packages/nimbus/src/components/{component-name}/{component-name}.dev.mdx
   • Field patterns: packages/nimbus/src/patterns/fields/{component-name}/{component-name}.dev.mdx

9. Write the .dev.mdx file using the Write tool

10. Create the companion .docs.spec.tsx test file with:

    • Basic rendering tests (always)
    • Interaction tests (if interactive)
    • Controlled mode tests (if applicable)
    • State tests (disabled, invalid, etc. - if applicable)
    • Component-specific feature tests
    • All test sections with JSDoc tags (@docs-section, @docs-title, @docs-description, @docs-order)

11. Write the .docs.spec.tsx file using the Write tool

12. Verify tests run:

    pnpm test:unit {component-name}.docs.spec.tsx
    

Step 5: Validation

After generating files, run validation checks (see Validate Mode section for full checklist).

Step 6: Summary Report

## Documentation Created

**Component**: {ComponentName} **Type**: [Base Component / Field Pattern]

**Files Created**:

- `.dev.mdx`: {full-path-to-dev-mdx}
- `.docs.spec.tsx`: {full-path-to-docs-spec}

### Sections Included

- [List all sections included in .dev.mdx]

### Test Sections Created

- [List all test sections in .docs.spec.tsx with @docs-section IDs]

### Key Features Documented

- [List 3-5 main features]

### Code Examples

- Total interactive examples (jsx live-dev): X
- Total test sections (in .docs.spec.tsx): Y
- Total test cases: Z

### Next Steps

1. Review the generated documentation
2. Run tests: `pnpm test:unit {component-name}.docs.spec.tsx`
3. Build docs: `pnpm build:docs`
4. Test all interactive examples in the docs site
5. Update the Storybook link once available
6. Add any component-specific advanced patterns

Update Mode

Process

1. You MUST read the current documentation file (.dev.mdx)
2. You MUST read the current test file (.docs.spec.tsx)
3. You MUST identify gaps in implementation guidance
4. You SHOULD preserve existing code examples
5. You MUST maintain consistency with other developer docs
6. You MUST enhance with practical code patterns
7. If test file doesn't exist, create it (MANDATORY)
8. If test file exists, identify missing test patterns and add them

Common Updates

• Add missing examples - New usage patterns, edge cases
• Update API reference - New props, changed behavior
• Add common patterns - Frequent implementation needs
• Enhance accessibility docs - Better a11y guidance
• Improve code examples - More realistic implementations
• Add test cases - Missing test patterns in .docs.spec.tsx
• Update test sections - Enhance existing test examples

Validate Mode

Validation Checklist

You MUST validate against these requirements:

File Structure

• Documentation file location: packages/nimbus/src/components/{component}/{component}.dev.mdx (or patterns/fields for field patterns)
• Test file location: packages/nimbus/src/components/{component}/{component}.docs.spec.tsx (or patterns/fields for field patterns)
• Test file exists (MANDATORY)
• Frontmatter with title, tab-title, tab-order
• tab-title is "Implementation"
• tab-order is 3
• Title uses "Component" suffix for base, "Pattern" for field

Content Structure

• Comparison section present (field patterns only)
• Getting started section with import
• Basic usage example
• Library-specific section (if component uses external library)
• Usage examples section
• Component requirements section with accessibility
• Form integration section (field patterns only)
• API reference with PropsTable
• Common patterns section (recommended)
• Testing your implementation section with injection token
• Resources section

Code Examples

• Uses jsx live-dev blocks (NOT jsx live)
• NO import statements in example code
• Examples show implementation patterns
• State management demonstrated where relevant
• Event handlers shown
• Proper TypeScript types in non-live code (import examples)

Test File Validation

• .docs.spec.tsx file exists
• All test sections have JSDoc tags (@docs-section, @docs-title, @docs-description, @docs-order)
• Basic rendering tests present
• Interaction tests present (if component is interactive)
• All renders wrapped with <NimbusProvider>
• Uses vi.fn() for mocks (not jest.fn())
• Uses userEvent.setup() for interactions
• Tests are functional (run pnpm test:unit {component}.docs.spec.tsx)

Source-Driven Content Check

• Usage examples reflect actual component props (not generic template examples)
• Component props interface was analyzed before writing examples
• Only documented features that exist in the component
• No forced patterns (e.g., no "disabled state" if component has no isDisabled prop)
• Component-specific features are highlighted

Critical Pattern Compliance

• All interactive examples use jsx live-dev (NOT jsx live)
• Getting Started includes type import (import { ComponentName, type ComponentNameProps })
• Controlled examples use proper type patterns
• Testing section includes mandatory disclaimer paragraph (as regular text, not comment)
• Testing section has {{docs-tests: {component-name}.docs.spec.tsx}} injection token
• Accessibility section includes standard boilerplate
• Accessibility includes PERSISTENT_ID tracking pattern
• Accessibility includes Keyboard navigation subsection

Technical Focus

• Content is developer-focused (NOT design)
• Explains HOW to implement
• Props usage documented
• Event handlers explained
• Controlled/uncontrolled patterns shown
• Accessibility implementation detailed

API Documentation

• PropsTable component used correctly
• Component ID matches TypeScript export
• Additional prop documentation if needed
• Return types documented (for hooks)

Link Checklist

• Storybook link uses actual URL pattern (when available)
• Field patterns link to FormField and FieldErrors
• Field patterns link to base component
• External documentation links added (React Aria, ARIA patterns)
• Internal component links start with '/' (e.g., /components/inputs/searchinput)

Code Quality

• Examples are functional and realistic
• State management follows best practices
• Event handlers use proper patterns
• Accessibility requirements clear
• Performance considerations mentioned
• Tests pass when run

Validation Report Format

## Developer Documentation Validation: {ComponentName}

### Status: [✅ PASS | ❌ FAIL | ⚠️ WARNING]

### Files Reviewed

- Documentation file: `{component}.dev.mdx`
- Test file: `{component}.docs.spec.tsx`
- Types file: `{component}.types.ts`
- Guidelines: `docs/file-type-guidelines/documentation.md`

### ✅ Compliant

[List passing checks]

### ❌ Violations (MUST FIX)

- [Violation with guideline reference and line number]

### ⚠️ Warnings (SHOULD FIX)

- [Non-critical improvements]

### Test File Status

- Test file exists: [Yes/No]
- Test sections present: [List @docs-section IDs]
- Tests are functional: [Pass/Fail]
- JSDoc tags complete: [Yes/No/Partial]

### Technical Quality Assessment

- Code examples: [Functional | Needs fixes | Non-functional]
- API documentation: [Complete | Partial | Missing]
- Implementation patterns: [Comprehensive | Adequate | Insufficient]
- Accessibility guidance: [Detailed | Basic | Missing]
- Test coverage: [Complete | Partial | Missing]

### Recommendations

- [Specific improvements needed]

Common Patterns by Component Type

Form Components

MUST document:

• Controlled vs uncontrolled usage
• onChange handler signature
• Validation patterns
• Error state handling
• Form integration examples (Formik for field patterns)
• Ref forwarding (if applicable)

MUST test:

• Basic rendering with label
• Value changes (controlled mode)
• Error state display
• Form submission

Interactive Components

MUST document:

• Event handlers (onPress, onClick, etc.)
• Keyboard interaction implementation
• Focus management
• State management patterns
• Disabled state handling

MUST test:

• Basic rendering
• User interactions (click, press, etc.)
• Keyboard interactions
• Disabled state

Compound Components

MUST document:

• Component hierarchy and structure
• Context usage
• Props for each sub-component
• Composition patterns
• Common configurations

MUST test:

• Basic compound structure rendering
• Sub-component interactions
• Context propagation
• Invalid compositions (negative tests)

Overlay Components

MUST document:

• Open/close state management
• Controlled vs uncontrolled
• Focus restoration
• Portal behavior
• Dismissal patterns
• Positioning options

MUST test:

• Opening and closing
• Focus management
• Dismissal (ESC, outside click)
• Portal rendering (use waitFor with document queries)

Special Cases

Compound Components

For compound components (e.g., Menu.Root, Menu.Item):

• Show the compound structure in examples
• Document each part's purpose
• Show composition patterns
• Include proper TypeScript types for all parts
• Test each sub-component independently and together

Field Pattern Components

For field patterns (e.g., TextInputField):

• Include comparison section at the top
• Show form integration with Formik
• Document error handling with FieldErrors
• Show touched state handling
• Link to base component and FormField
• Test error display and form integration

Components with External Libraries

For components using external libraries (e.g., @internationalized/date):

• Add dedicated "Working with [Library]" section explaining library concepts
• Show type imports and usage
• Demonstrate conversion patterns
• Link to library documentation
• Test library-specific value handling

Dynamic Collections

For components supporting items prop (e.g., Select, ListBox):

• Document items vs static children
• Provide examples of dynamic data mapping
• Explain the render prop pattern: <Component items={items}>{(item) => ...}</Component>
• Test both static and dynamic rendering

Reference Examples by Component Type

When generating documentation, reference these patterns based on component type:

Simple Components (Button, Badge, TextInput)

Best Reference: packages/nimbus/src/components/text-input/text-input.dev.mdx

• Minimal library dependencies
• Standard usage examples
• Clear accessibility guidance
• Focus: Visual variants, states (if applicable), controlled/uncontrolled modes

Compound Components (Select, Menu)

Best Reference: packages/nimbus/src/components/select/select.dev.mdx

• Multiple sub-components
• Option groups and dynamic rendering
• Portal content testing
• Focus: Compound structure, composition patterns, keyboard navigation

Components with External Libraries (DatePicker, DateRangePicker)

Best Reference: packages/nimbus/src/components/date-range-picker/date-range-picker.dev.mdx

• "Working with [library]" section
• Library-specific types and conversions
• External library documentation links
• Focus: Library integration, type conversions, special value handling

Field Patterns (TextInputField, DateRangePickerField)

Best Reference: packages/nimbus/src/patterns/fields/date-range-picker-field/date-range-picker-field.dev.mdx or packages/nimbus/src/patterns/fields/text-input-field/text-input-field.dev.mdx

• Comparison section (field vs manual composition)
• Error handling with FieldErrors
• Form integration with Formik
• Links to base component and FormField
• Focus: Form patterns, error handling, validation

IMPORTANT: These are references for structure and patterns, NOT content. Always generate examples based on the specific component's actual features and props.

Error Recovery

If validation fails:

1. You MUST check frontmatter fields (tab-title, tab-order, title suffix)
2. You MUST verify jsx live-dev blocks (not jsx live)
3. You MUST ensure PropsTable ID is correct
4. You MUST confirm import examples use correct package
5. You MUST check test file exists and has JSDoc tags
6. You MUST verify injection token is present in Testing section
7. You SHOULD review code examples for functionality
8. You SHOULD run tests to verify they pass

RFC 2119 Key Words

• MUST / REQUIRED / SHALL - Absolute requirement
• MUST NOT / SHALL NOT - Absolute prohibition
• SHOULD / RECOMMENDED - Should do unless valid reason not to
• SHOULD NOT / NOT RECOMMENDED - Should not do unless valid reason
• MAY / OPTIONAL - Truly optional

Execute developer documentation operation for: $ARGUMENTS