### Start Example App Packager

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/CONTRIBUTING.md

Starts the Metro bundler for the example application, allowing for live updates during development.

```sh
yarn example start
```

--------------------------------

### Run Example App on Web

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/CONTRIBUTING.md

Builds and runs the example application in a web browser.

```sh
yarn example web
```

--------------------------------

### Running the Materio UI Demo App

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/README.md

Provides instructions on how to clone the repository, install dependencies, and start the demo application to explore Materio UI components.

```sh
# Clone the repo
git clone https://github.com/Lalitj03/rn-materio-ui.git

# Install dependencies
cd rn-materio-ui
yarn install

# Start the demo app
yarn example start
```

--------------------------------

### Run Example App on iOS

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/CONTRIBUTING.md

Builds and runs the example application on an iOS simulator or device.

```sh
yarn example ios
```

--------------------------------

### Run Example App on Android

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/CONTRIBUTING.md

Builds and runs the example application on an Android emulator or device.

```sh
yarn example android
```

--------------------------------

### Button Component Examples

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Illustrates various ways to use the Button component, showcasing different variants, color combinations, and the integration of start and end icons.

```jsx
import { Button } from '@materio/rn-materio-ui';
import { Feather } from '@expo/vector-icons';

// Basic Button
<Button color="primary">Primary Button</Button>

// Variants
<Button variant="soft" color="secondary">Soft Button</Button>
<Button variant="outline" color="success">Outline Button</Button>
<Button variant="ghost" color="danger">Ghost Button</Button>

// With Icons
<Button
  color="primary"
  startIcon={<Feather name="mail" />}
  endIcon={<Feather name="arrow-right" />}
>
  Send Email
</Button>

// Disabled state
<Button disabled>Disabled Button</Button>

// Full width
<Button fullwidth>Full Width Button</Button>
```

--------------------------------

### Installation Instructions

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/README.md

Provides commands for installing the Materio UI library using different package managers like npm, yarn, and pnpm.

```sh
# Using npm
npm install @materio/rn-materio-ui

# Using yarn
yarn add @materio/rn-materio-ui

# Using pnpm
pnpm add @materio/rn-materio-ui
```

--------------------------------

### Install Materio UI Package

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Instructions for installing the Materio UI package using npm, yarn, or pnpm.

```bash
# Using npm
npm install @materio/rn-materio-ui

# Using yarn
yarn add @materio/rn-materio-ui

# Using pnpm
pnpm add @materio/rn-materio-ui
```

--------------------------------

### Basic Materio UI RN Setup with ThemeProvider

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Illustrates the fundamental setup of a React Native application using Materio UI RN. It shows how to wrap the application with `ThemeProvider` and `SafeAreaProvider`, and render basic components like `Typography` and `Button` with theme-applied styles.

```jsx
import React from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import {
  ThemeProvider,
  Button,
  Typography,
  theme, // Default theme
} from '@materio/rn-materio-ui';

export default function App() {
  return (
    <SafeAreaProvider>
      <ThemeProvider colorScheme="light" theme={theme}>
        <Typography variant="title" size="large" color="primary">
          Hello World
        </Typography>
        <Button color="primary">Click Me</Button>
      </ThemeProvider>
    </SafeAreaProvider>
  );
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/CONTRIBUTING.md

Installs all project dependencies using Yarn workspaces. This command must be run in the root directory.

```sh
yarn
```

--------------------------------

### IconButton Component Example

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Provides a practical example of using the IconButton component with an icon and an onPress handler.

```jsx
import { IconButton } from '@materio/rn-materio-ui';
import { Feather } from '@expo/vector-icons';

<IconButton color="primary" onPress={() => console.log('Pressed')}>
  <Feather name="heart" size={24} />
</IconButton>;
```

--------------------------------

### Basic App Setup with ThemeProvider

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/README.md

Demonstrates how to wrap a React Native application with `ThemeProvider` and use basic components like `Typography` and `Button`.

```jsx
import React from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { ThemeProvider, Button, Typography } from '@materio/rn-materio-ui';

export default function App() {
  return (
    <SafeAreaProvider>
      <ThemeProvider colorScheme="light">
        <Typography variant="title" size="large" color="primary">
          Hello World
        </Typography>
        <Button color="primary">Click Me</Button>
      </ThemeProvider>
    </SafeAreaProvider>
  );
}
```

--------------------------------

### Install Required Dependencies

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Lists the peer dependencies required for Materio UI to function correctly.

```bash
yarn add react-native-gesture-handler react-native-reanimated react-native-safe-area-context
```

--------------------------------

### Font Setup

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Instructions for setting up the Noto Sans font family for optimal UI rendering.

```bash
# Create a fonts directory if it doesn't exist
mkdir -p assets/fonts

