Self-hosted fitness tracker. Log workouts, track nutrition, and monitor progress. Docker deployment, mobile-friendly.
Lyftr Mobile — Conventions
Read this before touching mobile/. It is the native analog of the web app's
conventions: same design language, same tokens, same component names — expressed in
React Native / Expo idioms. When in doubt, open web/src/components/ui/ and mirror it.
1. Reuse boundary — logic is shared, UI is per-platform
- Logic lives in
@lyftr/sharedand is imported, never duplicated: types, the API client, Zustand stores, and pure utils (displayWeight,normalizeServerUrl,testServerConnection, ...). If you're about to write a type, a fetch, or a unit-conversion inmobile/, stop — it belongs inpackages/shared. - UI is authored per-platform, but mirror the web's component names and prop
shapes wherever an analog exists (
PageHeader,SectionHeader,SegmentedControl,EmptyState,IconButton,StepperTile+NumberField, ...), adapted to RN idioms:onPressnotonClick,TextInputPropsnot input attributes,accessibilityLabelnotaria-label. The two apps must stay legible to each other. - Don't re-roll primitives. Read
src/components/ui/first; if a screen needs a visual pattern twice, extract it there.
2. Styling rule (the one rule to remember)
Default: NativeWind className, using the shared token vocabulary — identical to
the web's: bg-surface-{base,raised,overlay,border,muted}, text-tx-{primary, secondary,muted,inverse}, bg-brand-500, text-error-400, border-surface-border,
opacity modifiers like bg-brand-500/10. These resolve from CSS variables
(global.css) and flip with the theme automatically.
Inline style + useTheme().colors|brand is required only where className can't
reach. The narrow, exhaustive exceptions:
- Animation-driven values — anything fed by Reanimated /
Animated(useAnimatedStyle, interpolations). SeeField.tsx,authui.tsx. - Gradients —
expo-linear-gradienttakes acolorsprop, useuseTheme().brand.gradient. - SVG / icon props —
lucide-react-nativecolor,react-native-svgstroke/fillare component props, not styles. - Values NativeWind can't express —
fontVariant: ['tabular-nums'], measured layout math,shadowColorglows, platform-conditional numbers.
Litmus test: if the value changes every frame, or is passed as a component prop
rather than a style, theme it inline via useTheme(); everything else is
className.
The auth screens (authui.tsx, AuthScaffold.tsx, (auth)/*) are grandfathered
100%-inline — they are working, Fabric-tuned code. Don't churn them to match this
rule; do follow the rule in everything new.
3. Theming
- Always go through tokens —
classNametokens oruseTheme()(colors,brand,accent). Never hard-code hex.accentexists because raw brand cyan is illegible on light surfaces: it resolves tocyanEdge(light) /cyanLight(dark). - Soft red (
errorSoft/error-400) reads on dark but washes out on light — pick viaisDark(seeAuthError,IconButton's danger variant). - Known debt (hard-coded hex to migrate to tokens when next touched — don't fix
drive-by):
AuthScaffoldgradient#00b8d9/#8b5cf6→brand.gradient;WeightChartstroke#00b8d9→brand.cyan;authuiLABEL_COLOR #94a3b8;weight.tsxTrash2 #f87171;RefreshControl tintColor #00b8d9(dashboard) and the_layout.tsxActivityIndicator.
4. Typography — use the primitives, or the fonts don't render
The brand fonts (Outfit for display, Plus Jakarta Sans for body) are loaded
per-weight in app/_layout.tsx — each weight is its own fontFamily
(Outfit_700Bold, PlusJakartaSans_600SemiBold, ...). Tailwind's font-bold sets
fontWeight, which does not select those families: bare font-bold /
font-semibold text silently renders in the system font.
Therefore:
- All text goes through
src/components/ui/Typography.tsx—AppText(variant + color props) or its wrappersHeading,Body,Label,Numeric, plus the legacyH1/Muted. - Bare
font-bold/font-semiboldon brand text is forbidden. Insideui/primitives, use the family classes (font-display,font-display-heavy,font-sans,font-sans-semibold,font-sans-bold,font-sans-heavy) fromtailwind.config.js. - Scale:
display28 /title24 (page H1) /heading18 (Outfit);subheading14 /body15 /bodySemibold15 /caption12 /label11-uppercase (Jakarta);numeric30 tabular (Outfit 800) for metric values. - The web uses JetBrains Mono for numerics; mobile approximates with Outfit +
tabular-numsrather than loading a third family (debt: revisit if numbers ever need true mono). - Don't stack a size class on a sized variant (
<AppText variant="body" className="text-xs">) — twofontSizeclasses leave the winner to stylesheet order. Pick the right variant;Mutedintentionally has no size so its callers'text-xskeeps working.
5. Component authoring
- One component per file in
src/components/ui/, named exports, re-exported from the barrelindex.ts(screens import the folder:../../src/components/ui). - Props declared as
interface Props(exported only when a consumer needs the type). - WHY-comments: explain the why (Fabric quirks, contrast decisions, layout constraints), never narrate the what.
- Strict TS, no
any. Generic where it pays (SegmentedControl<T extends string>). - Naming: PascalCase components, camelCase utils, hooks in
src/hooks/with auseprefix. Hooks ported from web keep the web name and a "port of web/... keep in sync" header (useNumericText). - Icons:
lucide-react-native, typed asLucideIcon, passed as the component (icon={Trash2}), sized viasizeprop.
6. Native-feel checklist
Hard-won on Fabric — violating these produces bugs that are expensive to rediscover:
- Never trigger a React re-render from a
TextInput's ownonFocus(e.g.setFocused(true)). On the New Architecture the re-render immediately re-blurs the input — keyboard flashes up, then dismisses. Drive focus styling (border/glow) off a Reanimated shared value (UI thread, zero re-renders). Reference implementations:ui/Field.tsx,authui.tsxIconInput. This applies to any focus-reactive input you ever write. - Keyboard + ScrollView: use the ScrollView's own
automaticallyAdjustKeyboardInsets+keyboardShouldPersistTaps="handled", notKeyboardAvoidingView— itspaddingbehavior fights the auto-inset and can bounce the tapped input out from under the touch. KeepAnimated.eventscroll handlers in auseRefso re-renders don't re-attach native listeners mid-focus (seeAuthScaffold). - Press feedback, haptics, safe areas: every tappable gets
active:scale-95(or anactive:background). Meaningful actions getexpo-haptics—selectionAsync()for choice changes (pills, segments),impactAsync(Light)for steppers; always.catch(() => {})(no-op platforms). Safe areas viareact-native-safe-area-contextonly (Screenhandles the top edge; tab bar / keyboard own the bottom).
State conventions: empty lists render EmptyState (never a bare string); form /
request errors render a boxed alert (authui's AuthError pattern: soft error bg,
error border, AlertCircle) or Field's error prop inline; transient success /
progression feedback uses Toast (to-build, mirror web's: icon chip + title +
description, auto-dismiss ~4s, docked above the tab bar); loading uses the control's
own loading prop (Button) or a pull-to-refresh RefreshControl — not full-screen
spinners for partial data. Full-screen initial load (a screen's first data fetch)
renders <Loading /> — the ported barbell rig — via if (initialLoading) return <Loading />, matching web; a small inline ActivityIndicator (brand color) is still
right for in-place spots like pagination footers and picker lists. Confirmations (destructive or otherwise) use
ConfirmSheet, not Alert.alert — a [pending, setPending] state drives
open/busy; it mirrors web's portal bottom sheet and stays on-theme (the OS Alert
was an interim stand-in).
7. Web → mobile component map
Web components/ui/ |
Mobile components/ui/ |
Status |
|---|---|---|
IconButton |
IconButton |
built |
SegmentedControl |
SegmentedControl |
built |
NumberField (+ useNumericText) |
NumberField (+ src/hooks/useNumericText) |
built |
PageHeader |
PageHeader |
built |
SectionHeader |
SectionHeader |
built |
StepperTile |
StepperTile |
built |
EmptyState |
EmptyState |
built |
Toast |
Toast |
built |
DateInput |
DateInput |
built (wraps @react-native-community/datetimepicker; value stays YYYY-MM-DD) |
| — (bottom-sheet shell) | Sheet |
built (base primitive — scrim-fade + slide-up, root insets, grabber; SHEET_ANIM_MS for follow-up timing. Build new sheets on this, don't re-derive the chrome) |
| portal confirm sheet (per page) | ConfirmSheet |
built on Sheet; use instead of Alert.alert for confirms — icon badge + centered copy + Cancel/confirm |
| mobile kebab (⋮) → portal menu | ActionSheet |
built on Sheet; slide-up options menu, actions: SheetAction[] (icon/label/destructive), layout='stack'|'row', optional rich header slot (item preview); fires each onPress after dismiss so a follow-up sheet doesn't overlap |
| — (semantic action presets) | editAction / deleteAction |
built (sheetActions.ts) — factories returning a SheetAction so a menu's Edit/Delete are defined once (icon + intent + default label). Prefer these over inline { icon, destructive, label }; add a preset when an action recurs. Keeps primitives free of app concepts (no kind enum, no per-action components) |
Loading (barbell rig) |
Loading |
built (full-screen initial-load state; barbell dips/flexes + rep-dot chase, Reanimated. if (initialLoading) return <Loading />, same as web) |
.card CSS class |
Card |
built |
.btn CSS classes |
Button |
built |
.input / .label CSS classes |
Field |
built (focus-glow, Fabric-safe) |
| — (web uses raw text) | Typography (AppText, Heading, Body, Label, Numeric, H1, Muted) |
built, mobile-only |
| — | Screen, Section, Stat, OptionPill, ListRow |
built, mobile-only |
Screens have not been migrated onto the new primitives yet (Section/Stat/
OptionPill/ListRow duplicate patterns still inlined in (tabs)/*) — adopt them
as screens are next touched.