@tamagui/cli 2.7.7 → 3.0.0-beta.643.1

package/dist/generate.cjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -6,71 +7,62 @@ 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
-  });
+	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;
+	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(
-// If the importer is in node compatibility mode or this is not an ESM
-// file that has been converted to a CommonJS file using a Babel-
-// compatible transform (i.e. "__esModule" has not been set), then set
-// "default" to the CommonJS "module.exports" for node compatibility.
-isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-  value: mod,
-  enumerable: true
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var generate_exports = {};
 __export(generate_exports, {
-  generateTypes: () => generateTypes,
-  getTypes: () => getTypes
+	generateTypes: () => generateTypes,
+	getTypes: () => getTypes
 });
 module.exports = __toCommonJS(generate_exports);
 var import_fs_extra = __toESM(require("fs-extra"));
 var import_ts_morph = require("ts-morph");
 var import_utils = require("./utils.cjs");
 async function generateTypes(options) {
-  const types = await getTypes(options);
-  await import_fs_extra.default.writeJSON(options.paths.types, types, {
-    spaces: 2
-  });
+	const types = await getTypes(options);
+	await import_fs_extra.default.writeJSON(options.paths.types, types, { spaces: 2 });
 }
 async function getTypes(options) {
-  const tamagui = await (0, import_utils.loadTamagui)(options.tamaguiOptions);
-  if (!tamagui) {
-    throw new Error(`No tamagui config`);
-  }
-  const nameToPaths = tamagui.nameToPaths || [];
-  const uniqueViewExportingPaths = new Set(Object.keys(nameToPaths).map(name => {
-    return `${[...nameToPaths[name]][0]}.ts*`;
-  }));
-  const project = new import_ts_morph.Project({
-    compilerOptions: {
-      noEmit: false,
-      declaration: true,
-      emitDeclarationOnly: true
-    },
-    skipAddingFilesFromTsConfig: true,
-    tsConfigFilePath: options.tsconfigPath
-  });
-  const files = project.addSourceFilesAtPaths([...uniqueViewExportingPaths]);
-  return Object.fromEntries(files.flatMap(x => {
-    return [...x.getExportedDeclarations()].map(([k, v]) => {
-      return [k, v[0].getType().getApparentType().getProperties().map(prop => {
-        return [prop.getEscapedName(), prop.getValueDeclaration()?.getType().getText()];
-      })];
-    });
-  }));
-}
+	const tamagui = await (0, import_utils.loadTamagui)(options.tamaguiOptions);
+	if (!tamagui) {
+		throw new Error(`No tamagui config`);
+	}
+	const nameToPaths = tamagui.nameToPaths || [];
+	const uniqueViewExportingPaths = new Set(Object.keys(nameToPaths).map((name) => {
+		return `${[...nameToPaths[name]][0]}.ts*`;
+	}));
+	const project = new import_ts_morph.Project({
+		compilerOptions: {
+			noEmit: false,
+			declaration: true,
+			emitDeclarationOnly: true
+		},
+		skipAddingFilesFromTsConfig: true,
+		tsConfigFilePath: options.tsconfigPath
+	});
+	const files = project.addSourceFilesAtPaths([...uniqueViewExportingPaths]);
+	return Object.fromEntries(files.flatMap((x) => {
+		return [...x.getExportedDeclarations()].map(([k, v]) => {
+			return [k, v[0].getType().getApparentType().getProperties().map((prop) => {
+				return [prop.getEscapedName(), prop.getValueDeclaration()?.getType().getText()];
+			})];
+		});
+	}));
+}

package/dist/index.cjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-require("./cli.cjs");
+
+require("./cli.cjs");

package/dist/migrate.cjs

