@frosted-ui/react-native 0.0.1-canary.93 → 0.0.1-canary.95

package/docs/llm/README.md

@@ -0,0 +1,118 @@
+# Frosted UI Design System — LLM Reference
+
+> This documentation is designed for AI/LLM consumption when generating React Native applications using the Frosted UI design system.
+
+## Accessing These Docs
+
+When `@frosted-ui/react-native` is installed in a project, these documentation files are available at:
+
+```
+node_modules/@frosted-ui/react-native/docs/llm/
+├── README.md           # This file (start here)
+├── COLOR_SYSTEM.md     # Color palettes, shades, variants
+├── TYPOGRAPHY.md       # Text scale, font weights, components
+├── COMPONENTS.md       # Full component API reference
+└── DESIGN_PATTERNS.md  # UX patterns, layout composition
+```
+
+**For AI Agents**: Read these files to understand how to properly use Frosted UI components. Start with this README, then reference specific docs as needed.
+
+## Purpose
+
+These guides provide structured, detailed information about Frosted UI conventions, patterns, and best practices. AI models should reference these documents when generating code to ensure consistency with the design system.
+
+## Available Documentation
+
+| Document                                   | Description                                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------------------ |
+| [COLOR_SYSTEM.md](./COLOR_SYSTEM.md)       | Complete guide to the color system, palettes, shades, variants, and accessibility    |
+| [TYPOGRAPHY.md](./TYPOGRAPHY.md)           | Typography scale, font weights, Text/Heading components, and automatic text styling  |
+| [COMPONENTS.md](./COMPONENTS.md)           | Full component reference with props, variants, and usage examples                    |
+| [DESIGN_PATTERNS.md](./DESIGN_PATTERNS.md) | **For Design Engineers** — UX patterns, layout composition, visual design principles |
+
+## Quick Import Reference
+
+```typescript
+// Core imports
+import {
+  // Theme
+  ThemeProvider,
+  useTheme,
+  useThemeTokens,
+
+  // Components
+  Button,
+  Badge,
+  Callout,
+  Card,
+  Checkbox,
+  CircularProgress,
+  Dialog,
+  Heading,
+  IconButton,
+  Progress,
+  RadioGroup,
+  Select,
+  Separator,
+  Skeleton,
+  Spinner,
+  Switch,
+  Tabs,
+  Text,
+  TextArea,
+  TextField,
+  Tooltip,
+
+  // Types
+  type AccentColor,
+  type Color,
+  type SemanticColor,
+} from '@frosted-ui/react-native';
+```
+
+## Key Principles
+
+### Component Usage
+
+1. **Use Frosted UI's Text** — Always use `<Text>` from `@frosted-ui/react-native`, not React Native's default
+2. **Text auto-styles in components** — `<Text>` inside `Button`, `Badge`, `Callout` etc. automatically gets correct size and color
+3. **Use semantic colors** — `danger`, `warning`, `success`, `info` instead of explicit color names for status indicators
+4. **Default to accent** — Most components default to the app's accent color; only override when semantically meaningful
+
+### Button Hierarchy
+
+5. **Primary action** — `variant="solid"` (one per view)
+6. **Secondary action** — `variant="soft" color="gray"`
+7. **Toolbar/neutral** — `variant="surface"` (pairs with form inputs)
+8. **Tertiary/inline** — `variant="ghost"`
+
+### Visual Design
+
+9. **Theme-aware** — All colors automatically adapt to light/dark mode
+10. **Consistent spacing** — Use 4, 8, 12, 16, 24, 32px scale for gaps and padding
+11. **Accessible** — Color combinations are designed to meet WCAG contrast requirements
+
+### Responsive Design
+
+12. **Mobile-first** — Design for mobile, content adapts to larger screens
+13. **Choose layout strategy** — Simple apps: centered (600px max). Complex apps: adaptive grid
+14. **Don't resize components** — Keep button sizes, fonts, etc. consistent across breakpoints
+15. **Use flexWrap for grids** — Let items wrap naturally based on screen width
+
+## App Structure Template
+
+```tsx
+import { ThemeProvider, PortalHost } from '@frosted-ui/react-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <ThemeProvider accentColor="blue">
+        {/* Your app content */}
+        <PortalHost />
+      </ThemeProvider>
+    </GestureHandlerRootView>
+  );
+}
+```

package/docs/llm/TYPOGRAPHY.md

