app-studio 0.8.0 → 0.8.1

package/docs/Animation.md

@@ -1,5 +1,7 @@
 # Animation
 
+> **React Native:** the entire animation system on this page compiles to CSS keyframes and `animation-timeline` rules, which **don't run** in React Native. The `Animation.*` helpers and the `animate` / `animateIn` / `animateOut` / `animateOn` props are accepted on native but have no visual effect. For motion on native, use `Animated` (RN core), `react-native-reanimated`, `LayoutAnimation`, or `moti`. See [Native.md → Animations](Native.md#animations).
+
 ## 1. Introduction
 
 App-Studio provides a powerful animation system through the `Animation` object and the `Element` component. This system allows you to easily add dynamic and engaging animations, including:

package/docs/Components.md

@@ -2,6 +2,8 @@
 
 App-Studio provides a comprehensive set of components built on the `Element` base component. This guide covers all the available components and their usage.
 
+> **React Native:** every component on this page also ships in the native build, rendered with the matching RN primitive (`View`, `Pressable`, `Text`, `Image`, `TextInput`, `ScrollView`, `SafeAreaView`). See [Native.md](Native.md) for the full mapping table and a list of native-only / web-only props.
+
 ## Element
 
 The `Element` component is the foundation of App-Studio. It is responsible for handling a large part of the styles of the other components. It takes care of responsiveness, shadow, margins, and padding among other properties.
@@ -75,6 +77,8 @@ import { Vertical, Horizontal, Center } from 'app-studio';
 ### Text
 For displaying text content with theme support. Extends the basic `span` HTML element.
 
+> **React Native:** renders `<Text>`. Adds `maxLines` (→ `numberOfLines`), `toUpperCase`, `isItalic`, `isStriked`, `isUnderlined`, `isSub`/`isSup`.
+
 ```tsx
 import { Text } from 'app-studio';
 
@@ -117,6 +121,8 @@ import { Image } from 'app-studio';
 />
 ```
 
+> **React Native:** `src` is translated to `{ uri: src }` automatically. To use a bundled asset, pass `source={require('./logo.png')}` instead. `alt` becomes `accessibilityLabel`.
+
 ## Form Components
 
 ### Form
@@ -129,6 +135,8 @@ Extends the basic `form` HTML element. It's used for creating forms and provides
 </Form>
 ```
 
+> **React Native:** `Form` is an alias for `View` — there is no `form` element on native. Drive submission manually from a `Button`'s `onPress` handler.
+
 ### Input
 Extends the basic `input` HTML element with additional styling properties.
 
@@ -150,6 +158,8 @@ import { Input } from 'app-studio';
 />
 ```
 
+> **React Native:** renders `<TextInput>`. Prefer `onChangeText={value => ...}` over `onChange`. The `on` map (hover/focus/etc.) is a no-op — use `TextInput`'s `onFocus`/`onBlur` props for focus styling.
+
 ### Button
 Interactive button component with built-in states and animations.
 
@@ -172,6 +182,8 @@ import { Button } from 'app-studio';
 </Button>
 ```
 
+> **React Native:** renders `<Pressable accessibilityRole="button">`. Use `onPress` (or keep `onClick` — it is forwarded to `onPress`). String/number children are wrapped in `<Text>` automatically. The `on` map is dropped — express press feedback via `Pressable`'s `({ pressed }) => style` callback or RN's `Animated` API.
+
 ## Feedback Components
 
 ### Skeleton

package/docs/Design.md

@@ -4,6 +4,8 @@
 
 The `app-studio` library provides a set of design props that simplify styling and enhance design integration. These props offer a more streamlined and efficient way to manage styling compared to using inline styles or CSS classes directly. They are particularly beneficial for implementing responsive and theme-aware styling, allowing you to easily adapt your components to different screen sizes and themes.
 
+> **React Native:** the design props on this page (direct style props, `widthHeight`, `shadow`, `media`, theme color strings, the component-level `theme` override) all work the same on native. The `shadow` prop expands to RN's `shadowColor` / `shadowOffset` / `shadowOpacity` / `shadowRadius` plus an Android `elevation`. See [Native.md → Styling Props on Native](Native.md#styling-props-on-native) for the supported-property list and native-only behavior.
+
 Here is an example:
 
 ```jsx

package/docs/Events.md

@@ -2,6 +2,8 @@
 
 App-Studio provides intuitive ways to manage events in your CSS through the `on` prop and underscore-prefixed properties. These features are designed to offer convenient ways to style elements based on various interactive states, represented by CSS pseudo-classes like `hover`, `active`, and `focus`.
 
