npm package: @novakit-app/foundation
Description: NovaKit Foundation - React Native UI Framework Core. The universal core that converts design rules → valid, performant React Native styles.
Author: NovaKit Team
Latest version: 1.0.34

# @novakit-app/foundation

> **The React Native styling foundation that brings Tailwind-like classes to
> mobile development**

Style your React Native app with familiar Tailwind-like classes. Write
`className="p-4 bg-primary rounded-lg"` and get beautiful, performant styles
automatically.

## 🚀 Quick Start

```bash
npm install @novakit-app/foundation
```

```tsx
import { View, Text } from "react-native";

export function MyComponent() {
	return (
		<View className="flex-row items-center p-4 bg-primary rounded-lg">
			<Text className="text-lg text-white">Hello World</Text>
		</View>
	);
}
```

## 📚 Documentation

### Core Concepts

- **[How It Works](./docs/HOW_IT_WORKS.md)** - Understanding the foundation
  architecture
- **[Installation & Setup](./docs/INSTALLATION.md)** - Complete setup guide
- **[Configuration](./docs/CONFIGURATION.md)** - Babel plugin and configuration
  options

### Feature Guides

- **[Layout & Flexbox](./docs/LAYOUT.md)** - Flexbox, positioning, and layout
  utilities
- **[Spacing System](./docs/SPACING.md)** - Padding, margin, width, height, and
  gap
- **[Color System](./docs/COLORS.md)** - Background, text, and border colors
- **[Typography](./docs/TYPOGRAPHY.md)** - Font sizes, weights, families, and
  text styling
- **[Borders & Radius](./docs/BORDERS.md)** - Border styles, widths, and border
  radius
- **[Shadows & Elevation](./docs/SHADOWS.md)** - Shadow effects and elevation
- **[Image Styling](./docs/IMAGES.md)** - Object fit and aspect ratio classes
- **[Arbitrary Values](./docs/ARBITRARY_VALUES.md)** - Custom values with
  bracket notation

### Advanced Topics

- **[Theme Integration](./docs/THEMES.md)** - Working with light/dark modes
- **[Performance](./docs/PERFORMANCE.md)** - Optimization and best practices
- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and solutions
- **[API Reference](./docs/API.md)** - Complete API documentation

## 🎯 Key Features

- 🎨 **Familiar Syntax**: Use Tailwind-like classes you already know
- ⚡ **Fast**: Optimized for React Native performance with compile-time
  processing
- 🌓 **Theme-Aware**: Works with light/dark modes automatically
- 📱 **RN-Native**: All styles are valid React Native properties
- 🔧 **Flexible**: Works with or without build tools
- 🚀 **Dynamic System**: 1,500+ classes automatically generated
- 🎯 **Zero Config**: Any color + shade combination just works
- 📦 **Lightweight**: No manual definitions needed

## 📊 What's Supported

### ✅ Fully Supported

- **Layout & Flexbox**: `flex`, `flex-row`, `items-center`, `justify-between`
- **Spacing**: `p-4`, `m-2`, `w-full`, `h-20`, `gap-2` (760+ classes)
- **Colors**: `bg-blue-500`, `text-red-300`, `border-green-400` (726+ classes)
- **Typography**: `text-lg`, `font-bold`, `text-center`, `font-sans`
- **Borders**: `border`, `border-gray-300`, `rounded-lg`
- **Shadows**: `shadow-md`, `shadow-[0,4,8,rgba(0,0,0,0.1)]`
- **Images**: `object-cover`, `aspect-square`, `aspect-video`
- **Arbitrary Values**: `p-[20]`, `bg-[#ff6b6b]`, `rounded-[12]`

### 🔄 React Native Optimized

- Uses `resizeMode` instead of `object-fit`
- Uses `aspectRatio` for responsive containers
- Uses `elevation` for Android shadows
- Uses `shadowOffset`, `shadowOpacity`, `shadowRadius` for iOS shadows
- Supports `gap`, `columnGap`, `rowGap` (React Native 0.71+)