@@ -0,0 +1,370 @@
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var migrate_exports = {};
+__export(migrate_exports, {
+	getMigrationPrompt: () => getMigrationPrompt,
+	printMigrationPrompt: () => printMigrationPrompt
+});
+module.exports = __toCommonJS(migrate_exports);
+function printMigrationPrompt({ from }) {
+	process.stdout.write(getMigrationPrompt({ from }));
+}
+function getMigrationPrompt({ from } = {}) {
+	const source = normalizeFrom(from);
+	if (source === "v1") {
+		return `${promptHeader("v1", "v3")}
+
+${v1ToV2Prompt}
+
+After the v1 to v2 pass is complete, apply the v2 to v3 pass below.
+
+${v2ToV3Prompt}
+`;
+	}
+	return `${promptHeader("v2", "v3")}
+
+${v2ToV3Prompt}
+`;
+}
+function normalizeFrom(from) {
+	const value = (from || "v2").toLowerCase().replace(/^from-?/, "");
+	if (value === "1" || value === "v1") return "v1";
+	if (value === "2" || value === "v2") return "v2";
+	throw new Error("Usage: tamagui migrate --from v2 | --from v1");
+}
+function promptHeader(from, to) {
+	return `You are migrating a Tamagui app from ${from} to ${to}.
+
+Work like a careful coding agent:
+
+- Read the app's Tamagui config, package manager, bundler, and component usage before editing.
+- Keep changes scoped to the migration.
+- Run the codemods listed below, then review the diff by hand.
+- Do not publish packages, rotate secrets, or change production infrastructure.
+- Validate with typecheck/build and at least one real app run or browser/native smoke test.
+- Report any behavior that cannot be migrated mechanically.`;
+}
+const v2ToV3Prompt = `## v2 -> v3 migration prompt
+
+### 1. Update dependencies
+
+- Bump every \`tamagui\` and \`@tamagui/*\` package together to v3.
+- Keep \`@tamagui/core\`, \`@tamagui/web\`, and \`tamagui\` deduped in the lockfile.
+- Run:
+
+\`\`\`bash
+npx tamagui check
+\`\`\`
+
+### 2. Migrate tokens and conditional styles
+
+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 --write \\
+  --report flat-values-report.md \\
+  --json flat-values-report.json \\
+  ./src
+\`\`\`
+
+For example, this V2 input:
+
+\`\`\`tsx
+<View bg="$background" hoverStyle={{ bg: '$backgroundHover' }} $sm={{ p: '$6' }} p="$4" />
+\`\`\`
+
+becomes:
+
+\`\`\`tsx
+<View bg="background hover:background-hover" p="4 sm:6" />
+\`\`\`
+
+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
+
+- 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.
+- Import animations from \`@tamagui/config/animations-css\`, \`animations-rn\`, \`animations-reanimated\`, or \`animations-motion\`.
+- Remove \`@tamagui/theme-builder\` and any V5 builder imports. Static \`@tamagui/themes/v5\`, \`/v5-subtle\`, and \`/v5-tokens\` imports remain supported.
+- 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\`.
+- 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"
+\`\`\`
+
+### 4. Run the Sheet codemod
+
+Run the codemod, then inspect every changed Sheet:
+
+\`\`\`bash
+node ./node_modules/tamagui/scripts/codemods/sheet-frame-to-container.js "src/**/*.{ts,tsx}"
+\`\`\`
+
+If working inside a Tamagui checkout, this path is also valid:
+
+\`\`\`bash
+node ./scripts/codemods/sheet-frame-to-container.js "src/**/*.{ts,tsx}"
+\`\`\`
+
+Migration rules:
+
+- Replace \`Sheet.Frame\` with \`Sheet.Container\` plus \`Sheet.Background\`.
+- Keep layout props such as \`padding\`, \`gap\`, \`height\`, \`maxHeight\`, and flex props on \`Sheet.Container\`.
+- Move visual surface props such as \`bg\`, \`borderRadius\`, \`elevation\`, and \`shadow*\` to \`Sheet.Background\`.
+- Keep \`Sheet.Overlay\` as a direct child of \`Sheet\`.
+- Add explicit clipping if old \`Sheet.Frame\` overflow clipping mattered.
+- \`disableHideBottomOverflow\` belongs on \`Sheet.Background\`.
+
+Before:
+
+\`\`\`tsx
+<Sheet>
+  <Sheet.Overlay />
+  <Sheet.Frame padding="$4" bg="$background" borderTopRadius="$6">
+    <Sheet.ScrollView>{children}</Sheet.ScrollView>
+  </Sheet.Frame>
+</Sheet>
+\`\`\`
+
+After:
+
+\`\`\`tsx
+<Sheet>
+  <Sheet.Overlay />
+  <Sheet.Container padding="4">
+    <Sheet.Background bg="background" borderTopRadius="6" />
+    <Sheet.ScrollView>{children}</Sheet.ScrollView>
+  </Sheet.Container>
+</Sheet>
+\`\`\`
+
+### 5. Remove deprecated v2 APIs
+
+Search:
+
+\`\`\`bash
+rg "focusable|fullscreen|themeInverse|<Theme inverse|Sheet\\.Frame|styleable\\(|inlineWhenUnflattened|\\$true|getTokenRelative|stepTokenUpOrDown|forceRemoveScrollEnabled|sizeAdjust"
+\`\`\`
+
+Replace:
+
+- \`focusable\` -> \`tabIndex\`.
+- \`fullscreen\` -> explicit \`position\` and \`inset\` props.
+- \`themeInverse\` -> \`theme="inverse"\`.
+- \`<Theme inverse>\` -> \`<Theme name="inverse">\`.
+- \`Sheet.Frame\` -> \`Sheet.Container\` plus \`Sheet.Background\`.
+- \`Component.styleable(fn)\` -> \`createStyledHOC(Component, fn)\` (same behavior, standalone function).
+- forwardRef wrapper statics -> direct refs and normal composition.
+- \`inlineWhenUnflattened\` -> remove it.
+- deprecated UI kit aliases -> current component names.
+- old platform style keys -> flat \`web:\`, \`native:\`, \`ios:\`, and \`android:\` clauses.
+- \`forceRemoveScrollEnabled\` -> \`disableRemoveScroll\` with inverted intent.
+- \`createCheckbox\` \`sizeAdjust\` -> explicit sizing math or component styles.
+
+### 6. Replace true tokens
+
+- Default v3 configs no longer export the legacy \`$true\` token key.
+- Component default size resolves to bare \`4\`.
+- Replace authored \`$true\` tokens with real bare keys such as \`4\`.
+- Do not change unrelated boolean props or boolean variant values.
+
+### 7. Replace token stepping
+
+Removed from \`@tamagui/get-token\`:
+
+- \`stepTokenUpOrDown\`
+- \`getTokenRelative\`
+- the second options argument to \`getSize\`, \`getSpace\`, and \`getRadius\`
+- \`shift\`, \`bounds\`, and \`excludeHalfSteps\`
+
+Before:
+
+\`\`\`tsx
+const padding = getSize(size, { shift: -2 })
+\`\`\`
+
+After:
+
+\`\`\`tsx
+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
+
+- \`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.
+
+### 9. Update FocusScope
+
+- Function-as-children is removed. Pass JSX children directly.
+- FocusScope renders a \`display: contents\` wrapper.
+- Use \`noFocus\` for zero-focus mode when focus should be rejected entirely.
+
+Before:
+
+\`\`\`tsx
+<FocusScope loop>
+  {({ ref, onKeyDown, tabIndex }) => (
+    <View ref={ref} onKeyDown={onKeyDown} tabIndex={tabIndex} />
+  )}
+</FocusScope>
+\`\`\`
+
+After:
+
+\`\`\`tsx
+<FocusScope loop>
+  <View />
+</FocusScope>
+\`\`\`
+
+### 10. Update Dialog, Popover, Select, and Adapt flows
+
+- Dialog, Popover, and Select use one Adapt handoff model.
+- Adapted Sheet content stays mounted through the sheet slide-out.
+- Parts own their presence animation lifecycles.
+- The \`onDidAnimate\` prop is replaced by the typed \`onTransition\` lifecycle: \`onTransition={(e) => e.phase === 'end' && e.cause === 'enter' && done()}\`.
+- \`Popover.Content forceMount\` now matches Dialog semantics.
+- \`Dialog.Content\` no longer accepts the old no-op \`size\` variant.
+- Non-modal Dialog content no longer enables RemoveScroll while open.
+- Remove internal imports such as \`useShowPopoverSheet\`, \`PopoverAdaptHiddenContext\`, or \`useSelectBreakpointActive\` if the app used them.
+
+### 11. Update Select
+
+- Keep \`name\` when Select participates in a form. Remove the unsupported \`autoComplete\` prop.
+- Use \`Select.Separator\` for visual grouping.
+- \`Select.Content\` accepts \`onEscapeKeyDown\` and \`onInteractOutside\`.
+- \`Select.Trigger\` and web \`Select.Viewport\` expose \`data-state="open" | "closed"\`.
+
+### 12. Update themed icons
+
+- \`<Icon size="4" />\` now resolves through the current font's \`font.size['4']\` scale.
+- Raw numeric icon sizes are unchanged.
+- Themed icons no longer accept Tamagui media or pseudo props directly.
+- Wrap icons in a styled \`View\` for media and state clauses.
+
+### 13. Check ScrollView web usage
+
+\`@tamagui/scroll-view\` now has its own web implementation. It supports \`scrollTo\`, \`scrollToEnd\`, \`getScrollableNode\`, RN-shaped \`onScroll\`, \`contentContainerStyle\`, \`horizontal\`, and indicator props.
+
+Replace unsupported old web/lite usage such as momentum events, \`snapTo*\`, and \`keyboardDismissMode\`.
+
+### 14. Optional Tailwind frontend
+
+Tailwind authoring is selected by the component package, with no global config:
+
+\`\`\`tsx
+import { View, Text, styled } from '@tamagui/tailwind'
+\`\`\`
+
+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.
+
+### 15. Verification
+
+- Run \`npx tamagui check\`.
+- 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.`;
+const v1ToV2Prompt = `## v1 -> v2 migration pass
+
+Bring the app to the v2 baseline before applying v3 changes.
+
+### Requirements
+
+- React 19+
+- React Native 0.81+ with New Architecture support
+- TypeScript 5+
+
+### Config
+
+- Move to \`@tamagui/config/v6\`.
+- 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\`.
+
+### v1 prop and API changes
+
+- \`animation\` -> \`transition\`.
+- \`AnimationProp\` -> \`TransitionProp\`.
+- \`tag\` -> \`render\`.
+- \`Stack\` -> \`View\`.
+- \`StackProps\` -> \`ViewProps\`.
+- \`space\` and \`spaceDirection\` -> \`gap\`.
+- \`themeInverse\` and \`<Theme inverse>\` -> \`theme="inverse"\` and \`<Theme name="inverse">\`.
+- \`onHoverIn\` / \`onHoverOut\` -> \`onPointerEnter\` / \`onPointerLeave\` or mouse events.
+- \`ellipse\` -> \`numberOfLines={1}\`.
+- React Native accessibility props -> ARIA/web equivalents where applicable.
+- React Native shadow props -> \`boxShadow\`.
+
+### v1 component changes
+
+- Input and Image prefer web-standard props such as \`type\`, \`inputMode\`, \`src\`, \`alt\`, and \`objectFit\`.
+- Button and ListItem no longer take direct text style props. Style text through child components.
+- Tabs uses \`Tabs.Tab\` instead of \`Tabs.Trigger\`; \`activationMode\` defaults to \`manual\`.
+- Group requires \`Group.Item\`; remove old separator/space/scrollable auto-cloning props.
+- Replace old \`Popover.Sheet\` subcomponents with standalone \`Sheet\` inside \`Adapt\`.
+- Add native setup imports where needed: \`@tamagui/native/setup-teleport\`, \`setup-gesture-handler\`, \`setup-expo-ui-menu\` or \`setup-zeego\`, \`setup-burnt\`, and linear-gradient setup.
+
+### v1 -> v2 verification
+
+- Run the app before starting v3 changes.
+- Verify layout affected by flex/position defaults.
+- Verify forms, tabs, groups, portals, native sheets, and Input/Image behavior.
+- Commit the v1 -> v2 migration separately if possible.`;