+> **React Native:** the `on={{ hover, active, focus, ... }}` map and every underscore-prefixed state modifier (`_hover`, `_focus`, `_active`, `_disabled`, `_checked`, …) are **web-only** — they're accepted on native but produce no visual change. RN drives interaction state through `Pressable`'s render-prop API (`style={({ pressed, hovered }) => ...}`) and its `onPressIn` / `onPressOut` / `onHoverIn` / `onHoverOut` callbacks; for input focus, use `<TextInput>`'s `onFocus` / `onBlur` directly. The full list of no-op props is in [Native.md → Web-Only Props](Native.md#web-only-props-no-ops-on-native).
+
 ---
 
 ## 1. Introduction to Event-Based Styling

package/docs/Hooks.md

@@ -2,6 +2,8 @@
 
 App-Studio provides a comprehensive set of React hooks to help you build interactive and responsive applications. This guide covers all the available hooks and their usage.
 
+> **React Native:** the hooks below are listed by their web behavior. Most have native counterparts; some are exported as **no-op stubs** so shared component code keeps compiling (e.g. `useHover`, `useFocus`, `useClickOutside`, `useElementPosition`, `useKeyPress`, `useOnScreen`, `useInView`, `useIframeStyles`, `useScroll`). The full per-hook breakdown lives in [Native.md → Hooks on Native](Native.md#hooks-on-native).
+
 ## Iframe Support
 
 Many hooks in App-Studio support working inside iframes for micro-frontend architectures, preview environments, and embedded widgets.

package/docs/IframeSupport.md

@@ -1,5 +1,7 @@
 # Iframe Support
 
+> **React Native:** iframes don't exist on native — everything on this page is **web-only**. The hooks listed below (`useScroll`, `useScrollAnimation`, `useScrollDirection`, `useSmoothScroll`, `useClickOutside`, `useIframeStyles`) and the `targetWindow` provider option have no native counterpart. On native, drive scroll behavior from `ScrollView` / `FlatList` `onScroll` callbacks instead. See [Native.md → Hooks on Native](Native.md#hooks-on-native).
+
 App-Studio provides first-class support for rendering components inside iframes. This enables use cases like:
 
 - **Micro-frontend architectures** - Isolate different parts of your application

package/docs/Native.md

@@ -0,0 +1,428 @@
+# React Native
+
+App-Studio ships a dedicated React Native build alongside its web build. The same import paths and prop-based styling API work in both environments — Metro picks the correct build automatically through the `react-native` export condition.
+
+## Table of Contents
+
+1. [Setup](#setup)
+2. [Component Mapping](#component-mapping)
+3. [Styling Props on Native](#styling-props-on-native)
+4. [Web-Only Props (No-ops on Native)](#web-only-props-no-ops-on-native)
+5. [Theme & Color Resolution](#theme--color-resolution)
+6. [Responsive & Media Queries](#responsive--media-queries)
+7. [Hooks on Native](#hooks-on-native)
+8. [Accessibility & Test IDs](#accessibility--test-ids)
+9. [Animations](#animations)
+10. [Differences Cheat Sheet](#differences-cheat-sheet)
+
+---
+
+## Setup
+
+### Requirements
+
+- React Native `>= 0.79` (Metro must support [package exports](https://reactnative.dev/blog/2023/06/21/package-exports-support); enabled by default in 0.79+).
+- React `>= 17`.
+
+### Install
+
+```bash
+npm install app-studio
+# or
+yarn add app-studio
+```
+
+App-Studio's only runtime dependencies (`color-convert`, `hyphenate-style-name`) are shared between web and native and require no extra Metro configuration.
+
+### Import paths
+
+Use the bare package name from any RN file — Metro resolves it to the native build:
+
+```tsx
+import {
+  View,
+  Text,
+  Button,
+  ThemeProvider,
+  ResponsiveProvider,
+  WindowSizeProvider,
+} from 'app-studio';
+```
+
+Two explicit subpaths are also available if you ever need to force a build:
+
+- `app-studio/native` — always loads the native build (useful for inspecting the API in a web tool, or for monorepos with non-standard resolvers).
+- `app-studio/web` — always loads the web build.
+
+You should not need these subpaths in normal application code.
+
+### Provider tree
+
+The provider API is identical to web. A typical RN entrypoint looks like:
+
+```tsx
+import React from 'react';
+import {
+  ThemeProvider,
+  ResponsiveProvider,
+  WindowSizeProvider,
+  AnalyticsProvider,
+} from 'app-studio';
+import RootScreen from './RootScreen';
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <WindowSizeProvider>
+        <ResponsiveProvider>
+          <AnalyticsProvider trackEvent={(event) => console.log(event)}>
+            <RootScreen />
+          </AnalyticsProvider>
+        </ResponsiveProvider>
+      </WindowSizeProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+---
+
+## Component Mapping
+
+Every cross-platform primitive renders a familiar React Native node under the hood. Children are wrapped or forwarded as needed.
+
+| App-Studio component                | Native renders as                                                          | Notes |
+| :---------------------------------- | :------------------------------------------------------------------------- | :---- |
+| `Element`, `View`, `Div`, `Span`    | `<View>` — or `<Pressable>` when `onPress`/`onClick` is provided           | Children are wrapped between optional `before` / `after` slots. |
+| `Horizontal`                        | `<View flexDirection="row">`                                               | |
+| `Vertical`                          | `<View flexDirection="column">`                                            | |
+| `Center`                            | `<View justifyContent="center" alignItems="center">`                       | |
+| `HorizontalResponsive`              | `<View flexDirection="row">` → `column` at `mobile` breakpoint             | Uses `useWindowDimensions` + `ResponsiveProvider`. |
+| `VerticalResponsive`                | `<View flexDirection="column">` → `row` at `mobile` breakpoint             | |
+| `Scroll`                            | `<ScrollView>`                                                             | Pass standard RN scroll props (e.g. `contentContainerStyle`, `horizontal`). |
+| `SafeArea`                          | `<SafeAreaView>` (from `react-native`)                                     | For richer behavior use `react-native-safe-area-context` directly. |
+| `Text`                              | `<Text>`                                                                   | See [Text-specific props](#text). |
+| `Image`                             | `<Image>`                                                                  | `src` is translated to `{ uri: src }` automatically; `source` is also accepted. |
+| `ImageBackground`                   | `<ImageBackground>`                                                        | Same `src` / `source` handling as `Image`. |
+| `Form`                              | `<View>`                                                                   | Form semantics don't exist in RN; treat it as an alias for `View`. |
+| `Input`                             | `<TextInput>`                                                              | Use `onChangeText` (not `onChange`). |
+| `Button`                            | `<Pressable accessibilityRole="button">`                                   | String / number children are wrapped in `<Text>` automatically. |
+| `Skeleton`                          | `<View accessibilityRole="progressbar">`                                   | Static placeholder — see [Animations](#animations) for shimmer notes. |
+
+### Text
+
+Native `Text` accepts a few extra typographic props that translate to RN-friendly equivalents:
+
+| Prop            | Mapping                                                                  |
+| :-------------- | :----------------------------------------------------------------------- |
+| `toUpperCase`   | Converts string children to uppercase before rendering.                  |
+| `isItalic`      | Sets `fontStyle: 'italic'`.                                              |
+| `isStriked`     | Sets `textDecorationLine: 'line-through'`.                               |
+| `isUnderlined`  | Sets `textDecorationLine: 'underline'`.                                  |
+| `isSub` / `isSup` | Forces `fontSize` to 12 unless an explicit size is provided.           |
+| `maxLines`      | Sets RN's `numberOfLines` prop.                                          |
+
+```tsx
+<Text fontSize={16} fontWeight="bold" maxLines={2} toUpperCase>
+  Important headline
+</Text>
+```
+
+### Image
+
+Pass either a remote URL via `src` (web-style) or a native `ImageSourcePropType` via `source`:
+
+```tsx
+<Image src="https://example.com/avatar.png" width={48} height={48} borderRadius={24} alt="User avatar" />
+
+// or with a bundled asset
+<Image source={require('./logo.png')} width={120} height={32} />
+```
+
+`alt` is forwarded as `accessibilityLabel`.
+
+### Button
+
+Wraps `Pressable`. A `disabled` prop short-circuits both `onPress` and `onClick`:
+
+```tsx
+<Button
+  paddingHorizontal={20}
+  paddingVertical={12}
+  backgroundColor="theme-primary"
+  borderRadius={8}
+  onPress={handleSubmit}
+  disabled={isSubmitting}
+>
+  Submit
+</Button>
+```
+
+String children become `<Text>` automatically; pass JSX directly for anything more complex.
+
+---
+
+## Styling Props on Native
+
+All cross-platform style props you already use on web work the same way on native, with the same theme-aware color resolution. The native style engine accepts the subset of CSS properties that React Native supports.
+
+### Supported style props
+
+The following props are read by the native style engine and applied to the underlying `View` / `Text` / `Image` style. Anything not in this list is passed through to React Native as-is.
+
+```
+Layout & Flex:   flex, flexDirection, flexBasis, flexGrow, flexShrink, flexWrap,
+                 alignContent, alignItems, alignSelf, justifyContent, gap,
+                 rowGap, columnGap, aspectRatio, direction, display, position,
+                 top, right, bottom, left, start, end, zIndex, overflow,
+
+Box model:       width, height, minWidth, minHeight, maxWidth, maxHeight,
+                 margin*, padding*, (including marginHorizontal/Vertical
+                 and paddingHorizontal/Vertical), borderWidth*,
+                 borderRadius*, borderColor*, borderStyle, borderCurve,
+
+Typography:      color, fontFamily, fontSize, fontStyle, fontWeight,
+                 fontVariant, lineHeight, letterSpacing, textAlign,
+                 textAlignVertical, textDecorationLine, textDecorationColor,
+                 textDecorationStyle, textShadow*, textTransform,
+                 verticalAlign, writingDirection, includeFontPadding,
+
+Visual:          backgroundColor, opacity, transform, transformOrigin,
+                 shadowColor, shadowOffset, shadowOpacity, shadowRadius,
+                 elevation, boxShadow, overlayColor, tintColor,
+                 backfaceVisibility, objectFit, resizeMode
+```
+
+### Native-only convenience props
+
+Two cross-platform props are expanded on native (they also exist on web with the same meaning):
+
+| Prop          | Behavior                                                                              |
+| :------------ | :------------------------------------------------------------------------------------ |
+| `widthHeight` | Sets both `width` and `height` to the same value.                                     |
+| `shadow`      | `true` or a number `0..1` — applies `shadowColor #000`, `shadowRadius 4`, `shadowOffset {0,1}`, `shadowOpacity` (defaulting to `0.2`), and a matching Android `elevation`. |
+
+```tsx
+<View widthHeight={48} backgroundColor="theme-primary" borderRadius={24} shadow={0.3} />
+```
+
+### `media`, `css`, and `style`
+
+The native style engine reads styles from four sources, merged in this order (later sources override earlier ones):
+
+1. Top-level style props on the component.
+2. `media={{ breakpoint: { ... } }}` entries matching the current width.
+3. `css={{ ... }}` (plain object only — raw CSS strings have no effect on native).
+4. `style={{ ... }}` (standard RN `StyleProp`, including arrays). `StyleSheet.flatten` is applied automatically.
+
+```tsx
+<View
+  padding={12}
+  backgroundColor="color-gray-100"
+  media={{ tablet: { padding: 24 }, desktop: { padding: 32 } }}
+  css={{ borderColor: 'theme-primary', borderWidth: 1 }}
+  style={{ borderRadius: 12 }}
+/>
+```
+
+### `onPress` & `onClick`
+
+Native components accept both. If either is set on a non-pressable primitive (`Element`/`View`), the component automatically renders as `Pressable`. `onClick` is forwarded to `Pressable`'s `onPress` so web code that uses `onClick` keeps working.
+
+---
+
+## Web-Only Props (No-ops on Native)
+
+To keep the prop API uniform across platforms, the native build *accepts* the following props but does nothing with them — they're silently dropped before reaching the underlying RN component. Code that targets both platforms can leave them in place.
+
+**State modifiers (underscore-prefixed):** `_hover`, `_active`, `_focus`, `_visited`, `_disabled`, `_enabled`, `_checked`, `_unchecked`, `_invalid`, `_valid`, `_required`, `_optional`, `_selected`, `_target`, `_firstChild`, `_lastChild`, `_onlyChild`, `_firstOfType`, `_lastOfType`, `_empty`, `_focusVisible`, `_focusWithin`, `_placeholder`, `_groupHover`, `_groupFocus`, `_groupActive`, `_groupDisabled`, `_peerHover`, `_peerFocus`, `_peerActive`, `_peerDisabled`, `_peerChecked`.
+
+**Pseudo-elements:** `_before`, `_after`, `_firstLetter`, `_firstLine`, `_selection`, `_backdrop`, `_marker`.
+
+**`on={{ ... }}`** — the `on` map (hover/focus/active/etc.) is also a no-op. RN drives interactions through `Pressable` props (`onPressIn`, `onPressOut`, `onHoverIn`, etc.); use those directly when you need interaction-driven style changes.
+
+**Other web-only props:**
+
+- `as` — RN components don't have HTML tags; the underlying primitive is fixed.
+- `className` — ignored.
+- `css` raw CSS strings — only object-form `css` is read on native.
+- CSS animations declared via `animate` / `animateIn` / `animateOut` / `animateOn` — see [Animations](#animations).
+
+If you write a component that's truly platform-divergent, the cleanest path is to split it into `MyComponent.tsx` (web) and `MyComponent.native.tsx` (native) — Metro will pick the `.native` file automatically.
+
+---
+
+## Theme & Color Resolution
+
+`ThemeProvider`, `useTheme`, and all the theme prop syntax work on native just like web. Pass color strings (`color-blue-500`, `theme-primary`, `light-white`, `dark-red-200`, `theme-primary-300` for 30% alpha, etc.) directly into any color-accepting prop and they resolve through the theme — no `getColor` call required:
+
+```tsx
+<View backgroundColor="theme-primary" padding={16}>
+  <Text color="color-white">Hello, native!</Text>
+</View>
+```
+
+### Implementation detail
+
+On web, alpha colors compile to `color-mix(...)` CSS. On native, the theme provider's `getColor` returns the resolved color string directly (hex or rgba), and the style engine substitutes it into any prop whose name contains `color` (case-insensitive) — `backgroundColor`, `borderColor`, `tintColor`, `shadowColor`, and so on.
+
+### `useTheme` API
+
+The native theme context exposes the same surface as web:
+
+```tsx
+const {
+  getColor,         // (name) => resolved color string
+  getColorHex,      // (name) => normalized hex
+  getColorRGBA,     // (name, alpha?: 0..1000) => rgba(...)
+  getColorScheme,   // (name) => palette or theme token name
+  getContrastColor, // (name) => 'black' | 'white'
+  theme,
+  colors,
+  themeMode,
+  setThemeMode,
+} = useTheme();
+```
+
+`getColor` returns concrete color values (hex/rgba), so you can pass them to third-party RN libraries that expect a plain string.
+
+### Scoped theme override
+
+`Element`, `View`, etc. accept a `theme` prop that locally overrides theme tokens for that subtree. The override applies only to `theme-*` color tokens consumed by *that* component's style props — it does not propagate to child components.
+
+```tsx
+<Element backgroundColor="theme-primary" theme={{ primary: 'color-purple-500' }}>
+  ...
+</Element>
+```
+
+---
+
+## Responsive & Media Queries
+
+The native `ResponsiveProvider` is powered by `useWindowDimensions()` from React Native, so it reacts to device rotation and split-screen mode automatically.
+
+**Default breakpoints (px):** `xs: 0`, `sm: 340`, `md: 560`, `lg: 1080`, `xl: 1300`.
+**Default devices:** `mobile: [xs, sm]`, `tablet: [md, lg]`, `desktop: [lg, xl]`.
+
+Pass `breakpoints` and `devices` props to `ResponsiveProvider` to customize them.
+
+### `media` prop
+
+Works the same as on web — keys can be breakpoint names or device names. On native, `media` styles are merged into the inline RN style object whenever the active breakpoint matches.
+
+```tsx
+<View
+  padding={12}
+  media={{
+    mobile: { padding: 12, flexDirection: 'column' },
+    tablet: { padding: 24, flexDirection: 'row' },
+  }}
+/>
+```
+
+### `useResponsive`
+
+```tsx
+import { useResponsive } from 'app-studio';
+
+function AdaptiveCard() {
+  const { screen, currentDevice, orientation, on } = useResponsive();
+
+  return (
+    <View flexDirection={on('mobile') ? 'column' : 'row'}>
+      <Text>{screen} · {currentDevice} · {orientation}</Text>
+    </View>
+  );
+}
+```
+
+`screen` (alias for `currentBreakpoint`), `currentDevice`, `orientation`, `on(name)`, and `is(name)` behave identically to web.
+
+---
+
+## Hooks on Native
+
+Some hooks are inherently web-only (DOM events, IntersectionObserver, keyboard listeners). On native they are exported as **safe stubs** so that shared component code keeps compiling — but you should not rely on them returning meaningful values.
+
+| Hook                  | Native behavior                                                                                |
+| :-------------------- | :--------------------------------------------------------------------------------------------- |
+| `useWindowSize`       | ✅ Works. Backed by RN's `useWindowDimensions`.                                                |
+| `useWindowDimensions` | ✅ Works. Same data as `useWindowSize`.                                                        |
+| `useResponsive`       | ✅ Works. Reads from `ResponsiveProvider`.                                                     |
+| `useBreakpoint`       | ✅ Works. Same as `useResponsive` minus width/height.                                          |
+| `useTheme`            | ✅ Works (covered above).                                                                      |
+| `useAnalytics`        | ✅ Works.                                                                                      |
+| `useMount`            | ✅ Works.                                                                                      |
+| `useHover`            | ⚠️ Stub. Returns `{ isHovered: false, hoverProps: {} }`. Use RN's `Pressable` `onHoverIn`/`onHoverOut` if you need hover on a mouse-capable device. |
+| `useActive`           | ⚠️ Stub. Returns `{ isActive: false, activeProps: {} }`. Use `Pressable` `onPressIn`/`onPressOut`. |
+| `useFocus`            | ⚠️ Stub. Returns `{ isFocused: false, focusProps: {} }`. Use `TextInput`'s `onFocus`/`onBlur` directly. |
+| `useClickOutside`     | ⚠️ Stub. Returns a ref and `isOutside: false`. Patterns like outside-tap dismissal need a `Pressable` overlay in RN. |
+| `useElementPosition`  | ⚠️ Stub. RN equivalent is `measure()` on a `ref`. |
+| `useKeyPress`         | ⚠️ Stub. Returns `false`. Use `react-native-keyboard-events` or platform-specific code. |
+| `useOnScreen`         | ⚠️ Stub. Returns `{ ref, isOnScreen: true }` — assume always visible. |
+| `useInView`           | ⚠️ Stub. Returns `{ ref, inView: true }`. For real visibility tracking inside lists, prefer `FlatList`'s `viewabilityConfig` / `onViewableItemsChanged`. |
+| `useIframeStyles`     | ⚠️ Stub. iframes don't exist on native. |
+| `useScroll`           | ⚠️ Stub. Returns zeroed values and no-op scroll methods. Drive scroll behavior from `ScrollView`/`FlatList`'s `onScroll`. |
+| `useScrollDirection`, `useSmoothScroll`, `useScrollAnimation`, `useInfiniteScroll` | ❌ Not exported on native. Build with RN's own scroll events. |
+
+The stubs exist so a single component body can run on both platforms without conditionals — but on native you should branch when meaningful interaction state is required.
+
+---
+
+## Accessibility & Test IDs
+
+The native build automatically rewrites two common web attributes to their RN equivalents:
+
+| Web prop       | Native prop            |
+| :------------- | :--------------------- |
+| `data-testid`  | `testID`               |
+| `aria-label`   | `accessibilityLabel`   |
+
+So shared component code can keep using `data-testid="submit"` and it will be picked up by Detox/Maestro/Appium without any changes.
+
+```tsx
+<Button data-testid="submit" aria-label="Submit form" onPress={handleSubmit}>
+  Submit
+</Button>
+```
+
+For RN-specific a11y APIs (`accessibilityRole`, `accessibilityState`, `accessibilityHint`, etc.) pass them through directly — they're forwarded untouched to the underlying primitive.
+
+---
+
+## Animations
+
+The `Animation.*` presets and the `animate` / `animateIn` / `animateOut` / `animateOn` props compile to CSS keyframes, which **don't run** in React Native. On native these props are accepted but have no visual effect.
+
+For motion on native, use one of:
+
+- **`Animated` API** (`react-native` core) for simple interpolations.
+- **`react-native-reanimated`** for performant, gesture-driven animations.
+- **`LayoutAnimation`** for automatic layout transitions.
+- **`moti`** for a declarative API similar to App-Studio's `animate` prop.
+
+A native-flavored animation system is on the roadmap — see [next.md](../next.md) for status. Until then, drop down to the libraries above for native motion.
+
+---
+
+## Differences Cheat Sheet
+
+| Concern                       | Web                                            | Native                                                                  |
+| :---------------------------- | :--------------------------------------------- | :---------------------------------------------------------------------- |
+| Underlying primitive          | HTML elements (`div`, `span`, `button`, …)     | RN primitives (`View`, `Pressable`, `Text`, `Image`, `TextInput`, …)    |
+| `as` prop                     | Selects HTML tag                               | Ignored                                                                 |
+| Pseudo-classes (`_hover`, `on`) | Compiled to CSS                              | Silently dropped — use `Pressable` event props instead                  |
+| Pseudo-elements (`_before`, `_after`) | Compiled to CSS                          | Silently dropped — render real components instead                       |
+| `className`                   | Applied to DOM element                         | Ignored                                                                 |
+| `css` raw string              | Injected into stylesheet                       | Ignored (object form still works)                                       |
+| `style`                       | Standard CSSProperties                         | RN `StyleProp` (object, array, or `StyleSheet` reference)               |
+| Animations                    | CSS keyframes via `Animation.*`                | No-op — bring `Animated` / Reanimated / Moti                            |
+| `Image` source                | `src` / `srcSet`                               | `src` (URI shorthand) or `source={...}`                                 |
+| `Input` change handler        | `onChange`                                     | `onChangeText` (RN-native) — `onChange` is also forwarded               |
+| Click handlers                | `onClick`                                      | `onPress` (preferred); `onClick` forwards to `onPress`                  |
+| Test IDs                      | `data-testid`                                  | `data-testid` (rewritten to `testID`) — or `testID` directly            |
+| A11y label                    | `aria-label`                                   | `aria-label` (rewritten to `accessibilityLabel`) — or `accessibilityLabel` directly |
+| `useScroll` family            | Reads from `window` / scroll containers        | Stubbed; use `ScrollView`/`FlatList` `onScroll`                         |
+| `useInView` / `useOnScreen`   | `IntersectionObserver`                         | Stubbed; use `FlatList` viewability                                     |
+| `useKeyPress`                 | DOM key events                                 | Stubbed                                                                 |

package/docs/Providers.md

@@ -2,6 +2,8 @@
 
 App-Studio includes several context providers to manage global state and functionality.
 
+> **React Native:** all four providers (`ThemeProvider`, `ResponsiveProvider`, `WindowSizeProvider`, `AnalyticsProvider`) are exported from the native build with the same API. On native, `ResponsiveProvider` and `WindowSizeProvider` are driven by RN's `useWindowDimensions()`, so they react to rotation and split-screen automatically. See [Native.md → Setup](Native.md#setup) for the recommended provider tree.
+
 ## ThemeProvider
 
 Manages theme context including colors, dark/light mode, and design tokens.

package/docs/README.md

@@ -58,6 +58,8 @@ import { View, Text, Button, ThemeProvider, ResponsiveProvider } from 'app-studi
 
 Metro resolves the package to App-Studio's native build through the `react-native` export condition. Use `app-studio/native` or `app-studio/web` only when you need an explicit platform subpath. Native exposes the cross-platform primitives/providers; web-only props such as `_hover`, pseudo-elements, CSS animations, and HTML `as` values are accepted as no-ops.
 
+See the [React Native guide](Native.md) for component mapping, native-only props, hook behavior on native, and a side-by-side cheat sheet.
+
 ## Core Concepts
 
 ### Element Component
@@ -90,13 +92,14 @@ Explore these guides to learn more about App-Studio:
 
 - [Components](Components.md) - Detailed documentation of all available components
 - [Hooks](Hooks.md) - Guide to the React hooks provided by App-Studio
-- [Theming](Theming.md) - How to customize colors and themes with theme colors and color palettes
+- [Theming](Theming.md) - Customize colors, theme tokens, color palettes, and component-level sub-theming via the `theme` prop
 - [Styling](Styling.md) - Advanced styling guide covering state modifiers, pseudo-elements, media queries, and the CSS system
 - [Animation](Animation.md) - Creating animations with App-Studio
 - [Responsive Design](Responsive.md) - Building responsive layouts
 - [Design System](Design.md) - Understanding the design system
 - [Event Handling](Events.md) - Working with events and interactions
 - [Providers](Providers.md) - Context providers for global state
+- [React Native](Native.md) - Using App-Studio in React Native projects (component mapping, native-only props, hook differences)
 - [Migration Guide](../codemod/README.md) - Migrating to App-Studio
 
 ---

package/docs/Responsive.md

@@ -2,6 +2,8 @@
 
 Creating a responsive design is an essential part of modern web development. In App-Studio, two primary features help you achieve this: `useResponsive` hook and the `media` prop. This document provides an overview and examples for both approaches.
 
+> **React Native:** both the `media` prop and `useResponsive` work on native. Width tracking is backed by RN's `useWindowDimensions`, so values update on rotation and split-screen. The default breakpoints (`xs: 0`, `sm: 340`, `md: 560`, `lg: 1080`, `xl: 1300`) and devices (`mobile`, `tablet`, `desktop`) are shared with web — override them by passing `breakpoints` / `devices` to `ResponsiveProvider`. See [Native.md → Responsive & Media Queries](Native.md#responsive--media-queries).
+
 ---
 
 ## 1. Media Prop for Responsive Design

package/docs/Styling.md

@@ -2,6 +2,8 @@
 
 This guide covers advanced styling techniques in App-Studio, including state modifiers, pseudo-elements, media queries, and the underlying CSS system.
 
+> **React Native:** state modifiers (`_hover`, `_focus`, `_disabled`, …), pseudo-elements (`_before`, `_after`, …), the `on={{ ... }}` map, and raw-string `css` are **web-only**. They are accepted on native but produce no output — express equivalent behavior with `Pressable`'s event props or RN's `Animated` API. Direct style props, the `media` map, object-form `css`, theme color strings, the `widthHeight` shorthand, and the `shadow` prop all work the same on native. See [Native.md → Styling Props on Native](Native.md#styling-props-on-native).
+
 ## Table of Contents
 
 1. [State Modifiers](#state-modifiers)

package/docs/Theming.md

@@ -2,6 +2,8 @@
 
 Theming is an essential part of any application. It allows you to maintain a consistent look and feel across your app. With App-Studio, theming becomes effortless through its `ThemeProvider` component. This document shows you how to set up theming in App-Studio.
 
+> **React Native:** the entire color system documented here (singletons, palettes, theme tokens, `light-`/`dark-` prefixes, alpha shorthand, component-level `theme` overrides) works identically on native. The only implementation difference: on web, alpha colors compile to `color-mix(...)` CSS; on native the theme provider returns concrete hex/rgba strings that get substituted into RN style props. See [Native.md → Theme & Color Resolution](Native.md#theme--color-resolution).
+
 ## Available Colors Reference
 
 App-Studio provides an extensive color system with three types of colors:
@@ -413,6 +415,57 @@ function Example() {
 
 This direct access syntax works with all color-related properties and can be used with both singleton colors (like `white`, `black`) and palette colors (like `red-200`, `blue-500`). It provides a convenient way to reference specific theme colors without having to use the `getColor` function from the `useTheme` hook.
 
+### Component-Level Sub-Theming
+
+Any component that extends `Element` (`View`, `Text`, `Button`, etc.) accepts a `theme` prop that remaps `theme-*` tokens **for that single component**, without touching the global `ThemeProvider`. Useful when a screen needs one "branded" element (a Startup Studio launch button, a special card, a colored chip) while the rest of the UI keeps the global palette.
+
+```javascript
+import { View, Text } from 'app-studio';
+
+function Example() {
+  return (
+    <View>
+      {/* Global theme-primary (no override) */}
+      <View backgroundColor="theme-primary" padding={20}>
+        <Text color="color-white">Global primary</Text>
+      </View>
+
+      {/* Same component, locally remapped to red */}
+      <View
+        backgroundColor="theme-primary"
+        theme={{ primary: 'color-red-500' }}
+        padding={20}
+      >
+        <Text color="color-white">Local primary = red-500</Text>
+      </View>
+
+      {/* Multiple slots at once */}
+      <View
+        backgroundColor="theme-primary"
+        borderColor="theme-secondary"
+        borderWidth={2}
+        borderStyle="solid"
+        theme={{
+          primary: 'color-indigo-600',
+          secondary: 'color-yellow-400',
+        }}
+        padding={20}
+      >
+        <Text color="color-white">indigo bg, yellow border</Text>
+      </View>
+    </View>
+  );
+}
+```
+
+**What the `theme` prop accepts**: a `Partial<Theme>` where each value is itself a color token (`'color-red-500'`, `'theme-secondary'`) or a direct color string (`'#ff0000'`). The keys match the global `Theme` shape (`primary`, `secondary`, `success`, `error`, `warning`, `disabled`, `loading`).
+
+**Alpha suffix works**: `theme-primary-200` on a component with `theme={{ primary: 'color-red-500' }}` resolves to `color-red-500` at 20% opacity via `color-mix()`.
+
+**Dark mode**: overrides that point at palette tokens (e.g., `'color-red-500'`) keep responding to global dark-mode switching, because the resolution returns the underlying CSS variable. Overrides that point at raw hex literals (`'#ff0000'`) bypass the palette and do **not** swap with dark mode — use palette tokens whenever you need dark-mode reactivity.
+
+**Scope**: the override applies only to the Element receiving the `theme` prop. Children that re-use `theme-primary` resolve against the global theme, not the parent's override. To remap an entire subtree, wrap it in a nested `ThemeProvider` instead, or set the `theme` prop on each child.
+
 ### Smart Text Contrast
 
 For text that needs to be visible on any background color (light, dark, or dynamic gradients), App-Studio provides a smart contrast feature.