Components

Every reusable UI primitive in frontend/components/ui/. These are theme-aware, presentation-only — no service calls, no business logic. Feature composites belong in higher-level folders (components/auth/, components/chat/, etc.).

This page is the catalog. For implementation details (the makeStyles(theme) factory pattern, how useTheme() flows in), see Frontend → Architecture.

Foundational

Button Primary (gold gradient), secondary (surface high), tertiary (ghost). Loading and disabled states. Always uses the md border radius.

Input Text input with floating label, validation, leading/trailing icon slots. Focus shifts background to surfaceContainerHighest and label to primary — no border swap.

Chip Tag / filter pill. Uses sm radius. Supports campfire-palette tinting for categorical accent.

Logo App mark, SVG, theme-aware. The only sanctioned brand mark in the codebase.

Layout & containers

ActionBar Sticky bottom action bar. Used inside modals and sheets when the primary action should always be reachable. Auto-respects safe-area insets on iOS.

GlassView Frosted/blurred surface. expo-blur on native, CSS backdrop-filter on web. Use sparingly — every glass surface is a moment.

NavBottomSheet Bottom sheet that hides the bottom nav while open (toggles isNavHidden via SheetContext). Pair with rich content that wants the full screen.

SnapBottomSheet Bottom sheet with snap detents (half-screen / full-screen). Pure UI gesture, no nav coupling.

Sheet (footer) The base sheet wraps a footer element in a standard action bar (surface background, 16 padding, safe-area bottom inset) and pads the body to clear it. footerBare opts out and renders the footer element as-is; footerOptions.keyboardOffset tunes keyboard avoidance. See SheetProps / ScreenSheetProps.

SwipeRow iOS-Mail-style left-swipe row: reveals one action (right) or several (rightActions, ~46px each); a single action can full-swipe to fire. Snaps open and holds until tapped or another row opens. Built on Reanimated + gesture-handler.

AnchoredPopover Popover anchored to a target element. Auto-flips position to stay in viewport.

Tooltip Hover tooltip on web, long-press tooltip on native. Same API; Platform.OS handles dispatch.

Feedback

Toast Notification rendered by ToastContext. Single queue. Variants: success, warning, error, info.

ConfirmationModal Yes/no destructive-action modal. Default-focuses the safe (cancel) button on open.

ConfirmDialog Centered confirm/destructive prompt (title + message + cancel/confirm). A modal, never a bottom sheet: confirms are usually raised from inside another sheet, where a second stacked sheet is confusing. Backs both useConfirm() (planner) and ConfirmSheet; destructive renders the confirm CTA in the danger tone.

ShareSheet Bottom sheet (mobile) / centered card (web) with circular brand-color targets (copy, native share, Messages, WhatsApp, X, Facebook, Reddit, LINE, in-app chat) and a copy-link bar.

Media & social

AssetImage Standard renderer for every network-loaded Tomoda asset (avatars, chat photos, moments, stamps, event covers). Wraps expo-image with memory-disk caching and a stable cacheKey derived from the URL path so cache entries survive base_url drift (DHCP, CDN swap). Pass cacheKey explicitly when the immutable storage key is available directly (e.g. chat metadata.images.keys).

UserAvatar Avatar with online indicator and initials fallback. Three sizes: sm, md, lg.

GroupAvatar Composite avatar for group chats — tessellates up to 4 participant avatars in a single circle.

GalleryCard Media gallery tile used in moments / events. Handles single image, multi-image carousel, and video preview.

StatCard Numeric stat tile (label + value + optional delta). Used on profile and admin dashboards.

Decorative & motion

FadeInView Mount animation wrapper. Default ease-out 240ms.

ScrollRevealView Reveals children as they enter the viewport on scroll. Used on landing / website surfaces, not in-product.

VoxelSlot Decorative animated tile (used on landing pages and brand-moment screens). The "physical display box" that grounds the 3D-toy aesthetic into the 2D UI.

Composition rules

• Use the primitive as-is. If you need a variant, add it to the primitive — don't fork.
• Stylesheet factories. Every component declares const makeStyles = (theme) => StyleSheet.create({...}) at the top. Components read theme via useTheme() once and memoize the resulting sheet — the factory runs on theme change, not on every render.
• Compose, don't extend. Build feature components by composing primitives. A ChatMessageBubble is a View wrapping UserAvatar + body-lg text + (optional) Toast-style reaction tray. It doesn't subclass anything.

Buttons and i18n length

Translated labels can be 20–40% longer than English (German for compound nouns, Finnish for case suffixes, Polish for long roots). The button primitive uses a three-tier graceful degradation so non-English labels never overrun siblings and almost never truncate with ….

Tier 1 — Standard row (default)

Wrap a row of buttons in <ButtonRow> from frontend/components/ui/Button.tsx. Every child is forced to flex: 1, so widths stay matched and side-by-side buttons render at the same font size. The label uses numberOfLines={1} + ellipsizeMode="tail" + flexShrink: 1. (We deliberately do not use adjustsFontSizeToFit — it shrinks each Text independently and produces mismatched font sizes across buttons in a row.)

Tier 2 — Compact size

For rows known to be tight even in English ("Accept" / "Decline" + "Block"; "Join" / "Chat" + "Manage"), pass size="compact" to the children. The primitive shrinks font (15→12) and horizontal padding (20→12), buying ~25% horizontal headroom before any stacking kicks in.

<ButtonRow>
  <Button size="compact" title={t('friend_detail.message')} ... />
  <Button size="compact" title={t('friend_detail.profile')} ... />
  <Button size="compact" title={t('common.share')} ... />
</ButtonRow>

Tier 3 — Auto-stack

If the natural label widths still wouldn't fit at the container's available width, <ButtonRow> flips to a vertical column (each child rendered full-width). Triggered only when text truly overflows — a small slack threshold prevents cosmetic stacking when labels are at the edge.

Set autoStack={false} if you've already designed for the worst case and want the row to stay horizontal regardless.

Authoring rule

Action-button text in feature components (actionBtnText, cancelBtnText, etc.) should follow the same pattern: add flexShrink: 1 to the style and pass numberOfLines={1} ellipsizeMode="tail" on the <Text>. Prefer <Button> + <ButtonRow> over hand-rolled <TouchableOpacity> for any new action surface.

Adding a primitive

1. Drop the file in frontend/components/ui/.
2. Follow the makeStyles(theme) pattern. No service calls inside, no business logic — just rendering.
3. Add an entry to this page in the same PR, under the appropriate grouping above. Include: purpose, key variants, sizing if relevant.
4. If the new primitive uses a previously-unused color token, also update Color.
5. If it introduces a new motion duration or easing, also update Motion.

Storybook?

Not today. The catalog above + the source files are the canonical references. A live Storybook is a candidate future addition; for now, pull the component into a temporary playground screen if you need to iterate visually.