Skip to content
Awesome LLM

uitk-react-to-harmony-migration

Migrate UITK React codebases to Harmony React using bundled, eval-proven workflows and a bundled component-mapping reference. Use when Codex needs to migrate a full UITK React app, convert a current screen or requested file set, choose between app-wide and current-screen migration modes, or package the Harmony migration workflow into another repository.

IDE:
claude
codex
vscode
Version:
0.0.0

UITK React to Harmony Migration

Overview

Use the bundled workflow references to drive either an app-wide UITK React migration or a current-screen migration. Default to the bundled mapping JSON unless the user explicitly provides a repo-local MAPPING_FILE override.

Choose Mode

  • Use MODE=current-screen when the request is about the current screen, current file, or a narrow requested file set.
  • Use MODE=app-wide when the request is about a full app, repo-wide migration, or a broader feature area.
  • If MODE is omitted, infer current-screen when a current file or explicit small file set is central. Otherwise infer app-wide.

Set Inputs

  • Require APP_ROOT.
  • Accept optional MODE.
  • Accept optional CURRENT_OPEN_FILE for current-screen mode.
  • Accept optional REQUESTED_FILES for extra in-scope files the developer already named.
  • Accept optional MAPPING_FILE. Use references/uitk-to-harmony-visual-mapping.json when the user does not explicitly point to a repo-local mapping file.
  • Treat the selected mapping file as authoritative for component mapping and prop drift decisions.
  • When the developer says utik or uitk, treat imports as @uhg-harmony/uitk-react. When the developer says harmony, treat imports as @uhg-harmony/react.

Run The Workflow

  • Read references/workflow-guide.md and references/workflow-manifest.json first.
  • Use the bundled mapping JSON as the source of truth unless the developer explicitly overrides it.
  • Do not read the mapping JSON whole. It is ~1.1 MB and exceeds the context window. Query it per component with jq '.[] | select(.uitkCodeComponentName=="<ComponentName>")' references/uitk-to-harmony-visual-mapping.json (or grep -A on the component name) and load only the entries in scope.
  • Do not inspect @uhg-harmony/react or @uhg-harmony/icons-react package exports (or similar package export surfaces) to infer mappings.
  • For app-wide, follow these bundled references in order:
    1. references/full-application/01-inventory-and-scope.md
    2. references/full-application/02-foundation-and-import-strategy.md
    3. references/full-application/03-straightforward-component-swaps.md
    4. references/full-application/04-ambiguous-and-structural-migrations.md
    5. references/full-application/05-verify-polish-and-handoff.md
  • For current-screen, follow references/by-screen/01-migrate-current-screen.md.
  • Keep the workflow action-oriented: inspect code, edit the workspace, verify the result, and report only the migration details that matter.

Preserve Guardrails

  • In current-screen mode, start from CURRENT_OPEN_FILE plus any REQUESTED_FILES.
  • Before editing adjacent supporting files in current-screen mode, verify that broader scope with the developer.
  • Do not turn current-screen work into a repo-wide sweep.
  • For ambiguous mappings, choose intentionally and explain why the selected Harmony component fits the actual usage.
  • For non-obvious or behavior-sensitive prop drift, collaborate with the developer instead of guessing.
  • If mapping details are missing or ambiguous, report unsupported cases or resolve them with the developer instead of silently falling back to package-export inspection.
  • Do not invent Harmony replacements for unsupported or documentation-only top-level null-mapped entries.