Add gluestack-ui cursorrules under Mobile Development

README.md

@@ -163,6 +163,7 @@ By adding selected `.mdc` files to `.cursor/rules/`, you can use these rules dir
 - [Android Native (Jetpack Compose)](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/android-jetpack-compose-cursorrules-prompt-file.mdc) - Android development with Jetpack Compose integration.
 - [Cursor Rules Pack v2](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/cursor-rules-pack-v2-cursorrules-prompt-file.mdc) - 7 sample production-tested rules (dependency discipline, error handling, state management, webhook security, and more). See the pack README for full-pack details.
 - [Flutter Expert](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/flutter-app-expert-cursorrules-prompt-file.mdc) - Flutter development with expert integration.
+- [gluestack-ui (React Native, Expo, Next.js, NativeWind)](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/gluestack-ui-cursorrules-prompt-file.mdc) - Semantic tokens, compound components (InputSlot/ButtonText), resolution hierarchy, tva variants, and cross-platform constraints. Adapted from the official gluestack/agent-skills repo.
 - [HarmonyOS ArkTS](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/harmony-arkts.mdc) - Components, state, resources, lifecycle, layout, and accessibility.
 - [NativeScript](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/nativescript-cursorrules-prompt-file.mdc) - Cross-platform mobile app development.
 - [React Native Expo](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/react-native-expo-cursorrules-prompt-file.mdc) - Expo-based mobile app development.

rules/gluestack-ui-cursorrules-prompt-file.mdc

