From ux-harness
Plan and execute a full-page or feature-area migration to the UX Harness standard. Scans an entire page directory, produces a migration plan with file-by-file target states and extraction order, writes characterization tests for the whole page, then orchestrates multiple ux-refactor calls incrementally. Produces a before/after migration report. For single-file cleanup use ux-refactor. Works on any React/Tailwind frontend codebase. Triggers on: "migrate this page", "ux-migrate", "bring this page up to standard", "decompose this feature", or any multi-file tech debt request targeting an entire page or feature area.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ux-harness:ux-migrateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Plan and execute a full-page migration to the UX Harness standard. This is the
Plan and execute a full-page migration to the UX Harness standard. This is the
orchestration skill — it coordinates multiple ux-refactor calls with a plan.
Announce at start: "Planning page migration to UX Harness standard..."
Run ux-prime to load:
Before scanning or planning anything, check if Storybook already has what you need.
Using the Storybook lookup table from ux-prime, for each file in the target directory:
STORYBOOK MATCH: [filename]:[lines] renders a [pattern] that matches [ComponentName] in Storybook
Story: [story file path] → stories: [variant list]
Source: [component source path]
Import: [import path]
Props needed: { [mapped props from the Storybook component's interface] }
Current code uses: [classes found in this file]
Storybook uses: [classes from the Storybook lookup for this component]
Recommendation: REPLACE raw JSX with <ComponentName ... /> import
PARTIAL MATCH: [filename]:[lines] resembles [ComponentName] but differs:
- Classes: file uses [X] where Storybook uses [Y]
- Props: file passes [X] but component expects [Y]
- Structure: file has [extra/missing element]
Recommendation: Evaluate if [ComponentName] can cover this case, or if the differences are intentional
STYLE DRIFT: [filename]:[line] uses [bg-gray-800] but Storybook uses [bg-bg-default] for this pattern
🛑 PROGRESSIVE DISCLOSURE GATE: Present Storybook matches to the user BEFORE proceeding to the scan. "Found 3 Storybook components that match patterns in this page. Want to replace these with imports before planning the full migration?" This avoids migrating code that should just be deleted and replaced with an import.
If the user approves Storybook replacements:
Read every file in the target page directory. For each file, collect:
| File | Lines | any count | Direct API calls | Has test? |
|---|---|---|---|---|
| PageName.tsx | X | Y | yes/no | yes/no |
| component1.tsx | X | Y | yes/no | yes/no |
| ... | ... | ... | ... | ... |
Also collect:
Based on the scan, select EXACTLY ONE path.
ux-refactor on each file directly.🛑 PROGRESSIVE DISCLOSURE GATE: Present the scan results and selected path to the user. "This page has 3,492 total lines across 8 files. Largest file is DataCardBody.tsx at 3,492 lines. Recommending Path C: major migration with checkpoints. Proceed?"
Check before every phase.
ai_docs/migrations/YYYY-MM-DD-migrate-[pagename]-checkpoint.md:
Create a structured plan:
# Migration Plan: [PageName]
## Current State
- Files: [count]
- Total lines: [count]
- Files over 150 lines: [count]
- Files over 200 lines: [count]
- Total `any` types: [count]
- Files with direct API calls: [count]
- Test coverage: [X/Y files have tests]
## Target State
- Estimated files after migration: [count]
- All files under 150 lines
- Zero `any` in business logic
- All API calls in service layer
- All business logic in hooks
- Tests for every file
## Migration Order
### Phase 1: Services (extract API calls)
1. [filename] → extract [apiCall] → [newServiceFile].ts
2. ...
### Phase 2: Hooks (extract business logic)
1. [filename] → extract [stateLogic] → [newHookFile].ts
2. ...
### Phase 3: Components (extract JSX blocks)
1. [filename] → extract [conditionalBlock] → [newComponentFile].tsx
2. ...
### Phase 4: Cleanup (types, styles, semantic tokens)
1. [filename] → replace [any] with [ProperType]
2. [filename] → replace [inlineStyle] with [tailwindClass]
3. [filename] → replace [rawTailwindColor] with [semanticTokenClass]
4. [filename] → replace [numericSpacing] with [namedSpacing]
5. ...
## High-Risk Areas
- [area]: [why it's risky, what could break]
## Dependencies
- [file A] must be refactored before [file B] because [reason]
Save to ai_docs/migrations/YYYY-MM-DD-migrate-[pagename].md.
🛑 PROGRESSIVE DISCLOSURE GATE: Present the plan to the user. Get explicit approval before executing. "Migration plan ready. 4 phases, estimated ~25 new files. Ready to proceed?"
Before any code changes, write characterization tests for the entire page:
Run all tests. Paste the output. They must ALL PASS against current code.
🛑 PROGRESSIVE DISCLOSURE GATE: Do not proceed to execution until characterization tests pass. "Characterization tests: 12/12 passing. Safe to start migration."
For each phase, in order:
For each API call extraction:
Checkpoint: Save progress after Phase 1. Re-check session health.
For each business logic extraction:
Checkpoint: Save progress after Phase 2. Re-check session health.
For each JSX extraction:
ux-refactor on the specific fileCheckpoint: Save progress after Phase 3. Re-check session health.
For each type/style fix:
any with proper typesbg-blue-500 → bg-background-primarytext-gray-500 → text-text-weakborder-red-200 → border-border-criticalux-prime context for correct mappingsgap-2 → gap-sm, p-4 → p-lg, gap-6 → gap-xl🛑 After all functional work is done, step back and verify the migrated code actually matches Storybook's established style.
This is NOT just "are semantic tokens used" — it's "does this look like it belongs in the same app as the Storybook components." Compare every migrated file against the Storybook Style Reference from ux-prime:
bg-bg-* classes used as similar Storybook components? Is the page background bg-bg-page? Are cards bg-bg-default or bg-bg-elevated?text-tx-header/text-tx-strong? Body text using text-tx-primary? Weak/muted text using text-tx-weak?border-bd-default where Storybook components do? Hover states using hover:border-bd-primary?rounded-xl? Buttons using rounded-lg? Badges using rounded-full? Match what Storybook uses.w-4 h-4 or w-5 h-5 like Storybook? Using lucide-react? Color inherited from parent?transition-colors or transition-all like Storybook components?hover:bg-bg-elevated, not a custom hover color)Storybook Style Verification:
✓ Dashboard/Card.tsx — backgrounds match (bg-bg-default), radius match (rounded-xl)
⚠ Dashboard/Header.tsx — uses text-lg where Storybook headers use text-2xl font-bold
⚠ Dashboard/MetricRow.tsx — gap-2 where similar Storybook widgets use gap-3
✗ Dashboard/Sidebar.tsx — uses rounded-md where Storybook SideNav uses rounded-lg
Style match score: 85% (17/20 patterns match Storybook)
Fix any drift before finalizing. The goal is that migrated code is visually indistinguishable from what's already in Storybook.
Evidence before claims. After completion, produce:
# Migration Report: [PageName]
## Before
- Files: [count]
- Total lines: [count]
- Largest file: [name] at [lines] lines
- `any` types: [count]
- Files with direct API calls: [count]
- Test files: [count]
## After
- Files: [count]
- Total lines: [count]
- Largest file: [name] at [lines] lines
- `any` types: [count]
- Files with direct API calls: [count]
- Test files: [count]
## Storybook Replacements (Step 2)
- Raw JSX blocks replaced with Storybook component imports: [count]
- Components used: [list with import paths and story references]
- Style drift fixed: [count of class corrections to match Storybook patterns]
## Changes Made
- Services extracted: [count]
- Hooks extracted: [count]
- Components extracted: [count]
- Types fixed: [count]
- Styles fixed: [count]
- Raw Tailwind colors → semantic tokens: [count]
- Numeric spacing → named spacing: [count]
## New Storybook Components
- [list any components promoted to Storybook]
## Tests
- All characterization tests: [passing/failing — command output]
- New test files created: [count]
Save to ai_docs/migrations/YYYY-MM-DD-migrate-[pagename]-report.md.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub jakecjones/ux-harness --plugin ux-harness