@@ -0,0 +1,516 @@
+# Frosted UI Typography System
+
+> **For AI/LLM Code Generation**: This document explains the Frosted UI typography system for React Native. Follow these guidelines to ensure consistent, readable text across your application.
+
+## Critical: Use Frosted UI's Text Component
+
+**Always use `<Text>` from `@frosted-ui/react-native` instead of React Native's default `<Text>` component.**
+
+```tsx
+// ❌ WRONG: React Native's Text has no design system integration
+import { Text } from 'react-native';
+
+// ✅ CORRECT: Frosted UI's Text with typography tokens and theme awareness
+import { Text } from '@frosted-ui/react-native';
+```
+
+### Why This Matters
+
+Frosted UI's `<Text>` component:
+
+1. **Applies typography tokens** — Consistent font sizes, line heights, and letter spacing
+2. **Theme-aware colors** — Automatically uses the correct text color for light/dark mode
+3. **Context-aware styling** — When placed inside components like `Button`, `Badge`, or `Callout`, text automatically receives the correct size and color
+4. **Color prop support** — Accepts a `color` prop for semantic coloring
+
+---
+
+## Typography Scale
+
+Frosted UI uses a 10-step typography scale (0-9). Each step defines `fontSize`, `lineHeight`, and `letterSpacing`.
+
+| Size | Font Size | Line Height | Use Case                              |
+| ---- | --------- | ----------- | ------------------------------------- |
+| `0`  | 10px      | 12px        | Tiny labels, captions                 |
+| `1`  | 12px      | 16px        | Small labels, helper text             |
+| `2`  | 14px      | 20px        | Secondary text, descriptions          |
+| `3`  | 16px      | 24px        | **Default body text** (mobile-first)  |
+| `4`  | 18px      | 26px        | Small headings, emphasized text       |
+| `5`  | 20px      | 28px        | Section headings                      |
+| `6`  | 24px      | 30px        | **Default heading size**, page titles |
+| `7`  | 28px      | 34px        | Large headings                        |
+| `8`  | 32px      | 38px        | Hero headings                         |
+| `9`  | 40px      | 48px        | Display text, hero sections           |
+
+---
+
+## Font Weights
+
+| Weight      | Value | Use Case                                  |
+| ----------- | ----- | ----------------------------------------- |
+| `light`     | 300   | De-emphasized text                        |
+| `regular`   | 400   | **Default for body text**                 |
+| `medium`    | 500   | Labels, slightly emphasized text          |
+| `semi-bold` | 600   | Sub-headings                              |
+| `bold`      | 700   | **Default for headings**, strong emphasis |
+
+---
+
+## Typography Components
+
+### `<Text>` — Body Text
+
+The primary component for all text content.
+
+```tsx
+import { Text } from '@frosted-ui/react-native';
+
+// Default body text (size="3", weight="regular", color=gray-12)
+<Text>Default body text</Text>
+
+// With size
+<Text size="1">Small helper text</Text>
+<Text size="2">Secondary text</Text>
+
+// With weight
+<Text weight="medium">Medium weight text</Text>
+<Text weight="bold">Bold text</Text>
+
+// With color (uses palette shade 11 for the specified color)
+<Text color="blue">Blue colored text</Text>
+<Text color="gray">Secondary/muted text</Text>
+
+// Combining props
+<Text size="1" weight="medium" color="gray">
+  Small, medium-weight, gray text
+</Text>
+```
+
+#### Text Props
+
+| Prop     | Type                                                                | Default           | Description                               |
+| -------- | ------------------------------------------------------------------- | ----------------- | ----------------------------------------- |
+| `size`   | `'0'` - `'9'`                                                       | `'3'`             | Typography scale step                     |
+| `weight` | `'light'` \| `'regular'` \| `'medium'` \| `'semi-bold'` \| `'bold'` | Inherited or none | Font weight                               |
+| `color`  | `Color`                                                             | `gray` (shade 12) | Text color (uses shade 11 of the palette) |
+
+---
+
+### `<Heading>` — Headings and Titles
+
+Use for page titles, section headings, and any hierarchical text structure.
+
+```tsx
+import { Heading } from '@frosted-ui/react-native';
+
+// Default heading (size="6", weight="bold")
+<Heading>Page Title</Heading>
+
+// Different sizes for hierarchy
+<Heading size="9">Hero Title</Heading>
+<Heading size="7">Section Title</Heading>
+<Heading size="5">Subsection Title</Heading>
+<Heading size="4">Card Title</Heading>
+
+// With color
+<Heading color="blue">Colored Heading</Heading>
+
+// Custom weight
+<Heading size="6" weight="semi-bold">Semi-bold Heading</Heading>
+```
+
+#### Heading Props
+
+| Prop     | Type                                                                | Default           | Description           |
+| -------- | ------------------------------------------------------------------- | ----------------- | --------------------- |
+| `size`   | `'0'` - `'9'`                                                       | `'6'`             | Typography scale step |
+| `weight` | `'light'` \| `'regular'` \| `'medium'` \| `'semi-bold'` \| `'bold'` | `'bold'`          | Font weight           |
+| `color`  | `Color`                                                             | `gray` (shade 12) | Text color            |
+
+---
+
+### `<Label>` — Form Labels
+
+Use for labeling form inputs. Use `nativeID` on Label and `aria-labelledby` on the input for accessibility.
+
+```tsx
+import { Label, TextField } from '@frosted-ui/react-native';
+import { View } from 'react-native';
+
+<View style={{ gap: 8 }}>
+  <Label nativeID="email">Email address</Label>
+  <TextField.Input placeholder="you@example.com" aria-labelledby="email" />
+</View>
+
+// Disabled state
+<Label nativeID="disabled-field" disabled>Disabled label</Label>
+```
+
+Label uses size `2` and weight `medium` by default.
+
+---
+
+### `<Code>` — Inline Code
+
+For displaying code snippets, technical values, or monospace text.
+
+```tsx
+import { Code } from '@frosted-ui/react-native';
+
+// Default (soft variant)
+<Text>Run <Code>npm install</Code> to get started</Text>
+
+// Variants
+<Code variant="soft">soft code</Code>
+<Code variant="solid">solid code</Code>
+<Code variant="outline">outline code</Code>
+<Code variant="ghost">ghost code</Code>
+
+// With color
+<Code color="green">success</Code>
+<Code color="red">error</Code>
+
+// Sizes match the typography scale
+<Code size="1">small code</Code>
+<Code size="3">larger code</Code>
+```
+
+---
+
+### `<Link>` — Pressable Text Links
+
+For navigation links and clickable text. Uses accent color by default.
+
+```tsx
+import { Link, Text } from '@frosted-ui/react-native';
+
+// Basic link
+<Link onPress={() => navigation.navigate('Terms')}>Terms of Service</Link>
+
+// Inline within text
+<Text>
+  By signing up, you agree to our <Link onPress={() => {}}>Terms</Link> and{' '}
+  <Link onPress={() => {}}>Privacy Policy</Link>.
+</Text>
+
+// With color
+<Link color="blue" onPress={() => {}}>Documentation</Link>
+<Link color="danger" onPress={() => {}}>Delete account</Link>
+
+// Underline options
+<Link underline="always" onPress={() => {}}>Always underlined</Link>
+<Link underline="auto" onPress={() => {}}>Underlined on press</Link>
+
+// Sizes and weights
+<Link size="2" weight="medium" onPress={() => {}}>Medium link</Link>
+```
+
+| Prop        | Type                            | Default    | Description                 |
+| ----------- | ------------------------------- | ---------- | --------------------------- |
+| `size`      | `'0'` - `'9'`                   | `'3'`      | Text size                   |
+| `weight`    | Font weight                     | —          | Font weight                 |
+| `color`     | `Color`                         | `'accent'` | Link color (uses a11 shade) |
+| `underline` | `'auto' \| 'hover' \| 'always'` | `'auto'`   | Underline behavior          |
+
+> **Note**: `Link` renders text internally — do NOT wrap children in `<Text>`.
+
+> **Inheritance**: When nested inside `<Text>`, Link automatically inherits `size` and `weight` from the parent, so inline links match surrounding text.
+
+---
+
+## Automatic Text Styling in Components
+
+**This is a key feature:** When you place `<Text>` inside certain Frosted UI components, the text automatically receives appropriate styling.
+
+### Components That Auto-Style Text
+
+| Component      | Text Behavior                                            |
+| -------------- | -------------------------------------------------------- |
+| `Button`       | Size matches button size, color based on variant         |
+| `Badge`        | Size matches badge size, color based on variant          |
+| `Callout`      | Size based on callout size, color from callout's palette |
+| `Tabs.Trigger` | Appropriate size and color for tab state                 |
+
+### Example: Button
+
+```tsx
+import { Button, Text } from '@frosted-ui/react-native';
+
+// ✅ Text automatically gets correct size and color
+<Button variant="solid" color="blue" size="2">
+  <Text>Submit</Text>
+</Button>
+
+// ✅ Same result - Text inherits from Button
+<Button variant="soft" color="danger">
+  <Text>Delete</Text>
+</Button>
+
+// ❌ DON'T manually style text inside buttons
+<Button variant="solid">
+  <Text style={{ color: 'white', fontSize: 14 }}>Wrong</Text>
+</Button>
+```
+
+### Example: Badge
+
+```tsx
+import { Badge, Text } from '@frosted-ui/react-native';
+
+// ✅ Text automatically styled
+<Badge color="success" variant="soft">
+  <Text>Completed</Text>
+</Badge>
+
+<Badge color="warning" variant="solid">
+  <Text>Pending</Text>
+</Badge>
+```
+
+### Example: Callout
+
+```tsx
+import { Callout, Text } from '@frosted-ui/react-native';
+
+// ✅ Text inherits callout's color and size
+<Callout.Root color="info">
+  <Callout.Text>
+    <Text>This text is automatically styled</Text>
+  </Callout.Text>
+</Callout.Root>;
+```
+
+---
+
+## Common Typography Patterns
+
+### Page Header
+
+```tsx
+import { Heading, Text } from '@frosted-ui/react-native';
+import { View } from 'react-native';
+
+<View style={{ gap: 4 }}>
+  <Heading size="6">Settings</Heading>
+  <Text size="2" color="gray">
+    Manage your account preferences
+  </Text>
+</View>;
+```
+
+### Section Header
+
+```tsx
+import { Heading, Text } from '@frosted-ui/react-native';
+import { View } from 'react-native';
+
+<View style={{ gap: 4 }}>
+  <Heading size="4">Notifications</Heading>
+  <Text size="2" color="gray">
+    Choose how you want to be notified
+  </Text>
+</View>;
+```
+
+### List Item with Description
+
+```tsx
+import { Text } from '@frosted-ui/react-native';
+import { View } from 'react-native';
+
+<View style={{ gap: 2 }}>
+  <Text size="2" weight="medium">
+    Email notifications
+  </Text>
+  <Text size="1" color="gray">
+    Receive updates about your account
+  </Text>
+</View>;
+```
+
+### Form Field
+
+```tsx
+import { Label, Text, TextField } from '@frosted-ui/react-native';
+import { View } from 'react-native';
+
+<View style={{ gap: 8 }}>
+  <Label nativeID="email">Email address</Label>
+  <TextField.Input placeholder="you@example.com" aria-labelledby="email" />
+  <Text size="1" color="gray">
+    We'll never share your email
+  </Text>
+</View>;
+```
+
+For inputs with icons, use the compound pattern:
+
+```tsx
+<View style={{ gap: 8 }}>
+  <Label nativeID="search">Search</Label>
+  <TextField.Root>
+    <TextField.Slot>
+      <SearchIcon size={16} />
+    </TextField.Slot>
+    <TextField.Input placeholder="Search..." aria-labelledby="search" />
+  </TextField.Root>
+</View>
+```
+
+### Error Message
+
+```tsx
+import { Text } from '@frosted-ui/react-native';
+
+<Text size="1" color="red">
+  This field is required
+</Text>;
+```
+
+### Empty State
+
+```tsx
+import { Heading, Text } from '@frosted-ui/react-native';
+import { View } from 'react-native';
+
+<View style={{ alignItems: 'center', gap: 8 }}>
+  <Heading size="4">No results found</Heading>
+  <Text size="2" color="gray" style={{ textAlign: 'center' }}>
+    Try adjusting your search or filters
+  </Text>
+</View>;
+```
+
+---
+
+## Typography Hierarchy Guidelines
+
+### Recommended Size Pairings
+
+| Context      | Heading Size | Body Size  | Description Size |
+| ------------ | ------------ | ---------- | ---------------- |
+| Hero section | `8` or `9`   | `3` or `4` | `2`              |
+| Page title   | `6` or `7`   | `2` or `3` | `2`              |
+| Section      | `4` or `5`   | `2`        | `1` or `2`       |
+| Card         | `3` or `4`   | `2`        | `1`              |
+| List item    | `2` (medium) | —          | `1`              |
+| Form field   | —            | `2`        | `1`              |
+
+### Visual Hierarchy Tips
+
+1. **Limit heading levels** — Use 2-3 heading sizes max per screen
+2. **Consistent spacing** — Use `gap: 4` between heading and description
+3. **Color for hierarchy** — Use `color="gray"` for secondary/description text
+4. **Weight for emphasis** — Use `weight="medium"` for labels, `weight="bold"` for headings
+
+---
+
+## ✅ DO's
+
+### Use the Frosted UI Text component
+
+```tsx
+// ✅ Correct
+import { Text } from '@frosted-ui/react-native';
+<Text size="2">Hello world</Text>;
+```
+
+### Use semantic components
+
+```tsx
+// ✅ Use Heading for titles
+<Heading size="5">Section Title</Heading>
+
+// ✅ Use Text for body content
+<Text>Body content goes here</Text>
+
+// ✅ Use Label for form labels
+<Label>Email address</Label>
+
+// ✅ Use Code for technical content
+<Text>Install with <Code>npm install</Code></Text>
+```
+
+### Let components handle text styling
+
+```tsx
+// ✅ Button handles text color and size automatically
+<Button color="danger">
+  <Text>Delete</Text>
+</Button>
+```
+
+### Use color="gray" for secondary text
+
+```tsx
+// ✅ Gray for descriptions and helper text
+<Text color="gray" size="2">
+  Optional helper text
+</Text>
+```
+
+---
+
+## ❌ DON'Ts
+
+### Don't use React Native's Text
+
+```tsx
+// ❌ Wrong
+import { Text } from 'react-native';
+```
+
+### Don't manually style text inside components
+
+```tsx
+// ❌ Don't override colors in buttons/badges
+<Button variant="solid">
+  <Text style={{ color: 'white' }}>Submit</Text>
+</Button>
+```
+
+### Don't use arbitrary font sizes
+
+```tsx
+// ❌ Don't use custom font sizes
+<Text style={{ fontSize: 15 }}>Custom size</Text>
+
+// ✅ Use the typography scale
+<Text size="2">Correct size</Text>
+```
+
+### Don't skip the size prop for intentional sizing
+
+```tsx
+// ❌ Ambiguous - what size is this?
+<Text>Some text</Text>
+
+// ✅ Default size is mobile-friendly
+<Text>Body text</Text> // Defaults to size="3"
+```
+
+---
+
+## Quick Reference
+
+### Text Sizes for Common Use Cases
+
+| Use Case                   | Size                          |
+| -------------------------- | ----------------------------- |
+| Page title                 | `6` - `9` (Heading)           |
+| Section title              | `4` - `5` (Heading)           |
+| Card title                 | `3` - `4` (Heading)           |
+| Body text                  | `3` (default)                 |
+| Secondary/description text | `3` with `color="gray"`       |
+| Helper text                | `1` - `2` with `color="gray"` |
+| Small labels               | `1`                           |
+| Tiny captions              | `0`                           |
+
+### Default Component Styling
+
+| Component | Default Size         | Default Weight   |
+| --------- | -------------------- | ---------------- |
+| `Text`    | `'3'` (mobile-first) | None (inherited) |
+| `Heading` | `6`                  | `bold`           |
+| `Label`   | `2`                  | `medium`         |
+| `Code`    | `2`                  | None             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frosted-ui/react-native",
-  "version": "0.0.1-canary.93",
+  "version": "0.0.1-canary.95",
   "private": false,
   "main": "expo-router/entry",
   "types": "./dist/index.d.ts",
