Quick Start

Install the SDK
```
pnpm add @objectifthunes/limestone-sdk react react-native
```
```
npm install @objectifthunes/limestone-sdk react react-native
```
```
yarn add @objectifthunes/limestone-sdk react react-native
```

Define a theme

defineTheme validates all tokens with Zod and returns a frozen ThemeAdapter. Every token group is required.

// theme.ts
import { defineTheme } from '@objectifthunes/limestone-sdk';

export const myTheme = defineTheme({
  name: 'my-theme',
  mode: 'light',
  tokens: {
    colors: {
      background: '#ffffff',
      foreground: '#0f172a',
      primary: '#6366f1',
      primaryForeground: '#ffffff',
      secondary: '#f1f5f9',
      secondaryForeground: '#0f172a',
      muted: '#f8fafc',
      mutedForeground: '#64748b',
      accent: '#f1f5f9',
      accentForeground: '#0f172a',
      destructive: '#ef4444',
      destructiveForeground: '#ffffff',
      card: '#ffffff',
      cardForeground: '#0f172a',
      border: '#e2e8f0',
      input: '#e2e8f0',
      ring: '#6366f1',
    },
    spacing: {
      xs: 4,
      sm: 8,
      md: 16,
      lg: 24,
      xl: 32,
      '2xl': 48,
      '3xl': 64,
      '4xl': 96,
    },
    radii: {
      none: 0,
      sm: 4,
      md: 8,
      lg: 12,
      xl: 16,
      full: 9999,
    },
    typography: {
      fontFamily: {
        display: 'System',
        body: 'System',
        mono: 'Courier',
      },
      sizes: {
        xs: 11,
        sm: 13,
        md: 15,
        lg: 17,
        xl: 20,
        '2xl': 24,
        '3xl': 30,
        '4xl': 36,
      },
      weights: {
        regular: '400',
        medium: '500',
        semibold: '600',
        bold: '700',
      },
      lineHeights: {
        tight: 1.25,
        normal: 1.5,
        relaxed: 1.75,
      },
    },
    shadows: {
      sm: { color: '#000000', offset: { width: 0, height: 1 }, radius: 2, opacity: 0.05, elevation: 1 },
      md: { color: '#000000', offset: { width: 0, height: 2 }, radius: 4, opacity: 0.08, elevation: 3 },
      lg: { color: '#000000', offset: { width: 0, height: 4 }, radius: 8, opacity: 0.12, elevation: 6 },
    },
    motion: {
      duration: { fast: 150, normal: 250, slow: 400 },
      easing: {
        default: 'ease-in-out',
        spring: { damping: 15, stiffness: 300 },
        bounce: { damping: 8, stiffness: 200 },
      },
    },
  },
});

Create a config

defineConfig wires the theme, API client, and any adapters together. Pass its return value directly to LimestoneProvider.

// config.ts
import { defineConfig } from '@objectifthunes/limestone-sdk';
import { myTheme } from './theme';

export const config = defineConfig({
  theme: myTheme,
  api: {
    baseUrl: 'https://api.example.com',
    auth: {
      refreshEndpoint: '/auth/refresh',
      tokenStorage: 'secure-store',
      onUnauthorized: () => { /* navigate to login */ },
    },
  },
});

Wrap your app in LimestoneProvider

Place LimestoneProvider at the root of the component tree — above any navigation or screen components.

// App.tsx
import React from 'react';
import { LimestoneProvider } from '@objectifthunes/limestone-sdk';
import { config } from './config';
import { RootNavigator } from './navigation/RootNavigator';

export default function App() {
  return (
    <LimestoneProvider config={config}>
      <RootNavigator />
    </LimestoneProvider>
  );
}

Use your first component

Stack, Text, and Pressable are all in the main barrel. Token-based props (gap, p, bg, rounded) resolve through the theme automatically.

// screens/HomeScreen.tsx
import React from 'react';
import {
  Stack,
  Text,
  Pressable,
} from '@objectifthunes/limestone-sdk';

export function HomeScreen() {
  return (
    <Stack p="lg" gap="md" bg="background" flex={1}>
      <Text variant="heading" size="2xl" weight="bold" color="foreground">
        Welcome
      </Text>
      <Text variant="body" color="mutedForeground">
        Your app is running with limestone-sdk.
      </Text>
      <Pressable
        bg="primary"
        rounded="md"
        p="md"
        center
        onPress={() => console.log('pressed')}
      >
        <Text variant="label" color="primaryForeground" weight="semibold">
          Get started
        </Text>
      </Pressable>
    </Stack>
  );
}

What just happened

defineTheme validated all token groups with Zod and produced a frozen ThemeAdapter object.
defineConfig consumed the theme and API options and produced a frozen LimestoneConfig.
LimestoneProvider created an observable Store<AppState>, an ApiClient, and a ThemeProvider — all wired to the config.
Inside the tree, Stack, Text, and Pressable called useTheme() internally. Shorthand props like p="lg" resolved to spacing.lg (24), and bg="background" resolved to colors.background from the token set.

No manual wiring required. Every component in the tree shares the same theme and store.

Next steps

Architecture — understand how ports, adapters, and the core layer are separated.
Configuration — full reference for defineConfig including adapters and features.
Theme engine — define multiple themes, dark mode, and component overrides.
Adapters — wire native capabilities like biometrics, camera, and notifications.

Installation

Architecture