package/dist/setup-prompt.cjs

@@ -0,0 +1,158 @@
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var setup_prompt_exports = {};
+__export(setup_prompt_exports, {
+	getSetupPrompt: () => getSetupPrompt,
+	printSetupPrompt: () => printSetupPrompt
+});
+module.exports = __toCommonJS(setup_prompt_exports);
+function printSetupPrompt() {
+	process.stdout.write(getSetupPrompt());
+}
+function getSetupPrompt() {
+	return `You are adding Tamagui v3 to a project that does not use it yet.
+
+Work like a careful coding agent:
+
+- Read the project first: package manager, bundler, framework, TypeScript config,
+  and whether it targets web, native, or both. Every choice below depends on it.
+- Make the smallest install that actually runs, then verify it before adding more.
+- Do not restyle existing components as part of setup.
+- Do not publish packages, rotate secrets, or change production infrastructure.
+- Stop and report if a step cannot be completed rather than guessing around it.
+
+## 1. Check the baseline
+
+Tamagui v3 requires React 19+, TypeScript 5+, and, for native apps, React Native
+0.81+ with the New Architecture enabled. Web-only apps have no React Native
+version requirement. If the project is below any of these, say so and stop.
+
+## 2. Install
+
+Tamagui v3 is currently a beta on the \`beta\` dist-tag. Resolve it once and pin
+every package to the same version, because a mixed install silently produces two
+copies of the runtime and styles that do nothing.
+
+\`\`\`bash
+V=$(npm view tamagui@beta version)
+npm i tamagui@$V @tamagui/config@$V
+\`\`\`
+
+\`tamagui\` is a superset of \`@tamagui/core\`. Install \`@tamagui/core\` alone
+only for a styling-only install with no UI kit.
+
+## 3. Create the config
+
+\`\`\`tsx
+// tamagui.config.ts
+import { defaultConfig } from '@tamagui/config/v6'
+import { createTamagui } from 'tamagui'
+
+export const config = createTamagui(defaultConfig)
+
+declare module 'tamagui' {
+  interface TamaguiCustomConfig extends typeof config {}
+}
+\`\`\`
+
+Pick an animation driver explicitly and import it from \`@tamagui/config\`:
+\`animations-css\` (web), \`animations-rn\`, \`animations-reanimated\`, or
+\`animations-motion\`. Do not install \`@tamagui/theme-builder\` or any v5 builder
+package; they are not part of v3.
+
+## 4. Wrap the app
+
+\`\`\`tsx
+import { TamaguiProvider, View } from 'tamagui'
+import { config } from './tamagui.config'
+
+export default function App() {
+  return (
+    <TamaguiProvider config={config} defaultTheme="light">
+      <View width={200} height={200} bg="background" />
+    </TamaguiProvider>
+  )
+}
+\`\`\`
+
+## 5. Wire the bundler
+
+Add the adapter for the bundler this project actually uses, and no others:
+
+- Vite: \`@tamagui/vite-plugin\`, or \`@tamagui/cli/vite\`
+- Metro: \`@tamagui/metro-plugin\`, or \`@tamagui/cli/metro\`
+- Next.js: \`@tamagui/next-plugin\`
+- Turbopack: the \`tamagui build\` precompile step
+
+There is no Webpack plugin in v3.
+
+The compiler is an optimization, not a requirement. If wiring it is not
+straightforward, skip it, note that you skipped it, and confirm the app runs
+first.
+
+## 6. Write styles the v3 way
+
+This is the part most likely to be written as if it were v2. In v3, token and
+theme names are bare, and conditions are flat clauses inside the value:
+
+\`\`\`tsx
+<View bg="background hover:background-hover" p="4 sm:6" />
+\`\`\`
+
+- No \`$\` sigils: \`bg="background"\`, not \`bg="$background"\`.
+- No condition objects: there is no \`hoverStyle={{ ... }}\` and no \`$sm={{ ... }}\`.
+- Modifiers chain left to right and read as prefixes: \`hover:sm:small\`.
+- Clauses work on variant props too, not just style props, so
+  \`size="large sm:small"\` selects a different variant value per condition.
+- When two clauses both apply, the winner is decided by specificity, not by
+  source order: first by platform (\`ios:\` beats \`native:\` beats unprefixed),
+  then by how many conditions the clause carries, then by category
+  (media < container < theme < group < state). Writing a clause later in the
+  string does not make it win.
+- A chain is capped at five distinct non-platform conditions.
+
+## 7. Verify before reporting success
+
+\`\`\`bash
+npx tamagui check
+\`\`\`
+
+\`tamagui check\` reports version mismatches, duplicate installs, lockfile
+problems, a missing config, and any v2 style syntax left in source. Then run the
+project's own typecheck and build, and start the app and confirm a Tamagui
+component renders with its styles applied. A passing typecheck is not sufficient:
+flat values are strings, so a misspelled token compiles cleanly and only shows up
+at runtime.
+
+## 8. Give the agent the project's own vocabulary
+
+Once the app runs, generate a description of this project's actual tokens,
+themes, and components so later prompts do not guess at them:
+
+\`\`\`bash
+npx tamagui generate-prompt
+\`\`\`
+
+That writes \`tamagui-prompt.md\`. Keep it in the repo and regenerate it when the
+config changes.
+`;
+}