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:

Read documentation guidelines:

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

Review component implementation for design decisions

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
description: Brief one-line description
documentState: InitialDraft # InitialDraft|ReviewedInternal|Published
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. Title and Overview

# Component Name

Brief introduction (1-2 sentences) from design perspective.

## 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

You MUST read the current documentation file (understand what exists before changing)
You SHOULD identify gaps in design guidance (visual hierarchy, use cases, color palette)
You MUST preserve existing structure and tone (don't rewrite what's working)
You MUST maintain consistency with other designer docs (don't deviate from established style without reason)
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 location: packages/nimbus/src/components/{component}/{component}.mdx (MUST match)
All required frontmatter fields present (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)

H1 title matching component name (UX clarity)
Introduction paragraph (sets context)
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

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:

You MUST verify frontmatter structure and unique ID (blocks build if wrong)
You MUST ensure menu hierarchy is correct (affects navigation)
You MUST confirm jsx live blocks (not jsx live-dev) (doc generation requirement)
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

writing-designer-documentation