@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/src/expo/skills/gluestack-nativewind/references/color-tokens.md

@@ -0,0 +1,343 @@
+# Color Tokens Reference
+
+This reference provides the complete semantic color token system for Gluestack UI v3.
+
+## Token Scale
+
+All color tokens follow the 0-950 scale:
+
+```
+0 → 50 → 100 → 200 → 300 → 400 → 500 → 600 → 700 → 800 → 900 → 950
+```
+
+Lower values are lighter, higher values are darker.
+
+## Semantic Color Categories
+
+### Primary (Brand Identity)
+
+Use for main brand elements, key interactive components, and primary actions.
+
+| Token         | Usage                            |
+| ------------- | -------------------------------- |
+| `primary-0`   | Lightest tint, subtle highlights |
+| `primary-50`  | Very light backgrounds           |
+| `primary-100` | Light hover states               |
+| `primary-200` | Light borders                    |
+| `primary-300` | Muted elements                   |
+| `primary-400` | Subdued text/icons               |
+| `primary-500` | **Default** - buttons, links     |
+| `primary-600` | Hover states for primary-500     |
+| `primary-700` | Active/pressed states            |
+| `primary-800` | Dark variant                     |
+| `primary-900` | Very dark variant                |
+| `primary-950` | Darkest shade                    |
+
+```tsx
+<Button className="bg-primary-500 hover:bg-primary-600 active:bg-primary-700">
+  <ButtonText className="text-typography-0">Primary Action</ButtonText>
+</Button>
+```
+
+### Secondary (Supporting Elements)
+
+Use for secondary actions, alternative buttons, and supporting UI.
+
+| Token           | Common Usage      |
+| --------------- | ----------------- |
+| `secondary-100` | Light backgrounds |
+| `secondary-200` | Borders, dividers |
+| `secondary-500` | Secondary buttons |
+| `secondary-600` | Hover states      |
+
+```tsx
+<Button className="bg-secondary-500">
+  <ButtonText>Secondary Action</ButtonText>
+</Button>
+```
+
+### Tertiary (Accent)
+
+Use for tertiary accents and warm tones.
+
+| Token          | Common Usage     |
+| -------------- | ---------------- |
+| `tertiary-400` | Accents          |
+| `tertiary-500` | Tertiary buttons |
+
+### Error (Destructive/Validation)
+
+Use for errors, validation failures, and destructive actions.
+
+| Token       | Common Usage                    |
+| ----------- | ------------------------------- |
+| `error-50`  | Light error backgrounds         |
+| `error-100` | Error container backgrounds     |
+| `error-400` | Error icons (light mode)        |
+| `error-500` | **Default** - error text, icons |
+| `error-600` | Error text (dark mode)          |
+| `error-700` | Dark error elements             |
+
+```tsx
+// Error message
+<Text className="text-error-500">This field is required</Text>
+
+// Error background
+<Box className="bg-error-50 border border-error-200 p-4">
+  <Text className="text-error-700">Error occurred</Text>
+</Box>
+
+// Destructive button
+<Button action="negative">
+  <ButtonText>Delete</ButtonText>
+</Button>
+```
+
+### Success (Positive/Confirmation)
+
+Use for success states, confirmations, and positive feedback.
+
+| Token         | Common Usage                      |
+| ------------- | --------------------------------- |
+| `success-50`  | Light success backgrounds         |
+| `success-100` | Success container backgrounds     |
+| `success-500` | **Default** - success text, icons |
+| `success-600` | Success text emphasis             |
+| `success-700` | Dark success elements             |
+
+```tsx
+// Success message
+<Text className="text-success-600">Changes saved successfully</Text>
+
+// Success background
+<Box className="bg-success-50 border border-success-200 p-4">
+  <Text className="text-success-700">Operation completed</Text>
+</Box>
+```
+
+### Warning (Caution/Attention)
+
+Use for warnings, caution states, and attention-required elements.
+
+| Token         | Common Usage                  |
+| ------------- | ----------------------------- |
+| `warning-50`  | Light warning backgrounds     |
+| `warning-100` | Warning container backgrounds |
+| `warning-400` | Warning icons                 |
+| `warning-500` | **Default** - warning text    |
+| `warning-600` | Warning text emphasis         |
+| `warning-700` | Dark warning elements         |
+
+```tsx
+// Warning message
+<Text className="text-warning-600">Please review before proceeding</Text>
+
+// Warning background
+<Box className="bg-warning-50 border border-warning-300 p-4">
+  <Text className="text-warning-700">Action required</Text>
+</Box>
+```
+
+### Info (Informational)
+
+Use for informational content, tips, and neutral highlights.
+
+| Token      | Common Usage                   |
+| ---------- | ------------------------------ |
+| `info-50`  | Light info backgrounds         |
+| `info-100` | Info container backgrounds     |
+| `info-500` | **Default** - info text, icons |
+| `info-600` | Info text emphasis             |
+| `info-700` | Dark info elements             |
+
+```tsx
+// Info message
+<Text className="text-info-600">Tip: You can also use keyboard shortcuts</Text>
+
+// Info background
+<Box className="bg-info-50 border border-info-200 p-4">
+  <Text className="text-info-700">Learn more about this feature</Text>
+</Box>
+```
+
+### Typography (Text Colors)
+
+Use for all text content. The scale provides contrast levels.
+
+| Token            | Usage                                |
+| ---------------- | ------------------------------------ |
+| `typography-0`   | White text (on dark backgrounds)     |
+| `typography-50`  | Very light text                      |
+| `typography-100` | Light placeholder text               |
+| `typography-200` | Disabled text                        |
+| `typography-300` | Tertiary text                        |
+| `typography-400` | Quaternary text                      |
+| `typography-500` | Secondary text, captions             |
+| `typography-600` | Muted body text                      |
+| `typography-700` | Body text                            |
+| `typography-800` | Emphasized text                      |
+| `typography-900` | **Default** - headings, primary text |
+| `typography-950` | Maximum contrast text                |
+
+```tsx
+// Primary heading
+<Heading className="text-typography-900">Page Title</Heading>
+
+// Body text
+<Text className="text-typography-700">Regular paragraph text</Text>
+
+// Secondary/muted text
+<Text className="text-typography-500">Last updated 2 hours ago</Text>
+
+// White text on dark background
+<Box className="bg-primary-500">
+  <Text className="text-typography-0">Button label</Text>
+</Box>
+```
+
+### Outline (Borders)
+
+Use for borders, dividers, and outlines.
+
+| Token         | Usage                              |
+| ------------- | ---------------------------------- |
+| `outline-0`   | White borders                      |
+| `outline-50`  | Very subtle borders                |
+| `outline-100` | Light dividers                     |
+| `outline-200` | **Default** - input borders, cards |
+| `outline-300` | Emphasized borders                 |
+| `outline-400` | Focus rings (muted)                |
+| `outline-500` | Strong borders                     |
+| `outline-600` | Dark borders                       |
+| `outline-700` | Very dark borders                  |
+
+```tsx
+// Card with border
+<Box className="border border-outline-200 rounded-lg p-4">
+  <Text>Card content</Text>
+</Box>
+
+// Input field
+<Input className="border border-outline-300 focus:border-primary-500" />
+
+// Divider
+<Box className="h-px bg-outline-100 my-4" />
+```
+
+### Background (Surface Colors)
+
+Use for component and page backgrounds.
+
+| Token            | Usage                                          |
+| ---------------- | ---------------------------------------------- |
+| `background-0`   | **Default** - white, main content (light mode) |
+| `background-50`  | Elevated surfaces, cards                       |
+| `background-100` | Subtle backgrounds                             |
+| `background-200` | Muted sections                                 |
+| `background-300` | Disabled states                                |
+| `background-400` | Hover states (dark)                            |
+| `background-500` | Mid-tone                                       |
+| `background-600` | Dark surfaces                                  |
+| `background-700` | Darker surfaces                                |
+| `background-800` | Very dark surfaces                             |
+| `background-900` | Near-black                                     |
+| `background-950` | **Default** - main content (dark mode)         |
+
+```tsx
+// Light mode page
+<Box className="bg-background-0 min-h-screen">
+  <Box className="bg-background-50 p-4 rounded-lg">
+    Card content
+  </Box>
+</Box>
+
+// Dark mode page
+<Box className="bg-background-950 min-h-screen">
+  <Box className="bg-background-900 p-4 rounded-lg">
+    Card content
+  </Box>
+</Box>
+```
+
+## Special Background Tokens
+
+State-specific background tokens for semantic meaning:
+
+| Token                   | Usage                    |
+| ----------------------- | ------------------------ |
+| `bg-background-error`   | Error state container    |
+| `bg-background-warning` | Warning state container  |
+| `bg-background-success` | Success state container  |
+| `bg-background-info`    | Info state container     |
+| `bg-background-muted`   | Muted/disabled container |
+
+```tsx
+// Error state
+<Box className="bg-background-error p-4 rounded-lg">
+  <Text className="text-error-700">Error message</Text>
+</Box>
+
+// Muted/disabled
+<Box className="bg-background-muted p-4 rounded-lg opacity-50">
+  <Text className="text-typography-500">Disabled content</Text>
+</Box>
+```
+
+## Indicator Tokens
+
+Use for focus rings and status indicators:
+
+| Token                    | Usage                   |
+| ------------------------ | ----------------------- |
+| `ring-indicator-primary` | Primary focus indicator |
+| `ring-indicator-info`    | Info focus indicator    |
+| `ring-indicator-error`   | Error focus indicator   |
+
+## Dark Mode Mapping
+
+Use `dark:` prefix for dark mode variants:
+
+```tsx
+// Text that adapts to dark mode
+<Text className="text-typography-900 dark:text-typography-0">
+  Adaptive text
+</Text>
+
+// Background that adapts
+<Box className="bg-background-0 dark:bg-background-950">
+  <Text className="text-typography-900 dark:text-typography-0">
+    Content
+  </Text>
+</Box>
+
+// Border that adapts
+<Box className="border border-outline-200 dark:border-outline-700">
+  Content
+</Box>
+```
+
+## Common Light/Dark Mode Pairs
+
+| Light Mode       | Dark Mode        | Usage           |
+| ---------------- | ---------------- | --------------- |
+| `background-0`   | `background-950` | Page background |
+| `background-50`  | `background-900` | Card background |
+| `typography-900` | `typography-0`   | Primary text    |
+| `typography-700` | `typography-200` | Body text       |
+| `typography-500` | `typography-400` | Secondary text  |
+| `outline-200`    | `outline-700`    | Borders         |
+| `outline-100`    | `outline-800`    | Dividers        |
+
+## Prohibited Raw Color Usage
+
+Never use raw Tailwind colors. Map to semantic tokens:
+
+| Raw Color                     | Semantic Token                              |
+| ----------------------------- | ------------------------------------------- |
+| `red-*`                       | `error-*`                                   |
+| `green-*`                     | `success-*`                                 |
+| `yellow-*`, `amber-*`         | `warning-*`                                 |
+| `blue-*`, `cyan-*`            | `info-*` or `primary-*`                     |
+| `gray-*`, `slate-*`, `zinc-*` | `typography-*`, `outline-*`, `background-*` |
+| `white`                       | `typography-0` or `background-0`            |
+| `black`                       | `typography-950` or `background-950`        |