### ❌ Not Supported (CSS-only features)

- CSS Grid (`grid`, `grid-cols-*`)
- CSS Transforms (`transform`, `rotate-*`, `scale-*`)
- CSS Filters (`filter`, `blur-*`, `brightness-*`)
- CSS Animations (`animate-*`)
- CSS Pseudo-classes (`hover:`, `focus:`, `active:`)

## 🏗️ Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   className     │───▶│  Babel Plugin    │───▶│  React Native   │
│ "p-4 bg-blue-500"│    │  (Compile Time)  │    │     Styles      │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │  Style Cache     │
                       │  (Performance)   │
                       └──────────────────┘
```

## 📈 Performance

- **Compile-time processing**: Styles are converted at build time
- **Zero runtime overhead**: No JavaScript execution for static styles
- **Intelligent caching**: Dynamic styles are cached for performance
- **Tree shaking**: Only used classes are included in the bundle

## 🔧 Dynamic System

The foundation automatically generates **1,500+ classes**:

### Color Classes (726+)

```tsx
// Any color + shade combination works automatically
<View className="bg-blue-500 text-white border-red-300">
<Text className="text-purple-600 bg-yellow-200">
```

### Spacing Classes (760+)

```tsx
// All spacing values work automatically
<View className="p-4 m-2 px-6 py-3 w-full h-20">
<Text className="mb-2 mt-6 gap-2">
```

### Layout Classes (50+)

```tsx
// Flexbox and layout utilities
<View className="flex flex-row items-center justify-between">
```

## 🎨 Real Examples

### Card Component

```tsx
<View className="bg-white p-6 rounded-xl shadow-md m-4">
	<Text className="text-xl font-bold text-gray-800 mb-2">Card Title</Text>
	<Text className="text-gray-600 leading-relaxed mb-4">
		This card uses dynamic colors and spacing!
	</Text>
	<View className="flex-row justify-end">
		<Text className="bg-blue-500 text-white px-4 py-2 rounded-lg font-semibold">
			Action
		</Text>
	</View>
</View>
```

### Image Gallery

```tsx
<View className="flex-row flex-wrap gap-2">
	{images.map((image) => (
		<View
			key={image.id}
			className="aspect-square w-24 bg-gray-100 rounded-md"
		>
			<Image
				source={{ uri: image.url }}
				className="object-cover w-full h-full rounded-md"
			/>
		</View>
	))}
</View>
```

### Typography Showcase

```tsx
<View className="p-4">
	<Text className="text-3xl font-bold text-gray-800 mb-2">Heading</Text>
	<Text className="text-lg font-medium text-gray-600 mb-4">
		Subheading
	</Text>
	<Text className="text-base text-gray-500 leading-relaxed">
		Body text with proper line height and spacing.
	</Text>
</View>
```

## 🔗 Integration

### With @novakit-app/theme

```tsx
import { ThemeProvider } from "@novakit-app/theme";

<ThemeProvider>
  <App />
</ThemeProvider>

// Automatically adapts to light/dark mode
<View className="bg-primary text-white">
  <Text>This adapts to your theme!</Text>
</View>
```

### With Expo

```js
// babel.config.js
module.exports = function (api) {
	api.cache(true);
	return {
		presets: ["babel-preset-expo"],
		overrides: [
			{
				test: ["./app", "./components", "./hooks"],
				plugins: [
					[
						require.resolve(
							"@novakit-app/foundation/babel-plugin"
						),
						{},
					],
				],
			},
		],
	};
};
```

## 📖 Learn More

- **[Complete Documentation](./docs/)** - Detailed guides for every feature
- **[Examples](./examples/)** - Real-world usage examples
- **[API Reference](./docs/API.md)** - Complete API documentation
- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and solutions

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md)
for details.

## 📄 License

MIT License - see [LICENSE](./LICENSE) for details.

---

**Ready to build beautiful React Native apps with familiar styling?** Start with
our [Quick Start Guide](./docs/INSTALLATION.md)!