mcpField
T
tamagui-best-practices

tamagui-best-practices

github.com/alleneubank设计与 UI50357 次安装18 周前更新
代码仓库

关于 tamagui-best-practices

tamagui-best-practices 是面向 Tamagui v1.x 开发者的编码技能，提供 Config v4、编译器优化组件模式及相关参考资料，涵盖覆盖层、表单、动画和设计令牌。

主要功能

  1. 01Config v4 配置指导
  2. 02编译器优化模式
  3. 03styled() 与变体用法
  4. 04覆盖层、表单和动画参考
  5. 05设计令牌与主题指导

适用场景

  1. 01配置 Tamagui v1.x 项目
  2. 02构建适合编译器优化的可复用组件
  3. 03实现对话框、表单或动画
  4. 04排查样式和主题常见问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alleneubank/claude-code --skill tamagui-best-practices

安装后在 Claude Code 中输入/tamagui-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

ANIMATION_PATTERNS.md
COMPILER_PATTERNS.md
DESIGN_SYSTEM.md
DIALOG_PATTERNS.md
FORM_PATTERNS.md
OVERLAY_PATTERNS.md

详细介绍

Tamagui 最佳实践

Tamagui v1.x 在基础知识之外的模式：Config v4、编译器优化、复合组件和注意事项。

参考文件 — 编写代码前请先阅读

上下文文件涵盖内容
Dialog、Sheet、模态覆盖层@DIALOG_PATTERNS.md自适应组件、无障碍支持
Form、Input、Label、验证@FORM_PATTERNS.mdzod 集成
动画、过渡效果@ANIMATION_PATTERNS.md驱动程序、enterStyle/exitStyle
Popover、Tooltip、Select@OVERLAY_PATTERNS.md覆盖层原语
编译器优化@COMPILER_PATTERNS.md编译器可以或无法展平的内容
设计令牌、主题@DESIGN_SYSTEM.md调色板、令牌结构

Config v4

使用 @tamagui/config/v4 的最简设置。对于新项目，添加 styleCompat: 'react-native'，使 flexBasis 与 React Native 行为保持一致：

import { defaultConfig } from '@tamagui/config/v4'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  settings: { ...defaultConfig.settings, styleCompat: 'react-native' },
})

declare module 'tamagui' {
  interface TamaguiCustomConfig extends typeof config {}
}

自定义主题请使用 createThemes 和 palette/accent/childrenThemes — 参见 @DESIGN_SYSTEM.md。

编译器优化规则

  • 使用 styled() 变体，而不是内联条件判断 — 动态值会破坏展平。
  • 避免使用带变量的 style={{ ... }}；改用变体属性。
  • context 模式（createStyledContext）会禁用编译器展平 — 用于更高层的组件（Button、Card），而非原语。
// BAD — breaks compiler
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />

// GOOD — use variants
const Box = styled(View, {
  variants: {
    dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
  },
})

styled() 与内联属性

  • styled()：可复用组件、由变体驱动的行为、可由编译器优化的原语。
  • 内联属性：对已有样式组件进行一次性布局调整。
  • variants 对象始终使用 as const（在推断的 const 泛型推出之前，这是 TypeScript 的限制）。

重要注意事项

属性顺序决定覆盖优先级 — 展开操作之后的属性无法被调用方覆盖：

// width is locked; backgroundColor can be overridden
<View backgroundColor="$red10" {...props} width={200} />

变体顺序很重要 — 后面的属性优先：

<Component scale={3} huge />  // scale = 3 (scale listed first)
<Component huge scale={3} />  // scale = 2 (huge overrides, comes first in variants)

包装样式化组件时使用 .styleable() — 保留变体继承：

const CorrectWrapper = StyledText.styleable((props, ref) => (
  <StyledText ref={ref} {...props} />
))

用于非标准令牌解析的 accept 属性（SVG fill/stroke、contentContainerStyle）：

const StyledSVG = styled(SVG, {}, { accept: { fill: 'color', stroke: 'color' } as const })

导入保持一致 — tamagui、@tamagui/core 和 @tamagui/button 是不同的包；每个项目选择一种方案。

切勿混用 RN StyleSheet 和 Tamagui — StyleSheet 值无法解析令牌。

Dialog/Sheet 的平台分支 — 使用 Adapt，而不是检查 Platform.OS（参见 @DIALOG_PATTERNS.md）。

快速参考

Config v4 简写：bg 表示 backgroundColor，p 表示 padding，m 表示 margin，w 表示 width，h 表示 height，br 表示 borderRadius

媒体断点：$xs 660px，$sm 800px，$md 1020px，$lg 1280px，$xl 1420px

动画驱动程序：css（Web，默认）、react-native-reanimated（原生，必需）

令牌 $ 前缀：在属性中使用（color="$color"），在主题定义中省略（{ color: palette[11] }）

获取最新文档

curl -sL "https://tamagui.dev/docs/core/configuration.md"
curl -sL "https://tamagui.dev/llms.txt"  # full index

评论

支持 Markdown