@@ -0,0 +1,134 @@
+---
+description: "Cursor rules for building UIs with gluestack-ui in React Native, Expo, and Next.js. Adapted from the official gluestack/agent-skills repo."
+globs: ["**/*.{ts,tsx,js,jsx}"]
+alwaysApply: false
+---
+
+# gluestack-ui
+
+gluestack-ui is a copy-paste universal component library for React Native, Expo, and Next.js, styled with NativeWind. Components live in `components/ui/` in your repo, not in `node_modules`.
+
+These rules are adapted from the official [gluestack/agent-skills](https://github.com/gluestack/agent-skills) skill (MIT-licensed). When in doubt, verify against the live docs at `https://gluestack.io/ui/docs/components/${componentName}/`.
+
+## Core principles
+
+1. **gluestack components over React Native primitives.** Use `<Box>`, `<HStack>`, `<VStack>`, `<Text>`, `<Heading>`, `<Pressable>` from `@/components/ui/...` instead of bare `<View>` / `<Text>` from `react-native`.
+2. **Component props over className utilities.** When a built-in prop exists (`size`, `variant`, `space`), use it instead of an equivalent `className`.
+3. **Semantic tokens ONLY.** NEVER use `typography-*`, `neutral-*`, `gray-*`, `slate-*`, or numbered colors (`red-500`, `blue-600`, `bg-blue-500`). ONLY use semantic tokens: `text-foreground`, `text-muted-foreground`, `bg-primary`, `bg-card`, `border-border`, `bg-destructive`, etc. Alpha is allowed (`/70`, `/90`).
+4. **className over inline styles.** Inline `style={...}` bypasses optimization and theming. Reserve it for runtime-computed values only.
+5. **Follow the spacing scale.** Use `0, 0.5, 1, 2, 3, 4, 6, 8, ...`. No arbitrary `p-[13px]` values.
+6. **Compound sub-components are required.** Never put bare text/icons inside parent components.
+7. **Use tva for variants** when standardizing repeated style combinations.
+8. **Dark mode via `dark:` prefix.** Uses CSS variables. Don't fork components per theme.
+
+## Resolution hierarchy
+
+When choosing how to style something, pick the highest item that works:
+
+1. Component props (`size`, `variant`, `space`)
+2. className utilities (semantic tokens only)
+3. Built-in gluestack component variants
+4. `tva` (Tailwind Variant Authority) for new reusable variants
+5. NativeWind interop (only to enable `className` on third-party components)
+6. Inline `style={...}` — last resort, must be justified in a comment
+
+## Compound component patterns
+
+```tsx
+// Layout with spacing prop
+<VStack space="lg" className="p-4">
+  <Heading size="xl" bold>Title</Heading>
+  <Text size="md" className="text-muted-foreground">Description</Text>
+</VStack>
+
+// Button — always wrap text in ButtonText, icons in ButtonIcon
+<Button variant="outline" size="lg">
+  <ButtonText>Click Me</ButtonText>
+  <ButtonIcon as={ChevronRightIcon} />
+</Button>
+
+// Input — InputIcon MUST be inside InputSlot. This is critical.
+<Input>
+  <InputSlot>
+    <InputIcon as={MailIcon} className="text-muted-foreground" />
+  </InputSlot>
+  <InputField placeholder="Enter email" />
+</Input>
+
+// FormControl cluster — don't render Input standalone if it has a label/error
+<FormControl isInvalid={hasError}>
+  <FormControlLabel>
+    <FormControlLabelText>Email</FormControlLabelText>
+  </FormControlLabel>
+  <Input>
+    <InputField value={email} onChangeText={setEmail} />
+  </Input>
+  <FormControlError>
+    <FormControlErrorText>{errorMessage}</FormControlErrorText>
+  </FormControlError>
+</FormControl>
+
+// Semantic color tokens — never raw colors
+<Box className="bg-primary">
+  <Text className="text-primary-foreground">Content</Text>
+</Box>
+```
+
+## Setup and imports
+
+- Components are added with the official CLI: `npx gluestack-ui@alpha init -y` then `npx gluestack-ui@alpha add --all -y` (or `add Button` for individual components).
+- Import path is local: `import { Button, ButtonText } from "@/components/ui/button"`.
+- **Don't import from `@gluestack-ui/themed`.** That's the legacy themed package — gluestack-ui now uses the copy-paste model.
+- The app must be wrapped in `<GluestackUIProvider>` at the root (see docs for the platform-specific setup).
+
+## Cross-platform constraints
+
+- Code must compile for web (Next.js / Expo Router web) AND native (iOS / Android). Avoid `document` / `window` in UI components, or guard with `Platform.OS === 'web'`.
+- Use the gluestack `<Pressable>` for tap targets — never `<div onClick>` for native compatibility.
+- For long lists, use `FlatList` / `SectionList` on native. gluestack doesn't ship list virtualization.
+- Use Reanimated for animations; avoid the legacy `Animated` API.
+- Wrap top-level screens in `SafeAreaView` (or use `useSafeAreaInsets`) for notch / status-bar safety.
+
+## Variants with tva
+
+When you find yourself repeating the same className combination across 3+ usages, lift it into a `tva` variant in the component's `styles.tsx`:
+
+```tsx
+import { tva } from "@gluestack-ui/nativewind-utils/tva";
+
+const badgeStyle = tva({
+  base: "rounded-md px-2 py-1",
+  variants: {
+    tone: {
+      success: "bg-success-100 text-success-700",
+      danger: "bg-destructive/10 text-destructive",
+    },
+    size: { sm: "text-xs", md: "text-sm" },
+  },
+  defaultVariants: { tone: "success", size: "md" },
+});
+```
+
+Don't add ad-hoc `cn()` overrides at the call site for the same combinations.
+
+## Accessibility
+
+- All interactive components accept `accessibilityLabel`. Set it for any icon-only button.
+- `FormControl` automatically wires label/error/help text to the input — keep them inside the cluster so screen readers see the relationship.
+
+## Anti-patterns to reject
+
+- Raw colors: `text-blue-600`, `bg-red-500`, `text-neutral-900`, `text-gray-700`, or legacy tokens like `text-typography-700`.
+- Bare strings inside `<Button>`, `<Alert>`, `<Toast>`, `<Tooltip>` — always use the matching `*Text` sub-component.
+- `<InputIcon>` outside `<InputSlot>`.
+- `<Input>` rendered without `<InputField>` inside it.
+- Inline `style={{ padding: 16 }}` when `className="p-4"` works.
+- Arbitrary spacing values like `p-[13px]`, `gap-[7px]`.
+- Mixing gluestack-ui primitives with another library's primitives (shadcn, NativeBase v3, react-native-paper) on the same screen.
+- Importing from `@gluestack-ui/themed` (legacy v1/v2 package).
+
+## Reference
+
+- Live docs: https://gluestack.io/ui/docs
+- Per-component docs: `https://gluestack.io/ui/docs/components/${componentName}/`
+- Official agent skill (source of these rules): https://github.com/gluestack/agent-skills