# Stratum — llms.txt

> Stratum is a copy-paste atomic design system for React Native (Expo).
> Paste this file into your AI tool to get idiomatic, type-correct Stratum code on the first try.

---

## What Is Stratum?

Stratum is an atomic design system for React Native with:
- **Unistyles 3.0** — zero-re-render theme switching via typed TypeScript style sheets
- **Three built-in themes** — Slate (Wealthsimple-inspired), Obsidian (Gumroad-inspired), Quartz (Go Club-inspired)
- **Atomic Design layers** — Tokens → Atoms → Molecules → Organisms → Templates → Screens
- **TypeScript throughout** — every prop, token, and theme value is typed
- **Copy-paste ownership** — components live in your repo; no black-box dependency

---

## Hard Rules (never violate these)

1. **Never hardcode values.** No hex colors, pixel sizes, or font sizes inline. Always use `theme.*` tokens.
2. **Import components from `@/components`.**  Import raw token values from `@/tokens`.
3. **Access the theme via `useTheme()`.** Never reach into theme files directly.
4. **Don't skip atomic layers.** A screen uses templates → organisms → molecules → atoms. Never put atoms directly in a screen unless that layer is trivially simple.
5. **Use `<Surface>` instead of `<View>` for themed backgrounds.** Surface handles BlurView on Quartz automatically.
6. **FormField owns its own error state.** Pass `errorMessage` to FormField; never set `isError` on the wrapped Input separately.
7. **Never import from the palette (`colors.ts`) in components.** Use `theme.colors.*` semantic slots only.
8. **`<IconButton>` always needs `accessibilityLabel`.** It is required by the type system.

---

## File Structure

```
src/
├── tokens/                    # Design tokens — import raw values from here
│   ├── spacing.ts             # 4px grid: xs(4) sm(8) md(16) lg(24) xl(32) 2xl(48) 3xl(64)
│   ├── typography.ts          # fontSizes, fontWeights, lineHeights, letterSpacings
│   ├── radii.ts               # borderRadius scale
│   ├── shadows.ts             # shadow presets
│   ├── borders.ts             # border widths
│   ├── theme-protocol.ts      # AppTheme interface
│   └── themes/
│       ├── registry.ts        # THEME_REGISTRY — single source of truth
│       ├── createTheme.ts     # createTheme(base, overrides) deep-merge utility
│       ├── slate.ts           # High-contrast B&W, pill buttons, soft shadows
│       ├── obsidian.ts        # Warm off-white, zero radii, thick borders, offset shadows
│       └── quartz.ts          # Electric blue, glass blur, aggressive opacity
├── providers/
│   ├── ThemeProvider.tsx      # Wrap your app in this
│   └── unistyles.ts           # Auto-derived from THEME_REGISTRY
├── hooks/
│   ├── useTheme.ts            # const theme = useTheme() — access active theme
│   └── useThemeToggle.ts      # const { themeName, setTheme, toggleColorScheme } = useThemeToggle()
├── components/
│   ├── 1-atoms/               # Text, Heading, Icon, Surface, Button, IconButton, Input,
│   │                          # TextArea, Checkbox, Switch, Radio, Slider, Card, Chip, Badge
│   ├── 2-molecules/           # FormField, SearchBar, SettingsRow, ListItem, ToggleRow, TagInput
│   ├── 3-organisms/           # TopNavBar, AuthForm, SettingsGroup, ListSection
│   └── 4-templates/           # AuthLayout, SettingsLayout
└── screens/                   # LoginScreen, SettingsScreen
```

---

## Tokens Reference

```ts
import { spacing, fontSizes, fontWeights, lineHeights, letterSpacings } from '@/tokens';

// Spacing — 4px grid
spacing.xs   // 4
spacing.sm   // 8
spacing.md   // 16
spacing.lg   // 24
spacing.xl   // 32
spacing['2xl'] // 48
spacing['3xl'] // 64

// Font sizes
fontSizes.xs  // 11
fontSizes.sm  // 13
fontSizes.md  // 15
fontSizes.lg  // 17
fontSizes.xl  // 20
fontSizes['2xl'] // 24
fontSizes['3xl'] // 30

// Font weights (string literals for RN)
fontWeights.regular  // '400'
fontWeights.medium   // '500'
fontWeights.semibold // '600'
fontWeights.bold     // '700'

// Line heights (multipliers — multiply by font size)
lineHeights.tight    // 1.2
lineHeights.normal   // 1.4
lineHeights.relaxed  // 1.6
```

