agentleFS
elbionredenicaelbionredenica/consumer-app-starter/.agents/skills/building-native-ui/SKILL.md

building-native-ui

Skill0 starsChanged 2 months agoMITView on GitHub

Complete guide for building beautiful apps with Expo Router. Covers fundamentals, styling, components, navigation, animations, patterns, and native tabs.

  • Reads credentials

15 other projects use a version of this, 15 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use web-design-guidelines and find-skills.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • VercelSkill

    web-design-guidelines

    Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

    Also in 3 projects that use this

  • VercelSkill

    find-skills

    Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

38 rules. 23 are common, 0 are distinctive, and 15 are very specific to this project.

  • 23

    Common

    Most of the 15 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 15

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    Always use import statements at the top of the file.

    line 42
  2. Very specific:

    Always use kebab-case for file names, e.g.

    line 43
  3. Common:

    Always remove old route files when moving or restructuring navigation

    line 44
  4. Common:

    Never use special characters in file names

    line 45
  5. Common:

    Never co-locate components, types, or utilities in the app directory.

    line 53
  6. Common:

    Ensure the app always has a route that matches "/", it may be inside a group route.

    line 54
  7. Common:

    Never use modules removed from React Native such as Picker, WebView, SafeAreaView, or AsyncStorage

    line 58
  8. Common:

    Never use legacy expo-permissions

    line 59
  9. Common:

    Always wrap root component in a scroll view for responsiveness

    line 71
  10. Very specific:

    Use <ScrollView contentInsetAdjustmentBehavior="automatic" /> instead of <SafeAreaView> for smarter safe area insets

    line 72
  11. Common:

    Use flexbox instead of Dimensions API

    line 74
  12. Very specific:

    ALWAYS prefer useWindowDimensions over Dimensions.get() to measure screen size

    line 75
  13. Common:

    Use expo-haptics conditionally on iOS to make more delightful experiences

    line 79
  14. Very specific:

    Use views with built-in haptics like <Switch /> from React Native and @react-native-community/datetimepicker

    line 80
  15. Very specific:

    When a route belongs to a Stack, its first child should almost always be a ScrollView with contentInsetAdjustmentBehavior="automatic" set

    line 81
  16. Very specific:

    When adding a ScrollView to the page it should almost always be the first component inside the route component

    line 82
  17. Very specific:

    Prefer headerSearchBarOptions in Stack.Screen options to add a search bar

    line 83
  18. Very specific:

    Use the <Text selectable /> prop on text containing data that could be copied

    line 84
  19. Common:

    Consider formatting large numbers like 1.4M or 38k

    line 85
  20. Common:

    Never use intrinsic elements like 'img' or 'div' unless in a webview or Expo DOM component

    line 86
  21. Common:

    Follow Apple Human Interface Guidelines.

    line 90
  22. Common:

    Prefer flex gap over margin and padding styles

    line 94
  23. Common:

    Prefer padding over margin where possible

    line 95
  24. Very specific:

    Always account for safe area, either with stack headers, tabs, or ScrollView/FlatList contentInsetAdjustmentBehavior="automatic"

    line 96
  25. Common:

    Ensure both top and bottom safe area insets are accounted for

    line 97
  26. Common:

    Add entering and exiting animations for state changes

    line 99
  27. Very specific:

    Use { borderCurve: 'continuous' } for rounded corners unless creating a capsule shape

    line 100
  28. Common:

    ALWAYS use a navigation stack title instead of a custom text element on the page

    line 101
  29. Very specific:

    When padding a ScrollView, use contentContainerStyle padding and gap instead of padding on the ScrollView itself (reduces clipping)

    line 102
  30. Very specific:

    Add the selectable prop to every <Text/> element displaying important data or error messages

    line 107
  31. Very specific:

    Use CSS boxShadow style prop.

    line 112
  32. Very specific:

    Use <Link href="/path" /> from 'expo-router' for navigation between routes.

    line 124
  33. Very specific:

    ALWAYS use _layout.tsx files to define stacks

    line 142
  34. Common:

    Use Stack from 'expo-router/stack' for native navigation stacks

    line 143
  35. Common:

    Add long press context menus to Link components:

    line 155
  36. Common:

    Use link previews frequently to enhance navigation:

    line 193
  37. Common:

    Prefer this to building a custom modal component.

    line 216
  38. Common:

    Create a shared group route so both tabs can push common screens:

    line 269

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Starter integration: root AGENTS.md and docs define the chosen stack and commands. Use Next.js for backend routes and EAS for native builds. Apply platform principles to React Native; do not create an Xcode project or product specification from these examples. Supporting references describe options, not installed capabilities.

