Sanity UI migration progress

Reports how far an @sanity/ui → v5 migration has progressed in a directory tree.

Migration model

This skill assumes a side-by-side setup:

• @sanity/ui — legacy package still on v3 or v4
• v5 alias (usually ui5) — v5 installed under a package alias, e.g. "ui5": "npm:@sanity/ui@alpha" in package.json
• Migrated components import from the alias; unmigrated ones still import from @sanity/ui

Both can coexist during a gradual, per-component migration.

When to use

• User asks for migration progress, status, or coverage
• After a migration batch — compare to a saved baseline
• CI or periodic snapshots (run the script, commit or archive output)

Quick start

Run the script from the repo root (paths below are relative to it).

All components in progress (any component with a v5 import):

bash .agents/skills/sanity-ui-migration-progress/scripts/measure-progress.sh <dir> [v5-alias] [@sanity/ui]

Specific component(s) (including before migration has started):

bash .agents/skills/sanity-ui-migration-progress/scripts/measure-progress.sh <dir> --component Flex
bash .agents/skills/sanity-ui-migration-progress/scripts/measure-progress.sh <dir> --component Box --component Flex

Detect alias when unsure:

rg -o '"([^"]+)":\s*"npm:@sanity/ui@' package.json -r '$1'

If the default ui5 finds no imports, the script auto-detects the alias from the nearest package.json at or above <dir>, then from any package.json below it.

Scope matters. Counts depend on the directory passed — scanning a subdirectory vs repo root (.) can differ when ui5 imports exist in multiple packages or apps. Always state the directory used in the report.

Choosing scope

Infer the directory from what the user says — do not default to a subdirectory unless they name one.

In monorepos, ui5 imports often live in several packages or apps — scanning only the main library undercounts repo-wide progress.

Workflow

- [ ] 1. Confirm directory, v5 alias, and optional component name(s)
- [ ] 2. Run measure-progress.sh
- [ ] 3. Present the table + call out partial components

Step 1 — Confirm scope

Ask or infer (see Choosing scope above):

Step 2 — Run the script

All in-progress components (repo-wide):

bash .agents/skills/sanity-ui-migration-progress/scripts/measure-progress.sh . ui5

Scoped to a subdirectory:

bash .agents/skills/sanity-ui-migration-progress/scripts/measure-progress.sh src/ ui5

One component:

bash .agents/skills/sanity-ui-migration-progress/scripts/measure-progress.sh <dir> ui5 --component Flex

If the user names a component, always pass --component — do not rely on discover mode.

If discover mode finds no v5 imports, report that and stop — do not attempt to install anything:

• No alias in package.json — the repo has no v5 side-by-side setup; nothing to measure
• Alias present, no imports — setup exists but migration has not started (or the directory is too narrow). Suggest --component <Name> to measure legacy usage for a specific component.

Example output columns:

The component list comes from v5 imports (discover mode) or from --component flags. Discover mode omits components not yet on v5; --component always reports the named component(s).

Step 3 — Present results

Summarize in plain language:

1. Fully migrated — leg imp = 0 and jsx unm = 0
2. In progress — v5 imports exist but legacy imports or JSX remain

Discover mode only lists components with at least one v5 import — everything in the table has migration started. Components still entirely on @sanity/ui do not appear unless the user passed --component.

Use this template:

## Migration progress: `<dir>`

**Scope:** `<dir>` · v5 alias `ui5` · `<date>`

| Component | v5 files | legacy files | JSX migrated | JSX remaining | JSX % |
| --------- | -------- | ------------ | ------------ | ------------- | ----- |
| …         | …        | …            | …            | …             | …     |

**Fully migrated:** …
**In progress:** …

Limitations

This skill reports only — it does not install dependencies or run migrations. If v5 is not present, say so and stop.