package/plugins/src/expo/skills/gluestack-nativewind/references/component-mapping.md

@@ -0,0 +1,307 @@
+# Component Mapping Reference
+
+This reference provides the complete mapping from React Native primitives to Gluestack UI v3 equivalents.
+
+## Core Layout Components
+
+| React Native           | Gluestack                      | Import Path                              |
+| ---------------------- | ------------------------------ | ---------------------------------------- |
+| `View`                 | `Box`                          | `@/components/ui/box`                    |
+| `ScrollView`           | `ScrollView`                   | `@/components/ui/scroll-view`            |
+| `SafeAreaView`         | Use `useSafeAreaInsets()` hook | `react-native-safe-area-context`         |
+| `KeyboardAvoidingView` | `KeyboardAvoidingView`         | `@/components/ui/keyboard-avoiding-view` |
+
+## Text Components
+
+| React Native     | Gluestack | Import Path               |
+| ---------------- | --------- | ------------------------- |
+| `Text`           | `Text`    | `@/components/ui/text`    |
+| `Text` (heading) | `Heading` | `@/components/ui/heading` |
+
+## Interactive Components
+
+| React Native               | Gluestack               | Import Path                 |
+| -------------------------- | ----------------------- | --------------------------- |
+| `TouchableOpacity`         | `Pressable`             | `@/components/ui/pressable` |
+| `TouchableHighlight`       | `Pressable`             | `@/components/ui/pressable` |
+| `TouchableWithoutFeedback` | `Pressable`             | `@/components/ui/pressable` |
+| `Button`                   | `Button` + `ButtonText` | `@/components/ui/button`    |
+| `Switch`                   | `Switch`                | `@/components/ui/switch`    |
+
+## Form Components
+
+| React Native            | Gluestack                    | Import Path                |
+| ----------------------- | ---------------------------- | -------------------------- |
+| `TextInput`             | `Input` + `InputField`       | `@/components/ui/input`    |
+| `TextInput` (multiline) | `Textarea` + `TextareaInput` | `@/components/ui/textarea` |
+| N/A                     | `Select`                     | `@/components/ui/select`   |
+| N/A                     | `Checkbox`                   | `@/components/ui/checkbox` |
+| N/A                     | `Radio`                      | `@/components/ui/radio`    |
+| N/A                     | `Slider`                     | `@/components/ui/slider`   |
+
+## Media Components
+
+| React Native | Gluestack | Import Path              |
+| ------------ | --------- | ------------------------ |
+| `Image`      | `Image`   | `@/components/ui/image`  |
+| N/A          | `Avatar`  | `@/components/ui/avatar` |
+| N/A          | `Icon`    | `@/components/ui/icon`   |
+
+## List Components
+
+| React Native      | Recommended               | Import Path           |
+| ----------------- | ------------------------- | --------------------- |
+| `FlatList`        | `FlashList`               | `@shopify/flash-list` |
+| `SectionList`     | `FlashList` with sections | `@shopify/flash-list` |
+| `VirtualizedList` | `FlashList`               | `@shopify/flash-list` |
+
+## Feedback Components
+
+| React Native        | Gluestack     | Import Path                    |
+| ------------------- | ------------- | ------------------------------ |
+| `ActivityIndicator` | `Spinner`     | `@/components/ui/spinner`      |
+| `Modal`             | `Modal`       | `@/components/ui/modal`        |
+| `Alert.alert()`     | `AlertDialog` | `@/components/ui/alert-dialog` |
+| N/A                 | `Toast`       | `@/components/ui/toast`        |
+| N/A                 | `Progress`    | `@/components/ui/progress`     |
+
+## Navigation Components
+
+| React Native | Gluestack     | Import Path                   |
+| ------------ | ------------- | ----------------------------- |
+| N/A          | `Menu`        | `@/components/ui/menu`        |
+| N/A          | `Actionsheet` | `@/components/ui/actionsheet` |
+| N/A          | `Popover`     | `@/components/ui/popover`     |
+| N/A          | `Tooltip`     | `@/components/ui/tooltip`     |
+
+## Overlay Components
+
+| React Native | Gluestack  | Import Path                |
+| ------------ | ---------- | -------------------------- |
+| `Modal`      | `Modal`    | `@/components/ui/modal`    |
+| N/A          | `Drawer`   | `@/components/ui/drawer`   |
+| N/A          | `Backdrop` | Part of overlay components |
+
+## Display Components
+
+| React Native | Gluestack   | Import Path                 |
+| ------------ | ----------- | --------------------------- |
+| N/A          | `Badge`     | `@/components/ui/badge`     |
+| N/A          | `Card`      | `@/components/ui/card`      |
+| N/A          | `Divider`   | `@/components/ui/divider`   |
+| N/A          | `Accordion` | `@/components/ui/accordion` |
+
+## Gluestack Sub-Component Patterns
+
+### Button
+
+```tsx
+import { Button, ButtonText, ButtonIcon, ButtonSpinner } from "@/components/ui/button";
+
+<Button action="primary" size="md" variant="solid">
+  <ButtonText>Submit</ButtonText>
+</Button>
+
+<Button action="secondary" isDisabled>
+  <ButtonSpinner />
+  <ButtonText>Loading...</ButtonText>
+</Button>
+
+<Button>
+  <ButtonText>Next</ButtonText>
+  <ButtonIcon as={ChevronRightIcon} />
+</Button>
+```
+
+### Input
+
+```tsx
+import { Input, InputField, InputSlot, InputIcon } from "@/components/ui/input";
+
+<Input variant="outline" size="md">
+  <InputField placeholder="Enter email" />
+</Input>
+
+<Input>
+  <InputSlot>
+    <InputIcon as={SearchIcon} />
+  </InputSlot>
+  <InputField placeholder="Search..." />
+</Input>
+
+<Input isInvalid>
+  <InputField />
+  <InputSlot>
+    <InputIcon as={AlertCircleIcon} className="text-error-500" />
+  </InputSlot>
+</Input>
+```
+
+### Select
+
+```tsx
+import {
+  Select,
+  SelectTrigger,
+  SelectInput,
+  SelectIcon,
+  SelectPortal,
+  SelectBackdrop,
+  SelectContent,
+  SelectDragIndicator,
+  SelectDragIndicatorWrapper,
+  SelectItem,
+} from "@/components/ui/select";
+
+<Select>
+  <SelectTrigger variant="outline" size="md">
+    <SelectInput placeholder="Select option" />
+    <SelectIcon as={ChevronDownIcon} />
+  </SelectTrigger>
+  <SelectPortal>
+    <SelectBackdrop />
+    <SelectContent>
+      <SelectDragIndicatorWrapper>
+        <SelectDragIndicator />
+      </SelectDragIndicatorWrapper>
+      <SelectItem label="Option 1" value="1" />
+      <SelectItem label="Option 2" value="2" />
+    </SelectContent>
+  </SelectPortal>
+</Select>;
+```
+
+### Modal
+
+```tsx
+import {
+  Modal,
+  ModalBackdrop,
+  ModalContent,
+  ModalHeader,
+  ModalCloseButton,
+  ModalBody,
+  ModalFooter,
+} from "@/components/ui/modal";
+
+<Modal isOpen={showModal} onClose={handleClose}>
+  <ModalBackdrop />
+  <ModalContent>
+    <ModalHeader>
+      <Heading size="lg">Title</Heading>
+      <ModalCloseButton>
+        <Icon as={CloseIcon} />
+      </ModalCloseButton>
+    </ModalHeader>
+    <ModalBody>
+      <Text>Modal content here</Text>
+    </ModalBody>
+    <ModalFooter>
+      <Button onPress={handleClose}>
+        <ButtonText>Close</ButtonText>
+      </Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>;
+```
+
+### Avatar
+
+```tsx
+import {
+  Avatar,
+  AvatarFallbackText,
+  AvatarImage,
+  AvatarBadge,
+} from "@/components/ui/avatar";
+
+<Avatar size="md">
+  <AvatarFallbackText>JD</AvatarFallbackText>
+  <AvatarImage source={{ uri: imageUrl }} />
+  <AvatarBadge />
+</Avatar>;
+```
+
+### Checkbox
+
+```tsx
+import {
+  Checkbox,
+  CheckboxIndicator,
+  CheckboxIcon,
+  CheckboxLabel,
+} from "@/components/ui/checkbox";
+
+<Checkbox value="terms" isChecked={isChecked} onChange={setIsChecked}>
+  <CheckboxIndicator>
+    <CheckboxIcon as={CheckIcon} />
+  </CheckboxIndicator>
+  <CheckboxLabel>Accept terms</CheckboxLabel>
+</Checkbox>;
+```
+
+### Toast
+
+```tsx
+import {
+  useToast,
+  Toast,
+  ToastTitle,
+  ToastDescription,
+} from "@/components/ui/toast";
+
+const toast = useToast();
+
+toast.show({
+  placement: "top",
+  render: ({ id }) => (
+    <Toast nativeID={id} action="success">
+      <ToastTitle>Success!</ToastTitle>
+      <ToastDescription>Your changes have been saved.</ToastDescription>
+    </Toast>
+  ),
+});
+```
+
+## Component Variants
+
+### Button Variants
+
+| Prop      | Values                                         |
+| --------- | ---------------------------------------------- |
+| `action`  | `primary`, `secondary`, `positive`, `negative` |
+| `variant` | `solid`, `outline`, `link`                     |
+| `size`    | `xs`, `sm`, `md`, `lg`, `xl`                   |
+
+### Input Variants
+
+| Prop      | Values                             |
+| --------- | ---------------------------------- |
+| `variant` | `outline`, `underlined`, `rounded` |
+| `size`    | `sm`, `md`, `lg`, `xl`             |
+
+### Text/Heading Sizes
+
+| Component | Sizes                                                                  |
+| --------- | ---------------------------------------------------------------------- |
+| `Text`    | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`, `6xl` |
+| `Heading` | `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`               |
+
+## When to Keep React Native Primitives
+
+Use React Native primitives only when:
+
+1. **Platform-specific native behavior** - Deep native integration required
+2. **Third-party library requirements** - Library expects RN primitives
+3. **Performance-critical rendering** - Measured wrapper overhead (rare)
+4. **Animated components** - Using `Animated.View`, `Animated.Text`, etc.
+
+```tsx
+// Acceptable: Animated primitives
+import Animated from "react-native-reanimated";
+
+const AnimatedBox = Animated.createAnimatedComponent(Box);
+
+// Acceptable: Platform-specific requirement
+import { Platform, PermissionsAndroid } from "react-native";
+```