Expo UI Guidelines

References

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. 
  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
  route-structure.md     Route conventions, dynamic routes, groups, folder organization
  search.md              Search bar with headers, useSearch hook, filtering patterns
  storage.md             SQLite, AsyncStorage, SecureStore
  tabs.md                NativeTabs, migration from JS tabs, iOS 26 features
  toolbar-and-headers.md Stack headers and toolbar buttons, menus, search (iOS only)
  visual-effects.md      Blur (expo-blur) and liquid glass (expo-glass-effect)
  webgpu-three.md        3D graphics, games, GPU visualizations with WebGPU and Three.js
  zoom-transitions.md    Apple Zoom: fluid zoom transitions with Link.AppleZoom (iOS 18+)

Running the app in this starter

Use pnpm dev from the repository root and the installed EAS development client. Native builds use the root build:ios:* commands with the owner's authorization. Do not run local native builds. See the root AGENTS.md and docs/releases.md. Upstream platform examples below are references; use the installed Expo SDK's APIs.

Code Style

  • Be cautious of unterminated strings. Ensure nested backticks are escaped; never forget to escape quotes correctly.
  • Always use import statements at the top of the file.
  • Always use kebab-case for file names, e.g. comment-card.tsx
  • Always remove old route files when moving or restructuring navigation
  • Never use special characters in file names
  • Configure tsconfig.json with path aliases, and prefer aliases over relative imports for refactors.

Routes

See ./references/route-structure.md for detailed route conventions.

  • Routes belong in the app directory.
  • Never co-locate components, types, or utilities in the app directory. This is an anti-pattern.
  • Ensure the app always has a route that matches "/", it may be inside a group route.

Library Preferences

  • Never use modules removed from React Native such as Picker, WebView, SafeAreaView, or AsyncStorage
  • Never use legacy expo-permissions
  • expo-audio not expo-av
  • expo-video not expo-av
  • expo-image with source="sf:name" for SF Symbols, not expo-symbols or @expo/vector-icons
  • react-native-safe-area-context not react-native SafeAreaView
  • process.env.EXPO_OS not Platform.OS
  • React.use not React.useContext
  • expo-image Image component instead of intrinsic element img
  • expo-glass-effect for liquid glass backdrops

Responsiveness

  • Always wrap root component in a scroll view for responsiveness
  • Use <ScrollView contentInsetAdjustmentBehavior="automatic" /> instead of <SafeAreaView> for smarter safe area insets
  • contentInsetAdjustmentBehavior="automatic" should be applied to FlatList and SectionList as well
  • Use flexbox instead of Dimensions API
  • ALWAYS prefer useWindowDimensions over Dimensions.get() to measure screen size

Behavior

  • Use expo-haptics conditionally on iOS to make more delightful experiences
  • Use views with built-in haptics like <Switch /> from React Native and @react-native-community/datetimepicker
  • When a route belongs to a Stack, its first child should almost always be a ScrollView with contentInsetAdjustmentBehavior="automatic" set
  • When adding a ScrollView to the page it should almost always be the first component inside the route component
  • Prefer headerSearchBarOptions in Stack.Screen options to add a search bar
  • Use the <Text selectable /> prop on text containing data that could be copied
  • Consider formatting large numbers like 1.4M or 38k
  • Never use intrinsic elements like 'img' or 'div' unless in a webview or Expo DOM component

Styling

Follow Apple Human Interface Guidelines.

General Styling Rules

  • Prefer flex gap over margin and padding styles
  • Prefer padding over margin where possible
  • Always account for safe area, either with stack headers, tabs, or ScrollView/FlatList contentInsetAdjustmentBehavior="automatic"
  • Ensure both top and bottom safe area insets are accounted for
  • Inline styles not StyleSheet.create unless reusing styles is faster
  • Add entering and exiting animations for state changes
  • Use { borderCurve: 'continuous' } for rounded corners unless creating a capsule shape
  • ALWAYS use a navigation stack title instead of a custom text element on the page
  • 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

