opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/building-native-ui/SKILL.md

@@ -2,17 +2,19 @@
 name: building-native-ui
 description: Complete guide for building beautiful apps with Expo Router. Covers fundamentals, styling, components, navigation, animations, patterns, and native tabs.
 risk: unknown
-source: community
-version: 1.0.1
+source: https://github.com/expo/skills/tree/main/plugins/expo/skills/building-native-ui
+source_repo: expo/skills
+source_type: official
+date_added: 2026-07-01
 license: MIT
+license_source: https://github.com/expo/skills/blob/main/LICENSE
 ---
 
 # Expo UI Guidelines
-
 ## When to Use
-- You are building a native-feeling Expo Router application and need guidance on navigation, controls, effects, or platform-specific UI.
-- You need to decide whether Expo Go is sufficient or a custom native build is actually required.
-- The task involves modern Expo UI patterns across animations, tabs, headers, storage, media, or visual effects.
+
+Use this skill when you need complete guide for building beautiful apps with Expo Router. Covers fundamentals, styling, components, navigation, animations, patterns, and native tabs.
+
 
 ## References
 
@@ -22,7 +24,7 @@ Consult these resources as needed:
 references/
   animations.md          Reanimated: entering, exiting, layout, scroll-driven, gestures
   controls.md            Native iOS: Switch, Slider, SegmentedControl, DateTimePicker, Picker
-  form-sheet.md          Form sheets in expo-router: configuration, footers and background interaction. 
+  form-sheet.md          Form sheets in expo-router: configuration, footers and background interaction.
   gradients.md           CSS gradients via experimental_backgroundImage (New Arch only)
   icons.md               SF Symbols via expo-image (sf: source), names, animations, weights
   media.md               Camera, audio, video, and file saving
@@ -95,6 +97,8 @@ See `./references/route-structure.md` for detailed route conventions.
 - `React.use` not `React.useContext`
 - `expo-image` Image component instead of intrinsic element `img`
 - `expo-glass-effect` for liquid glass backdrops
+- `Color` from `expo-router` for native semantic colors, not raw `PlatformColor` (type-safe, auto-adapts to light/dark)
+- In SDK 56+, never import from `@react-navigation/*` directly — use `expo-router/react-navigation` instead (covers `@react-navigation/native`, `/core`, `/elements`, `/routers`)
 
 ## Responsiveness
 
@@ -132,6 +136,58 @@ Follow Apple Human Interface Guidelines.
 - When padding a ScrollView, use `contentContainerStyle` padding and gap instead of padding on the ScrollView itself (reduces clipping)
 - CSS and Tailwind are not supported - use inline styles
 
