Decky

Directory Structure

/
├── src/
│   ├── app/                    # Expo Router pages
│   │   ├── _layout.tsx         # Root layout (theme setup, i18n init)
│   │   └── index.tsx           # Home/welcome screen
│   ├── components/             # App-level shared components
│   │   └── PageProvider.tsx    # Page wrapper (SafeAreaView + scroll)
│   └── lang/                   # Internationalization
│       ├── 18n.ts              # i18next configuration
│       └── translation-files/
│           ├── en.json         # English translations
│           └── tr.json         # Turkish translations
├── components/                 # Reusable molecules/atoms
│   └── molecules/
│       └── dynamic-text/       # Animated text rotation component
│           ├── index.tsx
│           ├── types.ts
│           ├── helpers.ts
│           └── const.ts
├── themes/                     # CSS theme files (OKLCH colors)
│   ├── decky.css               # Main Decky theme (lime accent)
│   ├── lavander.css            # Lavender theme
│   ├── mint.css                # Mint theme
│   ├── sky.css                 # Sky blue theme
│   └── alpha.css               # Alpha theme
├── assets/
│   ├── images/                 # App icons, splash screen, logo.png
│   └── fonts/                  # Custom fonts (Inter, SN Pro, etc.)
├── global.css                  # Global CSS entry (imports themes)
├── metro.config.js             # Uniwind + Metro config
├── app.json                    # Expo app config
└── tsconfig.json               # TypeScript config (path alias: @/*)

Active Theme

The active theme is decky-light (set in src/app/_layout.tsx):

Uniwind.setTheme('decky-light');

Decky Theme Colors (OKLCH)

• Accent: oklch(93.70% 0.2160 119.00) — bright lime/yellow-green (#d9fd0c-ish)
• Accent Foreground: oklch(15.00% 0.0500 119.00) — dark
• Background: Clean white (light) / Deep dark (dark)
• Primary / Card / Border / Muted: All defined in themes/decky.css

Available Themes

light, dark,
lavender-light, lavender-dark,
mint-light, mint-dark,
sky-light, sky-dark,
decky-light, decky-dark

Registered in metro.config.js under extraThemes.

Theming — Key Rules

• Always use CSS variable-based classes (bg-background, text-foreground, bg-primary) instead of hardcoded colors.
• Every theme variant must define the same set of CSS variables.
• Changes to metro.config.js require a Metro restart: npm start (script already uses -c flag for cache clearing).
• Theme CSS files live in themes/ and are imported via @import './themes/*.css'; in global.css.
• See the uniwind skill for full Uniwind API reference.

Internationalization (i18n)

• Library: i18next + react-i18next
• Languages: English (en), Turkish (tr)
• Config file: src/lang/18n.ts
• Translation files: src/lang/translation-files/{en,tr}.json
• Translation key format: UPPER_SNAKE_CASE inside the "translation" namespace

Translation Key Naming

Keys must be ALL_CAPS with underscores:

{
  "translation": {
    "WELCOME_TITLE": "Decky",
    "WELCOME_DESCRIPTION": "Build your vocabulary from the content you love",
    "GET_STARTED": "Get Started",
    "ADD_WORD": "Add Word",
    "MY_VOCABULARY": "My Vocabulary"
  }
}

Usage in Components

import { useTranslation } from 'react-i18next';

const { t } = useTranslation();
<Text>{t('WELCOME_TITLE')}</Text>

COPYRIGHT RULE for translations

Never mention specific platform names in translation strings. Use neutral terms:

Component Conventions

PageProvider

Every screen should be wrapped in PageProvider:

import PageProvider from '@/src/components/PageProvider';

export default function MyScreen() {
  return (
    <PageProvider scrollable={false}>
      {/* screen content */}
    </PageProvider>
  );
}

Props:

• children — required
• scrollable?: boolean — enables KeyboardAwareScrollView (default: false)

DynamicText

Animated text carousel component. Use on screens with rotating text/taglines:

import { DynamicText } from '@/components/molecules/dynamic-text';

<DynamicText
  items={['Hello', 'Merhaba', 'Bonjour', 'Hola']}
  animationPreset="slide"
  animationDirection="up"
  timing={{ interval: 2200, animationDuration: 500 }}
  loop
  text={{ fontSize: 24, fontWeight: '600', color: primaryColor }}
/>

Props: items, animationPreset ('fade'|'slide'|'scale'), animationDirection ('up'|'down'|'left'|'right'), timing, dot, text, loop, loopCount, paused, initialIndex, onAnimationComplete, onIndexChange.

Path Alias

Always use @/ for imports (maps to project root):

import PageProvider from '@/src/components/PageProvider';
import { DynamicText } from '@/components/molecules/dynamic-text';
import en from '@/src/lang/translation-files/en.json';

Navigation

Expo Router file-based routing under src/app/:

• src/app/_layout.tsx — Root Stack layout (headerShown: false)
• src/app/index.tsx — Home screen (route: /)
• Add new screens as src/app/[name].tsx or src/app/[name]/index.tsx

The root layout sets up:

• GestureHandlerRootView (must wrap everything)
• KeyboardProvider
• HeroUINativeProvider
• Uniwind theme: Uniwind.setTheme('decky-light')
• i18n initialization (import from @/src/lang/18n)

Styling Guidelines

1. Always use className — avoid StyleSheet.create() for new code
2. Use semantic CSS variables for colors: bg-background, text-foreground, bg-primary, border-border, etc.
3. Font classes: font-normal, font-medium, font-semibold, font-bold (mapped to Inter variants)
4. No hardcoded colors in className (except for illustrations/decorative elements)
5. HeroUI Native components are preferred for standard UI elements (Button, Input, Card, Modal, etc.)
6. React Native built-ins (View, Text, Pressable, ScrollView) support className directly via Uniwind
7. For third-party components needing className: use withUniwind() from 'uniwind'

Key Files Quick Reference

Development Commands

npm start          # Start with cache clear (expo start -c)
npm run ios        # Run on iOS with cache clear
npm run android    # Run on Android with cache clear
npm run web        # Run on web with cache clear
npm run lint       # ESLint

Important Reminders

1. Copyright: Never use YouTube, Netflix, Amazon Prime, or similar brand names in user-facing text
2. Translations: Add keys to BOTH en.json AND tr.json when adding new text
3. Themes: When adding theme CSS variables, add them to ALL theme variants (decky, lavender, mint, sky, alpha — both light and dark)
4. TypeScript: Strict mode is enabled — no any without justification
5. New Architecture: Enabled — use Pressable instead of TouchableOpacity
6. Fonts: Only single font per variable in @theme (no fallbacks — React Native limitation)