# Download Noto Sans fonts
# Place the following files in your assets/fonts directory:
# - NotoSans-Light.ttf
# - NotoSans-Regular.ttf
# - NotoSans-Medium.ttf
# - NotoSans-SemiBold.ttf
```

--------------------------------

### Partial Theme Extension Examples

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Demonstrates how to extend specific parts of the Materio UI theme, such as component default props, sizes, spacing, and color schemes for light mode.

```jsx
import { extendTheme } from '@materio/rn-materio-ui';

// Only customize component defaults
const buttonFocusedTheme = extendTheme({
  components: {
    Button: {
      defaultProps: {
        variant: 'outline',
        color: 'primary',
      },
      sizes: {
        md: {
          fontSize: 18,
          padding: { horizontal: 'xl', vertical: 'md' },
        },
      },
    },
  },
});

// Only customize spacing
const tightSpacingTheme = extendTheme({
  spacing: {
    xs: 2,
    sm: 4,
    md: 8,
    lg: 12,
    xl: 16,
  },
});

// Only customize colors for light mode
const lightOnlyTheme = extendTheme({
  colorScheme: {
    light: {
      surface: {
        background: '#f8fafc',
        paper: '#ffffff',
      },
    },
  },
});
```

--------------------------------

### Dynamic Theme Switching Example

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Demonstrates how to implement dynamic theme switching and color mode toggling using the ThemeProvider component. It shows importing custom themes and managing the current theme and color mode state.

```jsx
import React, { useState } from 'react';
import { ThemeProvider, Button, Menu, MenuItem } from '@materio/rn-materio-ui';
// Import your custom themes (these would be themes you've created)
import defaultTheme from './themes/default';
import frozenTheme from './themes/frozen';
import starwarsTheme from './themes/starwars';

const themes = {
  default: defaultTheme,
  frozen: frozenTheme,
  starwars: starwarsTheme,
};

export default function App() {
  const [currentTheme, setCurrentTheme] = useState('default');
  const [colorMode, setColorMode] = useState('light');

  return (
    <ThemeProvider theme={themes[currentTheme]} colorScheme={colorMode}>
      <Button onPress={() => setCurrentTheme('frozen')}>
        Switch to Frozen Theme
      </Button>
      <Button
        onPress={() => setColorMode(colorMode === 'light' ? 'dark' : 'light')}
      >
        Toggle {colorMode === 'light' ? 'Dark' : 'Light'} Mode
      </Button>
      {/* Your app content */}
    </ThemeProvider>
  );
}
```

--------------------------------

### Card Component Examples

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/README.md

Demonstrates how to use the `Card` and `ColoredCard` components for content presentation, including basic and colored variants.

```jsx
import { Card, ColoredCard, Typography } from '@materio/rn-materio-ui';

// Basic Card
<Card>
  <Typography variant="title" size="medium">Card Title</Typography>
  <Typography variant="body">Card content goes here</Typography>
</Card>

// Card with color
<ColoredCard color="primary" colorTone="low">
  <Typography>Colored Card Content</Typography>
</ColoredCard>
```

--------------------------------

### Spacing and Layout Example

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Shows how to apply theme-defined spacing, border radius, and border widths using the useTheme hook. Utilizes padding, margin, borderRadius, and borderWidth properties.

```jsx
import { useTheme, View } from '@materio/rn-materio-ui';

function SpacingExample() {
  const theme = useTheme();

  return (
    <View
      style={{
        padding: theme.spacing.md,
        margin: theme.spacing.lg,
        borderRadius: theme.borderRadius.md,
        borderWidth: theme.borderWidths.thin,
        borderColor: '#e5e5e5',
      }}
    >
      {/* Content */}
    </View>
  );
}
```

--------------------------------

### Typography Component Examples

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/README.md

Illustrates the usage of the `Typography` component with different variants, sizes, and color options.

```jsx
import { Typography } from '@materio/rn-materio-ui';

// Variants
<Typography variant="display">Display Text</Typography>
<Typography variant="headline">Headline Text</Typography>
<Typography variant="title">Title Text</Typography>
<Typography variant="body">Body Text</Typography>
<Typography variant="label">Label Text</Typography>
<Typography variant="caption">Caption Text</Typography>

// Sizes
<Typography variant="body" size="large">Large Body</Typography>
<Typography variant="body" size="medium">Medium Body</Typography>
<Typography variant="body" size="small">Small Body</Typography>