---

## Theme Protocol (AppTheme)

```ts
// Access via: const theme = useTheme()
theme.colors.background      // page background
theme.colors.surface         // card / panel background
theme.colors.surfaceRaised   // elevated surface (above surface)
theme.colors.textPrimary     // main body text
theme.colors.textSecondary   // secondary text (less emphasis)
theme.colors.textMuted       // placeholder, labels, captions
theme.colors.textInverse     // text on dark backgrounds
theme.colors.textOnAccent    // text on accent-coloured backgrounds
theme.colors.accent          // primary brand color
theme.colors.accentHover     // darker accent for press states
theme.colors.accentSubtle    // very light accent tint (chips, badges, pills)
theme.colors.success         // success signal color
theme.colors.successSubtle   // light success tint
theme.colors.warning         // warning signal color
theme.colors.warningSubtle   // light warning tint
theme.colors.error           // error / destructive color
theme.colors.errorSubtle     // light error tint
theme.colors.border          // default divider / input border
theme.colors.borderStrong    // emphasized border
theme.colors.borderSubtle    // very light separator
theme.colors.overlay         // modal scrim

theme.radius.none  // 0
theme.radius.sm    // 4 (Slate/Quartz) | 0 (Obsidian)
theme.radius.md    // 8 | 0
theme.radius.lg    // 12 | 0
theme.radius.xl    // 16 | 0
theme.radius.full  // 9999 (pill)

theme.border.thin    // 1 (Slate/Quartz) | 2 (Obsidian)
theme.border.medium  // 2 | 3
theme.border.strong  // 3 | 4

theme.shadow.none  // no shadow
theme.shadow.sm    // subtle elevation
theme.shadow.md    // card elevation
theme.shadow.lg    // modal / sheet elevation

theme.iconWeight   // 'regular' (Slate) | 'bold' (Obsidian) | 'light' (Quartz)
theme.buttonShape  // 'pill' (Slate/Quartz) | 'default' (Obsidian)

theme.typography.fontFamily.heading  // platform default or custom
theme.typography.fontFamily.body
theme.typography.fontFamily.mono
```

---

## Component APIs

### Text

```tsx
import { Text } from '@/components';

// Types
type TextVariant = 'body' | 'caption' | 'label';
type TextSize    = 'xs' | 'sm' | 'md' | 'lg';
type TextWeight  = 'regular' | 'medium' | 'semibold' | 'bold';
type TextColor   = 'primary' | 'secondary' | 'muted' | 'accent' | 'inverse' | 'onAccent';

// Props: variant?, size?, weight?, color?, children, numberOfLines?, style?
<Text variant="body" size="md">Main content</Text>
<Text variant="caption" color="muted">Timestamp · 3 min ago</Text>
<Text variant="label" weight="semibold" color="accent">See all</Text>
```

Variant defaults: `body` → md/regular, `caption` → xs/regular, `label` → sm/medium.

---

### Heading

```tsx
import { Heading } from '@/components';

// Props: level (1|2|3|4), style?
<Heading level={1}>Screen Title</Heading>
<Heading level={2}>Section Header</Heading>
<Heading level={3}>Card Title</Heading>
<Heading level={4}>Subsection</Heading>
```

---

### Icon

```tsx
import { Icon } from '@/components';
import { House, Bell, Gear } from 'phosphor-react-native';

// Types
type IconSize   = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
type IconColor  = 'primary' | 'secondary' | 'muted' | 'accent' | 'inverse' | 'onAccent'
                | 'success' | 'warning' | 'error';
type IconWeight = 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone';

// Props: icon (required), size?, color?, weight?, accessibilityLabel?, testID?
<Icon icon={House} size="md" color="primary" />
<Icon icon={Bell} size="lg" color="accent" weight="fill" />
// Leave weight unset to use theme.iconWeight — icons feel native to the theme
```

