Pattern Migrator

Overview

This skill provides a systematic workflow for migrating patterns between directories in a Storybook-based design system. It ensures all cross-references, Meta titles, URL patterns, and documentation links remain intact throughout the migration process.

When to Use This Skill

Apply this skill when:

• •Reorganizing Storybook directory structure
• •Moving patterns to different categories
• •Consolidating or splitting pattern collections
• •Refactoring documentation hierarchy
• •Performing bulk pattern migrations
• •Any task requiring careful tracking of Storybook URLs and cross-references

Migration Workflow

Follow this five-phase sequential process for reliable pattern migrations:

Phase 1: Analysis and Planning

Before making any changes, gather comprehensive context about the migration scope:

1. Directory Inventory

• •Use Glob or Bash tools to list all files in source and target directories
• •Identify pattern types:
  • •Simple .mdx files (documentation only)
  • •.mdx with companion .stories.tsx files
  • •Complex directories with multiple file types (TypeScript, JSON, CSS, HTML)

2. Meta Title Extraction

• •Read all .mdx files to identify current Meta component titles
• •Record both explicit titles (<Meta title="Category/Name" />) and story references (<Meta of={PatternStories} />)
• •For story references, locate and read the corresponding .stories.tsx file to find the Meta title

3. Cross-Reference Mapping

• •Search for internal Storybook links within pattern files
• •Identify all references following the pattern: ../?path=/docs/[category-name]--docs
• •Document incoming references (other patterns linking to this one)
• •Document outgoing references (this pattern linking to others)

4. Create Migration Plan

• •Draft a markdown file listing:
  • •Patterns to migrate (source → destination paths)
  • •Current and new Meta titles
  • •URL transformations (old → new Storybook URLs)
  • •Identified cross-references requiring updates
  • •Timeline and validation steps

Phase 2: File Structure Migration

Execute file moves systematically, handling each pattern type appropriately:

Simple Files (.mdx only)

1. •Move file to new location using mv or git commands
2. •Update Meta title to reflect new category structure
3. •Update any internal cross-references within the file
4. •Search codebase for external references to this pattern

Complex Patterns (with stories/components)

1. •Move entire directory structure to preserve file relationships
2. •Update Meta title in .stories.tsx file
3. •Check for and update import path dependencies in TypeScript files
4. •Update internal cross-references in .mdx files
5. •Search codebase for external references to this pattern

Important: Use git mv when working in a git repository to preserve file history.

Phase 3: URL Reference Updates

Understand Storybook URL transformation rules and update all references:

URL Transformation Rules Storybook generates URLs from Meta titles following these rules:

• •<Meta title="Category/Name" /> becomes ../?path=/docs/category-name--docs
• •Transformations:
  • •Spaces → hyphens
  • •Uppercase → lowercase
  • •Asterisks (*) → removed from URLs
  • •Forward slashes (/) → hyphens

Search Strategy

1. •Global search: Use Grep to find all instances of old URL patterns across the entire codebase
   • •Pattern: ../?path=/docs/old-category-pattern-name--docs
2. •Pattern-specific searches: Search for each moved pattern individually
3. •Cross-reference updates: Update all found references to use new URL patterns
4. •Import path updates: If TypeScript files import from moved patterns, update import statements

Phase 4: Documentation Updates

Ensure all supporting documentation reflects the new structure:

Update Documentation Files

• •Overview or index files that list patterns
• •AGENTS.md if it references the old directory structure
• •README files that mention the affected patterns
• •Any hierarchy or navigation documentation

Verify Documentation Standards

• •Ensure British spelling throughout (behaviour, organisation, colour)
• •Use sentence case for headings and titles
• •Follow project-specific documentation linking standards

Phase 5: Validation

Confirm the migration succeeded without breaking functionality:

1. Build Test Run Storybook build to check for errors:

npm run build-storybook

2. Link Verification

• •Start Storybook in development mode
• •Navigate through documentation to verify all links work
• •Check that moved patterns appear in correct categories
• •Verify cross-references open the correct documentation

3. TypeScript Compilation If the project uses TypeScript:

npm run typecheck

4. Cross-Reference Audit

• •Systematically verify internal documentation links function
• •Check that no references point to old locations
• •Confirm no broken links appear in the Storybook interface

File Types and Handling

Documentation Files

• •Simple .mdx: Move file, update Meta title, update references
• •Complex .mdx: Move file, update Meta title, update references, verify companion files moved

Story Files

• •.stories.tsx: Update Meta title, check import paths, move with companion .mdx file

Support Files

• •TypeScript files (.ts, .tsx): Check import paths, move with pattern directory
• •JSON data files: Move with pattern, check import references
• •HTML templates: Move with pattern, check references
• •CSS files: Move with pattern, check import paths

Risk Mitigation

Pre-Migration Checklist

• • Full pattern inventory completed
• • All cross-references documented
• • Migration plan reviewed and approved
• • Backup or version control commit made

During Migration

• • Test build after each major pattern migration
• • Update references immediately after moving files
• • Document any unexpected issues or discoveries

Post-Migration Validation

• • Full Storybook build succeeds
• • All documentation links function correctly
• • No broken imports in TypeScript compilation
• • Cross-reference audit completed

Success Criteria

A successful migration results in:

• •All patterns accessible in new Storybook locations
• •All cross-references functioning correctly
• •No broken links in documentation
• •Clean TypeScript compilation
• •Successful Storybook build
• •All import paths resolving correctly

References

For detailed technical specifications, command examples, and additional guidance, consult the comprehensive migration guide in references/pattern-migration-guide.md.

The reference guide includes:

• •Detailed command examples
• •Common URL reference patterns
• •Template code snippets
• •Additional risk mitigation strategies