// Colors
<Typography color="primary">Primary Text</Typography>
<Typography color="secondary">Secondary Text</Typography>
<Typography usageType="link">Link Text</Typography>
```

--------------------------------

### Theme-level Configuration Example

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/THEME_ARCHITECTURE.md

Demonstrates how to configure components at the theme level, including default properties and custom variants. This allows for centralized styling and a clear override hierarchy.

```typescript
const theme = {
  components: {
    Button: {
      defaultProps: { variant: 'soft', size: 'lg' },
      variants: {
        gradient: (theme, color) => ({
          /* custom styles */
        }),
      },
    },
  },
};
```

--------------------------------

### Button Component Examples

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/README.md

Showcases various ways to use the `Button` and `IconButton` components, including different variants, colors, and icon placements.

```jsx
import { Button, IconButton } from '@materio/rn-materio-ui';
import { Feather } from '@expo/vector-icons';

// Basic Button
<Button color="primary">Primary Button</Button>

// Variants
<Button variant="soft" color="secondary">Soft Button</Button>
<Button variant="outline" color="success">Outline Button</Button>
<Button variant="ghost" color="danger">Ghost Button</Button>

// With Icons
<Button
  color="primary"
  startIcon={<Feather name="mail" />}
  endIcon={<Feather name="arrow-right" />}
>
  Send Email
</Button>

// Icon Button
<IconButton color="primary">
  <Feather name="heart" />
</IconButton>
```

--------------------------------

### Jotai for Theme State Management

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Example of using Jotai with AsyncStorage to manage theme preferences (mode and selected theme) persistently.

```javascript
// atoms.ts
import AsyncStorage from '@react-native-async-storage/async-storage';
import { atomWithStorage } from 'jotai/utils';

export const themeModeAtom = atomWithStorage(
  'themeMode',
  'system' as 'system' | 'light' | 'dark',
  {
    getItem: async (key) => {
      const value = await AsyncStorage.getItem(key);
      return (value as 'system' | 'light' | 'dark') || 'system';
    },
    setItem: (key, value) => AsyncStorage.setItem(key, value),
    removeItem: (key) => AsyncStorage.removeItem(key),
  }
);

export const selectedThemeAtom = atomWithStorage(
  'selectedTheme',
  'default' as 'default' | 'frozen' | 'starwars' | 'oceanic' | 'zenith',
  {
    getItem: async (key) => {
      const value = await AsyncStorage.getItem(key);
      return value || 'default';
    },
    setItem: (key, value) => AsyncStorage.setItem(key, value),
    removeItem: (key) => AsyncStorage.removeItem(key),
  }
);
```

```javascript
// App.tsx
import React, { useMemo } from 'react';
import { useColorScheme } from 'react-native';
import { useAtomValue } from 'jotai';
import { ThemeProvider } from '@materio/rn-materio-ui';
import { themeModeAtom, selectedThemeAtom } from './atoms';
import { themes } from './themes';

export default function App() {
  const selectedTheme = useAtomValue(selectedThemeAtom);
  const themeMode = useAtomValue(themeModeAtom);
  const systemColorScheme = useColorScheme();

  const currentTheme = useMemo(() => {
    return themes[selectedTheme];
  }, [selectedTheme]);

  const colorMode = useMemo(() => {
    return themeMode === 'system' ? systemColorScheme || 'light' : themeMode;
  }, [themeMode, systemColorScheme]);

  return (
    <ThemeProvider colorScheme={colorMode} theme={currentTheme}> 
      {/* Your app */}
    </ThemeProvider>
  );
}
```

--------------------------------

### Creating a Custom 'Frozen' Theme

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Provides an example of creating a completely custom theme from scratch, inspired by winter aesthetics. It includes detailed configurations for color schemes (light and dark modes), typography, spacing, and border-radius.

```jsx
import { ThemeProvider, twcolors } from '@materio/rn-materio-ui';

