Styler Usage Guide

This guide will walk you through setting up Styler in your Mapples project, configuring themes, and using basic styling features.

Setting Up Themes in Mapples Creator

1. Access the Theme Configuration

🎨 Visual Configuration

In Mapples Creator, navigate to the Styler section in your project settings. Here you'll find the theme configuration interface where you can:

• Set up color schemes for light and dark modes
• Configure typography settings
• Define spacing and sizing values
• Set up responsive breakpoints

2. Sync Your Styler Configuration

Use the CLI command to sync your Styler configuration with your project:

npx @mapples/cli style --sync

✅ What This Does

This command will:

• Generate the necessary Styler configuration files
• Set up the theme system in your project
• Create default styling configurations
• Set up responsive breakpoints and typography

Basic Styler.create Usage

Creating Simple Styles

The most basic way to use Styler is with Styler.create():

import { Styler } from '@mapples/style';

const styles = Styler.create({
  container: {
    backgroundColor: 'theme.colors.background',
    padding: 'sizing.md',
    borderRadius: 'sizing.sm',
  },
  text: {
    color: 'theme.colors.text',
    fontSize: 'sizing.md',
  },
});

Using Theme Colors

🎨 Theme Colors

Reference theme colors using dot notation:

const buttonStyles = Styler.create({
  primaryButton: {
    backgroundColor: 'theme.colors.primary',
    color: 'theme.colors.background',
    padding: 'sizing.md',
    borderRadius: 'sizing.sm',
  },
  secondaryButton: {
    backgroundColor: 'theme.colors.surface',
    color: 'theme.colors.primary',
    borderWidth: 1,
    borderColor: 'theme.colors.primary',
    padding: 'sizing.md',
    borderRadius: 'sizing.sm',
  },
});

Using Sizing Values

Reference sizing values from your configuration:

const cardStyles = Styler.create({
  card: {
    padding: 'sizing.lg',
    margin: 'sizing.md',
    borderRadius: 'sizing.sm',
    shadowColor: 'theme.colors.text',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.1,
    shadowRadius: 4,
    elevation: 3,
  },
  content: {
    padding: 'sizing.md',
  },
  title: {
    fontSize: 'sizing.lg',
    fontWeight: 'bold',
    marginBottom: 'sizing.sm',
  },
});

Responsive Styles

📱 Responsive Design

Create responsive styles using breakpoint selectors:

const responsiveStyles = Styler.create({
  container: {
    flexDirection: 'column',
    padding: 'sizing.md',
    '&:tablet': {
      flexDirection: 'row',
      padding: 'sizing.lg',
    },
    '&:desktop': {
      flexDirection: 'row',
      padding: 'sizing.xl',
      maxWidth: 1200,
    },
  },
  item: {
    flex: 1,
    margin: 'sizing.sm',
    '&:mobile': {
      margin: 'sizing.xs',
    },
    '&:tablet': {
      flex: 0.5,
    },
    '&:desktop': {
      flex: 0.33,
    },
  },
});

Using Styled Components

Basic Component Styling

Use styled props to pass styling configuration to your components:

import React from 'react';
import { View, Text } from 'react-native';
import { useStyled } from '@mapples/style';

const MyComponent = ({ styled }) => {
  const processedStyle = useStyled(styled);

  return (
    <View style={processedStyle.container}>
      <Text style={processedStyle.title}>Hello World</Text>
      <Text style={processedStyle.subtitle}>Welcome to Styler</Text>
    </View>
  );
};

// Usage
<MyComponent
  styled={{
    container: {
      backgroundColor: 'theme.colors.surface',
      padding: 'sizing.lg',
      borderRadius: 'sizing.md',
    },
    title: {
      fontSize: 'sizing.xl',
      fontWeight: 'bold',
      color: 'theme.colors.text',
      marginBottom: 'sizing.sm',
    },
    subtitle: {
      fontSize: 'sizing.md',
      color: 'theme.colors.textSecondary',
    },
  }}
/>

Using Hooks for Dynamic Styling

