Communitygithub.com

ComeOnOliver/skillshub

提供 Tamagui 的進階模式,包括 Config v4、編譯器最佳化、styled context 以及跨平台樣式。必須在處理 Tamagui 專案(tamagui.config.ts、@tamagui 匯入)時使用。

skillshub 是什麼?

這個技能提供 Tamagui v1.x 的進階使用模式,超越基礎知識。它專注於 Config v4、編譯器最佳化、複合元件以及常見錯誤。支援所有開發平台(Web、iOS、Android),並需搭配 Tamagui 專案使用。技能強調透過強制性的上下文加載(如 @DIALOG_PATTERNS.md)來確保開發者在使用特定元件類型前先閱讀對應的模式檔案。主要功能包括使用 createThemes 進行主題自訂、利用 createStyledContext 建立複合元件、使用 styleable() 保留變體繼承,以及透過 accept prop 讓自訂元件支援 token/theme 解析。同時也點出了破壞編譯器最佳化的動態樣式、內聯函數、錯誤的匯入路徑、混合 RN StyleSheet 與 Tamagui 等反模式,並提供對應的解決方案。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/0xbigboss/tamagui-best-practices

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

此技能提供了超越基礎的 Tamagui v1.x 模式。它專注於 Config v4、編譯器最佳化、複合元件以及常見錯誤。

強制性上下文加載

在使用這些元件時,請在撰寫程式碼之前閱讀對應的模式檔案:

元件類型必要閱讀跨技能
Dialog、Sheet、模態覆蓋層@DIALOG_PATTERNS.md
Form、Input、Label、驗證@FORM_PATTERNS.mdtypescript-best-practices(zod)
動畫、轉場@ANIMATION_PATTERNS.md
Popover、Tooltip、Select@OVERLAY_PATTERNS.md
編譯器最佳化@COMPILER_PATTERNS.md
設計 Token、主題@DESIGN_SYSTEM.md

Config v4 快速入門

使用 @tamagui/config/v4 來簡化設定:

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

export const config = createTamagui(defaultConfig)

type CustomConfig = typeof config

declare module 'tamagui' {
  interface TamaguiCustomConfig extends CustomConfig {}
}

推薦設定(用於新專案,將 flexBasis 對齊 React Native):

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

createThemes 模式

若要自訂主題,請使用 createThemes 搭配色板/強調色/子主題:

import { createThemes, defaultComponentThemes } from '@tamagui/config/v4'

const generatedThemes = createThemes({
  componentThemes: defaultComponentThemes,
  base: {
    palette: {
      dark: ['#050505', '#151515', /* ...12 色 */ '#fff'],
      light: ['#fff', '#f8f8f8', /* ...12 色 */ '#000'],
    },
    extra: {
      light: { ...Colors.blue, shadowColor: 'rgba(0,0,0,0.04)' },
      dark: { ...Colors.blueDark, shadowColor: 'rgba(0,0,0,0.2)' },
    },
  },
  accent: {
    palette: { dark: lightPalette, light: darkPalette }, // 反轉
  },
  childrenThemes: {
    blue: { palette: { dark: Object.values(Colors.blueDark), light: Object.values(Colors.blue) } },
    red: { /* ... */ },
    green: { /* ... */ },
  },
})

Token 與主題語法

$ 前綴規則

  • Props(屬性):在 token 參考中使用 $ 前綴:<Text color="$color" fontSize="$4" />
  • 主題鍵:在主體定義中存取時不使用 $:{ color: palette[11] }
  • 變體中的 Token 存取:使用 tokens.size[name] 模式

變體展開運算子

特殊的展開運算子將 token 類別映射到變體值:

const Button = styled(View, {
  variants: {
    size: {
      // 映射 size token:$1、$2、$true 等
      '...size': (size, { tokens }) => ({
        height: tokens.size[size] ?? size,
        borderRadius: tokens.radius[size] ?? size,
        gap: tokens.space[size]?.val * 0.2,
      }),
    },
    textSize: {
      // 映射 fontSize token
      '...fontSize': (name, { font }) => ({
        fontSize: font?.size[name],
      }),
    },
  } as const,
})