+## Colors
+
+Use the `Color` API from `expo-router` for native semantic colors. It is a type-safe wrapper over `PlatformColor` that exposes iOS UIKit colors through `Color.ios.*` and Android Material 3 colors through `Color.android.material.*` (static) or `Color.android.dynamic.*` (adapts to the user's wallpaper on Android 12+). These resolve on-device and automatically adapt to light/dark mode and accessibility settings, so you no longer maintain separate light/dark hex tables or a `colors.web.ts` file.
+
+`Color` is platform-specific, so wrap each value in `Platform.select` with a `default` hex fallback for web. Centralize the palette in `theme/colors.ts` and import `colors` everywhere:
+
+```tsx
+// theme/colors.ts
+import { Platform } from "react-native";
+import { Color } from "expo-router";
+
+export const colors = {
+  label: Platform.select({
+    ios: Color.ios.label,
+    android: Color.android.dynamic.onSurface,
+    default: "#000000",
+  })!,
+  secondaryLabel: Platform.select({
+    ios: Color.ios.secondaryLabel,
+    android: Color.android.dynamic.onSurfaceVariant,
+    default: "#3c3c43",
+  })!,
+  separator: Platform.select({
+    ios: Color.ios.separator,
+    android: Color.android.dynamic.outlineVariant,
+    default: "#c6c6c8",
+  })!,
+  systemBackground: Platform.select({
+    ios: Color.ios.systemBackground,
+    android: Color.android.dynamic.surface,
+    default: "#ffffff",
+  })!,
+  systemBlue: Platform.select({
+    ios: Color.ios.systemBlue,
+    android: Color.android.dynamic.primary,
+    default: "#007aff",
+  })!,
+};
+```
+
+```tsx
+import { colors } from "@/theme/colors";
+
+<View style={{ backgroundColor: colors.systemBackground }}>
+  <Text style={{ color: colors.label }}>Title</Text>
+</View>;
+```
+
+- iOS re-resolves these colors automatically when the system theme changes. On Android, call `useColorScheme()` inside any component that renders them so it re-renders when the theme flips (required when React Compiler memoizes the component).
+- Don't pass `Color` / `PlatformColor` values into Reanimated styles — use static colors there (see `references/animations.md`).
+- `Platform.select({...})!` returns `string | OpaqueColorValue`. Most React Native style props accept `ColorValue` (`string | OpaqueColorValue`) so this works fine. But some third-party props only accept `string` (e.g. `tintColor` on `expo-image`). Cast when needed: `colors.label as string`.
+
 ## Text Styling
 
 - Add the `selectable` prop to every `<Text/>` element displaying important data or error messages
@@ -278,20 +334,22 @@ app/
 
 ```tsx
 // app/_layout.tsx
-import { NativeTabs, Icon, Label } from "expo-router/unstable-native-tabs";
-import { Theme } from "../components/theme";
+import { NativeTabs } from "expo-router/unstable-native-tabs";
+import { ThemeProvider, DarkTheme, DefaultTheme } from "expo-router/react-navigation";
+import { useColorScheme } from "react-native";
 
 export default function Layout() {
+  const colorScheme = useColorScheme();
   return (
-    <Theme>
+    <ThemeProvider value={colorScheme === "dark" ? DarkTheme : DefaultTheme}>
       <NativeTabs>
         <NativeTabs.Trigger name="(index)">
-          <Icon sf="list.dash" />
-          <Label>Items</Label>
+          <NativeTabs.Trigger.Icon sf="list.dash" md="list" />
+          <NativeTabs.Trigger.Label>Items</NativeTabs.Trigger.Label>
         </NativeTabs.Trigger>
         <NativeTabs.Trigger name="(search)" role="search" />
       </NativeTabs>
-    </Theme>
+    </ThemeProvider>
   );
 }
 ```
@@ -301,7 +359,7 @@ Create a shared group route so both tabs can push common screens:
 ```tsx
 // app/(index,search)/_layout.tsx
 import { Stack } from "expo-router/stack";
-import { PlatformColor } from "react-native";
+import { colors } from "@/theme/colors";
 
 export default function Layout({ segment }) {
   const screen = segment.match(/\((.*)\)/)?.[1]!;
@@ -314,7 +372,7 @@ export default function Layout({ segment }) {
         headerShadowVisible: false,
         headerLargeTitleShadowVisible: false,
         headerLargeStyle: { backgroundColor: "transparent" },
-        headerTitleStyle: { color: PlatformColor("label") },
+        headerTitleStyle: { color: colors.label },
         headerLargeTitle: true,
         headerBlurEffect: "none",
         headerBackButtonDisplayMode: "minimal",
@@ -328,6 +386,7 @@ export default function Layout({ segment }) {
 ```
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- Use this skill only when the task clearly matches its upstream product or API scope.
+- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
+- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/building-native-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Building Native UI"
+  short_description: "Build beautiful Expo Router UI with native-feeling navigation, controls, media, animation, and visual effects"
+  default_prompt: "Use $building-native-ui to build or refactor Expo Router UI, choose native-feeling navigation and controls, structure routes, style screens, and decide when Expo Go is enough before creating native builds."

package/bundled-skills/building-native-ui/references/animations.md

@@ -0,0 +1,220 @@
+# Animations
+
+Use Reanimated v4. Avoid React Native's built-in Animated API.
+
+## Entering and Exiting Animations
+
+Use Animated.View with entering and exiting animations. Layout animations can animate state changes.
+
+```tsx
+import Animated, {
+  FadeIn,
+  FadeOut,
+  LinearTransition,
+} from "react-native-reanimated";
+
+function App() {
+  return (
+    <Animated.View
+      entering={FadeIn}
+      exiting={FadeOut}
+      layout={LinearTransition}
+    />
+  );
+}
+```
+
+## On-Scroll Animations
+
+Create high-performance scroll animations using Reanimated's hooks:
+
+```tsx
+import Animated, {
+  useAnimatedRef,
+  useScrollViewOffset,
+  useAnimatedStyle,
+  interpolate,
+} from "react-native-reanimated";
+
+function Page() {
+  const ref = useAnimatedRef();
+  const scroll = useScrollViewOffset(ref);
+
+  const style = useAnimatedStyle(() => ({
+    opacity: interpolate(scroll.value, [0, 30], [0, 1], "clamp"),
+  }));
+
+  return (
+    <Animated.ScrollView ref={ref}>
+      <Animated.View style={style} />
+    </Animated.ScrollView>
+  );
+}
+```
+
+## Common Animation Presets
+
+### Entering Animations
+
+- `FadeIn`, `FadeInUp`, `FadeInDown`, `FadeInLeft`, `FadeInRight`
+- `SlideInUp`, `SlideInDown`, `SlideInLeft`, `SlideInRight`
+- `ZoomIn`, `ZoomInUp`, `ZoomInDown`
+- `BounceIn`, `BounceInUp`, `BounceInDown`
+
+### Exiting Animations
+
+- `FadeOut`, `FadeOutUp`, `FadeOutDown`, `FadeOutLeft`, `FadeOutRight`
+- `SlideOutUp`, `SlideOutDown`, `SlideOutLeft`, `SlideOutRight`
+- `ZoomOut`, `ZoomOutUp`, `ZoomOutDown`
+- `BounceOut`, `BounceOutUp`, `BounceOutDown`
+
+### Layout Animations
+
+- `LinearTransition` — Smooth linear interpolation
+- `SequencedTransition` — Sequenced property changes
+- `FadingTransition` — Fade between states
+
+## Customizing Animations
+
+```tsx
+<Animated.View
+  entering={FadeInDown.duration(500).delay(200)}
+  exiting={FadeOut.duration(300)}
+/>
+```
+
+### Modifiers
+
+```tsx
+// Duration in milliseconds
+FadeIn.duration(300);
+
+// Delay before starting
+FadeIn.delay(100);
+
+// Spring physics
+FadeIn.springify();
+FadeIn.springify().damping(15).stiffness(100);
+
+// Easing curves
+FadeIn.easing(Easing.bezier(0.25, 0.1, 0.25, 1));
+
+// Chaining
+FadeInDown.duration(400).delay(200).springify();
+```
+
+## Shared Value Animations
+
+For imperative control over animations:
+
+```tsx
+import {
+  useSharedValue,
+  withSpring,
+  withTiming,
+} from "react-native-reanimated";
+
+const offset = useSharedValue(0);
+
+// Spring animation
+offset.value = withSpring(100);
+
+// Timing animation
+offset.value = withTiming(100, { duration: 300 });
+
+// Use in styles
+const style = useAnimatedStyle(() => ({
+  transform: [{ translateX: offset.value }],
+}));
+```
+
+## Gesture Animations
+
+Combine with React Native Gesture Handler:
+
+```tsx
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withSpring,
+} from "react-native-reanimated";
+
+function DraggableBox() {
+  const translateX = useSharedValue(0);
+  const translateY = useSharedValue(0);
+
+  const gesture = Gesture.Pan()
+    .onUpdate((e) => {
+      translateX.value = e.translationX;
+      translateY.value = e.translationY;
+    })
+    .onEnd(() => {
+      translateX.value = withSpring(0);
+      translateY.value = withSpring(0);
+    });
+
+  const style = useAnimatedStyle(() => ({
+    transform: [
+      { translateX: translateX.value },
+      { translateY: translateY.value },
+    ],
+  }));
+
+  return (
+    <GestureDetector gesture={gesture}>
+      <Animated.View style={[styles.box, style]} />
+    </GestureDetector>
+  );
+}
+```
+
+## Keyboard Animations
+
+Animate with keyboard height changes:
+
+```tsx
+import Animated, {
+  useAnimatedKeyboard,
+  useAnimatedStyle,
+} from "react-native-reanimated";
+
+function KeyboardAwareView() {
+  const keyboard = useAnimatedKeyboard();
+
+  const style = useAnimatedStyle(() => ({
+    paddingBottom: keyboard.height.value,
+  }));
+
+  return <Animated.View style={style}>{/* content */}</Animated.View>;
+}
+```
+
+## Staggered List Animations
+
+Animate list items with delays:
+
+```tsx
+{
+  items.map((item, index) => (
+    <Animated.View
+      key={item.id}
+      entering={FadeInUp.delay(index * 50)}
+      exiting={FadeOutUp}
+    >
+      <ListItem item={item} />
+    </Animated.View>
+  ));
+}
+```
+
+## Best Practices
+
+- Add entering and exiting animations for state changes
+- Use layout animations when items are added/removed from lists
+- Use `useAnimatedStyle` for scroll-driven animations
+- Prefer `interpolate` with "clamp" for bounded values
+- You can't pass `Color` (from expo-router) or `PlatformColor` values to reanimated views or styles; use static colors instead
+- Keep animations under 300ms for responsive feel
+- Use spring animations for natural movement
+- Avoid animating layout properties (width, height) when possible — prefer transforms

package/bundled-skills/building-native-ui/references/controls.md

@@ -0,0 +1,270 @@
+# Native Controls
+
+Native iOS controls provide built-in haptics, accessibility, and platform-appropriate styling.
+
+## Switch
+
+Use for binary on/off settings. Has built-in haptics.
+
+```tsx
+import { Switch } from "react-native";
+import { useState } from "react";
+
+const [enabled, setEnabled] = useState(false);
+
+<Switch value={enabled} onValueChange={setEnabled} />;
+```
+
+### Customization
+
+```tsx
+<Switch
+  value={enabled}
+  onValueChange={setEnabled}
+  trackColor={{ false: "#767577", true: "#81b0ff" }}
+  thumbColor={enabled ? "#f5dd4b" : "#f4f3f4"}
+  ios_backgroundColor="#3e3e3e"
+/>
+```
+
+## Segmented Control
+
+Use for non-navigational tabs or mode selection. Avoid changing default colors.
+
+```tsx
+import SegmentedControl from "@react-native-segmented-control/segmented-control";
+import { useState } from "react";
+
+const [index, setIndex] = useState(0);
+
+<SegmentedControl
+  values={["All", "Active", "Done"]}
+  selectedIndex={index}
+  onChange={({ nativeEvent }) => setIndex(nativeEvent.selectedSegmentIndex)}
+/>;
+```
+
+### Rules
+
+- Maximum 4 options — use a picker for more
+- Keep labels short (1-2 words)
+- Avoid custom colors — native styling adapts to dark mode
+
+### With Icons (iOS 14+)
+
+```tsx
+<SegmentedControl
+  values={[
+    { label: "List", icon: "list.bullet" },
+    { label: "Grid", icon: "square.grid.2x2" },
+  ]}
+  selectedIndex={index}
+  onChange={({ nativeEvent }) => setIndex(nativeEvent.selectedSegmentIndex)}
+/>
+```
+
+## Slider
+
+Continuous value selection.
+
+```tsx
+import Slider from "@react-native-community/slider";
+import { useState } from "react";
+
+const [value, setValue] = useState(0.5);
+
+<Slider
+  value={value}
+  onValueChange={setValue}
+  minimumValue={0}
+  maximumValue={1}
+/>;
+```
+
+### Customization
+
+```tsx
+<Slider
+  value={value}
+  onValueChange={setValue}
+  minimumValue={0}
+  maximumValue={100}
+  step={1}
+  minimumTrackTintColor="#007AFF"
+  maximumTrackTintColor="#E5E5EA"
+  thumbTintColor="#007AFF"
+/>
+```
+
+### Discrete Steps
+
+```tsx
+<Slider
+  value={value}
+  onValueChange={setValue}
+  minimumValue={0}
+  maximumValue={10}
+  step={1}
+/>
+```
+
+## Date/Time Picker
+
+Compact pickers with popovers. Has built-in haptics.
+
+```tsx
+import DateTimePicker from "@react-native-community/datetimepicker";
+import { useState } from "react";
+
+const [date, setDate] = useState(new Date());
+
+<DateTimePicker
+  value={date}
+  onChange={(event, selectedDate) => {
+    if (selectedDate) setDate(selectedDate);
+  }}
+  mode="datetime"
+/>;
+```
+
+### Modes
+
+- `date` — Date only
+- `time` — Time only
+- `datetime` — Date and time
+
+### Display Styles
+
+```tsx
+// Compact inline (default)
+<DateTimePicker value={date} mode="date" />
+
+// Spinner wheel
+<DateTimePicker
+  value={date}
+  mode="date"
+  display="spinner"
+  style={{ width: 200, height: 150 }}
+/>
+
+// Full calendar
+<DateTimePicker value={date} mode="date" display="inline" />
+```
+
+### Time Intervals
+
+```tsx
+<DateTimePicker
+  value={date}
+  mode="time"
+  minuteInterval={15}
+/>
+```
+
+### Min/Max Dates
+
+```tsx
+<DateTimePicker
+  value={date}
+  mode="date"
+  minimumDate={new Date(2020, 0, 1)}
+  maximumDate={new Date(2030, 11, 31)}
+/>
+```
+
+## Stepper
+
+Increment/decrement numeric values.
+
+```tsx
+import { Stepper } from "react-native";
+import { useState } from "react";
+
+const [count, setCount] = useState(0);
+
+<Stepper
+  value={count}
+  onValueChange={setCount}
+  minimumValue={0}
+  maximumValue={10}
+/>;
+```
+
+## TextInput
+
+Native text input with various keyboard types.
+
+```tsx
+import { TextInput } from "react-native";
+
+<TextInput
+  placeholder="Enter text..."
+  placeholderTextColor="#999"
+  style={{
+    padding: 12,
+    fontSize: 16,
+    borderRadius: 8,
+    backgroundColor: "#f0f0f0",
+  }}
+/>
+```
+
+### Keyboard Types
+
+```tsx
+// Email
+<TextInput keyboardType="email-address" autoCapitalize="none" />
+
+// Phone
+<TextInput keyboardType="phone-pad" />
+
+// Number
+<TextInput keyboardType="numeric" />
+
+// Password
+<TextInput secureTextEntry />
+
+// Search
+<TextInput
+  returnKeyType="search"
+  enablesReturnKeyAutomatically
+/>
+```
+
+### Multiline
+
+```tsx
+<TextInput
+  multiline
+  numberOfLines={4}
+  textAlignVertical="top"
+  style={{ minHeight: 100 }}
+/>
+```
+
+## Picker (Wheel)
+
+For selection from many options (5+ items).
+
+```tsx
+import { Picker } from "@react-native-picker/picker";
+import { useState } from "react";
+
+const [selected, setSelected] = useState("js");
+
+<Picker selectedValue={selected} onValueChange={setSelected}>
+  <Picker.Item label="JavaScript" value="js" />
+  <Picker.Item label="TypeScript" value="ts" />
+  <Picker.Item label="Python" value="py" />
+  <Picker.Item label="Go" value="go" />
+</Picker>;
+```
+
+## Best Practices
+
+- **Haptics**: Switch and DateTimePicker have built-in haptics — don't add extra
+- **Accessibility**: Native controls have proper accessibility labels by default
+- **Dark Mode**: Avoid custom colors — native styling adapts automatically
+- **Spacing**: Use consistent padding around controls (12-16pt)
+- **Labels**: Place labels above or to the left of controls
+- **Grouping**: Group related controls in sections with headers