aether-ui

iOS-first React Native component library built as a Tailwind CSS / NativeWind preset for Expo. All components use tailwind-variants for styling and NativeWind CSS variables for theming.

Color tokens: See colors.md Hooks & utilities: See hooks.md, utilities.md Provider setup: See provider.md Detailed component API: See references/ directory

iOS Only

This library targets iOS exclusively. Android and web are not supported and won't be. Do not add platform checks or cross-platform fallbacks.

Imports

All components are named exports from the main entrypoint:

import { Button, ButtonLabel, Card, CardHeader, Text } from "@byarcadia-app/aether";

Icons are a separate entrypoint:

import { IconSymbol } from "@byarcadia-app/aether/icons";

Compound Components

Card, TextField, and List use sub-components composed as children (not configuration props). All sub-components are flat named exports — import them directly. Internally, each has a displayName like Aether.Card.CardTitle used by getElementByDisplayName() to extract and position children. See individual reference files for usage examples.

Styling System

All component styling uses tailwind-variants (tv()) from the tailwind-variants package. Variant constants are exported as named exports for external access (e.g., buttonVariants, textVariants).

• cn(...classes) — Fast string join. No conflict resolution. Use for simple concatenation.
• cnx(...classes) — Merge with Tailwind conflict resolution via tailwind-merge. Prefer this when accepting className from component props.
• Custom color palettes via colorPalette prop on AetherProvider.

-> utilities.md for full utility API.

Color Tokens

HSLA-based semantic color system via NativeWind CSS variables. Tokens: base (background, foreground, surface), semantic (primary, secondary, success, warning, danger, info), UI (muted, border, input, ring), special (glass, tag colors). Every semantic color has a -foreground variant.

Usage: bg-primary, text-foreground, text-danger-foreground, border-border, bg-muted.

-> colors.md for the complete token table.

Hooks

• useInterFonts() — Load Inter font family
• useColorScheme() — Get "light" or "dark"
• useThemeColor(token) — Resolve token to runtime HSLA string
• useNavigationTheme() — React Navigation theme with aether colors
• useAnimationDisabled() — Check global animation-disabled state

-> hooks.md for full signatures and examples.

Haptics

Exports hapticsImpact(style: HapticFeedbackStyle) for triggering haptic feedback. Button has a built-in haptics prop. Use hapticsImpact() directly for custom interactive components.

Provider Setup

All aether components require AetherProvider at the root. Key props: colorPalette, disableAnimations, allowFontScaling, maxFontSizeMultiplier.

-> provider.md for full configuration options.

References

Typography

Heading: H1–H4 components following iOS Human Interface Guidelines sizing. Inter font family with configurable weight. Text: Body text with size variants (lg, md, sm, xs) and weight variants (regular, medium, semibold, bold). Caption: Small auxiliary text in two sizes (md, sm). Muted foreground color by default.

Buttons

Button: Primary interactive element with 5 variants (primary, secondary, outline, ghost, destructive). Supports shimmer, loading spinner, haptic feedback, press animation. Compound: ButtonLabel, ButtonShimmer. GlassButton: iOS 26+ LiquidGlass button via @callstack/liquid-glass. Falls back to standard primary Button on older iOS. HighlightTappable: Lightweight press feedback wrapper with subtle background highlight on touch.

Forms

TextField: Compound input with TextFieldLabel, TextFieldInput, TextFieldInputStartContent, TextFieldInputEndContent, TextFieldDescription, TextFieldErrorMessage. Animated focus border, clearable, multiline, validation. ErrorView: Conditional error message display. Renders danger-colored message when error string provided, nothing otherwise.

Layout & Structure

Layout (VStack / HStack): Polymorphic flexbox primitives. Accept as prop to render as any React Native component. Card: Compound card with CardHeader, CardTitle, CardDescription, CardBody, CardImage, CardFooter. Optionally pressable with haptics. Surface-based variants (solid, glass, fog). Surface: Layered background container. Three variants: solid (opaque), glass (translucent blur), fog (subtle gradient). Auto-darkens by nesting depth via level prop. List: Compound list following iOS Settings patterns. ListItem, ListItemContent, ListItemIcon, ListItemAccessory, ListSectionHeader, ListItemChevron (animated), ListItemCollapse (animated expand/collapse).

Feedback

Skeleton: Pulsing loading placeholder. Theme-aware, respects global animation-disabled state. ScrollFade: Gradient fade overlay for scroll container edges. Position top or bottom. AnimationWrapper: Declarative enter/exit/layout animation via react-native-reanimated. Consumer-controlled, not affected by global animation-disabled state.

Icons

IconSymbol: SF Symbols component for iOS via expo-symbols. Separate entrypoint: @byarcadia-app/aether/icons.

Theming & Configuration

Colors: Complete HSLA color token table for light and dark themes. Provider: AetherProvider configuration — theme injection, animation control, text config. Hooks: All hook signatures and usage examples. Utilities: cn(), cnx() class name utilities and other helpers.