Text Styling

  • Add the selectable prop to every <Text/> element displaying important data or error messages
  • Counters should use { fontVariant: 'tabular-nums' } for alignment

Shadows

Use CSS boxShadow style prop. NEVER use legacy React Native shadow or elevation styles.

<View style={{ boxShadow: "0 1px 2px rgba(0, 0, 0, 0.05)" }} />

'inset' shadows are supported.

Navigation

Link

Use <Link href="/path" /> from 'expo-router' for navigation between routes.

import { Link } from 'expo-router';

// Basic link
<Link href="/path" />

// Wrapping custom components
<Link href="/path" asChild>
  <Pressable>...</Pressable>
</Link>

Whenever possible, include a <Link.Preview> to follow iOS conventions. Add context menus and previews frequently to enhance navigation.

Stack

  • ALWAYS use _layout.tsx files to define stacks
  • Use Stack from 'expo-router/stack' for native navigation stacks

Page Title

Set the page title in Stack.Screen options:

<Stack.Screen options={{ title: "Home" }} />

Context Menus

Add long press context menus to Link components:

import { Link } from "expo-router";

<Link href="/settings" asChild>
  <Link.Trigger>
    <Pressable>
      <Card />
    </Pressable>
  </Link.Trigger>
  <Link.Menu>
    <Link.MenuAction
      title="Share"
      icon="square.and.arrow.up"
      onPress={handleSharePress}
    />
    <Link.MenuAction
      title="Block"
      icon="nosign"
      destructive
      onPress={handleBlockPress}
    />
    <Link.Menu title="More" icon="ellipsis">
      <Link.MenuAction title="Copy" icon="doc.on.doc" onPress={() => {}} />
      <Link.MenuAction
        title="Delete"
        icon="trash"
        destructive
        onPress={() => {}}
      />
    </Link.Menu>
  </Link.Menu>
</Link>;

Link Previews

Use link previews frequently to enhance navigation:

<Link href="/settings">
  <Link.Trigger>
    <Pressable>
      <Card />
    </Pressable>
  </Link.Trigger>
  <Link.Preview />
</Link>

Link preview can be used with context menus.

Modal

Present a screen as a modal:

<Stack.Screen name="modal" options={{ presentation: "modal" }} />

Prefer this to building a custom modal component.

Sheet

Present a screen as a dynamic form sheet:

<Stack.Screen
  name="sheet"
  options={{
    presentation: "formSheet",
    sheetGrabberVisible: true,
    sheetAllowedDetents: [0.5, 1.0],
    contentStyle: { backgroundColor: "transparent" },
  }}
/>
  • Using contentStyle: { backgroundColor: "transparent" } makes the background liquid glass on iOS 26+.

Common route structure

A standard app layout with tabs and stacks inside each tab:

app/
  _layout.tsx — <NativeTabs />
  (index,search)/
    _layout.tsx — <Stack />
    index.tsx — Main list
    search.tsx — Search view
// app/_layout.tsx
import { NativeTabs, Icon, Label } from "expo-router/unstable-native-tabs";
import { Theme } from "../components/theme";

export default function Layout() {
  return (
    <Theme>
      <NativeTabs>
        <NativeTabs.Trigger name="(index)">
          <Icon sf="list.dash" />
          <Label>Items</Label>
        </NativeTabs.Trigger>
        <NativeTabs.Trigger name="(search)" role="search" />
      </NativeTabs>
    </Theme>
  );
}

Create a shared group route so both tabs can push common screens:

// app/(index,search)/_layout.tsx
import { Stack } from "expo-router/stack";
import { PlatformColor } from "react-native";

export default function Layout({ segment }) {
  const screen = segment.match(/\((.*)\)/)?.[1]!;
  const titles: Record<string, string> = { index: "Items", search: "Search" };

  return (
    <Stack
      screenOptions={{
        headerTransparent: true,
        headerShadowVisible: false,
        headerLargeTitleShadowVisible: false,
        headerLargeStyle: { backgroundColor: "transparent" },
        headerTitleStyle: { color: PlatformColor("label") },
        headerLargeTitle: true,
        headerBlurEffect: "none",
        headerBackButtonDisplayMode: "minimal",
      }}
    >
      <Stack.Screen name={screen} options={{ title: titles[screen] }} />
      <Stack.Screen name="i/[id]" options={{ headerLargeTitle: false }} />
    </Stack>
  );
}

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.