---

### Surface

```tsx
import { Surface } from '@/components';

// Props: elevation?, padding?, radius?, border?, children
// On Quartz: renders BlurView when theme.effects.blurIntensity > 0
// On Slate/Obsidian: plain themed View
<Surface elevation="md" padding="md" radius="lg" border>
  {children}
</Surface>
```

---

### Button

```tsx
import { Button } from '@/components';

// Types
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
type ButtonSize    = 'sm' | 'md' | 'lg';
type ButtonShape   = 'default' | 'pill';

// Props: variant?, size?, shape?, isElevated?, isLoading?, isDisabled?, onPress?, children
<Button variant="primary" size="md" onPress={handleSubmit}>
  Save Changes
</Button>
<Button variant="secondary" size="sm" onPress={handleCancel}>
  Cancel
</Button>
<Button variant="ghost" onPress={handleSkip}>Skip</Button>
<Button variant="destructive" onPress={handleDelete}>Delete Account</Button>
<Button variant="primary" isLoading onPress={handleSubmit}>Saving…</Button>

// Rules:
// - One primary button per screen
// - destructive only for irreversible actions (delete, remove, not logout)
// - ghost for low-emphasis actions (skip, dismiss, see more)
// - Omit shape to use theme.buttonShape (pill for Slate/Quartz, default for Obsidian)
```

---

### IconButton

```tsx
import { IconButton } from '@/components';
import { ArrowLeft, X, MagnifyingGlass } from 'phosphor-react-native';

// Props: icon (required), accessibilityLabel (required), variant?, size?, shape?, isElevated?, isDisabled?, onPress?
<IconButton
  icon={ArrowLeft}
  accessibilityLabel="Go back"
  variant="ghost"
  size="md"
  onPress={router.back}
/>
```

---

### Input

```tsx
import { Input } from '@/components';

// Types
type InputShape = 'default' | 'pill';

// Props: value, onChangeText, placeholder?, isError?, isDisabled?, shape?,
//        keyboardType?, autoCapitalize?, secureTextEntry?, returnKeyType?,
//        onSubmitEditing?, onFocus?, onBlur?
<Input
  value={email}
  onChangeText={setEmail}
  placeholder="you@example.com"
  keyboardType="email-address"
  autoCapitalize="none"
/>
<Input value={query} onChangeText={setQuery} shape="pill" placeholder="Search…" />

// Use FormField (not bare Input) in forms — FormField adds label + error handling
```

---

### TextArea

```tsx
import { TextArea } from '@/components';

// Props: value, onChangeText, placeholder?, numberOfLines?, isError?, isDisabled?, shape?
<TextArea
  value={bio}
  onChangeText={setBio}
  placeholder="Tell us about yourself…"
  numberOfLines={4}
/>
```

---

### Checkbox

```tsx
import { Checkbox } from '@/components';

// Props: checked, onToggle, label?, isDisabled?, testID?
<Checkbox checked={agreed} onToggle={setAgreed} label="I agree to the terms" />
```

---

### Switch

```tsx
import { Switch } from '@/components';

// Props: value, onValueChange, accessibilityLabel (required), isDisabled?, testID?
<Switch
  value={notificationsEnabled}
  onValueChange={setNotificationsEnabled}
  accessibilityLabel="Enable push notifications"
/>
```

---

### Radio

```tsx
import { Radio } from '@/components';

// Props: value (this option's value), selectedValue, onSelect, label?, isDisabled?
// Always use Radio in a group — never render a single Radio
const [plan, setPlan] = useState('monthly');
<Radio value="monthly" selectedValue={plan} onSelect={setPlan} label="Monthly" />
<Radio value="annual"  selectedValue={plan} onSelect={setPlan} label="Annual — save 20%" />
```

---

### Slider

