Tamagui 官方 AI Skill 完全指南安装、项目配置注入与核心编码规范【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamaguiTamagui 是一个面向 Web 与 React Native 的通用 React UI 框架本仓库 plans/tamagui-skill/skills/tamagui/README.md 即其官方 Claude Code skill 的入口文档配套的 SKILL.md 与references/目录给出了完整的行为定义。本文以此文档为骨架结合仓库内tamaguiCLI 的generate-prompt实现与真实生成产物系统讲解如何安装并启用该 skill、如何让 AI 读取你项目的真实 token/主题/媒体查询配置、以及 skill 内置的styled()用法、复合组件、动画、反模式与编译器优化要点。读完你可以直接把它接入自己的 Tamagui 项目让 Claude Code 写出与项目设计系统完全一致、且可被编译器静态提取的代码。一、Skill 是什么AI 助手操作 Tamagui 的“官方操作手册”该 skill 是 Tamagui 官方维护、面向 Claude Code以及其他支持 skill 的 Agent的指令包。它的定位不是一份人类阅读的普通文档而是一份结构化的、可在特定场景自动激活的行为说明书当 AI 处理与 Tamagui 相关的代码时它会被自动加载约束 AI 使用正确的 API 与模式。在 SKILL.md 的 frontmatter 中通过name: tamagui与一段description声明了触发条件name: tamagui description: | Universal React UI framework for web and native. Use when building cross-platform apps with Tamagui, creating styled components with styled(), configuring design tokens/themes, using Tamagui UI components, or working with animations. Triggers: tamagui, styled(), $token, XStack/YStack, useTheme, tamagui/* imports, createStyledContext, variants. version: 1.0.0可以看到触发词覆盖了styled()、$token、XStack/YStack、useTheme、tamagui/*导入、createStyledContext、variants等几乎所有日常编码会出现的词汇因此只要对话中出现这些模式skill 就会介入。README 中列出了 skill 提供的能力清单核心样式模式styled()、variants、tokens 的用法组件用法Button、Dialog、Sheet 等常用组件动画指导驱动选择与配置方式反模式规避明确指出常见的错误写法编译器优化提示如何让样式被构建期静态提取。从目录结构看skill 的内容组织为见 README 的Whats Included章节plans/tamagui-skill/skills/tamagui/ ├── SKILL.md # 主 skill 文件约 600 行 └── references/ ├── components.md # 组件 API 速查 ├── animations.md # 动画驱动与模式 └── configuration.md # 配置搭建指南其中 components.md 覆盖布局XStack/YStack/ZStack、输入Button/Input/Checkbox/Switch/RadioGroup/Slider、浮层Dialog/Sheet/Popover/Tooltip、导航Tabs/Select、展示Card/Avatar/Progress以及 Adapt 响应式模式animations.md 给出四个动画驱动的选择矩阵与完整配置示例configuration.md 则讲解createTamagui、tokens、themes、fonts、media、shorthands、settings 等完整配置面。二、安装一行命令接入 Claude CodeREADME 给出的安装方式非常轻量npx skills add tamagui/tamagui-skills执行后skills/tamagui/目录即本仓库中plans/tamagui-skill/skills/tamagui/下的内容会被安装到你的 skill 目录中。之后每当对话中出现 Tamagui 代码相关的内容skill 自动激活AI 会遵循其中的样式模式、组件用法、动画指导、反模式清单与编译器优化建议来编写和修改代码。三、项目专属配置注入npx tamagui generate-prompt3.1 为什么要生成项目专属配置Tamagui 的 token、主题、媒体查询、简写shorthands、字体等完全由每个项目自己的tamagui.config.ts决定。官方默认主题与你的项目可能完全不同——例如本仓库 tamagui.dev 的space.$4是18而 skill 文档示例中写作16。因此 SKILL.md 明确要求在写任何 Tamagui 代码之前先获取项目的实际配置。3.2 命令与产物npx tamagui generate-prompt该命令会输出tamagui-prompt.md其中包含项目独有的设计 tokenspace、size、radius、color、zIndex主题名称与层级结构可用组件清单媒体查询断点简写属性映射字体家族关键要求之后引用 token/主题/媒体查询名称时一律以该文件为准不要猜测或使用默认值。3.3 底层实现从配置 JSON 到 Markdown这个命令的实现位于 code/core/cli/src/generate-prompt.ts。其流程是先通过loadTamagui()重新加载并生成配置设置TAMAGUI_KEEP_THEMES 1保留主题信息读取paths.dotDir下的tamagui.config.json.tamagui目录若不存在则报错提示先运行tamagui generate调用generateMarkdown(config)将 JSON 序列化为 Markdown写入output || cwd/tamagui-prompt.md。// code/core/cli/src/generate-prompt.ts 中的核心流程 await loadTamagui({ ...options.tamaguiOptions, platform: web }) const configPath join(paths.dotDir, tamagui.config.json) if (!FS.existsSync(configPath)) { throw new Error(Config file not found at ${configPath}. Please run tamagui generate first.) } const markdown generateMarkdown(config) const outputPath output || join(process.cwd(), tamagui-prompt.md) await FS.writeFile(outputPath, markdown, utf-8)在 cli.ts 中可以看到generate命令也会把 prompt 同步生成一份到.tamagui/prompt.md确保配置与提示文件始终联动。generateMarkdown中还有一些值得注意的细节简写感知若配置开启了onlyAllowShorthands生成文档时会把完整属性名替换为简写例如backgroundColor→bg并给出“✅ 必须用简写 / ❌ 完整名会报错”的示例主题层级解析通过按_拆分主题名如light_blue_alt1_Button自动归类为基础主题light/dark、颜色方案blue、red…、变体alt1…与组件主题四层组件分组扫描config.components中各模块的nameToInfo将DialogClose、DialogContent这类命名归并为Dialog.Close、Dialog.Content的静态属性形式输出。3.4 真实产物长什么样本仓库自带的 code/tamagui.dev/tamagui-prompt.md 就是一次真实的生成结果共 454 行可以直接作为参照。其结构依次为Configuration SettingsdefaultFont: body、onlyAllowShorthands: false简写与完整名均可使用、webContainerType: inline-sizeShorthand Properties列出了bg → backgroundColor、p → padding、px → paddingHorizontal、rounded → borderRadius、z → zIndex等 30 余条映射Themes层级化呈现 Level 1dark/light、Level 2accent、blue、gray、red 等 15 个颜色方案、组件主题Button、Input、Slider、Switch、Tooltip…并说明light_blue_alt1_Button这种组合命名规则以及inverse明暗互换与reset回退到祖父主题两个特殊属性Tokensspace、size、radius、zIndex 的完整数值表例如space.$4 18、size.$10 104、radius.$4 9并附使用示例Media Queries包含xs/sm/md/lg/xl、gtSm/gtMd/gtLg、pointerFine等 30 个断点的具体媒体条件如gtLarge: {minWidth:901}Fontsbody、heading、mono、silkscreen、cherryBombComponents完整组件清单含Card.Background、Checkbox.IndicatorFrame、Progress.Indicator等静态属性子组件。这份文件正是 AI 在写代码时“查 token 名、查断点名、查组件名”的依据。四、核心概念skill 内置的编码规范SKILL.md 是 skill 的主行为文件其中沉淀了作者认为“写 Tamagui 代码必须知道”的核心概念。以下按原文结构展开。4.1styled()以扩展方式创建组件import { View, Text, styled } from tamagui/core const Card styled(View, { padding: $4, // 使用 $ 前缀引用 token backgroundColor: $background, borderRadius: $4, variants: { size: { small: { padding: $2 }, large: { padding: $6 }, }, elevated: { true: { boxShadow: 0 8px 24px $shadow4, }, }, } as const, // 类型推断必需 defaultVariants: { size: small, }, }) // 使用 Card sizelarge elevated /skill 强调的关键规则variants 对象必须加as const否则 TypeScript 无法推断变体类型token 一律用$前缀$4、$background、$color11prop 顺序很重要——后面的 prop 覆盖前面的variants 中定义在后面的变体覆盖前面的。从源码结构看styled是tamagui/core即 code/core/core/src导出的核心 APIUI 层所有组件Button、Card 等本质上都是基于View/Text用styled扩展出来的这解释了“所有组件都继承 View/Text”的设计。4.2 Stack 组件布局三兄弟import { XStack, YStack, ZStack } from tamagui // XStack flexDirection: row // YStack flexDirection: column // ZStack position: relative 绝对定位子元素 YStack gap$4 padding$4 XStack justifyContentspace-between alignItemscenter TextLabel/Text ButtonAction/Button /XStack /YStack4.3 主题嵌套与层级组合import { Theme } from tamagui Theme namedark Theme nameblue {/* 实际使用 dark_blue 主题 */} ButtonBlue button on dark/Button /Theme /Theme const theme useTheme() console.log(theme.background.val) // 真实颜色值 console.log(theme.color11.val) // 高对比文本色skill 记录了 Tamagui 的12 级颜色刻度约定范围用途$color1-4背景从弱到强调$color5-6边框、分隔线$color7-8hover / active 状态$color9-10实色背景$color11-12文本低到高对比4.4 响应式样式媒体查询以$前缀的 props 形式使用断点名以tamagui-prompt.md为准YStack padding$4 $gtSm{{ padding: $6 }} $gtMd{{ padding: $8 }} flexDirectioncolumn $gtLg{{ flexDirection: row }} / // 或使用 hook const media useMedia() if (media.gtMd) { // 渲染 medium 屏幕的内容 }注意正确顺序基础值在前响应式覆盖在后否则基础值会反过来覆盖响应式值详见下文反模式。4.5 动画transition 进入/退出样式import { AnimatePresence } from tamagui AnimatePresence {show ( YStack keymodal // 退出动画必需 key transitionquick enterStyle{{ opacity: 0, y: -20 }} exitStyle{{ opacity: 0, y: 20 }} opacity{1} y{0} / )} /AnimatePresence动画驱动详细矩阵见 references/animations.md驱动包名适用场景CSStamagui/animations-css纯 Web 应用包体最小React Nativetamagui/animations-react-native原生应用基础动画Reanimatedtamagui/animations-reanimated原生应用性能最佳Motiontamagui/animations-motion跨平台弹簧物理重要差异CSS 驱动使用缓动字符串easing string不支持弹簧物理其余驱动支持 spring 配置。五、复合组件createStyledContextwithStaticProperties对于共享状态的复合组件如 Card 的 size 级联skill 推荐如下模式import { createStyledContext, styled, View, Text } from tamagui/core import { withStaticProperties } from tamagui/helpers const CardContext createStyledContext({ size: medium as small | medium | large }) const CardFrame styled(View, { context: CardContext, padding: $4, backgroundColor: $background, variants: { size: { small: { padding: $2 }, medium: { padding: $4 }, large: { padding: $6 }, }, } as const, }) const CardTitle styled(Text, { context: CardContext, // 从父级继承 size fontWeight: bold, variants: { size: { small: { fontSize: $4 }, medium: { fontSize: $5 }, large: { fontSize: $6 }, }, } as const, }) export const Card withStaticProperties(CardFrame, { Title: CardTitle, }) // size 自动级联到子组件 Card sizelarge Card.TitleLarge Title/Card.Title /CardwithStaticProperties是tamagui/helpers提供的工具函数它把子组件以静态属性的形式挂到主组件上Card.Title这与本仓库 UI 包中大量组件的公开形态一致例如 tamagui.dev 生成清单中的Dialog.Title、Checkbox.Indicator。这也解释了为何 generate-prompt.ts 会把DialogClose这类命名自动归并输出为Dialog.Close——这正是静态属性模式的命名约定。六、常见实战模式6.1 Dialog Adapt移动端自动变为 Sheetimport { Dialog, Sheet, Adapt, Button } from tamagui Dialog Dialog.Trigger asChild ButtonOpen/Button /Dialog.Trigger Adapt whensm platformtouch Sheet modal dismissOnSnapToBottom Sheet.Frame padding$4 Adapt.Contents / /Sheet.Frame Sheet.Overlay / /Sheet /Adapt Dialog.Portal Dialog.Overlay keyoverlay transitionquick opacity{0.5} enterStyle{{ opacity: 0 }} exitStyle{{ opacity: 0 }} / Dialog.Content keycontent transitionquick enterStyle{{ opacity: 0, scale: 0.95 }} exitStyle{{ opacity: 0, scale: 0.95 }} Dialog.TitleTitle/Dialog.Title Dialog.DescriptionDescription/Dialog.Description Dialog.Close asChild ButtonClose/Button /Dialog.Close /Dialog.Content /Dialog.Portal /Dialog要点Adapt包裹的 Sheet 在sm断点 触摸平台下接管渲染Adapt.Contents注入 Dialog 的原始内容浮层子组件带key以便退出动画生效。6.2 表单Input Labelimport { Input, Label, YStack, XStack, Button } from tamagui YStack gap$4 padding$4 YStack gap$2 Label htmlForemailEmail/Label Input idemail placeholderemailexample.com autoCapitalizenone keyboardTypeemail-address / /YStack XStack gap$2 justifyContentflex-end Button variantoutlinedCancel/Button Button themeblueSubmit/Button /XStack /YStack完整的组件 API 速查Dialog、Sheet、Popover、Tooltip、Tabs、Select、Card、Avatar、Spinner、Progress、ScrollView、Image 等可在 references/components.md 中按需查阅。七、反模式清单skill 明令禁止的写法这是 skill 最有实战价值的部分——直接列出“AI 最容易写错”的地方7.1 ❌ 编造animationprop不存在animationprop这是最常被臆造的一个。真正的 prop 是transition其值是TransitionProp一个配置中注册的动画名、一个对象或一个数组。CSS transition 字符串不是 TransitionProp。// bad - 不存在这个 prop View animationquick / // bad - CSS 字符串不是 TransitionProp View transitionall 0.2s ease / // good - 配置在 animations 下注册的名字 View transitionquick /只有当配置注册了多个驱动时才使用animatedBydriver指定驱动。7.2 ❌ 把现代样式 prop 当成“仅 Web”backdropFilter、mixBlendMode、boxShadow、filter、backgroundImage、transition、cursor、userSelect都是一等公民的类型化 propReact Native 的新架构New Architecture在原生侧原生实现了它们。特别是backdropFilter是真正的原生高斯背景模糊——做毛玻璃效果不需要额外的 blur view 包。把其中一个在 iOS 上当作 no-op 是过时的假设。// bad - 传统 RN 阴影把 web 与 native 割裂 View shadowColor$shadowColor shadowOffset{{ width: 0, height: 8 }} shadowRadius{10} / // good - 一条 token 化路径通吃两端 View boxShadow0 8px 24px $shadow4 /Tamagui 自身也在朝这个方向演进通过一个配置项把 border、outline、shadow 的长手属性longhands从类型系统中移除统一使用组合式的border、outline、boxShadow——因为混用简写与长写会在 atomic CSS 特异性上互相打架。7.3 ❌ 硬编码值而非 token// bad View padding{16} backgroundColor#fff / // good - 使用设计 token View padding$4 backgroundColor$background /7.4 ❌ variants 缺少as const// bad - TypeScript 无法推断变体类型 variants: { size: { small: {...}, large: {...} } } // good variants: { size: { small: {...}, large: {...} } } as const7.5 ❌ 在styled()里做平台检测// bad - 无法被编译器提取 const Box styled(View, { padding: Platform.OS web ? 10 : 20, }) // good - 使用平台修饰符 const Box styled(View, { padding: 20, $platform-web: { padding: 10 }, })7.6 ❌ 没有AnimatePresence的exitStyle// bad - 退出动画不会生效 {show View exitStyle{{ opacity: 0 }} /} // good AnimatePresence {show View keybox exitStyle{{ opacity: 0 }} /} /AnimatePresence7.7 ❌ 阻止编译器提取的动态值// bad - 运行时变量阻止编译器提取 const dynamicPadding isPremium ? $6 : $4 View padding{dynamicPadding} / // good - 内联三元表达式可被提取 View padding{isPremium ? $6 : $4} /7.8 ❌ 错误的媒体查询顺序// bad - 基础值覆盖了响应式值 View $gtMd{{ padding: $8 }} padding$4 / // good - 基础值在前响应式覆盖在后 View padding$4 $gtMd{{ padding: $8 }} /7.9 ❌ 在 CSS 驱动上使用弹簧动画// bad - CSS 驱动不支持弹簧物理 import { createAnimations } from tamagui/animations-css const anims createAnimations({ bouncy: { type: spring, damping: 10 } // 不会生效 }) // good for CSS driver - 使用缓动字符串 const anims createAnimations({ bouncy: cubic-bezier(0.68, -0.55, 0.265, 1.55) 300ms })八、编译器优化让样式在构建期被静态提取Tamagui 的编译器会在构建期把静态样式提取为 CSS。要保证样式能被提取skill 给出四条准则使用 token——$4可提取16可能不行使用内联三元——padding{x ? $4 : $2}可提取避免运行时变量——计算得到的值无法提取使用 variants——优于条件式 prop。验证提取是否生效的方式开发模式下查找data-tamagui属性启用编译器后 bundle 体积应更小样式应以 CSS class 形式出现而非内联样式。九、TypeScript 集成import { GetProps, styled, View } from tamagui/core const MyComponent styled(View, { variants: { size: { small: {}, large: {} } } as const, }) // 提取 props 类型 type MyComponentProps GetPropstypeof MyComponent // 用自定义 props 扩展 interface ExtendedProps extends MyComponentProps { onCustomEvent?: () void }项目侧的类型接入见 references/configuration.md是通过declare module tamagui注入自定义配置类型// tamagui.config.ts const config createTamagui({...}) export type Conf typeof config declare module tamagui { interface TamaguiCustomConfig extends Conf {} }十、配置速查与安装集成10.1createTamagui与预置配置import { createTamagui } from tamagui/core const config createTamagui({ tokens, themes, fonts, media, shorthands, animations, settings, })大多数项目应从预置配置起步v5 系列// v5 CSS 动画Web import { config } from tamagui/config/v5-css // v5 Motion 动画跨平台弹簧 import { config } from tamagui/config/v5-motion // v5 Reanimated原生性能最佳 import { config } from tamagui/config/v5-reanimated // v5 基础版不带动画自行添加 import { defaultConfig } from tamagui/config/v5 import { animations } from tamagui/config/v5-css export default createTamagui({ ...defaultConfig, animations, })10.2 Provider 接入import { TamaguiProvider } from tamagui import config from ./tamagui.config export default function App() { return ( TamaguiProvider config{config} {/* app content */} /TamaguiProvider ) }10.3 动画配置速查CSS 驱动缓动字符串import { createAnimations } from tamagui/animations-css const animations createAnimations({ fast: ease-in 150ms, medium: ease-in-out 300ms, slow: ease-out 500ms, bouncy: cubic-bezier(0.68, -0.55, 0.265, 1.55) 400ms, })Spring 驱动RN/Reanimated/Motionimport { createAnimations } from tamagui/animations-react-native const animations createAnimations({ fast: { type: spring, damping: 20, stiffness: 300 }, medium: { type: spring, damping: 15, stiffness: 200 }, bouncy: { type: spring, damping: 8, mass: 0.8, stiffness: 100 }, })动画使用要点详见 references/animations.mdAnimatePresence子元素必须给key最终值要写在组件本身而非只写在enterStyleopacity 动画建议加overshootClamping防止负值过渡动画也可按属性细粒度覆盖View transition{[ fast, { opacity: { type: timing, duration: 500 }, scale: { overshootClamping: true }, }, ]} opacity{1} scale{1} /十一、快速参考表模式示例Tokenpadding$4主题值backgroundColor$background颜色刻度color$color11高对比文本响应式$gtSm{{ padding: $6 }}变体Button sizelarge variantoutlined /动画transitionquick enterStyle{{ opacity: 0 }}主题切换Theme namedarkTheme nameblue复合组件CardCard.Title配合createStyledContext结语让 AI 写“符合项目设计系统”的代码Tamagui 官方 skill 的价值在于两条链路静态的编码规范styled()、token 前缀、as const、反模式清单、编译器提取准则与动态的项目配置注入npx tamagui generate-prompt产出tamagui-prompt.md。前者保证 AI 写出的代码 API 正确、风格统一、可被优化后者保证这些代码恰好落在你项目的 token 与断点体系内而不是套用与项目无关的默认值。接入你自己的项目只需两步npx skills add tamagui/tamagui-skills安装 skill然后在项目根目录运行npx tamagui generate-prompt生成项目专属配置若未先执行过tamagui generate命令会提示先完成配置构建。之后让 Claude Code 处理 Tamagui 相关代码时它便会以这两份材料为准——这正是本仓库 plans/tamagui-skill/skills/tamagui/ 目录所沉淀的全部内容。【免费下载链接】tamaguiStyle React fast with 100% parity on React Native, an optional UI kit, and optimizing compiler.项目地址: https://gitcode.com/GitHub_Trending/ta/tamagui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
