---
name: strongtie-docs
description: "Generate documentation for React components using Storybook, MDX, or JSDoc based on project conventions. Use when: (1) Creating documentation for new components, (2) Updating existing documentation, (3) Adding Storybook stories."
---

# Documentation Generation Skill

Generate documentation for React components following Simpson Strong-Tie patterns.

## When to Use This Skill

- Creating documentation for new components
- Updating existing component documentation
- Adding Storybook stories
- Writing MDX documentation pages

## Workflow Overview

1. **Analyze Component** - Understand props, variants, and usage
2. **Add JSDoc** - To wrapper component in `src/components/`
3. **Create Story** - In `stories/components/`
4. **Create MDX** - In `apps/docs/content/docs/components/`
5. **Create Examples** - In `apps/docs/registry/example/`
6. **Update Registry** - In `apps/docs/registry/registry-examples.ts`

## Step 1: JSDoc Documentation

Add comprehensive JSDoc to the wrapper component:

```typescript
/**
 * Button is a clickable interactive element that triggers actions or navigates within an application.
 *
 * Buttons are fundamental UI components used to initiate actions, submit forms, or navigate to different
 * views. They come in various visual styles (variants) to indicate importance and different sizes to
 * accommodate various layouts. Buttons support full keyboard navigation and accessibility features,
 * including proper focus management and ARIA attributes.
 *
 * The component supports rendering as a child element via the `asChild` prop, allowing you to apply
 * button styling to links, custom components, or other interactive elements while maintaining proper
 * semantics. Use buttons for primary actions, secondary actions, destructive operations, or as simple
 * text links depending on the visual hierarchy needs of your interface.
 *
 * @example
 * <Button variant="default" size="lg">
 *   Click me
 * </Button>
 *
 * @example
 * // As a link
 * <Button asChild>
 *   <a href="/dashboard">Go to Dashboard</a>
 * </Button>
 */
```

## Step 2: Storybook Story

Create story in `stories/components/component-name.stories.tsx`:

```typescript
import type { Meta, StoryObj } from "@storybook/react"
import { Component } from "@/components/component"

const meta: Meta<typeof Component> = {
  title: "Components/Component",
  component: Component,
  tags: ["autodocs"],
  argTypes: {
    variant: {
      control: { type: "select" },
      options: ["default", "secondary"],
      description: "Visual style variant",
      table: {
        type: { summary: "default | secondary" },
        defaultValue: { summary: "default" },
      },
    },
    size: {
      control: { type: "select" },
      options: ["default", "sm", "lg"],
      description: "Size of the component",
      table: {
        type: { summary: "default | sm | lg" },
        defaultValue: { summary: "default" },
      },
    },
  },
}

export default meta
type Story = StoryObj<typeof Component>

export const Default: Story = {
  args: { children: "Content" },
}

export const Variants: Story = {
  render: () => (
    <div className="flex gap-4">
      <Component variant="default">Default</Component>
      <Component variant="secondary">Secondary</Component>
    </div>
  ),
}
```

## Step 3: MDX Documentation

Create MDX in `apps/docs/content/docs/components/component-name.mdx`:

```mdx
---
title: Component Name
description: Brief description of what the component does and when to use it.
---

Detailed description of the component, its purpose, and common use cases. This should be 2-3 sentences
that help developers understand when and why to use this component.

## Example

<ComponentPreview name="component-default" />

## Installation

```bash
npm install @strongtie/design-system
```

```tsx
import { Component } from "@strongtie/design-system/component"
```

## Props

### `<Component>`

| Prop      | Type                           | Default     | Description                    |
| --------- | ------------------------------ | ----------- | ------------------------------ |
| `variant` | `"default" \| "secondary"`     | `"default"` | Visual style of the component  |
| `size`    | `"default" \| "sm" \| "lg"`    | `"default"` | Size of the component          |

## Examples

<ComponentPreview name="component-default" />

### Variants

<ComponentPreview name="component-variants" />

### Sizes

<ComponentPreview name="component-sizes" />

## Styling

Components can be styled using the `className` prop. The design system uses Tailwind CSS for styling.

### Classes

CSS classes used by this component:

- `component-name`

## Accessibility

- Component is keyboard accessible
- Focus states are visible
- [Add specific accessibility notes]
```

## Step 4: Example Components

Create examples in `apps/docs/registry/example/`:

```typescript
// component-default.tsx
"use client"

import { Component } from "@strongtie/design-system/component"

export default function ComponentDefault() {
  return <Component>Default content</Component>
}
```

```typescript
// component-variants.tsx
"use client"

import { Component } from "@strongtie/design-system/component"

export default function ComponentVariants() {
  return (
    <div className="flex gap-4">
      <Component variant="default">Default</Component>
      <Component variant="secondary">Secondary</Component>
    </div>
  )
}
```

## Step 5: Update Registry

Add to `apps/docs/registry/registry-examples.ts`:

```typescript
{
  name: "component-default",
  type: "registry:example",
  title: "Component Default",
  description: "Default component example.",
  registryDependencies: [],
  files: [
    {
      path: "example/component-default.tsx",
      type: "registry:example",
    },
  ],
},
{
  name: "component-variants",
  type: "registry:example",
  title: "Component Variants",
  description: "Component variant examples.",
  registryDependencies: [],
  files: [
    {
      path: "example/component-variants.tsx",
      type: "registry:example",
    },
  ],
},
```

## Documentation Checklist

- [ ] JSDoc on wrapper component
- [ ] Storybook story with argTypes
- [ ] MDX documentation page
- [ ] Example components in registry
- [ ] Registry entries added
- [ ] Props table complete
- [ ] Accessibility section
- [ ] All variants documented

## Reference

- MDX patterns: `apps/docs/content/docs/components/button.mdx`
- Story patterns: `packages/design-system/stories/components/button.stories.tsx`
- Example patterns: `apps/docs/registry/example/button-default.tsx`
- Registry: `apps/docs/registry/registry-examples.ts`