🔧 Dynamic Styling

Use hooks for dynamic styling based on runtime conditions:

import React from 'react';
import { View, Text } from 'react-native';
import { useTheme, useSizing, useResponsive } from '@mapples/style';

const DynamicComponent = () => {
  const { getColor } = useTheme();
  const { getSize } = useSizing();
  const { getResponsiveStyle } = useResponsive();

  return (
    <View
      style={{
        backgroundColor: getColor('theme.colors.background'),
        padding: getSize('md'),
        ...getResponsiveStyle({
          flexDirection: 'column',
          '&:tablet': { flexDirection: 'row' },
        }),
      }}
    >
      <Text style={{ color: getColor('theme.colors.text') }}>
        Dynamic content
      </Text>
    </View>
  );
};

Typography Component

🔤 Typography System

Use the Typography component for consistent text styling:

import React from 'react';
import { Typography } from '@mapples/style';

const TextExample = () => {
  return (
    <View>
      <Typography variant="heading1">Main Title</Typography>
      <Typography variant="heading2">Section Title</Typography>
      <Typography variant="body" color="theme.colors.primary">
        Body text with primary color
      </Typography>
      <Typography variant="caption">
        Small caption text
      </Typography>
    </View>
  );
};

Advanced Usage Patterns

Style Composition

Combine multiple style sources for reusable patterns:

const baseStyles = Styler.create({
  button: {
    padding: 'sizing.md',
    borderRadius: 'sizing.sm',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

const variantStyles = Styler.create({
  primary: {
    backgroundColor: 'theme.colors.primary',
    color: 'theme.colors.background',
  },
  secondary: {
    backgroundColor: 'theme.colors.surface',
    color: 'theme.colors.primary',
    borderWidth: 1,
    borderColor: 'theme.colors.primary',
  },
});

// Combine styles
const combinedStyles = Styler.create({
  primaryButton: {
    ...baseStyles.button,
    ...variantStyles.primary,
  },
  secondaryButton: {
    ...baseStyles.button,
    ...variantStyles.secondary,
  },
});

Conditional Styling

🎯 Conditional Styles

Apply styles based on component state or props:

const conditionalStyles = Styler.create({
  container: {
    backgroundColor: 'theme.colors.surface',
    padding: 'sizing.md',
    // Conditional styles based on props
    '&:hover': {
      backgroundColor: 'theme.colors.primary',
      color: 'theme.colors.background',
    },
    '&:active': {
      transform: [{ scale: 0.95 }],
    },
  },
});

Style Arrays and Flattening

Combine multiple style objects into arrays and flatten them:

const styleArray = [
  baseStyles.container,
  variantStyles.primary,
  conditionalStyles.hover,
];

// Flatten style arrays
const flattenedStyle = Styler.flatten(styleArray);

Best Practices

✅ Use Theme References

Always reference theme values instead of hardcoded values:

// ✅ Good
backgroundColor: 'theme.colors.primary'

// ❌ Avoid
backgroundColor: '#007AFF'

Use the sizing system for consistent spacing:

// ✅ Good
padding: 'sizing.md'
margin: 'sizing.lg'

// ❌ Avoid
padding: 16
margin: 24

📱 Plan for Responsiveness

Always consider different screen sizes:

const responsiveStyles = Styler.create({
  container: {
    padding: 'sizing.md',
    '&:tablet': { padding: 'sizing.lg' },
    '&:desktop': { padding: 'sizing.xl' },
  },
});

🔧 Use TypeScript

Take advantage of TypeScript for better development experience:

interface ButtonProps {
  variant: 'primary' | 'secondary';
  size: 'sm' | 'md' | 'lg';
  styled?: StyledProps<ButtonProps>;
}

What's Next?

🔤 Typography

Learn how to use the Typography component and configure typography settings.

Typography →

🎨 Styled Components

Learn how to create and use styled components like StyledView with styled props.

Styled Components →

🍳 Cookbook

Explore advanced examples and patterns for custom components and styling.

Advanced Examples →