// Example: Creating a custom "Frozen" theme
const frozenTheme = {
  colorScheme: {
    light: {
      palette: {
        primary: {
          base: { main: twcolors.blue[600], contrast: '#ffffff' },
          high: { main: twcolors.blue[800], contrast: twcolors.blue[50] },
          low: { main: twcolors.blue[100], contrast: twcolors.blue[900] },
        },
        secondary: {
          base: { main: twcolors.purple[500], contrast: '#ffffff' },
          high: { main: twcolors.purple[700], contrast: twcolors.purple[50] },
          low: { main: twcolors.purple[300], contrast: twcolors.purple[900] },
        },
        // ... other colors customized for frozen theme
      },
      surface: {
        background: twcolors.slate[50],
        paper: '#ffffff',
        divider: twcolors.slate[300],
        overlay: 'rgba(255, 255, 255, 0.9)',
        input: twcolors.slate[100],
      },
      typography: {
        primary: twcolors.slate[900],
        secondary: twcolors.slate[700],
        disabled: twcolors.slate[400],
        hint: twcolors.slate[500],
        link: twcolors.blue[600],
        error: twcolors.rose[600],
      },
    },
    dark: {
      // Dark mode variants of the frozen theme
      palette: {
        primary: {
          base: { main: twcolors.cyan[400], contrast: twcolors.slate[900] },
          high: { main: twcolors.cyan[100], contrast: twcolors.cyan[900] },
          low: { main: twcolors.cyan[600], contrast: '#ffffff' },
        },
        // ... other dark mode colors
      },
      surface: {
        background: twcolors.slate[900],
        paper: twcolors.slate[800],
        divider: twcolors.slate[600],
        overlay: 'rgba(148, 163, 184, 0.1)',
        input: twcolors.slate[700],
      },
      typography: {
        primary: twcolors.slate[50],
        secondary: twcolors.slate[200],
        disabled: twcolors.slate[500],
        hint: twcolors.slate[400],
        link: twcolors.cyan[300],
        error: twcolors.red[400],
      },
    },
  },
  typography: {
    tokens: {
      // Typography configuration with refined spacing for winter theme
      display: {
        large: {
          fontFamily: 'NotoSansLight',
          fontWeight: 'light',
          fontSize: 57,
          tracking: -0.25,
          lineHeight: 64,
        },
        // ... other typography tokens
      },
    },
    weightMap: {
      light: { fontFamily: 'NotoSansLight', fontWeight: '300' },
      regular: { fontFamily: 'NotoSansRegular', fontWeight: '400' },
      medium: { fontFamily: 'NotoSansMedium', fontWeight: '500' },
      semibold: { fontFamily: 'NotoSansSemiBold', fontWeight: '600' },
      bold: { fontFamily: 'NotoSansBold', fontWeight: '700' },
    },
  },
  spacing: {
    none: 0,
    xs: 2, // Tighter spacing for frozen precision
    sm: 6, // Slightly smaller than default
    md: 10, // More refined intervals
    lg: 14, // Crisp, clean spacing
    xl: 20, // Elegant larger spacing
    2xl: 28, // Sophisticated extra large
    3xl: 36, // Premium maximum spacing
  },
  borderRadius: {
    none: 0,
    xs: 2, // Subtle crystalline edges
    sm: 6, // Soft ice corners
    md: 10, // Balanced frozen curves
    lg: 14, // Elegant ice formation
    xl: 20, // Smooth glacier edges
    2xl: 28, // Flowing ice shapes
    3xl: 36, // Organic winter forms
  },
};

```

--------------------------------

### Theme Customization: Combining createPalette and extendTheme

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Shows how to effectively combine `createPalette` and `extendTheme` to build complex themes. This example demonstrates creating a brand-specific color palette and then integrating it into the theme along with custom spacing and component styles.

```jsx
// ✅ Good: Use both utilities together
const brandPalette = createPalette({
  primary: 'indigo',
  secondary: 'pink',
});

const brandTheme = extendTheme({
  colorScheme: {
    light: { palette: brandPalette.light },
    dark: { palette: brandPalette.dark },
  },
  spacing: { xs: 3, sm: 6, md: 12 },
  components: {
    Button: {
      baseStyle: { borderRadius: 'xl' },
    },
  },
});
```

--------------------------------

### Dependency Installation

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/README.md

Lists the peer dependencies required for Materio UI, including gesture handler, reanimated, and safe area context.

```sh
yarn add react-native-gesture-handler react-native-reanimated react-native-safe-area-context
```

--------------------------------

### Theme Customization Example

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/THEME_ARCHITECTURE.md

Demonstrates how to extend the Materio UI theme to customize components like the Button. This includes setting default props, defining new variants, and overriding existing sizes.

```typescript
const customTheme = extendTheme({
  components: {
    Button: {
      defaultProps: {
        variant: 'soft', // All buttons are soft by default
        size: 'lg', // All buttons are large by default
      },
      variants: {
        // Add custom variant
        gradient: (theme, colorScheme) => ({
          backgroundColor: 'linear-gradient(...)',
          textColor: 'white',
        }),
      },
      sizes: {
        // Override existing size
        md: {
          fontSize: 18, // Larger than default
          minHeight: 44,
        },
      },
    },
  },
});
```

--------------------------------

### Component Usage Example

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/THEME_ARCHITECTURE.md

Illustrates how to use the Button component with default theme props and how to override them for specific instances. It also shows the usage of a custom variant defined in the theme.

```tsx
// Simple usage with theme defaults
<Button>Click me</Button>

