@tamagui/cli 3.0.0-beta.924.1 → 3.0.0

package/dist/icons.cjs

@@ -0,0 +1,263 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: () => from[key],
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var icons_exports = {};
+__export(icons_exports, {
+	HEROICONS_VERSION: () => HEROICONS_VERSION,
+	LUCIDE_VERSION: () => LUCIDE_VERSION,
+	PHOSPHOR_VERSION: () => PHOSPHOR_VERSION,
+	addIcons: () => addIcons,
+	svgToComponent: () => svgToComponent
+});
+module.exports = __toCommonJS(icons_exports);
+var import_node_fs = require("node:fs");
+var import_promises = require("node:fs/promises");
+var import_node_path = __toESM(require("node:path"));
+var import_chalk = __toESM(require("chalk"));
+const LUCIDE_VERSION = "1.49.0";
+const HEROICONS_VERSION = "2.2.0";
+const PHOSPHOR_VERSION = "2.1.1";
+const libraries = [
+	"lucide",
+	"heroicons",
+	"phosphor"
+];
+const phosphorWeights = [
+	"regular",
+	"bold",
+	"duotone",
+	"fill",
+	"light",
+	"thin"
+];
+const heroiconsDirs = {
+	outline: "24/outline",
+	solid: "24/solid",
+	mini: "20/solid",
+	micro: "16/solid"
+};
+async function addIcons(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const from = options.from ?? "lucide";
+	const outDir = import_node_path.default.resolve(cwd, options.out ?? "components/icons");
+	const localDir = libraries.includes(from) ? null : import_node_path.default.resolve(cwd, from);
+	if (localDir && !((0, import_node_fs.existsSync)(localDir) && (0, import_node_fs.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(", ")}`);
+	}
+	const icons = [...new Set(options.names)].map((arg) => {
+		const [name, source = name] = arg.split("=");
+		const isKebab = (x) => /^[a-z0-9-]+$/.test(x);
+		const isPascal = (x) => /^[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 = import_node_path.default.join(localDir, `${icon.file}.svg`);
+			return {
+				...icon,
+				svg: (0, import_node_fs.existsSync)(file) ? await (0, import_promises.readFile)(file, "utf-8") : null
+			};
+		}
+		const url = sourceUrl(from, 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 (0, import_promises.mkdir)(outDir, { recursive: true });
+	for (const icon of loaded) {
+		const file = import_node_path.default.join(outDir, `${icon.componentName}.tsx`);
+		await (0, import_promises.writeFile)(file, svgToComponent(icon.componentName, icon.svg));
+		console.info(`${import_chalk.default.green("wrote")} ${import_node_path.default.relative(cwd, file)}`);
+	}
+	const components = (await (0, import_promises.readdir)(outDir)).filter((file) => file.endsWith(".tsx")).map((file) => file.slice(0, -".tsx".length)).sort();
+	await (0, import_promises.writeFile)(import_node_path.default.join(outDir, "index.ts"), components.map((name) => `export { ${name} } from './${name}'`).join("\n") + "\n");
+	console.info(`${import_chalk.default.green("wrote")} ${import_node_path.default.relative(cwd, import_node_path.default.join(outDir, "index.ts"))} (${components.length} icons)`);
+}
+function sourceUrl(library, file, options) {
+	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) {
+	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) {
+	return name.split("-").map((part) => part ? part[0].toUpperCase() + part.slice(1) : part).join("");
+}
+function stripIconSuffix(name) {
+	return name.endsWith("Icon") && name.length > 4 ? name.slice(0, -4) : name;
+}
+function parseSvg(svg) {
+	const root = {
+		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 = {
+			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 = {
+	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"
+};
+const restrictedNames = [
+	"Infinity",
+	"NaN",
+	"undefined"
+];
+function svgToComponent(name, svg) {
+	const root = parseSvg(svg);
+	const used = /* @__PURE__ */ new Set();
+	const ref = (element) => element === name ? `_${element}` : element;
+	const jsxAttr = (attrName, value) => {
+		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) => letter.toUpperCase());
+		return value === "currentColor" ? `${prop}={color}` : `${prop}="${value}"`;
+	};
+	const keepAttr = ([attrName]) => !(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`);
+	const rootStroke = rootAttrs.some(([attrName, value]) => attrName === "stroke" && value === "currentColor");
+	const strokeWidth = rootAttrs.find(([attrName]) => attrName === "stroke-width")?.[1];
+	const emit = (node, indent) => {
+		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}>
+${node.children.map((child) => emit(child, `${indent}  `)).join("\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} }` : "";
+	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/dist/migrate.cjs

@@ -64,6 +64,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.
@@ -80,8 +100,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
@@ -102,46 +124,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, \u2026)\` targets for review.
 Check each rewritten callsite against these rules:
@@ -181,7 +179,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:
@@ -200,6 +198,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
@@ -251,12 +251,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
 
@@ -315,6 +317,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
@@ -325,15 +330,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
 
 Bring the app to the v2 baseline before applying v3 changes.
@@ -346,12 +405,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/dist/preview-theme.cjs

@@ -0,0 +1,70 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: () => from[key],
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var preview_theme_exports = {};
+__export(preview_theme_exports, { previewTheme: () => previewTheme });
+module.exports = __toCommonJS(preview_theme_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_chalk = __toESM(require("chalk"));
+var import_opener = __toESM(require("opener"));
+async function previewTheme(options) {
+	const themeInput = (options.theme || options.themeArg || "").trim();
+	let themeData = null;
+	if (themeInput) {
+		if (themeInput.startsWith("{") || themeInput.startsWith("[")) {
+			try {
+				themeData = JSON.parse(themeInput);
+			} catch (err) {
+				throw new Error(`Invalid JSON provided for --theme: ${err.message}`);
+			}
+		} else {
+			const filePath = import_node_path.default.resolve(process.cwd(), themeInput);
+			if (!import_node_fs.default.existsSync(filePath)) {
+				throw new Error(`Theme file not found at: ${filePath}`);
+			}
+			try {
+				const fileContent = import_node_fs.default.readFileSync(filePath, "utf-8");
+				themeData = JSON.parse(fileContent);
+			} catch (err) {
+				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(import_chalk.default.green(`Opening theme preview:`), targetUrl);
+	(0, import_opener.default)(targetUrl);
+}