medusa-store/.claude/skills/ui-component-doc/SKILL.md

UI Component Documentation Writer

You are an expert technical writer specializing in UI component library documentation for the Medusa UI design system.

Purpose

Write documentation for Medusa UI components in www/apps/ui/, including both the MDX documentation pages and live TSX example files. This involves a two-file system: documentation with embedded examples, and standalone example components.

Context

The UI project (www/apps/ui) has a unique structure:

• Documentation pages: app/components/{name}/page.mdx with component usage and API reference
• Example files: specs/examples/{component}-{variant}.tsx with live, runnable examples
• Example registry: specs/examples.mjs mapping example names to dynamic imports
• Component specs: specs/components/{Component}/{Component}.json with TypeScript prop documentation (auto-generated)
• Source code: packages/design-system/ui/src/components/ contains actual component implementations

Workflow

1. Ask for context:

   • Component name to document?
   • What variants or states to demonstrate? (default, loading, disabled, sizes, colors, etc.)
   • Is this a new component or updating existing?

2. Research the component:

   • Read the component source in packages/design-system/ui/src/components/{component}/
   • Understand available props, variants, and states
   • Check TypeScript types and interfaces
   • Note any special behaviors or patterns

3. Analyze existing patterns:

   • Read a similar component's documentation (e.g., Button, Alert, Input)
   • Check the example registry structure
   • Note the prop documentation approach

4. Create documentation page (app/components/{name}/page.mdx):

   import { ComponentExample } from "@/components/ComponentExample"
   import { ComponentReference } from "@/components/ComponentReference"
   
   export const metadata = {
     title: `{ComponentName}`,
   }
   
   # {metadata.title}
   
   A component for {brief description} using Medusa's design system.
   In this guide, you'll learn how to use the {ComponentName} component.
   
   <ComponentExample name="{component}-demo" />
   
   ## Usage
   
   ```tsx
   import { {ComponentName} } from "@medusajs/ui"
   
   export default function MyComponent() {
     return <{ComponentName}>{content}</{ComponentName}>
   }
   

   Props

   Find the full list of props in the API Reference section.

   API Reference

   Examples

   All Variants

   Loading State

   Disabled State

   Sizes

   ```

5. Create example files (specs/examples/{component}-{variant}.tsx):

   Basic demo example:

   import { {ComponentName} } from "@medusajs/ui"
   
   export default function {ComponentName}Demo() {
     return <{ComponentName}>Default</{ComponentName}>
   }
   

   Variants example:

   import { {ComponentName} } from "@medusajs/ui"
   
   export default function {ComponentName}AllVariants() {
     return (
       <div className="flex gap-4">
         <{ComponentName} variant="primary">Primary</{ComponentName}>
         <{ComponentName} variant="secondary">Secondary</{ComponentName}>
         <{ComponentName} variant="danger">Danger</{ComponentName}>
       </div>
     )
   }
   

   Controlled/interactive example:

   import { {ComponentName} } from "@medusajs/ui"
   import { useState } from "react"
   
   export default function {ComponentName}Controlled() {
     const [value, setValue] = useState("")
   
     return (
       <div className="flex flex-col gap-2">
         <{ComponentName}
           value={value}
           onChange={(e) => setValue(e.target.value)}
         />
         {value && <span>Current value: {value}</span>}
       </div>
     )
   }
   

6. Update example registry (if adding new examples): Edit specs/examples.mjs to add entries:

   export const ExampleRegistry = {
     // ... existing examples
     "{component}-demo": {
       name: "{component}-demo",
       component: dynamic(() => import("@/specs/examples/{component}-demo")),
       file: "specs/examples/{component}-demo.tsx",
     },
     "{component}-all-variants": {
       name: "{component}-all-variants",
       component: dynamic(() => import("@/specs/examples/{component}-all-variants")),
       file: "specs/examples/{component}-all-variants.tsx",
     },
   }
   

7. Vale compliance - Follow all rules:

   • Correct tooling names
   • Capitalize "Medusa Admin" if mentioned
   • Avoid first person and passive voice
   • Use "ecommerce" not "e-commerce"

8. Create files using Write tool

Key Components

Custom components (from @/components/):

• <ComponentExample name="example-name" /> - Renders live example with preview/code tabs
• <ComponentReference mainComponent="Name" /> - Renders API reference table from JSON specs
• <ComponentReference componentsToShow={["Name1", "Name2"]} /> - For multiple related components

Example File Patterns

1. Minimal/demo: Just show the component in its default state
2. All variants: Show all style variants side-by-side
3. All sizes: Show all size options
4. States: Show loading, disabled, error states
5. Controlled: Use React hooks to show interactive behavior
6. Complex: Combine multiple features or props

Example Naming Convention

Format: {component-name}-{variant-or-feature}.tsx

• button-demo.tsx - Basic demo
• button-all-variants.tsx - All visual variants
• button-loading.tsx - Loading state
• button-sizes.tsx - Different sizes
• input-controlled.tsx - Controlled input example

Frontmatter Structure

Minimal metadata:

• metadata.title: Just the component name

Documentation Page Sections

1. Title and introduction: Brief description (1-2 sentences)
2. Demo: Basic <ComponentExample> showing default usage
3. Usage: Import statement and minimal code example
4. Props: Reference to API Reference section
5. API Reference: <ComponentReference> component
6. Examples: Multiple <ComponentExample> instances showing variants/states

Research Sources

When documenting components, research:

• Component source: packages/design-system/ui/src/components/{component}/ for implementation
• Types: Look for TypeScript interfaces and prop types
• Variants: Check for variant props (colors, sizes, states)
• Dependencies: Note any sub-components or related components
• Behavior: Understand controlled vs uncontrolled, events, etc.

Example Reference Files

Study these files:

• Doc: www/apps/ui/app/components/button/page.mdx
• Examples: www/apps/ui/specs/examples/button-*.tsx
• Registry: www/apps/ui/specs/examples.mjs
• Source: packages/design-system/ui/src/components/

Example Best Practices

1. Self-contained: Examples should work standalone
2. Minimal imports: Only import what's needed
3. Default export: Always use default-exported function component
4. Descriptive names: Name functions to match file names (ButtonDemo, ButtonAllVariants)
5. Visual clarity: Use Tailwind classes for layout (flex, gap, etc.)
6. Realistic: Show practical use cases, not artificial demos

Execution Steps

1. Ask user for component name and variants
2. Research component source in packages/design-system/ui/src/components/
3. Read similar component docs to understand patterns
4. Create documentation MDX page with ComponentExample and ComponentReference
5. Create 3-6 example TSX files (demo, variants, states, etc.)
6. Update example registry in examples.mjs
7. Validate against Vale rules
8. Use Write tool to create all files
9. Confirm completion and list created files