// Override props when needed
<Button variant="outline" size="sm" color="primary">
  Small outline button
</Button>

// Custom variant from theme
<Button variant="gradient">
  Gradient button
</Button>
```

--------------------------------

### Using Tailwind CSS Colors

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Demonstrates how to import and utilize Tailwind CSS color scales provided by the library for custom styling. Includes examples of common color scales.

```jsx
import { twcolors } from '@materio/rn-materio-ui';

// Use Tailwind colors anywhere in your app
const customStyle = {
  backgroundColor: twcolors.blue[500],
  borderColor: twcolors.slate[300],
  color: twcolors.gray[900],
};

// Available color scales include:
// slate, gray, zinc, neutral, stone, red, orange, amber, yellow,
// lime, green, emerald, teal, cyan, sky, blue, indigo, violet,
// purple, fuchsia, pink, rose
```

--------------------------------

### Materio UI RN Chip Component Documentation

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

This section details the props available for the Chip component, including children, color, variant, size, rounded, startIcon, endIcon, and onPress. It also provides comprehensive examples of how to use the Chip with different configurations.

```APIDOC
Chip Component Documentation:

Description:
  Compact elements that represent inputs, attributes, or actions.

Props:
  children (string): **Required** Text content of the chip.
  color (ButtonColors): Chip color. Defaults to 'neutral'.
  variant (ButtonVariants): Chip style variant. Defaults to 'soft'.
  size (ButtonSizes): Chip size. Defaults to 'md'.
  rounded ('none' | 'full'): Border radius of the chip.
  startIcon (React.ReactElement): Icon to display at the start of the chip.
  endIcon (React.ReactElement): Icon to display at the end of the chip.
  onPress (function): Function called when the chip is pressed.

Examples:
  // Basic Chip
  <Chip>Basic Chip</Chip>

  // Different variants
  <View>
    <Chip variant="solid" color="primary">Solid</Chip>
    <Chip variant="soft" color="secondary">Soft</Chip>
    <Chip variant="outline" color="success">Outline</Chip>
    <Chip variant="ghost" color="warning">Ghost</Chip>
  </View>

  // Different sizes
  <View>
    <Chip size="xs">Extra Small</Chip>
    <Chip size="sm">Small</Chip>
    <Chip size="md">Medium</Chip>
    <Chip size="lg">Large</Chip>
    <Chip size="xl">Extra Large</Chip>
  </View>

  // Different colors
  <View>
    <Chip color="primary">Primary</Chip>
    <Chip color="secondary">Secondary</Chip>
    <Chip color="success">Success</Chip>
    <Chip color="warning">Warning</Chip>
    <Chip color="danger">Danger</Chip>
    <Chip color="info">Info</Chip>
    <Chip color="neutral">Neutral</Chip>
  </View>

  // With icons
  <View>
    <Chip startIcon={<Feather name="check" size={16} />} color="success">
      Selected
    </Chip>

    <Chip endIcon={<Feather name="info" size={16} />} color="info">
      Information
    </Chip>

    <Chip
      startIcon={<Feather name="user" size={16} />}
      endIcon={<Feather name="x" size={16} />}
      color="primary"
    >
      User
    </Chip>
  </View>

  // Rounded chips
  <View>
    <Chip rounded="none">Square Chip</Chip>
    <Chip rounded="full">Fully Rounded</Chip>
  </View>

  // Interactive
  <Chip onPress={() => console.log('Chip pressed')}>Pressable Chip</Chip>
```

--------------------------------

### Enhanced Theme Integration Usage

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Provides examples of how components like Button, Card, and Paper utilize the theme system for spacing, border radius, and border widths. It shows how to apply theme values directly to component props.

```jsx
import { Button, Card, Paper } from '@materio/rn-materio-ui';

// All these components now use theme values
<Button size="lg">
  Uses theme.spacing.xl for padding and theme.borderRadius.lg for corners
</Button>

<Card rounded="md" variant="outline">
  Uses theme.borderRadius.md and theme.borderWidths.medium
</Card>

<Paper rounded="lg" variant="outline">
  Supports both theme keys and custom values
</Paper>
```

--------------------------------

### Materio UI RN Theme Switching (Light/Dark and Custom)

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Provides an example of implementing theme switching in a React Native application using Materio UI RN. It demonstrates toggling between light and dark color schemes and switching between predefined and custom theme configurations.

```javascript
import React, { useState } from 'react';
import { View, Switch } from 'react-native';
import {
  ThemeProvider,
  Button,
  Typography,
  theme as defaultTheme, // Default theme
  twcolors,
} from '@materio/rn-materio-ui';