```tsx
import { Slider } from '@/components';

// Props: value, onValueChange, minimumValue?, maximumValue?, step?, accessibilityLabel (required), isDisabled?
<Slider
  value={volume}
  onValueChange={setVolume}
  minimumValue={0}
  maximumValue={100}
  step={1}
  accessibilityLabel="Volume"
/>
```

---

### Card

```tsx
import { Card } from '@/components';

// Props: padding?, border?, isElevated?, onPress?, children, accessibilityLabel?
<Card padding="md" border>
  <Heading level={3}>Card Title</Heading>
  <Text color="secondary">Card content goes here.</Text>
</Card>
// Pressable card:
<Card padding="md" onPress={handlePress} accessibilityLabel="View invoice">
  {content}
</Card>
```

Padding options: `'sm'` (8) | `'md'` (16) | `'lg'` (24) | `'xl'` (32). Minimum is `'sm'`.

---

### Chip

```tsx
import { Chip } from '@/components';

// Props: label, isSelected?, onPress?, onRemove?, variant?, isDisabled?
<Chip label="React Native" isSelected onPress={() => toggle('rn')} />
<Chip label="TypeScript" onRemove={() => remove('ts')} />
```

---

### Badge

```tsx
import { Badge } from '@/components';

// Types
type BadgeVariant = 'default' | 'accent' | 'success' | 'warning' | 'error';

// Props: label, variant?
<Badge label="Pro" variant="accent" />
<Badge label="Active" variant="success" />
<Badge label="Pending" variant="warning" />
<Badge label="Expired" variant="error" />
<Badge label="Draft" />  {/* default — neutral */}

// Badge is non-interactive (display only). Use Chip for selectable/removable tags.
```

---

### FormField

```tsx
import { FormField } from '@/components';

// labelPosition controls the label interaction pattern:
//   'above'  (default) — semibold label above input; best for 3+ field forms
//   'inline' — animated floating label; best for short 1-2 field forms
//
// Never mix labelPosition values within a single form.

// Props: label?, value, onChangeText, placeholder?, isRequired?, hint?,
//        errorMessage?, labelPosition?, shape?, isDisabled?, secureTextEntry?,
//        keyboardType?, autoCapitalize?, autoCorrect?, returnKeyType?,
//        onSubmitEditing?, onFocus?, onBlur?

<FormField
  label="Email"
  value={email}
  onChangeText={setEmail}
  placeholder="you@example.com"
  keyboardType="email-address"
  autoCapitalize="none"
  isRequired
  errorMessage={emailError}   // drives error state on the Input automatically
/>

// Inline floating label (Wealthsimple-style):
<FormField
  label="Password"
  value={password}
  onChangeText={setPassword}
  secureTextEntry
  labelPosition="inline"
  errorMessage={passwordError}
/>

// Pill shape:
<FormField label="Search" value={q} onChangeText={setQ} shape="pill" />
```

---

### SearchBar

```tsx
import { SearchBar } from '@/components';

// Props: value, onChangeText, onClear, placeholder?
<SearchBar
  value={query}
  onChangeText={setQuery}
  onClear={() => setQuery('')}
  placeholder="Search components…"
/>
```

---

### SettingsRow

```tsx
import { SettingsRow } from '@/components';
import { Bell, Globe } from 'phosphor-react-native';

// Types
type SettingsRowAccessory = 'switch' | 'chevron' | 'value' | 'badge';

// Props: label, description?, leftIcon?, labelSize?, rightAccessory?,
//        checked?, onToggle?, value?, onPress?, badgeLabel?, badgeTone?, isDisabled?

// Switch row (preference toggle):
<SettingsRow
  label="Push notifications"
  description="Alerts sent to your device"
  leftIcon={Bell}
  rightAccessory="switch"
  checked={notifications}
  onToggle={setNotifications}
/>

// Navigation row (taps to a detail screen):
<SettingsRow
  label="Language"
  leftIcon={Globe}
  rightAccessory="value"
  value="English"
  onPress={openLanguage}
/>

// Chevron row (taps to a subscreen):
<SettingsRow label="Privacy Policy" rightAccessory="chevron" onPress={openPrivacy} />

// Use SettingsGroup (organism) instead of bare SettingsRow when you have 2+ rows.
```

