Writing Designer Documentation

Writing Designer Documentation Skill

You are a Nimbus designer documentation specialist. Create, update, or validate designer MDX files ({component}.mdx) that explain design patterns, visual guidelines, and usage recommendations for non-technical audiences.

CRITICAL: Focus on design decisions, visual patterns, and usage guidelines—NOT implementation details.

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

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

Mode Detection

• create - Generate new designer documentation file
• update - Enhance existing documentation, add sections, update guidelines
• validate - Check documentation compliance with guidelines

You MUST default to create if no mode is specified. This ensures missing docs get created rather than accidentally updating an existing file.

Required Research (All Modes)

Before implementation, you SHOULD research these areas in parallel:

1. Read documentation guidelines:

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

2. Review component implementation for design decisions

3. Check design system documentation:

   ls packages/nimbus/src/components/*/*.mdx
   

Additionally:

• You MUST analyze the component's design purpose and visual patterns (ensures content is design-focused, not implementation)
• You SHOULD check for Figma design resources (improves completeness if available)

File Structure

Location

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

Required Frontmatter

---
id: Components-ComponentName
title: Component Name
exportName: ComponentName
description: Brief one-line description
lifecycleState: Stable # Experimental|Alpha|Beta|Stable|Deprecated
order: 999
menu:
  - Components
  - Category Name # Inputs, Data Display, Navigation, Feedback, Overlay, Layout, Typography
  - Component Name
tags:
  - component
  - relevant-keywords
figmaLink: https://www.figma.com/design/...
---

Content Structure (REQUIRED)

1. Overview

The component title and description are rendered from frontmatter. Content starts directly with the Overview section—do not add a # Component Name heading or introductory paragraph in the body.

## Overview

Explain: design purpose, key visual characteristics, primary use cases, design
rationale.

### Resources

[Figma library](figmaLink) [Related ARIA Pattern](ariaPatternLink) # If
applicable

2. Design Hierarchy (if applicable)

### Hierarchy

Explain primary, secondary, tertiary actions with design rationale and jsx live
examples.

3. Variables (REQUIRED)

## Variables

### Size

Explain each size with design rationale:

```jsx live
const App = () => (
  <Stack direction="horizontal" gap="400">
    <ComponentName size="sm">Small</ComponentName>
    <ComponentName size="md">Medium (default)</ComponentName>
    <ComponentName size="lg">Large</ComponentName>
  </Stack>
);
```

Color Palette

Document each variant's purpose:

const App = () => (
  <Stack direction="horizontal" gap="400">
    <ComponentName colorPalette="primary">Primary</ComponentName>
    <ComponentName colorPalette="critical">Critical</ComponentName>
  </Stack>
);

### 4. Guidelines (OPTIONAL but RECOMMENDED)

```markdown
## Guidelines

### Best practices

- Design principle with rationale
- Visual hierarchy guidance

### When to use

> [!TIP]\
> Use when...
- Use case 1
- Use case 2

> [!CAUTION]\
> When NOT to use
- Avoid case 1
- Anti-pattern to avoid

5. Writing Guidelines (if applicable)

## Writing guidelines

Guidelines for content creators and terminology preferences.

## Preferred words

| Text       | Description    |
| ---------- | -------------- |
| **Save**   | When to use    |
| **Cancel** | Design context |

## Avoid these words

| Avoid    | Use instead            |
| -------- | ---------------------- |
| OK       | Actions that explain   |
| Continue | Context-specific words |

6. Usage Examples (Optional)

Show correct vs. incorrect usage with Do/Don't sections and jsx live examples.

Code Examples (jsx live Blocks)

CRITICAL: Use jsx live blocks (NOT jsx live-dev).

All Nimbus components available globally—NO imports needed. For detailed jsx live patterns, see writing-developer-documentation skill.

Create Mode

Step 1: Gather design context (purpose, hierarchy, colors, sizes, icons, Figma resources) Step 2: Write frontmatter with ID, menu hierarchy, tags Step 3: Write overview explaining component from design perspective Step 4: Document visual variants with jsx live examples and rationale Step 5: Create actionable design guidelines (best practices, when to use/avoid) Step 6: Add writing guidelines if text content applies

Update Mode

1. You MUST read the current documentation file (understand what exists before changing)
2. You SHOULD identify gaps in design guidance (visual hierarchy, use cases, color palette)
3. You MUST preserve existing structure and tone (don't rewrite what's working)
4. You MUST maintain consistency with other designer docs (don't deviate from established style without reason)
5. You SHOULD enhance with visual examples where they clarify (not every section needs jsx live examples, only places where visual demonstration helps)

Common updates: missing sections, better examples, updated guidelines, Figma links, clearer explanations.

Validate Mode

Validation Checklist

File Structure (ALL REQUIRED - breaks build or navigation if violated)

• File location: packages/nimbus/src/components/{component}/{component}.mdx (MUST match)
• All required frontmatter fields present: id, title, exportName, description, order, menu, tags (MUST exist)
• ID follows pattern: Components-{ComponentName} (MUST match, breaks search/routing if wrong)
• Menu hierarchy includes proper category (MUST have)
• Tags array present (MUST have)
• Figma link present (SHOULD have if available)

Content Structure (SHOULD have unless inapplicable)

• No duplicate # Component Name heading in body (title comes from frontmatter)
• Overview section explaining design purpose (design rationale)
• Resources section with links (reference materials)
• Variables section with jsx live examples (shows options)
• Guidelines section (helps designers decide when to use)

Code Examples

• MUST use jsx live blocks (NOT jsx live-dev)
• MUST NOT have import statements
• MUST be visually focused on design, not implementation
• MUST show design variants clearly
• SHOULD be production-ready examples

Design Focus

• MUST be designer-focused (NOT implementation)
• MUST explain WHEN and WHY to use
• MUST document visual hierarchy and color palette
• MUST include size variants with rationale
• SHOULD mention accessibility from user perspective

Writing Quality

• MUST have clear, concise descriptions
• MUST include design rationale
• MUST document best practices
• MUST identify anti-patterns
• MUST have consistent tone
• MUST avoid technical jargon

Validation Report

## Designer Documentation Validation: {ComponentName}

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

### ✅ Compliant

[List passing checks]

### ❌ Violations (MUST FIX)

[Violations with line references]

### ⚠️ Warnings (SHOULD FIX)

[Non-critical improvements]

### Design Focus Assessment

- Design rationale: [Present | Partial | Missing]
- Visual examples: [Comprehensive | Adequate | Insufficient]
- Guidelines quality: [Excellent | Good | Needs improvement]
- Writing guidelines: [Present | Not applicable | Missing]

### Recommendations

[Specific improvements needed]

Common Component Patterns

Button-type: Visual hierarchy (primary/secondary/tertiary), action importance, color semantics, icon placement, button labels

Form: Input states, validation feedback, error presentation, size variants, labels

Feedback: Visual importance hierarchy, color semantics (info/success/warning/error), quick-recognition icons, message content

Overlay: When to use vs. alternatives, size/placement guidelines, content structure, dismissal patterns, user-perspective accessibility

Error Recovery

If validation fails:

1. You MUST verify frontmatter structure and unique ID (blocks build if wrong)
2. You MUST ensure menu hierarchy is correct (affects navigation)
3. You MUST confirm jsx live blocks (not jsx live-dev) (doc generation requirement)
4. You SHOULD review tone (designer-focused, not technical) - fixes readability

Reference Examples

• Simple: packages/nimbus/src/components/badge/badge.mdx
• Form: packages/nimbus/src/components/text-input/text-input.mdx
• Interactive: packages/nimbus/src/components/button/button.mdx
• Overlay: packages/nimbus/src/components/dialog/dialog.mdx

Execute designer documentation operation for: $ARGUMENTS