// Example of creating custom themes (you can import pre-made ones too)
const customTheme = {
  colorScheme: {
    light: {
      palette: {
        primary: { 
          base: { main: twcolors.purple[600], contrast: twcolors.white },
          high: { main: twcolors.purple[800], contrast: twcolors.purple[50] },
          low: { main: twcolors.purple[100], contrast: twcolors.purple[900] },
        },
        // ... other colors
      },
      surface: { main: twcolors.white, contrast: twcolors.black },
      typography: {
        primary: twcolors.black,
        secondary: twcolors.gray[600],
        disabled: twcolors.gray[400],
      },
    },
    dark: {
      palette: {
        primary: {
          base: { main: twcolors.purple[400], contrast: twcolors.black },
          high: { main: twcolors.purple[200], contrast: twcolors.purple[900] },
          low: { main: twcolors.purple[800], contrast: twcolors.purple[100] },
        },
        // ... other colors
      },
      surface: { main: twcolors.gray[900], contrast: twcolors.white },
      typography: {
        primary: twcolors.white,
        secondary: twcolors.gray[300],
        disabled: twcolors.gray[500],
      },
    },
  },
  typography: {
    /* typography config */
  },
  spacing: {
    /* spacing config */
  },
  borderRadius: {
    /* border radius config */
  },
  // ... other theme properties
};

export default function App() {
  const [isDarkMode, setIsDarkMode] = useState(false);
  const [selectedTheme, setSelectedTheme] = useState('default');

  const themes = {
    default: defaultTheme,
    custom: customTheme,
  };

  return (
    <ThemeProvider
      colorScheme={isDarkMode ? 'dark' : 'light'}
      theme={themes[selectedTheme]}
    >
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <Typography variant="body" size="medium">
          {isDarkMode ? 'Dark Mode' : 'Light Mode'}
        </Typography>

        <Switch
          value={isDarkMode}
          onValueChange={() => setIsDarkMode((prev) => !prev)}
        />

        <Button color="primary" onPress={() => setIsDarkMode((prev) => !prev)}>
          Toggle Theme Mode
        </Button>

        <Button
          color="secondary"
          onPress={() =>
            setSelectedTheme(selectedTheme === 'default' ? 'custom' : 'default')
          }
        >
          Switch Theme Style
        </Button>
      </View>
    </ThemeProvider>
  );
}
```

--------------------------------

### Theme Customization: Consistent Color Usage

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Highlights the importance of using theme-defined color names for consistent and adaptable styling. The example shows how to reference theme colors within component variants, contrasting it with the pitfalls of using hardcoded color values.

```jsx
// ✅ Good: Use theme color names consistently
const theme = extendTheme({
  components: {
    Button: {
      variants: {
        solid: (theme, color) => ({
          backgroundColor: `${color}.high.main`,
          textColor: `${color}.high.contrast`,
        }),
      },
    },
  },
});

// ❌ Avoid: Hardcoded colors in component styles
const badTheme = extendTheme({
  components: {
    Button: {
      variants: {
        solid: () => ({
          backgroundColor: '#3b82f6', // Hardcoded, won't adapt
          textColor: '#ffffff',
        }),
      },
    },
  },
});
```

--------------------------------

### Responsive Design: Adapting Layouts with Dimensions API

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Explains how to create responsive layouts in React Native using Materio UI components. This example utilizes the `Dimensions` API to detect screen width and conditionally apply different padding and text sizes based on whether the screen is small.

```jsx
import { Dimensions } from 'react-native';
import { Card, Typography, useTheme } from '@materio/rn-materio-ui';

function ResponsiveComponent() {
  const theme = useTheme();
  const { width } = Dimensions.get('window');

  // Calculate responsive values
  const isSmallScreen = width < 375;
  const cardPadding = isSmallScreen ? theme.spacing.sm : theme.spacing.lg;
  const titleSize = isSmallScreen ? 'small' : 'large';

  return (
    <Card style={{ padding: cardPadding }}>
      <Typography variant="title" size={titleSize}>
        Responsive Title
      </Typography>
    </Card>
  );
}
```

--------------------------------

### Quick Theme Customization

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Shows how to quickly customize themes in Materio UI using `createPalette` and `extendTheme` utilities for defining color schemes and spacing.

```javascript
import {
  createPalette,
  extendTheme,
  ThemeProvider,
} from '@materio/rn-materio-ui';

// Step 1: Create a custom color palette
const customPalette = createPalette({
  primary: 'violet', // Uses violet-500 as base
  secondary: 'pink', // Uses pink-500 as base
  success: 'emerald', // Uses emerald-500 as base
  warning: 'amber',
  danger: 'red',
  info: 'sky',
});

