@tamagui/cli 3.0.0-beta.924.1 → 3.0.0

package/src/icons.ts

@@ -0,0 +1,308 @@
+// `tamagui icons add`: writes one themed react-native-svg component per icon,
+// plus an index of every component in the output dir. sources are pinned
+// upstream releases fetched from unpkg, or a local dir of svg files.
+
+import { existsSync, statSync } from 'node:fs'
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import chalk from 'chalk'
+
+// pinned so a cli release only changes output when these move
+export const LUCIDE_VERSION = '1.49.0'
+export const HEROICONS_VERSION = '2.2.0'
+export const PHOSPHOR_VERSION = '2.1.1'
+
+const libraries = ['lucide', 'heroicons', 'phosphor'] as const
+type Library = (typeof libraries)[number]
+
+const phosphorWeights = ['regular', 'bold', 'duotone', 'fill', 'light', 'thin']
+// heroicons ships outline only at 24px; solid at 24px, mini at 20px, micro at 16px
+const heroiconsDirs: Record<string, string> = {
+  outline: '24/outline',
+  solid: '24/solid',
+  mini: '20/solid',
+  micro: '16/solid',
+}
+
+export type AddIconsOptions = {
+  names: string[]
+  // a library name, or a dir holding <kebab-name>.svg files
+  from?: string
+  weight?: string
+  variant?: string
+  out?: string
+  cwd?: string
+}
+
+export async function addIcons(options: AddIconsOptions) {
+  const cwd = options.cwd ?? process.cwd()
+  const from = options.from ?? 'lucide'
+  const outDir = path.resolve(cwd, options.out ?? 'components/icons')
+  const localDir = libraries.includes(from as Library) ? null : path.resolve(cwd, from)
+
+  if (localDir && !(existsSync(localDir) && statSync(localDir).isDirectory())) {
+    throw new Error(
+      `--from must be ${libraries.join(', ')}, or a directory of svg files (got "${from}")`
+    )
+  }
+  if (!options.names.length) {
+    throw new Error('give the icons to add, e.g. `tamagui icons add Search ChevronDown`')
+  }
+  if (options.weight && from !== 'phosphor') {
+    throw new Error('--weight applies to phosphor only')
+  }
+  if (options.weight && !phosphorWeights.includes(options.weight)) {
+    throw new Error(`--weight is one of ${phosphorWeights.join(', ')}`)
+  }
+  if (options.variant && from !== 'heroicons') {
+    throw new Error('--variant applies to heroicons only')
+  }
+  if (options.variant && !heroiconsDirs[options.variant]) {
+    throw new Error(`--variant is one of ${Object.keys(heroiconsDirs).join(', ')}`)
+  }
+
+  // `Search=magnifying-glass` keeps the component name while drawing another
+  // source icon, so a set can switch libraries without touching its imports
+  const icons = [...new Set(options.names)].map((arg) => {
+    const [name, source = name] = arg.split('=')
+    const isKebab = (x: string) => /^[a-z0-9-]+$/.test(x)
+    const isPascal = (x: string) => /^[A-Z][A-Za-z0-9]*$/.test(x)
+    if (
+      !(isKebab(name) || isPascal(name)) ||
+      !(isKebab(source) || isPascal(source)) ||
+      (source !== name && !isPascal(name))
+    ) {
+      throw new Error(
+        `icon names are PascalCase, kebab-case, or Name=source-name, got "${arg}"`
+      )
+    }
+    return {
+      componentName: isKebab(name) ? kebabToPascal(name) : name,
+      file: isKebab(source) ? source : pascalToKebab(stripIconSuffix(source)),
+    }
+  })
+
+  const loaded = await Promise.all(
+    icons.map(async (icon) => {
+      if (localDir) {
+        const file = path.join(localDir, `${icon.file}.svg`)
+        return { ...icon, svg: existsSync(file) ? await readFile(file, 'utf-8') : null }
+      }
+      const url = sourceUrl(from as Library, icon.file, options)
+      const response = await fetch(url)
+      if (response.status === 404) return { ...icon, svg: null }
+      if (!response.ok) {
+        throw new Error(`fetching ${url} failed (${response.status})`)
+      }
+      return { ...icon, svg: await response.text() }
+    })
+  )
+
+  const unknown = loaded.filter((icon) => icon.svg === null)
+  if (unknown.length) {
+    throw new Error(
+      `unknown ${from} icon${unknown.length === 1 ? '' : 's'}: ${unknown
+        .map((icon) => `${icon.componentName} (${icon.file}.svg)`)
+        .join(', ')}`
+    )
+  }
+
+  await mkdir(outDir, { recursive: true })
+  for (const icon of loaded) {
+    const file = path.join(outDir, `${icon.componentName}.tsx`)
+    await writeFile(file, svgToComponent(icon.componentName, icon.svg!))
+    console.info(`${chalk.green('wrote')} ${path.relative(cwd, file)}`)
+  }
+
+  // the index lists every component in the dir, so repeated adds accumulate
+  const components = (await readdir(outDir))
+    .filter((file) => file.endsWith('.tsx'))
+    .map((file) => file.slice(0, -'.tsx'.length))
+    .sort()
+  await writeFile(
+    path.join(outDir, 'index.ts'),
+    components.map((name) => `export { ${name} } from './${name}'`).join('\n') + '\n'
+  )
+  console.info(
+    `${chalk.green('wrote')} ${path.relative(cwd, path.join(outDir, 'index.ts'))} (${components.length} icons)`
+  )
+}
+
+function sourceUrl(library: Library, file: string, options: AddIconsOptions) {
+  switch (library) {
+    case 'lucide':
+      return `https://unpkg.com/lucide-static@${LUCIDE_VERSION}/icons/${file}.svg`
+    case 'heroicons':
+      return `https://unpkg.com/heroicons@${HEROICONS_VERSION}/${heroiconsDirs[options.variant ?? 'outline']}/${file}.svg`
+    case 'phosphor': {
+      const weight = options.weight ?? 'regular'
+      const name = weight === 'regular' ? file : `${file}-${weight}`
+      return `https://unpkg.com/@phosphor-icons/core@${PHOSPHOR_VERSION}/assets/${weight}/${name}.svg`
+    }
+  }
+}
+
+function pascalToKebab(name: string) {
+  return name
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Za-z])(\d)/g, '$1-$2')
+    .toLowerCase()
+}
+
+function kebabToPascal(name: string) {
+  return name
+    .split('-')
+    .map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part))
+    .join('')
+}
+
+// one trailing Icon is dropped for the lookup only: HeartIcon finds heart
+function stripIconSuffix(name: string) {
+  return name.endsWith('Icon') && name.length > 4 ? name.slice(0, -4) : name
+}
+
+type SvgNode = {
+  tag: string
+  attrs: [name: string, value: string][]
+  children: SvgNode[]
+}
+
+// upstream icon files are machine-written and shallow; this handles nesting so
+// a grouped source never drops shapes
+function parseSvg(svg: string): SvgNode {
+  const root: SvgNode = { tag: '', attrs: [], children: [] }
+  const stack = [root]
+  const tagPattern = /<(\/?)([A-Za-z][A-Za-z0-9]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)(\/?)>/g
+  for (const [, closing, tag, attrText, selfClose] of svg
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .matchAll(tagPattern)) {
+    if (closing) {
+      if (stack.pop()?.tag !== tag) throw new Error(`mismatched </${tag}> in svg`)
+      continue
+    }
+    const node: SvgNode = { tag, attrs: [], children: [] }
+    for (const [, name, double, single] of attrText.matchAll(
+      /([A-Za-z_:][A-Za-z0-9_.:-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g
+    )) {
+      node.attrs.push([name, double ?? single])
+    }
+    stack[stack.length - 1].children.push(node)
+    if (!selfClose) stack.push(node)
+  }
+  const svgNode = root.children.find((node) => node.tag === 'svg')
+  if (stack.length !== 1 || !svgNode)
+    throw new Error('svg source has no complete <svg> root')
+  return svgNode
+}
+
+const elements: Record<string, string> = {
+  path: 'Path',
+  circle: 'Circle',
+  ellipse: 'Ellipse',
+  line: 'Line',
+  polyline: 'Polyline',
+  polygon: 'Polygon',
+  rect: 'Rect',
+  g: 'G',
+  defs: 'Defs',
+  clipPath: 'ClipPath',
+  linearGradient: 'LinearGradient',
+  radialGradient: 'RadialGradient',
+  stop: 'Stop',
+  use: 'Use',
+}
+
+// globals a component name would shadow; oxlint/eslint flag these
+const restrictedNames = ['Infinity', 'NaN', 'undefined']
+
+export function svgToComponent(name: string, svg: string) {
+  const root = parseSvg(svg)
+  const used = new Set<string>()
+  const ref = (element: string) => (element === name ? `_${element}` : element)
+
+  const jsxAttr = (attrName: string, value: string) => {
+    if (attrName === 'style') {
+      throw new Error(`${name}: style attributes have no react-native-svg equivalent`)
+    }
+    const prop =
+      attrName === 'xlink:href'
+        ? 'href'
+        : attrName.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())
+    return value === 'currentColor' ? `${prop}={color}` : `${prop}="${value}"`
+  }
+  const keepAttr = ([attrName]: [string, string]) =>
+    !(
+      attrName === 'xmlns' ||
+      attrName.startsWith('xmlns:') ||
+      attrName === 'class' ||
+      attrName === 'version' ||
+      attrName.startsWith('data-') ||
+      attrName.startsWith('aria-')
+    )
+
+  const rootAttrs = root.attrs.filter(keepAttr)
+  const viewBox = rootAttrs.find(([attrName]) => attrName === 'viewBox')?.[1]
+  if (!viewBox) throw new Error(`${name}: svg source has no viewBox`)
+  // native draws children with their own stroke, so a currentColor stroke on
+  // the root is repeated on each child that has none
+  const rootStroke = rootAttrs.some(
+    ([attrName, value]) => attrName === 'stroke' && value === 'currentColor'
+  )
+  const strokeWidth = rootAttrs.find(([attrName]) => attrName === 'stroke-width')?.[1]
+
+  const emit = (node: SvgNode, indent: string): string => {
+    const element = elements[node.tag]
+    if (!element) throw new Error(`${name}: unsupported svg element <${node.tag}>`)
+    used.add(element)
+    const attrs = node.attrs.filter(keepAttr).map(([n, v]) => jsxAttr(n, v))
+    if (rootStroke && !node.attrs.some(([n]) => n === 'stroke') && node.tag !== 'g') {
+      attrs.push('stroke={color}')
+    }
+    const open = `${indent}<${ref(element)}${attrs.map((attr) => ` ${attr}`).join('')}`
+    if (!node.children.length) return `${open} />`
+    return `${open}>\n${node.children.map((child) => emit(child, `${indent}  `)).join('\n')}\n${indent}</${ref(element)}>`
+  }
+
+  const children = root.children.map((child) => emit(child, '        '))
+  if (!children.length) throw new Error(`${name}: svg source draws nothing`)
+
+  const svgAttrs = [
+    'width={size}',
+    'height={size}',
+    ...rootAttrs
+      .filter(([attrName]) => attrName !== 'width' && attrName !== 'height')
+      .map(([attrName, value]) => jsxAttr(attrName, value)),
+    '{...otherProps}',
+  ]
+  const imports = [...used]
+    .sort()
+    .map((element) => (element === name ? `${element} as _${element}` : element))
+  const themedOptions =
+    strokeWidth && strokeWidth !== '2' ? `, { defaultStrokeWidth: ${strokeWidth} }` : ''
+
+  // the explicit component type lets isolatedDeclarations builds emit types.
+  // themed resolves theme and token values before the inner component runs, so
+  // it reads plain svg values rather than the app's token-typed IconProps
+  return `${restrictedNames.includes(name) ? '/* eslint-disable no-shadow-restricted-names */\n' : ''}import { memo, type JSX } from 'react'
+import { Svg, ${imports.join(', ')}, type SvgProps } from 'react-native-svg'
+import { themed, type IconProps } from '@tamagui/helpers-icon'
+
+export const ${name}: (props: IconProps) => JSX.Element = themed(
+  memo(function ${name}(props: IconProps) {
+    const { color = 'black', size = 24, ...otherProps } = props as SvgProps & {
+      color?: string
+      size?: number
+    }
+    return (
+      <Svg
+${svgAttrs.map((attr) => `        ${attr}`).join('\n')}
+      >
+${children.join('\n')}
+      </Svg>
+    )
+  })${themedOptions}
+)
+`
+}

package/src/migrate.ts

@@ -48,6 +48,26 @@ Work like a careful coding agent:
 
 const v2ToV3Prompt = `## v2 -> v3 migration prompt
 
+### 0. Choose the intermediate checkpoint before editing
+
+The Tamagui package version and the config version are separate. Tamagui V3
+supports Config v5; upgrading the runtime does not require Config v6.
+
+- Coming from V2: first reach V3 packages and APIs with the app's existing token, theme, font, media, and animation values. Keep custom config values. If an old config entry is no longer exported, preserve its resolved values in an app-owned config; do not substitute v6 defaults.
+- Coming from Config v5 or v5-subtle: keep that config during the V3 API upgrade. Keep the 12-step adaptive colors, spacing, radii, font scales, and breakpoint meanings. Do not remap them to the v6 scale.
+- Already running V3 with Config v5: this intermediate checkpoint is valid. Inventory remaining V2 APIs before applying codemods; do not repeat completed work or treat Config v5 as an upgrade failure.
+- Do not combine this pass with wholesale \`html.*\` adoption, Tailwind conversion, new skins, or a theme redesign unless separately requested.
+
+Record the starting package/config versions and representative light/dark,
+responsive, and native screenshots. Name the intended checkpoint in the plan:
+"V3 API, existing design values." Visual changes during this pass need an
+explanation or a fix, not automatic screenshot acceptance.
+
+The checkpoint is complete when the required API migration, report review,
+typecheck/build, and real app checks in step 15 pass. Leave Config v6 and other
+optional design changes in a separate follow-up; do not start them just because
+the V3 API work is finished.
+
 ### 1. Update dependencies
 
 - Bump every \`tamagui\` and \`@tamagui/*\` package together to v3.
@@ -64,8 +84,10 @@ V3 accepts bare token/theme names and flat clauses only. Run the transactional
 flat-values codemod from your project root, dry run first:
 
 \`\`\`bash
-npx @tamagui/codemod-flat-values --report flat-values-report.md ./src
+npx @tamagui/codemod-flat-values --source-semantics v2-pixels \\
+  --report flat-values-report.md ./src
 npx @tamagui/codemod-flat-values --write \\
+  --source-semantics v2-pixels \\
   --report flat-values-report.md \\
   --json flat-values-report.json \\
   ./src
@@ -86,46 +108,22 @@ becomes:
 Resolve every report row and rerun until the app has no V2 authoring. Do not
 add a compatibility setting or restore condition-object parsing.
 
-### 3. Migrate config and themes
+### 3. Preserve config values while migrating required APIs
 
-- New applications should use \`defaultConfig\` from \`@tamagui/config/v6\`.
-- Existing V5 applications can keep \`@tamagui/config/v5\` or \`/v5-subtle\` while migrating incrementally. These are frozen static compatibility packs, so they preserve the V5 token and theme values but will not receive new theme-builder features.
+- Existing Config v5 applications should keep \`@tamagui/config/v5\` or \`/v5-subtle\` while migrating incrementally. These are frozen static compatibility packs, so they preserve the V5 token and theme values but will not receive new theme-builder features.
 - Import animations from \`@tamagui/config/animations-css\`, \`animations-rn\`, \`animations-reanimated\`, or \`animations-motion\`.
 - Apps using Sheet or animated-number hooks with the CSS driver must import \`createAnimations\` from \`@tamagui/animations-css/extras\`. The root entry omits those hooks.
-- Remove \`@tamagui/theme-builder\` and any V5 builder imports. Static \`@tamagui/themes/v5\`, \`/v5-subtle\`, and \`/v5-tokens\` imports remain supported.
-- An app that GENERATES its v5 themes (\`createV5Theme\`, \`subtleChildrenThemes\`, \`createPalettes\`) has two ways to stay on v5 for this migration: run the builder once and serialize the result to a static literal, or import the same builders from \`@tamagui/config-v5\` (and \`@tamagui/config-v5/builder\`), the opt-in package that carries them. Take one of those when the themes are built from values the app only knows at runtime; the v6 recipe move below is a separate migration.
-- Use \`createThemes\`, \`levels\`, scales, and the other recipe helpers from \`@tamagui/themes/builder\`.
-- Remove \`componentThemes\`, \`templates\`, \`masks\`, \`childrenThemes\`, and \`grandChildrenThemes\`. Express hierarchy in the recipe tree, semantic values in scales, and exact one-theme overrides in \`values\`.
+- Remove \`@tamagui/theme-builder\` and V5 builder imports from packages that no longer export them. Static \`@tamagui/themes/v5\`, \`/v5-subtle\`, and \`/v5-tokens\` imports remain supported.
+- An app that GENERATES its v5 themes (\`createV5Theme\`, \`subtleChildrenThemes\`, \`createPalettes\`) has two ways to stay on v5 for this migration: run the builder once and serialize the result to a static literal, or import the same builders from \`@tamagui/config-v5\` (and \`@tamagui/config-v5/builder\`), the opt-in package that carries them. Take one of those when the themes are built from values the app only knows at runtime; the optional v6 recipe move in the appendix is a separate migration.
 - Component names no longer select uppercase theme segments automatically. Replace component themes with explicit normal theme or \`level2\` boundaries in component skins.
 
-Rename the adaptive 12-step ramp approximately:
-
-- \`color1\` -> \`color1\`
-- \`color2\` -> \`color2\`
-- \`color3\` -> \`color3\`
-- \`color4\` -> \`color4\`
-- \`color5\` -> \`color5\`
-- \`color6\` and \`color7\` -> \`color6\`
-- \`color8\` -> \`color7\`
-- \`color9\` -> \`color8\`
-- \`color10\` -> \`color9\`
-- \`color11\` -> \`color10\`
-- \`color12\` -> \`color11\`
-
-The endpoints are exact; inspect contrast in the compressed middle. Replace
-\`surface1\` with \`level2\`, \`surface2\` with \`level3\`, and \`surface3\`
-or \`surface4\` with \`level4\`. Levels are relative and preserve a surrounding
-color theme when nested.
-
-Search the config and application together:
-
-\`\`\`bash
-rg "@tamagui/theme-builder|v5-builder|createV5Theme|componentThemes|grandChildrenThemes|surface[1-4]|color12"
-\`\`\`
+Do not apply the v6 color remap or recipe conversion in the optional appendix
+while keeping Config v5. Reserved API/theme-key spelling changes still apply;
+preserve the resolved values behind the renamed keys.
 
 ### 4. Migrate Sheet anatomy
 
-The flat-values codemod from step 1 rewrites every provable \`Sheet.Frame\` to
+The flat-values codemod from step 2 rewrites every provable \`Sheet.Frame\` to
 \`Sheet.Container\` with a \`Sheet.Background\` first child carrying the surface
 props, and reports spreads and \`styled(Sheet.Frame, …)\` targets for review.
 Check each rewritten callsite against these rules:
@@ -165,7 +163,7 @@ After:
 Search:
 
 \`\`\`bash
-rg "focusable|fullscreen|themeInverse|<Theme inverse|Sheet\\.Frame|styleable\\(|inlineWhenUnflattened|\\$true|getTokenRelative|stepTokenUpOrDown|forceRemoveScrollEnabled|sizeAdjust|getExpandedShorthands|usePropsAndStyle|useProps|useStyle"
+rg "focusable|fullscreen|themeInverse|<Theme inverse|Sheet\\.Frame|styleable\\(|inlineWhenUnflattened|\\$true|getTokenRelative|stepTokenUpOrDown|forceRemoveScrollEnabled|sizeAdjust|getExpandedShorthands|usePropsAndStyle|useProps|useStyle|Unspaced|spacedChildren"
 \`\`\`
 
 Replace:
@@ -184,6 +182,8 @@ Replace:
 - \`createCheckbox\` \`sizeAdjust\` -> explicit sizing math or component styles.
 - \`getExpandedShorthands\` -> \`getExpandedShorthand(key, props)\` when behavior code needs one authored prop and must accept its configured shorthand.
 - \`useProps\`, \`useStyle\`, and \`usePropsAndStyle\` -> keep conditional values on styled Tamagui components; use \`splitStyleProps\` only when a wrapper must partition authored props.
+- \`<Unspaced>\` -> its children, and \`spacedChildren\` -> \`gap\`: stacks no longer insert spacers.
+- a \`theme\`, handler, or other non-style key inside \`variants\` -> set it on a wrapper one level up. Variants hold styles and aria/data attributes only; type checking flags the rest.
 
 V2 could spread one style across its base prop, pseudo-style objects, media
 objects, and platform objects. The removed hooks gathered those separate
@@ -235,12 +235,14 @@ const padding = getVariableValue(getSize(size)) * 0.6
 
 Use explicit token keys when you need a named smaller or larger token. Use numeric multiplication when proportional sizing is intended.
 
-### 8. Audit font size values
+### 8. Migrate line heights and audit font size values
 
 - \`fontSize={17}\` is a raw numeric platform value and keeps platform-default line-height behavior.
 - \`fontSize="17px"\` is an exact pixel value.
-- Configured font \`size\` and \`lineHeight\` tokens should use px strings when exact web pixels are intended.
-- Convert custom config font tokens to px strings if exact pixels were intended.
+- V3 interprets numeric Tamagui \`lineHeight\` props as ratios on web and native. The flat-values command above explicitly selects \`v2-pixels\`, so old numeric Tamagui styles become px strings, including values below 4.
+- Keep raw React Native and Restyle numeric styles unchanged. Review every \`ambiguous-line-height-*\` report entry where a shared object, untyped expression, or extracted token value needs a boundary-specific decision.
+- Configured font \`lineHeight\` numbers remain absolute pixels. Numeric strings such as \`"1.5"\` are ratios, while \`"24px"\` is explicit. The codemod does not rewrite font configuration.
+- Rerun the codemod with the same source semantics until it reports no remaining line-height work. Explicit px output is idempotent.
 
 ### 9. Update FocusScope
 
@@ -299,6 +301,9 @@ Replace unsupported old web/lite usage such as momentum events, \`snapTo*\`, and
 
 ### 14. Optional Tailwind frontend
 
+Skip this in the intermediate V3 API checkpoint unless Tailwind adoption was
+separately requested. It does not require changing the whole app to Config v6.
+
 Tailwind authoring is selected by the component package, with no global config:
 
 \`\`\`tsx
@@ -309,15 +314,69 @@ Keep importing regular Tamagui components from \`tamagui\` or
 \`@tamagui/core\`. Do not mix utility classes and Tamagui style props on the
 same component; choose the import whose styling language that component uses.
 
+### Required API follow-ups
+
+- Transition values: replace arrays with \`{ preset: 'quick', opacity: 'lazy' }\`, rename the transition object's \`default\` to \`preset\`, and place physics under \`spring\`. Move \`animateOnly\` into \`transition.properties\`. Read the upgrade guide's transition section before converting driver-specific options.
+- Groups and containers: \`group="card"\` enables \`group-hover/card:\` and other group states. Size queries require \`container="card"\` and use \`@sm/card:\`; a group alone no longer enables container measurement.
+- Control sizes: Config v6 uses \`xs | sm | md | lg | xl\` (default \`md\`). Keep numeric token keys while retaining Config v5, then map control sizes when separately adopting v6. Shape and icon geometry still uses size tokens or numbers.
+- Remove top-level \`createTamagui({ defaultProps })\`. Put default styles in \`styled()\` definitions and inherited non-style defaults in \`Component.Props\`.
+- Toast: replace \`useToastController().show(title, { message })\` with \`toast(title, { description: message })\`. Import \`Toast\` and \`toast\` from \`tamagui/toast\`; mount \`Toast.Root\` and \`Toast.List\` with the desired parts once in the app. The old provider/controller API is removed.
+- Replace \`ThemeableStack\` and \`SizableStack\` with \`YStack\` or \`XStack\` plus explicit styles; use \`elevation\` for elevation and border width/color for borders.
+- Checked/selected states: Checkbox, Switch, Tabs and ToggleGroup read \`background-press\`; customize \`activeStyle\` to override it per instance. Audit the resulting active background against the previous app and customize its theme or skin where needed.
+
 ### 15. Verification
 
-- Run \`npx tamagui check\`.
+- Run \`npx tamagui check --strict\`.
 - Run typecheck and build.
 - Start the app and manually test screens using Sheet, Dialog, Popover, Select, FocusScope, icons, and ScrollView.
 - Test Adapt breakpoints where popovers/selects/dialogs become sheets.
 - Verify keyboard focus, Escape, outside click, scroll locking, and close animations.
 - Inspect icon alignment next to text at each app size token.
-- If the Tailwind frontend is used, compare web and native output for the classes used.`
+- If the Tailwind frontend is used, compare web and native output for the classes used.
+- Compare the same screens and resolved control dimensions with the baseline. Keeping Config v5 preserves the scales, but does not prove that changed component APIs preserve every layout.
+- Report the final package version, retained config, manual fixes, runtime evidence, and deferred optional work. A validated V3 app on Config v5 is a completed migration.
+
+### Optional follow-up: Config v6, only when separately requested
+
+This appendix is not part of the intermediate V3 API checkpoint. Start a new
+reviewable change after that checkpoint is validated. Record new visual
+acceptance criteria before changing design values.
+
+- New apps can start with \`defaultConfig\` from \`@tamagui/config/v6\`.
+- For an existing app, inventory and compare resolved spacing, size, radius, font, icon, and media values. Map by resolved value when preserving appearance; the same token name can mean a different number in v6.
+- Preserve breakpoint meaning: changing a max-width key to a min-width key can invert responsive behavior.
+
+- Use \`createThemes\`, \`levels\`, scales, and the other recipe helpers from \`@tamagui/themes/builder\`.
+- Remove \`componentThemes\`, \`templates\`, \`masks\`, \`childrenThemes\`, and \`grandChildrenThemes\`. Express hierarchy in the recipe tree, semantic values in scales, and exact one-theme overrides in \`values\`.
+
+Rename the adaptive 12-step ramp approximately:
+
+- \`color1\` -> \`color-1\`
+- \`color2\` -> \`color-2\`
+- \`color3\` -> \`color-3\`
+- \`color4\` -> \`color-4\`
+- \`color5\` -> \`color-5\`
+- \`color6\` and \`color7\` -> \`color-6\`
+- \`color8\` -> \`color-7\`
+- \`color9\` -> \`color-8\`
+- \`color10\` -> \`color-9\`
+- \`color11\` -> \`color-10\`
+- \`color12\` -> \`color-11\`
+
+The endpoints are exact; inspect contrast in the compressed middle. Replace
+\`surface1\` with \`level2\`, \`surface2\` with \`level3\`, and \`surface3\`
+or \`surface4\` with \`level4\`. Levels are relative and preserve a surrounding
+color theme when nested.
+
+Search the config and application together:
+
+\`\`\`bash
+rg "@tamagui/theme-builder|v5-builder|createV5Theme|componentThemes|grandChildrenThemes|surface[1-4]|color12"
+\`\`\`
+
+Validate the config change separately with light/dark screenshots, responsive
+layouts, text and icon alignment, and every platform the app ships. Do not
+accept visual drift merely because the codemod and typecheck are green.`
 
 const v1ToV2Prompt = `## v1 -> v2 migration pass
 
@@ -331,12 +390,12 @@ Bring the app to the v2 baseline before applying v3 changes.
 
 ### Config
 
-- Move to \`@tamagui/config/v6\`.
+- Preserve the app's existing token, theme, font, and breakpoint values while reaching the v2 API baseline. Keep supported Config v5 imports or serialize the old generated config into app-owned values when an entry is no longer exported. Config v6 is a separate optional migration after the v3 checkpoint below.
 - Import animations separately from \`@tamagui/config/animations-css\`, \`animations-rn\`, \`animations-reanimated\`, or \`animations-motion\`.
 - Move root \`createTamagui\` settings into \`settings\`.
 - Account for the defaults \`flexBasis: 0\` and \`position: static\`. Use \`styleCompat: 'legacy'\` or explicit props if needed.
 - Rename media queries: \`$2xl\` -> \`$xxl\`, \`$2xs\` -> \`$xxs\`, and max queries to kebab-case such as \`$max-md\`.
-- Update colors and themes to the v3 recipe helpers in \`@tamagui/themes/builder\`.
+- Preserve resolved colors and themes; defer v6 recipe conversion to the optional follow-up below.
 
 ### v1 prop and API changes
 

package/src/preview-theme.ts

@@ -0,0 +1,54 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import chalk from 'chalk'
+import open from 'opener'
+
+export interface PreviewThemeOptions {
+  theme?: string
+  themeArg?: string
+  url?: string
+  print?: boolean
+}
+
+export async function previewTheme(options: PreviewThemeOptions) {
+  const themeInput = (options.theme || options.themeArg || '').trim()
+  let themeData: any = null
+
+  if (themeInput) {
+    if (themeInput.startsWith('{') || themeInput.startsWith('[')) {
+      try {
+        themeData = JSON.parse(themeInput)
+      } catch (err: any) {
+        throw new Error(`Invalid JSON provided for --theme: ${err.message}`)
+      }
+    } else {
+      const filePath = path.resolve(process.cwd(), themeInput)
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Theme file not found at: ${filePath}`)
+      }
+      try {
+        const fileContent = fs.readFileSync(filePath, 'utf-8')
+        themeData = JSON.parse(fileContent)
+      } catch (err: any) {
+        throw new Error(`Failed to read theme file ${filePath}: ${err.message}`)
+      }
+    }
+  }
+
+  const baseUrl = options.url || 'https://tamagui.dev/theme'
+  let targetUrl = baseUrl
+
+  if (themeData) {
+    const jsonStr = JSON.stringify(themeData)
+    const base64 = Buffer.from(jsonStr).toString('base64')
+    targetUrl = `${baseUrl}#theme=${encodeURIComponent(base64)}`
+  }
+
+  if (options.print) {
+    console.info(targetUrl)
+    return
+  }
+
+  console.info(chalk.green(`Opening theme preview:`), targetUrl)
+  open(targetUrl)
+}