重要:在變體物件上使用 as const,直到 TypeScript 支援推斷的 const 泛型。

使用 createStyledContext 建立複合元件

用於像 <Button><Button.Text>Click</Button.Text></Button> 這樣的複合 API:

import {
  SizeTokens,
  View,
  Text,
  createStyledContext,
  styled,
  withStaticProperties,
} from '@tamagui/core'

// 1. 建立帶有共享變體型別的 context
export const ButtonContext = createStyledContext<{ size: SizeTokens }>({
  size: '$medium',
})

// 2. 建立帶有 context 的框架
export const ButtonFrame = styled(View, {
  name: 'Button',
  context: ButtonContext,
  variants: {
    size: {
      '...size': (name, { tokens }) => ({
        height: tokens.size[name],
        borderRadius: tokens.radius[name],
        gap: tokens.space[name].val * 0.2,
      }),
    },
  } as const,
  defaultVariants: {
    size: '$medium',
  },
})

// 3. 建立帶有相同 context 的文字(變體自動同步)
export const ButtonText = styled(Text, {
  name: 'ButtonText',
  context: ButtonContext,
  variants: {
    size: {
      '...fontSize': (name, { font }) => ({
        fontSize: font?.size[name],
      }),
    },
  } as const,
})

// 4. 使用 withStaticProperties 組合
export const Button = withStaticProperties(ButtonFrame, {
  Props: ButtonContext.Provider,
  Text: ButtonText,
})

使用方式:

<Button size="$large">
  <Button.Text>點擊我</Button.Text>
</Button>

// 或從上方覆蓋預設值:
<Button.Props size="$small">
  <Button><Button.Text>小型</Button.Text></Button>
</Button.Props>

注意:context 模式不適用於編譯器扁平化。請用於高層級元件(Button、Card),而非基礎元件(Stack、Text)。

用於封裝元件的 styleable()

將 styled 元件封裝在函式元件中時,請使用 .styleable() 以保留變體繼承:

const StyledText = styled(Text)

// 不使用 styleable - 變體繼承失效
const BrokenWrapper = (props) => <StyledText {...props} />

// 使用 styleable - 正確
const CorrectWrapper = StyledText.styleable((props, ref) => (
  <StyledText ref={ref} {...props} />
))

// 現在這樣可以運作:
const StyledCorrectWrapper = styled(CorrectWrapper, {
  variants: {
    bold: { true: { fontWeight: 'bold' } },
  },
})

加入額外的 Props

傳入泛型型別參數以加入額外的 props:

type ExtraProps = { icon?: React.ReactNode }

const IconText = StyledText.styleable<ExtraProps>((props, ref) => {
  const { icon, ...rest } = props
  return (
    <XStack>
      {icon}
      <StyledText ref={ref} {...rest} />
    </XStack>
  )
})

自訂元件的 accept Prop

啟用對非標準 props 的 token/theme 解析:

// 對於應接受主題顏色的 SVG fill/stroke
const StyledSVG = styled(SVG, {}, {
  accept: { fill: 'color', stroke: 'color' } as const,
})

// 使用方式:<StyledSVG fill="$blue10" />

// 對於樣式物件(如 ScrollView 的 contentContainerStyle)
const MyScrollView = styled(ScrollView, {}, {
  accept: { contentContainerStyle: 'style' } as const,
})

// 使用方式:<MyScrollView contentContainerStyle={{ padding: '$4' }} />

重要:請在 accept 物件上使用 as const。

Prop 順序很重要

在 styled() 中,prop 順序決定覆蓋優先權:

// backgroundColor 可以被 props 覆蓋
const Overridable = (props) => (
  <View backgroundColor="$red10" {...props} width={200} />
)
// width 無法被覆蓋(在展開之後)