// Step 2: Extend the default theme with your palette and other customizations
const myTheme = extendTheme({
  colorScheme: {
    light: {
      palette: customPalette.light,
    },
    dark: {
      palette: customPalette.dark,
    },
  },
  // Customize other aspects
  spacing: {
    xs: 3,
    sm: 6,
    md: 12,
    lg: 18,
  },
  borderRadius: {
    xs: 2,
    sm: 6,
    md: 10,
    lg: 16,
  },
});

// Step 3: Use your custom theme
export default function App() {
  return (
    <ThemeProvider theme={myTheme} colorScheme="light">
      {/* Your app */}
    </ThemeProvider>
  );
}
```

--------------------------------

### Color Resolution Strategies

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/THEME_ARCHITECTURE.md

Illustrates two approaches for color resolution: a static, compile-time validated path and a dynamic, function-based method for runtime customization, both ensuring type safety.

```typescript
// Static approach - compile-time validated
backgroundColor: 'primary.base.main';

// Dynamic approach - runtime flexibility
backgroundColor: (theme, colorScheme) =>
  theme.colorScheme[colorScheme].palette[color].base.main;
```

--------------------------------

### Development Tools

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/CONTRIBUTING.md

Lists the primary tools used for development, including linting, formatting, type checking, and testing.

```APIDOC
Development Tools:

- TypeScript: For type checking.
- ESLint: For linting code style and potential errors.
- Prettier: For code formatting.
- Jest: For running unit tests.
```

--------------------------------

### Theme Customization: createPalette for Color Schemes

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Demonstrates the recommended approach of using `createPalette` for generating consistent color schemes, including automatic contrast ratio and tone generation. It contrasts this with the less efficient method of manually defining every color variant.

```jsx
// ✅ Good: Use createPalette for consistent color generation
const palette = createPalette({
  primary: 'blue',
  secondary: 'purple',
  // This automatically generates proper contrast ratios and tones
});

// ❌ Avoid: Manually defining every color variant
const manualColors = {
  primary: {
    base: { main: '#3b82f6', contrast: '#ffffff' },
    high: { main: '#1d4ed8', contrast: '#dbeafe' },
    low: { main: '#dbeafe', contrast: '#1e3a8a' },
    // Lots of manual work and potential inconsistencies
  },
};
```

--------------------------------

### Materio UI API Reference

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Provides an overview of the available API functions and utilities within the Materio UI library, including theme customization functions.

```APIDOC
Materio UI Utilities:

createPalette(paletteOptions: object): object
  - Creates a color palette object.
  - Parameters:
    - paletteOptions: An object containing color definitions.
  - Returns: A formatted palette object.

extendTheme(theme: object, overrides: object): object
  - Extends an existing theme with new or modified properties.
  - Parameters:
    - theme: The base theme object.
    - overrides: An object containing properties to override or add.
  - Returns: The extended theme object.

invertTone(color: string): string
  - Inverts the tone of a given color string.
  - Parameters:
    - color: The color string to invert.
  - Returns: The inverted color string.

Theme System:
  - Provides a comprehensive system for customizing the UI's appearance.
  - Includes color system, typography, and spacing.

Available Exports:
  - Access to all components and utility functions.

Tailwind Colors:
  - Built-in support for Tailwind CSS color names for easy integration.

TypeScript Support:
  - Full TypeScript definitions for enhanced developer experience and type safety.
```

--------------------------------

### Publish to npm

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/CONTRIBUTING.md

Publishes a new version of the library to npm using release-it. This command handles version bumping, tagging, and release creation.

```sh
yarn release
```

--------------------------------

### Backdrop Component Usage

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Demonstrates how to use the Backdrop component for overlaying content, including its props for press handling, color, and animation.

```jsx
import {
  Backdrop,
  Button,
  View,
  Typography,
} from '@materio/rn-materio-ui';