---

### ListItem

```tsx
import { ListItem } from '@/components';
import { Envelope, User } from 'phosphor-react-native';

// Types
type ListItemRightElement = 'chevron' | 'none';

// Props: label, description?, leftIcon?, rightElement?, onPress?, isDisabled?
<ListItem
  label="Alice Johnson"
  description="alice@example.com"
  leftIcon={User}
  rightElement="chevron"
  onPress={openProfile}
/>

// Use ListSection (organism) instead of bare ListItem when you have 2+ items.
// Use SettingsRow (not ListItem) for preference/settings rows.
```

---

### ToggleRow

```tsx
import { ToggleRow } from '@/components';
import { Bell } from 'phosphor-react-native';

// Props: label, description?, leftIcon?, value, onValueChange, isDisabled?
<ToggleRow
  label="Marketing emails"
  description="Product tips and new releases"
  value={marketing}
  onValueChange={setMarketing}
/>

// ToggleRow is simpler than SettingsRow — no icon, just label + Switch.
// Use SettingsRow when you need leftIcon, value display, or chevron navigation.
```

---

### TagInput

```tsx
import { TagInput } from '@/components';

// Props: tags, onTagsChange, placeholder?, maxTags?
const [tags, setTags] = useState<string[]>(['React Native']);
<TagInput
  tags={tags}
  onTagsChange={setTags}
  placeholder="Add a tag…"
  maxTags={10}
/>
// Type a value and press Return or comma to add it. Tap × on a chip to remove.
```

---

### TopNavBar

```tsx
import { TopNavBar } from '@/components';
import { MagnifyingGlass, Sliders } from 'phosphor-react-native';

// Props: title, onBack?, rightActions?
// rightActions: Array<{ icon, onPress, accessibilityLabel }>
<TopNavBar
  title="Settings"
  onBack={router.back}
  rightActions={[
    { icon: MagnifyingGlass, onPress: openSearch, accessibilityLabel: 'Search' },
  ]}
/>

// Every screen that is not a root tab should have a TopNavBar.
// Maximum 2 rightActions — use an IconButton overflow menu for more.
```

---

### SettingsGroup

```tsx
import { SettingsGroup } from '@/components';
import { Bell, Lock, Globe } from 'phosphor-react-native';

// Props: title?, rows: SettingsRowProps[]
<SettingsGroup
  title="Notifications"
  rows={[
    {
      label: 'Push alerts',
      leftIcon: Bell,
      rightAccessory: 'switch',
      checked: push,
      onToggle: setPush,
    },
    {
      label: 'Email digest',
      leftIcon: Bell,
      rightAccessory: 'switch',
      checked: email,
      onToggle: setEmail,
    },
  ]}
/>

// SettingsGroup handles the card container, hairline dividers, and rounded corners.
// Each entry in `rows` accepts all SettingsRowProps.
```

---

### ListSection

```tsx
import { ListSection } from '@/components';
import { Star, Archive } from 'phosphor-react-native';

// Props: title?, items: ListItemProps[]
<ListSection
  title="Recent"
  items={[
    {
      label: 'Invoice #1042',
      description: 'Sent 2 days ago',
      leftIcon: Star,
      rightElement: 'chevron',
      onPress: () => openInvoice('1042'),
    },
    {
      label: 'Invoice #1041',
      description: 'Sent 5 days ago',
      leftIcon: Archive,
      rightElement: 'chevron',
      onPress: () => openInvoice('1041'),
    },
  ]}
/>
```

---

### AuthForm

```tsx
import { AuthForm } from '@/components';

// Props: mode?, email, onChangeEmail, password, onChangePassword,
//        confirmPassword?, onChangeConfirmPassword?,
//        emailError?, passwordError?, confirmPasswordError?,
//        isLoading?, onSubmit, onForgotPassword?,
//        socialActions?, footerText?, footerActionLabel?, onFooterAction?

// AuthForm is controlled — the parent owns all field values and validation.
// Pass error strings back as errorMessage props; AuthForm never validates internally.
<AuthForm
  mode="login"
  email={email}
  onChangeEmail={setEmail}
  password={password}
  onChangePassword={setPassword}
  emailError={errors.email}
  passwordError={errors.password}
  isLoading={isSubmitting}
  onSubmit={handleLogin}
  onForgotPassword={() => router.push('/forgot-password')}
  footerText="Don't have an account?"
  footerActionLabel="Sign up"
  onFooterAction={() => router.push('/signup')}
/>
```

