@butternutbox/pawprint-native 0.0.1

package/eslint.config.js

@@ -0,0 +1,3 @@
+import baseConfig from "@repo/eslint-config/react.mjs"
+
+export default [...baseConfig]

package/llms.txt

@@ -0,0 +1,458 @@
+# Component Development – LLM Instructions (React Native)
+
+Full reference: `packages/pawprint-native/COMPONENT_GUIDELINES.md`
+
+Always use the equivalent component in `packages/pawprint-web/src/components` as a reference for API design (props, variants, sizes). Convert it to React Native using `@rn-primitives/*`, `@emotion/native`, and standard React Native primitives (`View`, `Pressable`, `Text`, etc.).
+
+---
+
+# 🔒 Hard Rules (MUST / MUST NOT)
+
+## Code Integrity
+
+- **MUST NOT** modify any existing file unless explicitly required by Step 7 (exports only).
+- **MUST NOT** refactor, improve, or clean up unrelated code.
+- **MUST NOT** recreate components that already exist.
+- **MUST** reuse existing components (Typography, Icon, Spinner, etc.) whenever possible.
+- Existing code includes:
+  - Any file not newly created for this component
+  - Tokens
+  - Theme
+  - Other components
+  - Shared types
+  - Utilities and fonts
+
+---
+
+## Token Usage (Strict Order)
+
+You **MUST** follow this exact fallback order:
+
+1. Component tokens
+   `theme.tokens.components.[component].*`
+
+2. Semantic tokens
+   `theme.tokens.semantics.*`
+
+3. Primitive tokens
+   `theme.tokens.primitives.*`
+
+4. If no token exists → hardcode value with comment:
+   `// TODO: Add token`
+
+Rules:
+- **MUST NOT** hardcode values if a token exists.
+- Layout values (gap, padding, margin, etc.) MUST use tokens if available.
+- If no layout token exists, hardcode with `// TODO: Add token`.
+- Token values are strings — use `parseTokenValue()` to convert:
+  ```tsx
+  const parseTokenValue = (value: string): number => parseFloat(value)
+  ```
+
+---
+
+## Visual Styling Rules
+
+- **MUST NOT** add visual styles not defined in:
+  - Design tokens
+  - Figma design
+
+This includes:
+- opacity (unless for disabled states in tokens)
+- letterSpacing
+- shadows
+- extra borders
+- etc.
+
+Animations are allowed **ONLY if present in tokens or Figma** — use `Animated` or `react-native-reanimated`.
+
+Layout properties (flexDirection, gap, margin, padding, alignItems, justifyContent) are allowed for structure.
+
+---
+
+## Layout Stability
+
+- **MUST prevent layout shifts**
+- Use `transparent` borders instead of removing borders.
+- Use fixed `height`/`minWidth` from tokens to maintain consistent sizing.
+
+---
+
+## Scope Restrictions
+
+You may only create files inside:
+
+`packages/pawprint-native/src/.../<component>`
+
+You may only modify:
+- Required export barrel files (Step 7)
+
+You **MUST NOT** modify:
+- Tokens
+- Theme
+- Unrelated components
+- Config files
+- Storybook config
+
+---
+
+## i18n
+
+- The design system is **i18n-agnostic**. Components MUST NOT handle translation, interpolation, or localisation.
+- MUST NOT import or depend on `i18next`, `react-i18next`, or any translation library.
+- Components accept `children` or typed props — never translation keys.
+- Consuming apps are responsible for resolving translations and passing already-rendered strings or React nodes.
+
+---
+
+# 🧭 Workflow
+
+---
+
+## Step 0 – Requirement Gate (MANDATORY)
+
+Ask ONE question at a time.
+
+If any answer is missing:
+→ Ask only the next missing question.
+→ STOP.
+→ Do NOT proceed.
+
+Questions:
+
+a. Ask component level using `ask_user_question` tool with options:
+   - atoms
+   - molecules
+   - organisms
+
+b. Ask for component name (plain text)
+
+c. Ask for Figma URL (plain text)
+
+d. Ask for specific requirements or constraints (plain text)
+
+Examples:
+- Exclude certain variants
+- Custom prop structure
+- Platform-specific behavior
+- Accessibility constraints
+
+⚠️ DO NOT proceed until ALL answers are received.
+
+---
+
+## Step 1 – Mandatory Analysis (Before Implementation)
+
+### 1. RN Primitives Check
+
+- Check if `@rn-primitives` has a matching component:
+  ```
+  @rn-primitives/checkbox
+  @rn-primitives/switch
+  @rn-primitives/slider
+  @rn-primitives/accordion
+  @rn-primitives/dialog
+  @rn-primitives/radio-group
+  @rn-primitives/select
+  @rn-primitives/tabs
+  @rn-primitives/toggle
+  @rn-primitives/toggle-group
+  @rn-primitives/separator
+  @rn-primitives/progress
+  @rn-primitives/label
+  @rn-primitives/collapsible
+  @rn-primitives/popover
+  @rn-primitives/tooltip
+  @rn-primitives/context-menu
+  @rn-primitives/dropdown-menu
+  @rn-primitives/menubar
+  @rn-primitives/navigation-menu
+  @rn-primitives/hover-card
+  @rn-primitives/alert-dialog
+  @rn-primitives/toolbar
+  @rn-primitives/toast
+  @rn-primitives/aspect-ratio
+  @rn-primitives/table
+  @rn-primitives/portal
+  ```
+- If a matching primitive exists → MUST use it as the foundation.
+- MUST NOT recreate accessible behavior manually when a primitive is available.
+
+---
+
+### 2. Web Component Reference
+
+- Use `read_file` on:
+  `packages/pawprint-web/src/components/{atoms,molecules}/[ComponentName]/[ComponentName].tsx`
+- Study the web component's:
+  - Prop types and variants
+  - Token paths used
+  - JSDoc documentation
+  - API surface
+
+You MUST document:
+- Which props and variants the web component has
+- How they will map to the native implementation
+- Any platform-specific differences
+
+---
+
+### 3. Existing Native Component Audit
+
+- Use `list_dir` and `read_file` on:
+  `packages/pawprint-native/src`
+- Identify reusable native components (Typography, Icon, Spinner, Illustration, etc.).
+
+You MUST document:
+- Which existing components will be reused
+- How they map to Figma elements
+
+---
+
+### 4. Token Audit
+
+- Use `read_file` or `grep_search` on:
+  `packages/pawprint-tokens/build/tokens.d.ts`
+
+You MUST document:
+- Exact token paths available
+
+Example:
+`theme.tokens.components.buttons.button.colour.background.primary`
+
+You MUST list exact token paths before coding.
+
+---
+
+### 5. Figma Analysis
+
+- Use `mcp0_get_screenshot`
+- Document:
+
+  - All variants
+  - All states (default, pressed, disabled, error, selected, checked, etc.)
+  - Exact layout order
+  - Element positioning
+  - Spacing
+  - Sizing
+  - Typography
+  - Colors
+
+You MUST NOT invent variants or states not visible in Figma.
+
+Note: React Native does not have hover states — skip hover unless the component runs on web via Expo.
+
+---
+
+## Step 2 – Decision Points
+
+If multiple valid approaches exist:
+
+- Use `ask_user_question`
+- Present:
+  - What was detected
+  - Architectural recommendation
+  - Clear options
+  - Allow multi-select if needed
+
+Do NOT proceed without user confirmation when structural decisions exist.
+
+---
+
+## Step 3 – Implementation Rules
+
+- Only implement what is explicitly requested.
+- Use `@rn-primitives` components if available as the accessible foundation.
+- Use standard React Native primitives for layout:
+
+  - `View` → generic container
+  - `Pressable` → interactive elements (NOT `TouchableOpacity`)
+  - `ScrollView` → scrollable content
+  - `FlatList` → long lists
+
+- Compose existing design system components (Typography, Icon, Spinner).
+- Apply tokens using strict fallback strategy.
+- Use `styled` from `@emotion/native` for token-driven styles.
+- Use `useTheme` from `@emotion/react` for dynamic token access in component body.
+- Use `parseTokenValue()` to convert string tokens to numbers.
+- Prefix internal styled props to avoid clashes with native props:
+  ```tsx
+  // ✅ GOOD: badgeVariant, badgeSize (prefixed)
+  // ❌ BAD: variant, size (may clash with native props)
+  ```
+- Use proper TypeScript types.
+- Use `React.forwardRef<View, Props>` (or `Pressable`, `TextInput` as appropriate).
+- Always use `Typography` for text — NEVER raw `<Text>`.
+- Add comprehensive JSDoc comments on the component export:
+
+  ```tsx
+  /**
+   * Short description of what the component is and does.
+   *
+   * @param {"variant-a" | "variant-b"} [variant="variant-a"] - Description.
+   * @param {"sm" | "md" | "lg"} [size="md"] - Description.
+   * @param {boolean} [disabled=false] - Description.
+   *
+   * @example
+   * ```tsx
+   * import { Component } from "@butternutbox/pawprint-native"
+   *
+   * <Component size="md">Content</Component>
+   * ```
+   */
+  export const Component = React.forwardRef<View, ComponentProps>(
+    (props, ref) => { ... }
+  )
+  ```
+
+- Do NOT add comments inside TypeScript type definitions.
+- Follow `COMPONENT_GUIDELINES.md`.
+
+---
+
+## Step 4 – Interactive States
+
+React Native has no CSS pseudo-classes. Handle states via:
+
+- `Pressable` `style` callback for pressed state:
+  ```tsx
+  <Pressable style={({ pressed }) => [
+    styles.base,
+    pressed && styles.pressed
+  ]} />
+  ```
+- Props on styled components for variant/disabled states:
+  ```tsx
+  const StyledButton = styled(Pressable)<{ isDisabled: boolean }>(
+    ({ theme, isDisabled }) => ({
+      backgroundColor: isDisabled
+        ? tokens.colour.background.disabled
+        : tokens.colour.background.default,
+      opacity: isDisabled ? 0.5 : 1
+    })
+  )
+  ```
+- `Animated` or `react-native-reanimated` for animated transitions.
+
+States to implement:
+- default
+- pressed (via Pressable callback)
+- disabled (via `disabled` prop + visual tokens)
+- error / success (via `state` or `variant` prop)
+- checked / selected (for toggles, checkboxes, radios)
+
+Do NOT implement hover states (not available on mobile).
+
+---
+
+## Step 5 – Accessibility
+
+- Use `accessible={true}` on interactive elements.
+- Set `accessibilityRole`:
+  - `"button"` for buttons
+  - `"checkbox"` for checkboxes
+  - `"switch"` for switches
+  - `"image"` for icons/illustrations with labels
+  - `"link"` for links
+  - `"adjustable"` for sliders
+  - `"radio"` for radio buttons
+- Set `accessibilityLabel` for icon-only or image components.
+- Set `accessibilityState` for stateful components:
+  ```tsx
+  accessibilityState={{ disabled, checked, selected }}
+  ```
+- Set `accessibilityHint` when the action is not obvious from the label.
+- Ensure sufficient color contrast (use semantic tokens).
+- Dev-mode `console.warn` when `aria-label` is missing on meaningful icons.
+
+---
+
+## Step 6 – Storybook Requirements
+
+- Co-locate stories in the component folder: `[ComponentName].stories.tsx`
+- Use CSF format with `export default { title, component, argTypes }`.
+- Every argType MUST have a `description` field.
+- Create stories for:
+  - ALL variants
+  - ALL states
+- Include:
+  - `Playground` story with args for every controllable prop
+  - `AllVariants` story showcasing all variant/size combinations
+  - State-specific stories (disabled, loading, error, etc.)
+- Use `StyleSheet.create` for story layout styles.
+- For interactive controlled components, use `React.useState` in the story render.
+
+---
+
+## Step 7 – Export Requirements
+
+You MUST:
+
+1. Create `index.ts` in the component folder:
+   ```tsx
+   export { [Component] } from "./[Component]"
+   export type { [Component]Props } from "./[Component]"
+   ```
+2. Export from:
+   - `atoms/index.ts`
+   - OR `molecules/index.ts`
+   - OR `organisms/index.ts`
+3. Export from main:
+   `components/index.ts`
+4. Verify the export chain reaches `src/index.ts`.
+
+No other files may be modified.
+
+---
+
+## Step 8 – Visual Verification
+
+- Compare Storybook rendering with Figma screenshot.
+- Verify:
+  - Spacing
+  - Sizing
+  - Colors
+  - Typography
+  - Alignment
+- Test all interactive states visually.
+- Test on both iOS and Android (or Expo web) if possible.
+
+---
+
+## Step 9 – Parity Check
+
+- Compare the native component API with the web version:
+  - Same prop names where possible
+  - Same variants and sizes
+  - Same token paths
+- Document any platform-specific differences in JSDoc:
+  ```tsx
+  /**
+   * ...
+   * Note: Unlike the web version, `top` and `bottom` accept numbers only (not strings).
+   */
+  ```
+
+---
+
+# 📦 Required Output Format
+
+Before coding, you MUST provide:
+
+1. Web component reference (props, variants from web version)
+2. RN Primitives check result (available primitive or "none — building custom")
+3. Reuse mapping (existing native components → Figma elements)
+4. Token paths that will be used (exact strings)
+5. Proposed component API (props + variants)
+6. Platform differences from web version (if any)
+7. File plan (new files + modified export files)
+
+After coding:
+
+- Provide code grouped by file
+- Clearly label each file path
+- List exactly which files were:
+  - Created
+  - Modified
+
+You MUST NOT output anything outside this structure.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@butternutbox/pawprint-native",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "ButternutBox Pawprint Design System - React Native Components",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf .turbo node_modules dist",
+    "lint:check": "eslint src --max-warnings 0",
+    "type:check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@butternutbox/pawprint-tokens": "^0.0.1",
+    "@emotion/native": "^11.11.0",
+    "@emotion/react": "^11.14.0",
+    "@rn-primitives/avatar": "^1.4.0",
+    "@rn-primitives/checkbox": "^1.4.0",
+    "@rn-primitives/portal": "^1.0.5",
+    "@rn-primitives/slider": "^1.4.0",
+    "@rn-primitives/slot": "^1.0.5",
+    "@rn-primitives/switch": "^1.4.0",
+    "@rn-primitives/toggle": "^1.4.0",
+    "@rn-primitives/types": "^1.0.5",
+    "expo": "^55.0.9"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.74.0"
+  },
+  "devDependencies": {
+    "@butternutbox/pawprint-icons": "workspace:*",
+    "@butternutbox/pawprint-illustrations": "workspace:*",
+    "@repo/eslint-config": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "@types/react": "~19.1.10",
+    "@types/react-native": "^0.73.0",
+    "eslint": "^8.57.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components/atoms/Avatar/Avatar.stories.tsx

@@ -0,0 +1,125 @@
+import React from "react"
+import { View, StyleSheet } from "react-native"
+import { Avatar } from "./Avatar"
+import type { AvatarProps } from "./Avatar"
+
+const DOG_PHOTO_URL = "https://placedog.net/200/200"
+
+export default {
+  title: "Atoms/Avatar",
+  component: Avatar,
+  argTypes: {
+    src: {
+      control: { type: "text" },
+      description: "Image source URL"
+    },
+    alt: {
+      control: { type: "text" },
+      description: "Accessible label (required)"
+    },
+    size: {
+      control: { type: "select" },
+      options: ["sm", "md", "lg"],
+      description: "Size variant"
+    },
+    border: {
+      control: { type: "select" },
+      options: ["none", "sm", "md"],
+      description: "Border width variant"
+    },
+    fallbackType: {
+      control: { type: "select" },
+      options: ["string", "image"],
+      description: "Fallback display type (auto-detected)"
+    },
+    fallbackString: {
+      control: { type: "text" },
+      description: "Text to display as fallback (e.g. user initials)"
+    }
+  }
+}
+
+export const Default = (args: AvatarProps) => <Avatar {...args} />
+Default.args = {
+  src: DOG_PHOTO_URL,
+  alt: "User Photo",
+  size: "md",
+  border: "none"
+}
+
+export const Sizes = () => (
+  <View style={styles.row}>
+    <Avatar src={DOG_PHOTO_URL} alt="Small avatar" size="sm" />
+    <Avatar src={DOG_PHOTO_URL} alt="Medium avatar" size="md" />
+    <Avatar src={DOG_PHOTO_URL} alt="Large avatar" size="lg" />
+  </View>
+)
+
+export const Borders = () => (
+  <View style={styles.row}>
+    <Avatar src={DOG_PHOTO_URL} alt="No border" border="none" />
+    <Avatar src={DOG_PHOTO_URL} alt="Small border" border="sm" />
+    <Avatar src={DOG_PHOTO_URL} alt="Medium border" border="md" />
+  </View>
+)
+
+export const FallbackString = (args: AvatarProps) => <Avatar {...args} />
+FallbackString.args = {
+  alt: "User initials",
+  fallbackString: "JD",
+  size: "md"
+}
+
+export const FallbackStringSizes = () => (
+  <View style={styles.row}>
+    <Avatar alt="Small" fallbackString="AB" size="sm" />
+    <Avatar alt="Medium" fallbackString="CD" size="md" />
+    <Avatar alt="Large" fallbackString="EF" size="lg" />
+  </View>
+)
+
+export const FallbackImage = (args: AvatarProps) => <Avatar {...args} />
+FallbackImage.args = {
+  alt: "Default avatar icon",
+  fallbackType: "image",
+  size: "md"
+}
+
+export const BrokenImage = () => (
+  <View style={styles.row}>
+    <Avatar
+      src="https://broken-link.com/photo.jpg"
+      alt="Broken with string fallback"
+      fallbackString="JD"
+      fallbackType="string"
+    />
+    <Avatar
+      src="https://broken-link.com/photo.jpg"
+      alt="Broken with image fallback"
+      fallbackType="image"
+    />
+  </View>
+)
+
+export const BordersWithFallback = () => (
+  <View style={styles.row}>
+    <Avatar alt="No border" fallbackString="AB" border="none" />
+    <Avatar alt="Small border" fallbackString="CD" border="sm" />
+    <Avatar alt="Medium border" fallbackString="EF" border="md" />
+  </View>
+)
+
+export const LongInitials = (args: AvatarProps) => <Avatar {...args} />
+LongInitials.args = {
+  alt: "Long initials",
+  fallbackString: "ABC",
+  size: "lg"
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    gap: 16,
+    alignItems: "center"
+  }
+})