function BackdropExample() {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button onPress={() => setVisible(true)}>Show Backdrop</Button>

      {visible && (
        <Backdrop onPress={() => setVisible(false)}>
          <View
            style={{
              position: 'absolute',
              top: '50%',
              left: '50%',
              marginTop: -100,
              marginLeft: -150,
              width: 300,
              padding: 20,
              borderRadius: 10,
              backgroundColor: 'white',
              alignItems: 'center',
            }}
          >
            <Typography variant="title" size="medium" gutterBottom>
              Modal Content
            </Typography>
            <Typography variant="body" gutterBottom>
              This is displayed over a backdrop
            </Typography>
            <Button onPress={() => setVisible(false)}>Close</Button>
          </View>
        </Backdrop>
      )}
    </>
  );
}
```

--------------------------------

### ColoredCard Component Documentation

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

This section details the ColoredCard component, its available props, and usage examples. The component allows for customization of background color, color tone, variant, border radius, padding, and pressability. It is designed to integrate seamlessly with the Materio UI theme.

```APIDOC
ColoredCard:
  Props:
    color: ThemeColors | 'neutral' (default)
      Description: Card background color. Accepts predefined theme colors.
    colorTone: ThemeColorTones | 'low' (default)
      Description: Color tone for the background. Options include 'low', 'base', 'high'.
    variant: PaperVariants | 'solid' (default)
      Description: Card variant style. Options include 'solid' and 'outline'.
    rounded: keyof Theme['borderRadius'] | number | 'md' (default)
      Description: Border radius of the card. Can be a theme key or a number.
    padding: keyof Theme['spacing'] | number | 'sm' (default)
      Description: Internal padding for the card. Can be a theme key or a number.
    pressable: boolean | false (default)
      Description: Whether the card is pressable.
    enabled: boolean | true (default)
      Description: Whether the card is enabled.
    onPress?: () => void
      Description: Callback function when the card is pressed (only if pressable is true).

  Examples:
    // Basic ColoredCard
    <ColoredCard color="primary" colorTone="low">
      <Typography>Colored Card Content</Typography>
    </ColoredCard>

    // Different color tones
    <View>
      <ColoredCard color="primary" colorTone="low" padding="md">
        <Typography>Primary Low Tone</Typography>
      </ColoredCard>
      <ColoredCard color="primary" colorTone="base" padding="md">
        <Typography>Primary Base Tone</Typography>
      </ColoredCard>
      <ColoredCard color="primary" colorTone="high" padding="md">
        <Typography>Primary High Tone</Typography>
      </ColoredCard>
    </View>

    // Different colors
    <View>
      <ColoredCard color="secondary" colorTone="low" padding="md">
        <Typography>Secondary Color</Typography>
      </ColoredCard>
      <ColoredCard color="success" colorTone="low" padding="md">
        <Typography>Success Color</Typography>
      </ColoredCard>
      <ColoredCard color="warning" colorTone="low" padding="md">
        <Typography>Warning Color</Typography>
      </ColoredCard>
    </View>

    // Outlined variant
    <ColoredCard
      color="secondary"
      colorTone="base"
      variant="outline"
      padding="lg"
    >
      <Typography>Outlined Colored Card</Typography>
    </ColoredCard>

    // Custom rounded corners
    <ColoredCard
      color="info"
      colorTone="low"
      rounded="xl"
      padding="md"
    >
      <Typography>Extra Large Rounded</Typography>
    </ColoredCard>

    // Pressable ColoredCard
    <ColoredCard
      color="success"
      colorTone="low"
      pressable
      onPress={() => console.log('Card pressed')}
      padding="md"
    >
      <Typography>Pressable Colored Card</Typography>
    </ColoredCard>

    // Disabled card
    <ColoredCard
      color="primary"
      colorTone="base"
      enabled={false}
      padding="md"
    >
      <Typography>Disabled Card</Typography>
    </ColoredCard>
```

--------------------------------

### Component Configuration Pattern Interface

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/THEME_ARCHITECTURE.md

Illustrates the pattern for configuring individual components. It specifies default properties, base styles, and styles for different sizes and variants.

```typescript
interface ComponentConfig<TVariants, TSizes> {
  // Default variant and size
  defaultProps?: {
    variant?: TVariants;
    size?: TSizes;
    color?: ButtonColors;
  };

  // Base styles (applied to all variants)
  baseStyle?: ComponentStyle;

  // Size-specific styles
  sizes?: Record<TSizes, ComponentStyle>;

  // Variant-specific styles
  variants?: Record<TVariants, ComponentStyle | VariantFunction>;
}
```

--------------------------------

### Run Unit Tests

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/CONTRIBUTING.md

Executes the unit tests using Jest.

```sh
yarn test
```

--------------------------------

### Theme Performance Optimization

Source: https://github.com/lalitj03/rn-materio-ui/blob/main/docs/DOCUMENTATION.md

Provides strategies for optimizing theme performance, including memoizing theme objects and lazy loading themes using dynamic imports.

```javascript
import React, { useMemo } from 'react';

// Lazy load themes
const loadTheme = (themeName) => {
  switch (themeName) {
    case 'frozen':
      return import('./themes/frozen').then((m) => m.default);
    case 'starwars':
      return import('./themes/starwars').then((m) => m.default);
    default:
      return import('./themes/default').then((m) => m.default);
  }
};

// Memoized theme selector
const useSelectedTheme = (themeName) => {
  return useMemo(() => {
    return loadTheme(themeName);
  }, [themeName]);
};
```