update migration skill

Author: reidbarber

packages/dev/s2-docs/migration-references/focused-app-setup.md

@@ -1,37 +1,132 @@
 # Manual fixes after the codemod
 
-## Known gaps to handle explicitly
+## Icons and illustrations
 
-- `@react-spectrum/toast` imports are not automatically migrated. Move them to S2, then re-check `ToastContainer` mounts and `ToastQueue` usages.
-- v3 `Provider` and `defaultTheme` wrappers in apps and tests need human review. S2 does not use the v3 theme object model.
+- If the codemod leaves `TODO(S2-upgrade)` next to an icon or illustration import, pick the nearest S2 replacement manually.
 
-## Imports and packages
+## Layout components
 
-- Collapse v3 component imports onto `@react-spectrum/s2`.
-- Keep using `@spectrum-icons/*` only when there is no S2 icon or illustration equivalent. Prefer `@react-spectrum/s2/icons/*` and `@react-spectrum/s2/illustrations` when possible.
-- If the codemod leaves `TODO(S2-upgrade)` next to an icon or illustration import, pick the nearest S2 replacement manually.
+`Flex`, `Grid`, `View`, and `Well` are not part of S2. These should be updated to `div` elements styled with the macro.
+
+### Flex example
+
+Before:
+
+```jsx
+<Flex direction="column">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</Flex>
+```
+
+After:
+
+```jsx
+<div className={style({display: 'flex', flexDirection: 'column'})}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+### Grid example
+
+Before:
+
+```jsx
+<Grid justifyContent="center">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</Grid>
+```
+
+After:
 
-## App and Provider setup
+```jsx
+<div className={style({display: 'grid', justifyContent: 'center'})}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
 
-- Full-page apps usually add `import '@react-spectrum/s2/page.css';` at the entrypoint and no longer need a mandatory root Provider just to supply `theme={defaultTheme}`.
-- Embedded sections still use S2 `Provider` with an explicit `background`.
-- Keep or add S2 `Provider` only when locale, router integration, color-scheme/background overrides, or SSR `elementType="html"` behavior are needed.
-- Preserve unrelated wrappers such as routing, store, analytics, i18n, and host-framework providers. Replace or remove only the React Spectrum-specific layer.
+### View example
 
-## Style and layout follow-ups
+Before:
 
-- Convert v3 style props and `UNSAFE_style` cases to the S2 style macro when possible.
-- `Flex` and `Grid` often become `div` elements styled with the macro.
-- Review `ClearSlots` and other direct `@react-spectrum/utils` imports manually. These are not part of the common S2 app surface.
+```jsx
+<View>
+  Content
+</View>
+```
+
+After:
+
+```jsx
+<div>
+  Content
+</div>
+```
+### Well example
+
+Before:
+
+```jsx
+<Well>
+  Content
+</Well>
+```
+
+After:
+
+```jsx
+<div className={style({
+  display: 'block',
+  textAlign: 'start',
+  padding: 16,
+  minWidth: 160,
+  marginTop: 4,
+  borderWidth: 1,
+  borderRadius: 'sm',
+  borderStyle: 'solid',
+  borderColor: 'transparent-black-75',
+  font: 'body-sm'
+})}>
+  Content
+</div>
+```
+
+## UNSAFE_style and UNSAFE_className
+
+Move `UNSAFE_style` usage to the S2 style macro when possible.
+
+Move `UNSAFE_className` usage to the S2 style macro when possible.
 
 ## Dialogs and collections
 
 - `DialogContainer` and `useDialogContainer` still exist in S2, but the import path changes and dismiss logic may need to move between `Dialog`, `DialogTrigger`, and `DialogContainer`.