---

### AuthLayout

```tsx
import { AuthLayout } from '@/components';

// Props: logo?, title?, subtitle?, children (required), footer?
<AuthLayout
  logo={<BrandLogo />}
  title="Welcome back"
  subtitle="Log in to continue"
  footer={<Text variant="caption" color="muted">v1.0</Text>}
>
  <AuthForm ... />
</AuthLayout>

// AuthLayout provides keyboard-aware centering. Don't put navigation logic here.
```

---

### SettingsLayout

```tsx
import { SettingsLayout } from '@/components';

// Props: title, onBack?, rightActions?, children (required), footer?
<SettingsLayout
  title="Settings"
  onBack={router.back}
>
  <SettingsGroup title="Account" rows={accountRows} />
  <SettingsGroup title="Notifications" rows={notificationRows} />
</SettingsLayout>

// SettingsLayout renders TopNavBar + scrollable content. Use it for any settings
// or detail screen. Pass footer for a fixed bottom action (e.g. save button).
```

---

## Composition Patterns

### Login Screen

```tsx
export function LoginScreen() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [errors, setErrors] = useState({ email: '', password: '' });
  const [isLoading, setIsLoading] = useState(false);

  async function handleSubmit() {
    const newErrors = { email: '', password: '' };
    if (!email.includes('@')) newErrors.email = 'Enter a valid email address';
    if (password.length < 8) newErrors.password = 'Password must be at least 8 characters';
    setErrors(newErrors);
    if (newErrors.email || newErrors.password) return;

    setIsLoading(true);
    try {
      await login(email, password);
      router.replace('/home');
    } finally {
      setIsLoading(false);
    }
  }

  return (
    <AuthLayout
      title="Welcome back"
      subtitle="Log in to your account"
    >
      <AuthForm
        mode="login"
        email={email} onChangeEmail={setEmail}
        password={password} onChangePassword={setPassword}
        emailError={errors.email}
        passwordError={errors.password}
        isLoading={isLoading}
        onSubmit={handleSubmit}
        onForgotPassword={() => router.push('/forgot-password')}
        footerText="New here?"
        footerActionLabel="Create account"
        onFooterAction={() => router.push('/signup')}
      />
    </AuthLayout>
  );
}
```

### Settings Screen

```tsx
export function AccountSettingsScreen() {
  const [push, setPush] = useState(true);
  const [email, setEmail] = useState(false);

  return (
    <SettingsLayout title="Account" onBack={router.back}>
      <SettingsGroup
        title="Profile"
        rows={[
          { label: 'Display Name', rightAccessory: 'value', value: 'Sarah Chen', onPress: editName },
          { label: 'Email', rightAccessory: 'value', value: 'sarah@example.com', onPress: editEmail },
        ]}
      />
      <SettingsGroup
        title="Notifications"
        rows={[
          { label: 'Push alerts', rightAccessory: 'switch', checked: push, onToggle: setPush },
          { label: 'Email digest', rightAccessory: 'switch', checked: email, onToggle: setEmail },
        ]}
      />
      <SettingsGroup
        title="Account"
        rows={[
          { label: 'Privacy Policy', rightAccessory: 'chevron', onPress: openPrivacy },
          { label: 'Delete Account', rightAccessory: 'chevron', onPress: confirmDelete },
        ]}
      />
    </SettingsLayout>
  );
}
```

### Custom Theme