@@ -9,17 +9,21 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./llm-docs": "./docs/llm/README.md",
+    "./llm-docs/*": "./docs/llm/*"
   },
   "sideEffects": false,
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs/llm"
   ],
   "peerDependencies": {
     "lucide-react-native": ">=0.300.0",
     "react": ">=18.0.0",
     "react-native": ">=0.70.0",
+    "react-native-gesture-handler": ">=2.0.0",
     "react-native-reanimated": ">=3.0.0",
     "react-native-safe-area-context": ">=4.0.0",
     "react-native-screens": ">=3.0.0",
@@ -37,6 +41,7 @@
   },
   "dependencies": {
     "@frosted-ui/colors": "workspace:*",
+    "@rn-primitives/slider": "^1.2.0",
     "@rn-primitives/accordion": "^1.2.0",
     "@rn-primitives/alert-dialog": "^1.2.0",
     "@rn-primitives/aspect-ratio": "^1.2.0",
@@ -78,6 +83,7 @@
     "react": "19.1.0",
     "react-dom": "19.1.0",
     "react-native": "0.81.5",
+    "react-native-gesture-handler": "~2.24.0",
     "react-native-reanimated": "~4.1.1",
     "react-native-safe-area-context": "~5.6.0",
     "react-native-screens": "~4.16.0",