@jhm1909/ag-kit 0.1.0

package/.agent/skills/mobile-developer/building-ui/references/tabs.md

@@ -0,0 +1,368 @@
+# Native Tabs
+
+Always prefer NativeTabs from 'expo-router/unstable-native-tabs' for the best iOS experience.
+
+**Requires SDK 54+**
+
+## Basic Usage
+
+```tsx
+import {
+  NativeTabs,
+  Icon,
+  Label,
+  Badge,
+} from "expo-router/unstable-native-tabs";
+
+export default function TabLayout() {
+  return (
+    <NativeTabs minimizeBehavior="onScrollDown">
+      <NativeTabs.Trigger name="index">
+        <Label>Home</Label>
+        <Icon sf="house.fill" />
+        <Badge>9+</Badge>
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name="settings">
+        <Icon sf="gear" />
+        <Label>Settings</Label>
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name="(search)" role="search">
+        <Label>Search</Label>
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  );
+}
+```
+
+## Rules
+
+- You must include a trigger for each tab
+- The `NativeTabs.Trigger` 'name' must match the route name, including parentheses (e.g. `<NativeTabs.Trigger name="(search)">`)
+- Prefer search tab to be last in the list so it can combine with the search bar
+- Use the 'role' prop for common tab types
+
+## Platform Features
+
+Native Tabs use platform-specific tab bar implementations:
+
+- **iOS 26+**: Liquid glass effects with system-native appearance
+- **Android**: Material 3 bottom navigation
+- Better performance and native feel
+
+## Icon Component
+
+```tsx
+// SF Symbol only (iOS)
+<Icon sf="house.fill" />
+
+// With Android drawable
+<Icon sf="house.fill" drawable="ic_home" />
+
+// Custom image source
+<Icon src={require('./icon.png')} />
+
+// State variants (default/selected)
+<Icon sf={{ default: "house", selected: "house.fill" }} />
+```
+
+## Label Component
+
+```tsx
+// Basic label
+<Label>Home</Label>
+
+// Hidden label (icon only)
+<Label hidden>Home</Label>
+```
+
+## Badge Component
+
+```tsx
+// Numeric badge
+<Badge>9+</Badge>
+
+// Dot indicator (empty badge)
+<Badge />
+```
+
+## iOS 26 Features
+
+### Liquid Glass Tab Bar
+
+The tab bar automatically adopts liquid glass appearance on iOS 26+.
+
+### Minimize on Scroll
+
+```tsx
+<NativeTabs minimizeBehavior="onScrollDown">
+```
+
+### Search Tab
+
+Add a dedicated search tab that integrates with the tab bar search field:
+
+```tsx
+<NativeTabs.Trigger name="(search)" role="search">
+  <Label>Search</Label>
+</NativeTabs.Trigger>
+```
+
+**Note**: Place search tab last for best UX.
+
+### Role Prop
+
+Use semantic roles for special tab types:
+
+```tsx
+<NativeTabs.Trigger name="search" role="search" />
+<NativeTabs.Trigger name="favorites" role="favorites" />
+<NativeTabs.Trigger name="more" role="more" />
+```
+
+Available roles: `search` | `more` | `favorites` | `bookmarks` | `contacts` | `downloads` | `featured` | `history` | `mostRecent` | `mostViewed` | `recents` | `topRated`
+
+## Customization
+
+### Tint Color
+
+```tsx
+<NativeTabs tintColor="#007AFF">
+```
+
+### Dynamic Colors (iOS)
+
+Use DynamicColorIOS for colors that adapt to liquid glass:
+
+```tsx
+import { DynamicColorIOS, Platform } from 'react-native';
+
+const adaptiveBlue = Platform.select({
+  ios: DynamicColorIOS({ light: '#007AFF', dark: '#0A84FF' }),
+  default: '#007AFF',
+});
+
+<NativeTabs tintColor={adaptiveBlue}>
+```
+
+## Conditional Tabs
+
+Hide tabs conditionally:
+
+```tsx
+<NativeTabs.Trigger name="admin" hidden={!isAdmin}>
+  <Label>Admin</Label>
+  <Icon sf="shield.fill" />
+</NativeTabs.Trigger>
+```
+
+## Behavior Options
+
+```tsx
+<NativeTabs.Trigger
+  name="home"
+  disablePopToTop    // Don't pop stack when tapping active tab
+  disableScrollToTop // Don't scroll to top when tapping active tab
+>
+```
+
+## Using Vector Icons
+
+If you must use @expo/vector-icons instead of SF Symbols:
+
+```tsx
+import { VectorIcon } from "expo-router/unstable-native-tabs";
+import Ionicons from "@expo/vector-icons/Ionicons";
+
+<NativeTabs.Trigger name="home">
+  <VectorIcon vector={Ionicons} name="home" />
+  <Label>Home</Label>
+</NativeTabs.Trigger>;
+```
+
+**Prefer SF Symbols over vector icons for native feel on Apple platforms.**
+
+## Structure with Stacks
+
+Native tabs don't render headers. Nest Stacks inside each tab for navigation headers:
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs, Icon, Label } from "expo-router/unstable-native-tabs";
+
+export default function TabLayout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name="(home)">
+        <Label>Home</Label>
+        <Icon sf="house.fill" />
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  );
+}
+
+// app/(tabs)/(home)/_layout.tsx
+import Stack from "expo-router/stack";
+
+export default function HomeStack() {
+  return (
+    <Stack>
+      <Stack.Screen
+        name="index"
+        options={{ title: "Home", headerLargeTitle: true }}
+      />
+      <Stack.Screen name="details" options={{ title: "Details" }} />
+    </Stack>
+  );
+}
+```
+
+## Migration from JS Tabs
+
+### Before (JS Tabs)
+
+```tsx
+import { Tabs } from "expo-router";
+
+export default function TabLayout() {
+  return (
+    <Tabs>
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: "Home",
+          tabBarIcon: ({ color }) => (
+            <IconSymbol name="house.fill" color={color} />
+          ),
+        }}
+      />
+      <Tabs.Screen
+        name="settings"
+        options={{
+          title: "Settings",
+          tabBarIcon: ({ color }) => <IconSymbol name="gear" color={color} />,
+        }}
+      />
+    </Tabs>
+  );
+}
+```
+
+### After (Native Tabs)
+
+```tsx
+import { NativeTabs, Icon, Label } from "expo-router/unstable-native-tabs";
+
+export default function TabLayout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name="index">
+        <Label>Home</Label>
+        <Icon sf="house.fill" />
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name="settings">
+        <Label>Settings</Label>
+        <Icon sf="gear" />
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  );
+}
+```
+
+### Key Differences
+
+| JS Tabs                    | Native Tabs               |
+| -------------------------- | ------------------------- |
+| `<Tabs.Screen>`            | `<NativeTabs.Trigger>`    |
+| `options={{ title }}`      | `<Label>Title</Label>`    |
+| `options={{ tabBarIcon }}` | `<Icon sf="symbol" />`    |
+| Props-based API            | React component-based API |
+| `tabBarBadge` option       | `<Badge>` component       |
+
+### Migration Steps
+
+1. **Change imports**
+
+   ```tsx
+   // Remove
+   import { Tabs } from "expo-router";
+
+   // Add
+   import {
+     NativeTabs,
+     Icon,
+     Label,
+     Badge,
+   } from "expo-router/unstable-native-tabs";
+   ```
+
+2. **Replace Tabs with NativeTabs**
+
+   ```tsx
+   // Before
+   <Tabs screenOptions={{ ... }}>
+
+   // After
+   <NativeTabs>
+   ```
+
+3. **Convert each Screen to Trigger**
+
+   ```tsx
+   // Before
+   <Tabs.Screen
+     name="home"
+     options={{
+       title: 'Home',
+       tabBarIcon: ({ color }) => <Icon name="house" color={color} />,
+       tabBarBadge: 3,
+     }}
+   />
+
+   // After
+   <NativeTabs.Trigger name="home">
+     <Label>Home</Label>
+     <Icon sf="house.fill" />
+     <Badge>3</Badge>
+   </NativeTabs.Trigger>
+   ```
+
+4. **Move headers to nested Stack** - Native tabs don't render headers
+   ```
+   app/
+     (tabs)/
+       _layout.tsx      <- NativeTabs
+       (home)/
+         _layout.tsx    <- Stack with headers
+         index.tsx
+       (settings)/
+         _layout.tsx    <- Stack with headers
+         index.tsx
+   ```
+
+## Limitations
+
+- **Android**: Maximum 5 tabs (Material Design constraint)
+- **Nesting**: Native tabs cannot nest inside other native tabs
+- **Tab bar height**: Cannot be measured programmatically
+- **FlatList transparency**: Use `disableTransparentOnScrollEdge` to fix issues
+
+## Keyboard Handling (Android)
+
+Configure in app.json:
+
+```json
+{
+  "expo": {
+    "android": {
+      "softwareKeyboardLayoutMode": "resize"
+    }
+  }
+}
+```
+
+## Common Issues
+
+1. **Icons not showing on Android**: Add `drawable` prop or use `VectorIcon`
+2. **Headers missing**: Nest a Stack inside each tab group
+3. **Trigger name mismatch**: Ensure `name` matches exact route name including parentheses
+4. **Badge not visible**: Badge must be a child of Trigger, not a prop

package/.agent/skills/mobile-developer/building-ui/references/visual-effects.md

@@ -0,0 +1,197 @@
+# Visual Effects
+
+## Backdrop Blur
+
+Use `expo-blur` for blur effects. Prefer systemMaterial tints as they adapt to dark mode.
+
+```tsx
+import { BlurView } from "expo-blur";
+
+<BlurView tint="systemMaterial" intensity={100} />;
+```
+
+### Tint Options
+
+```tsx
+// System materials (adapt to dark mode)
+<BlurView tint="systemMaterial" />
+<BlurView tint="systemThinMaterial" />
+<BlurView tint="systemUltraThinMaterial" />
+<BlurView tint="systemThickMaterial" />
+<BlurView tint="systemChromeMaterial" />
+
+// Basic tints
+<BlurView tint="light" />
+<BlurView tint="dark" />
+<BlurView tint="default" />
+
+// Prominent (more visible)
+<BlurView tint="prominent" />
+
+// Extra light/dark
+<BlurView tint="extraLight" />
+```
+
+### Intensity
+
+Control blur strength with `intensity` (0-100):
+
+```tsx
+<BlurView tint="systemMaterial" intensity={50} />  // Subtle
+<BlurView tint="systemMaterial" intensity={100} /> // Full
+```
+
+### Rounded Corners
+
+BlurView requires `overflow: 'hidden'` to clip rounded corners:
+
+```tsx
+<BlurView
+  tint="systemMaterial"
+  intensity={100}
+  style={{
+    borderRadius: 16,
+    overflow: 'hidden',
+  }}
+/>
+```
+
+### Overlay Pattern
+
+Common pattern for overlaying blur on content:
+
+```tsx
+<View style={{ position: 'relative' }}>
+  <Image source={{ uri: '...' }} style={{ width: '100%', height: 200 }} />
+  <BlurView
+    tint="systemUltraThinMaterial"
+    intensity={80}
+    style={{
+      position: 'absolute',
+      bottom: 0,
+      left: 0,
+      right: 0,
+      padding: 16,
+    }}
+  >
+    <Text style={{ color: 'white' }}>Caption</Text>
+  </BlurView>
+</View>
+```
+
+## Glass Effects (iOS 26+)
+
+Use `expo-glass-effect` for liquid glass backdrops on iOS 26+.
+
+```tsx
+import { GlassView } from "expo-glass-effect";
+
+<GlassView style={{ borderRadius: 16, padding: 16 }}>
+  <Text>Content inside glass</Text>
+</GlassView>
+```
+
+### Interactive Glass
+
+Add `isInteractive` for buttons and pressable glass:
+
+```tsx
+import { GlassView } from "expo-glass-effect";
+import { SymbolView } from "expo-symbols";
+import { PlatformColor } from "react-native";
+
+<GlassView isInteractive style={{ borderRadius: 50 }}>
+  <Pressable style={{ padding: 12 }} onPress={handlePress}>
+    <SymbolView name="plus" tintColor={PlatformColor("label")} size={36} />
+  </Pressable>
+</GlassView>
+```
+
+### Glass Buttons
+
+Create liquid glass buttons:
+
+```tsx
+function GlassButton({ icon, onPress }) {
+  return (
+    <GlassView isInteractive style={{ borderRadius: 50 }}>
+      <Pressable style={{ padding: 12 }} onPress={onPress}>
+        <SymbolView name={icon} tintColor={PlatformColor("label")} size={24} />
+      </Pressable>
+    </GlassView>
+  );
+}
+
+// Usage
+<GlassButton icon="plus" onPress={handleAdd} />
+<GlassButton icon="gear" onPress={handleSettings} />
+```
+
+### Glass Card
+
+```tsx
+<GlassView style={{ borderRadius: 20, padding: 20 }}>
+  <Text style={{ fontSize: 18, fontWeight: '600', color: PlatformColor("label") }}>
+    Card Title
+  </Text>
+  <Text style={{ color: PlatformColor("secondaryLabel"), marginTop: 8 }}>
+    Card content goes here
+  </Text>
+</GlassView>
+```
+
+### Checking Availability
+
+```tsx
+import { isLiquidGlassAvailable } from "expo-glass-effect";
+
+if (isLiquidGlassAvailable()) {
+  // Use GlassView
+} else {
+  // Fallback to BlurView or solid background
+}
+```
+
+### Fallback Pattern
+
+```tsx
+import { GlassView, isLiquidGlassAvailable } from "expo-glass-effect";
+import { BlurView } from "expo-blur";
+
+function AdaptiveGlass({ children, style }) {
+  if (isLiquidGlassAvailable()) {
+    return <GlassView style={style}>{children}</GlassView>;
+  }
+
+  return (
+    <BlurView tint="systemMaterial" intensity={80} style={style}>
+      {children}
+    </BlurView>
+  );
+}
+```
+
+## Sheet with Glass Background
+
+Make sheet backgrounds liquid glass on iOS 26+:
+
+```tsx
+<Stack.Screen
+  name="sheet"
+  options={{
+    presentation: "formSheet",
+    sheetGrabberVisible: true,
+    sheetAllowedDetents: [0.5, 1.0],
+    contentStyle: { backgroundColor: "transparent" },
+  }}
+/>
+```
+
+## Best Practices
+
+- Use `systemMaterial` tints for automatic dark mode support
+- Always set `overflow: 'hidden'` on BlurView for rounded corners
+- Use `isInteractive` on GlassView for buttons and pressables
+- Check `isLiquidGlassAvailable()` and provide fallbacks
+- Avoid nesting blur views (performance impact)
+- Keep blur intensity reasonable (50-100) for readability