// 變體順序也很重要:
<Component scale={3} huge />  // scale = 3(scale 在先)
<Component huge scale={3} />  // scale = 2(huge 覆蓋)

反模式

動態樣式會破壞最佳化

// 不好 - 破壞編譯器最佳化
<View style={{ width: someVariable * 2 }} />
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />

// 好 - 使用變體
const Box = styled(View, {
  variants: {
    dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
  },
})
<Box dark={isDark} />

內聯函數

// 不好 - 每次渲染都建立新函數
<View onPress={() => handlePress(id)} />

// 好 - 穩定的參考
const handlePressCallback = useCallback(() => handlePress(id), [id])
<View onPress={handlePressCallback} />

錯誤的匯入路徑

// 這些是不同的套件,內容不同:
import { View } from 'tamagui'           // 完整 UI 工具組
import { View } from '@tamagui/core'     // 僅核心(較小)
import { Button } from '@tamagui/button' // 單個元件

// 選擇一種方式並保持一致

混合 RN StyleSheet 與 Tamagui

// 不好 - StyleSheet 的值無法解析 token
const styles = StyleSheet.create({ box: { padding: 20 } })
<View style={styles.box} backgroundColor="$blue10" />

// 好 - 全部使用 Tamagui
<View padding="$4" backgroundColor="$blue10" />

針對 Dialog/Sheet 使用 Platform.OS 分支

// 不好 - 手動平台分支
if (Platform.OS === 'web') {
  return <Dialog>...</Dialog>
}
return <Sheet>...</Sheet>

// 好 - 使用 Adapt(請參閱 @DIALOG_PATTERNS.md)
<Dialog>
  <Dialog.Portal>...</Dialog.Portal>
  <Adapt when="sm" platform="touch">
    <Sheet><Adapt.Contents /></Sheet>
  </Adapt>
</Dialog>

取得最新文件

如需最新的 API 詳細資訊,請直接擷取 markdown 文件:

# 核心文件
curl -sL "https://tamagui.dev/docs/core/configuration.md"
curl -sL "https://tamagui.dev/docs/core/styled.md"
curl -sL "https://tamagui.dev/docs/core/variants.md"
curl -sL "https://tamagui.dev/docs/core/animations.md"

# 元件文件
curl -sL "https://tamagui.dev/ui/sheet.md"
curl -sL "https://tamagui.dev/ui/dialog.md"
curl -sL "https://tamagui.dev/ui/select.md"

# 完整文件索引
curl -sL "https://tamagui.dev/llms.txt"

對於 HTML 頁面,請使用適當的選擇器搭配 web-fetch 技能。

快速參考

Config v4 簡寫(對齊 Tailwind)

簡寫屬性
bgbackgroundColor
ppadding
mmargin
wwidth
hheight
brborderRadius

媒體查詢中斷點

Token預設值伺服器預設值
$xs660pxtrue
$sm800pxfalse
$md1020pxfalse
$lg1280pxfalse
$xl1420pxfalse

動畫驅動程式

驅動程式平台使用案例
cssWeb預設,最佳效能
react-native-reanimatedNative原生動畫所需

其他模式檔案

  • @DIALOG_PATTERNS.md - Dialog、Sheet、Adapt、無障礙
  • @FORM_PATTERNS.md - Form、Input、Label、搭配 zod 驗證
  • @ANIMATION_PATTERNS.md - 動畫驅動程式、enterStyle/exitStyle
  • @OVERLAY_PATTERNS.md - Popover、Tooltip、Select
  • @COMPILER_PATTERNS.md - 編譯器最佳化詳細資訊
  • @DESIGN_SYSTEM.md - 設計 Token 與主題設定

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Next.js 16+ uses App Router with Server Components by default. Client Components are only used when interactivity is needed (hooks, event handlers, browser APIs).

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相關技能