Project Structure

After copying Stratum’s files into your repo, the src/ directory looks like this:

src/
├── tokens/                    # Design tokens — the foundation
│   ├── colors.ts              # Base palette (internal — don't import in components)
│   ├── 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               # Border radius scale
│   ├── shadows.ts             # Shadow presets
│   ├── borders.ts             # Border widths
│   ├── theme-protocol.ts      # AppTheme interface — the contract all themes implement
│   └── themes/
│       ├── registry.ts        # THEME_REGISTRY — single source of truth for all themes
│       ├── createTheme.ts     # Deep-merge utility for custom themes
│       ├── slate.ts           # Wealthsimple-inspired theme
│       ├── obsidian.ts        # Gumroad-inspired theme
│       └── quartz.ts          # Go Club-inspired theme
├── providers/
│   ├── ThemeProvider.tsx      # Wraps your app; provides theme context
│   └── unistyles.ts           # Unistyles config — auto-derived from THEME_REGISTRY
├── hooks/
│   ├── useTheme.ts            # const theme = useTheme() — read active theme tokens
│   └── useThemeToggle.ts      # const { setTheme, toggleColorScheme } = useThemeToggle()
├── components/
│   ├── 1-atoms/               # 15 foundational components
│   ├── 2-molecules/           # 6 single-job composites
│   ├── 3-organisms/           # 4 section-level composites
│   ├── 4-templates/           # 2 layout shells
│   └── index.ts               # Barrel export — import from '@/components'
└── screens/
    ├── LoginScreen.tsx
    └── SettingsScreen.tsx

Rules

Imports

• Components: always from @/components
• Raw token values: from @/tokens (spacing, fontSizes, etc.)
• Theme context: via useTheme() from @/hooks/useTheme
• Never: hardcode colors, pixel values, or font sizes

Atomic layers

• Atoms own raw styling and render via <Surface> for themed backgrounds
• Molecules combine 2+ atoms into one-job units — no business logic
• Organisms assemble meaningful sections from molecules and atoms
• Templates define layout slots only (header, content, footer as ReactNode props)
• Screens bind templates to data, navigation, and state

Adding a new theme

1. Create src/tokens/themes/mytheme.ts implementing AppTheme
2. Add one entry to THEME_REGISTRY in src/tokens/themes/registry.ts
3. Everything else auto-derives — Unistyles, ThemeProvider, TypeScript types

The @/ alias

All imports use the @/ alias which resolves to src/. This is configured in tsconfig.json and babel.config.js. See Installation for setup details.