# Getting started

> Install the OTF SDK packages, wire up theming, and ship your first screen.

The OTF SDK is published as scoped packages on npm under `@otfdashkit/*`. Install the ones
you need for your platform.

## Web project (Next.js, Vite, Remix, …)

```bash
npm install @otfdashkit/ui @otfdashkit/tokens
```

Add the token CSS import **before** the component CSS in your global stylesheet:

```css title="app/globals.css"
@import '@otfdashkit/tokens/web.css';
@import '@otfdashkit/ui/styles';

/* your own styles below */
```

Set the default theme on the document **before the first paint** so users don't see
a flash of unstyled colors:

```html title="app/layout.tsx"
<script
  dangerouslySetInnerHTML={{
    __html: `
      const t = localStorage.getItem('otf-theme') || 'theme-minimal'
      const s = localStorage.getItem('otf-color-scheme') || 'dark'
      document.documentElement.className = \`\${t} \${s}\`
    `,
  }}
/>
```

You're done. Import a component:

```tsx title="app/page.tsx"
import { Persona, Stat, EmptyState } from '@otfdashkit/ui'

export default function Page() {
  return (
    <div className="p-6 grid gap-4">
      <Stat label="Active users" value="12,406" delta="+12%" />
      <EmptyState title="No projects yet" description="Create your first project to get started." />
    </div>
  )
}
```

## React Native project (Expo)

```bash
npm install @otfdashkit/ui-native @otfdashkit/tokens
```

`@otfdashkit/ui-native` is built on Tamagui. Wire the provider once in your root layout:

```tsx title="app/_layout.tsx"
import { OtfProvider, createTamagui, tamaguiDefaultConfig } from '@otfdashkit/ui-native'

const config = createTamagui(tamaguiDefaultConfig)

export default function RootLayout({ children }) {
  return <OtfProvider config={config}>{children}</OtfProvider>
}
```

Then import primitives the same way you would on web:

```tsx
import { YStack, Text, Card } from '@otfdashkit/ui-native'

export default function Screen() {
  return (
    <YStack padding="$4" gap="$3">
      <Text fontSize="$8" fontWeight="700">Welcome</Text>
      <Card padding="$4">Hello from OTF.</Card>
    </YStack>
  )
}
```

## Both platforms in one repo

If you're building one product across web + native (which is what the OTF kits do), use a
monorepo and consume both packages from the same workspace. Share business logic, screens,
and theme tokens — keep platform-specific glue thin. See the
[Templates](/docs/templates) page for the canonical layout the kits use.

## Learn more

<Cards>
  <Card title="Theme + palette switching" href="/docs/tokens/overview" description="Runtime theme switching across 4 palettes, custom palette authoring, dark/light mapping." />
  <Card title="Components — Web" href="/docs/components/ui/overview" description="The full @otfdashkit/ui surface — primitives, composites, blocks, and advanced." />
  <Card title="Components — Native" href="/docs/components/ui-native/overview" description="Tamagui-styled primitives, layouts, and patterns built for Expo SDK 54." />
  <Card title="AI tool integration" href="/docs/ai-tools/overview" description="CLAUDE.md, .cursorrules, AGENTS.md, lovable.md — kept in sync by @otfdashkit/ai." />
</Cards>

## FAQ

<Accordions type="single">
  <Accordion title="Do I need a monorepo to use OTF?">
    No. Either package (`@otfdashkit/ui` or `@otfdashkit/ui-native`) works in a standalone
    Vite/Next/Expo app. The monorepo pattern is only needed when you want to share screens
    and business logic across web + native — that's what the paid kits do.
  </Accordion>
  <Accordion title="Why Tamagui for the native side instead of plain RN StyleSheet?">
    Tamagui gives us the same token-driven theming model as Tailwind on web (without the
    string-based class soup), and its compiler hoists styles at build time so runtime cost
    matches StyleSheet. The shared `@otfdashkit/tokens` package wires both worlds.
  </Accordion>
  <Accordion title="Is it safe to use the SDK in production?">
    The components themselves are stable — every paid kit consumes them directly. APIs may
    still polish at minor versions until v1.0.0; pin a version if that matters to you.
    Full-stack kits (SaaS Dashboard, Fitness) are production-ready and built to last.
  </Accordion>
  <Accordion title="Can I use only one package and skip the others?">
    Yes. `@otfdashkit/ui` ships standalone, `@otfdashkit/ui-native` ships standalone,
    `@otfdashkit/tokens` is consumed by both but you only need it explicitly if you're
    authoring custom palettes or referencing tokens in app code outside the components.
  </Accordion>
</Accordions>