-- When `Item` survives the codemod, rename it based on its parent: `MenuItem`, `PickerItem`, `ComboBoxItem`, `ListBoxItem`, `Tab`, `TabPanel`, `Tag`, `Breadcrumb`, and similar.
+- When `Item` survives the codemod, rename it based on its parent component:
+
+  | Parent component | v3 child | S2 child |
+  |---|---|---|
+  | Menu / ActionMenu | Item | MenuItem |
+  | Picker | Item | PickerItem |
+  | ComboBox | Item | ComboBoxItem |
+  | ListBox | Item | ListBoxItem |
+  | Tabs | Item | Tab / TabPanel |
+  | TagGroup | Item | Tag |
+  | Breadcrumbs | Item | Breadcrumb |
+
 - Preserve React `key` when mapping arrays, but ensure collection data items expose `id` when S2 expects it.
 - Table and ListView migrations often need manual review for row headers, nested columns, and explicit item ids.
 
-## Tests
+## Toast migration
 
-- Replace v3 Provider/defaultTheme test wrappers with the minimal S2 `Provider` props the test actually needs, or remove the wrapper entirely if no S2 context is required.
-- Update toast mocks and assertions that still reference `@react-spectrum/toast` or old dialog markup.
+- Move `ToastContainer` and `ToastQueue` imports from `@react-spectrum/toast` to `@react-spectrum/s2`.
+- Keep a shared `ToastContainer` mounted near the app root or test harness, then update all queue calls to use the S2 import path.
+- S2 supports `ToastQueue.neutral`, `positive`, `negative`, and `info`.
+- Re-check options such as `timeout`, `actionLabel`, `onAction`, `shouldCloseOnAction`, and `onClose` after the import move.
+- The queue methods still return a close function. Keep programmatic dismissal logic when the existing UX depends on it.
+- Search for every `ToastContainer` mount and every `ToastQueue` usage after moving imports. Shared app roots, secondary entrypoints, and test harnesses are easy to miss.

packages/dev/s2-docs/migration-references/focused-manual-fixes.md

@@ -0,0 +1,23 @@
+# Inspection checklist
+
+## Minimum tool versions
+
+These tools are not all strictly required, but if the project uses them they must be at these minimum versions to avoid issues with the `with {type: 'macro'}` import syntax:
+
+- **TypeScript 5.3+** — required for the import attributes syntax (`with {type: 'macro'}`).
+- **Babel 7.27.0+** or the `@babel/plugin-syntax-import-attributes` plugin — enables Babel to parse import attributes. Alternatively, `@babel/preset-env` with `shippedProposals: true` also enables import attribute parsing.
+- **ESLint 9.14.0+** with `@typescript-eslint/parser`.
+- **Prettier 3.1.1+** — needed to format `with {type: 'macro'}` import syntax correctly.
+
+## What to look for
+
+- Search package manifests and source for `@adobe/react-spectrum`, `@react-spectrum/*`, and `@spectrum-icons/*`.
+- In monorepos or mixed-tooling repos, inspect the target package or app first instead of assuming the root manifest represents the runtime target being migrated.
+- Determine the package manager from the relevant lockfile or workspace setup.
+- Detect the bundler at the migration target level. The workspace root may include Storybook, Vite, or other tooling that does not represent the runtime bundler for the package being migrated.
+  - **Parcel v2.12.0+** already supports S2 style macros natively.
+  - **Vite, webpack, Next.js, Rollup, ESBuild** and similar toolchains need `unplugin-parcel-macros`. Keep plugin ordering correct so macros run before the rest of the toolchain.
+  - If the repo already has a framework-specific S2 or macro setup, preserve it instead of layering a second macro configuration on top.
+- Find **all** app entrypoints, including standalone pages, alternate render roots, embedded sub-apps, utility apps, and test-only render targets. Do not assume there is only one entry.
+- Locate root providers, shared test wrappers, toast setup, and any direct `defaultTheme` usage.
+- Search for `ToastContainer`, `ToastQueue`, `DialogContainer`, `useDialogContainer`, `ClearSlots`, style props, and `UNSAFE_style`. These are common follow-up areas after the codemod.