```tsx
import { createTheme } from '@/tokens/themes/createTheme';
import { slateThemeLight, slateThemeDark } from '@/tokens/themes/slate';

// Override only what changes — everything else inherits from Slate
export const brandThemeLight = createTheme(slateThemeLight, {
  colors: {
    accent:       '#E11D48',
    accentHover:  '#BE123C',
    accentSubtle: '#FFF1F2',
  },
});

export const brandThemeDark = createTheme(slateThemeDark, {
  colors: {
    accent:       '#FB7185',
    accentHover:  '#F43F5E',
    accentSubtle: '#4C0519',
  },
});

// Register in src/tokens/themes/registry.ts:
// { name: 'brand', label: 'Brand', light: brandThemeLight, dark: brandThemeDark }
// Everything else (Unistyles, ThemeProvider, TypeScript types) auto-derives.
```

### App Setup

```tsx
import { ThemeProvider } from '@/providers/ThemeProvider';
// Unistyles must be imported before ThemeProvider at the entry point
import '@/providers/unistyles';

export default function App() {
  return (
    <ThemeProvider initialTheme="slate" initialColorScheme="light">
      {/* your navigator goes here */}
    </ThemeProvider>
  );
}
```

### Theme Switching

```tsx
import { useThemeToggle } from '@/hooks/useThemeToggle';

function ThemeBar() {
  const { themeName, colorScheme, setTheme, toggleColorScheme } = useThemeToggle();

  return (
    <View>
      <Button onPress={() => setTheme('slate')}>Slate</Button>
      <Button onPress={() => setTheme('obsidian')}>Obsidian</Button>
      <Button onPress={() => setTheme('quartz')}>Quartz</Button>
      <Button onPress={toggleColorScheme}>
        {colorScheme === 'light' ? 'Dark mode' : 'Light mode'}
      </Button>
    </View>
  );
}
```

---

## CLI — stratum-uikit

Stratum ships a CLI that copies components into your project (shadcn model — you own the files).

### Setup

```bash
# Scaffold tokens, providers, hooks (run once per project)
npx stratum-uikit init

# Then install peer deps
npx expo install react-native-unistyles react-native-nitro-modules phosphor-react-native
```

`init` writes `stratum.config.json` and copies:
- `src/tokens/` — all token files + Slate theme
- `src/providers/` — ThemeProvider, unistyles.ts
- `src/hooks/` — useTheme, useThemeToggle

### Adding components

```bash
# Atoms
npx stratum-uikit add atom/Button
npx stratum-uikit add atom/Input
npx stratum-uikit add atom/Surface

# Molecules
npx stratum-uikit add molecule/FormField
npx stratum-uikit add molecule/SettingsRow

# Organisms — dependencies resolved automatically
npx stratum-uikit add organism/AuthForm
# ^ also adds: FormField, Button, Input, Text (dep chain)

npx stratum-uikit add organism/SettingsGroup
# ^ also adds: SettingsRow, Text (dep chain)

# Templates
npx stratum-uikit add template/AuthLayout
npx stratum-uikit add template/SettingsLayout
```

Layer prefixes: `atom/`, `molecule/`, `organism/`, `template/`

### Themes

```bash
npx stratum-uikit theme list
# Prints: slate [default], obsidian, quartz with descriptions
```

To add Obsidian or Quartz: copy the theme file from the docs, add one entry to THEME_REGISTRY. `theme add` is coming in v2.

---

## Atomic Layer Decision Guide

| If you need… | Use |
|---|---|
| A single text label | `Text` or `Heading` |
| An interactive button | `Button` (with text) or `IconButton` (icon-only) |
| A form input with label + error | `FormField` |
| A bare text input | `Input` (only if no label/error needed) |
| A themed container | `Surface` (dynamic) or `Card` (content card) |
| A status indicator | `Badge` (display) or `Chip` (interactive) |
| A settings preference row | `SettingsRow` |
| A content list row | `ListItem` |
| Multiple settings rows grouped | `SettingsGroup` |
| Multiple content rows grouped | `ListSection` |
| A search + results | `SearchBar` + `ListSection` |
| An auth form | `AuthForm` |
| A screen with nav bar + scroll | `SettingsLayout` |
| A centred auth screen | `AuthLayout` |

---

*Stratum llms.txt — generated for AI consumption. Paste into Cursor, Claude, or any context window.*