![\"Aether\"](\".github/assets/banner.png\")
\n \n
\n ![\"npm](\"https://img.shields.io/npm/v/@byarcadia-app/aether?style=flat\")
![\"License\"](\"https://img.shields.io/npm/l/@byarcadia-app/aether?style=flat\")
![\"iOS](\"https://img.shields.io/badge/platform-iOS-black?style=flat\"){kind=icon}
![\"Alpha\"](\"https://img.shields.io/badge/status-alpha-orange?style=flat\"){kind=icon}
\n iOS-first React Native component library for Expo — powered by a built-in Tailwind CSS / NativeWind preset.\n
\n\nNamed after the Greek primordial deity of light and the pure upper air that gods breathe — Aether sits between your app and the design layer, providing the atmosphere for your UI.\n\n> **iOS only.** This library targets iOS exclusively. I'm building it for my own projects where iOS is the only platform I care about. Android and web are not supported and won't be.\n\n## What it does\n\n- **[Tailwind Preset](docs/colors.md)** — HSLA color token system (25+ semantic tokens) with light and dark themes\n- **[Theme Providers](docs/provider.md)** — automatic dark mode via NativeWind CSS variables (`vars()` API), global animation control with iOS Reduce Motion support\n- **Typography** — [Heading](src/ui/typography/heading/heading.md), [Text](src/ui/typography/text/text.md), [Caption](src/ui/typography/caption/caption.md) components following iOS HIG sizing\n- **[Layout](src/ui/layout/layout.md)** — VStack, HStack polymorphic flexbox primitives\n- **[Icons](src/ui/icons/icon-symbol.md)** — IconSymbol with SF Symbols (iOS), theme color integration, separate entrypoint\n- **Buttons** — [Button](src/ui/buttons/button/button.md) (5 variants, shimmer, loading), [GlassButton](src/ui/buttons/glass-button/glass-button.md) (iOS 26+ Liquid Glass), [HighlightTappable](src/ui/buttons/highlight-tappable/highlight-tappable.md)\n- **[Surface](src/ui/surface/surface.md)** — Layered backgrounds with visual hierarchy (solid, glass, fog variants)\n- **[Card](src/ui/card/card.md)** — Compound card component (header, body, footer, image) with optional pressable\n- **Forms** — [TextField](src/ui/forms/text-field/text-field.md) compound input (label, validation, clearable, multiline, animated focus) and [ErrorView](src/ui/forms/error-view/error-view.md)\n- **[List](src/ui/list/list.md)** — Compound list component (items, sections, collapsible, accessories, chevron) following iOS Settings patterns\n- **[Skeleton](src/ui/skeleton/skeleton.md)** — Pulsing loading placeholder with theme-aware colors\n- **[ScrollFade](src/ui/scroll-fade/scroll-fade.md)** — Gradient fade overlay for scroll container edges\n- **[AnimationWrapper](src/ui/animation-wrapper/animation-wrapper.md)** — Declarative enter/exit/layout animation wrapper\n- **[React Navigation](docs/hooks.md)** — theme integration hook\n- **[Inter Font](docs/hooks.md)** — built-in font loading for the Inter family\n- **[Utilities](docs/utilities.md)** — class-name merging (`cn`, `cnx`), HSLA color manipulation, compound component child extraction\n\n## Inspiration\n\nThis project draws heavily from:\n\n- [React Aria](https://react-spectrum.adobe.com/react-aria/) — Adobe's headless UI primitives. The gold standard for accessible component architecture and composable API design.\n- [HeroUI Native](https://github.com/heroui-inc/heroui-native) — A React Native component library built on NativeWind and tailwind-variants. Closest to what Aether aims to be in terms of styling approach.\n- [RN Primitives](https://github.com/roninoss/rn-primitives) — Unstyled, accessible primitives for React Native.\n- [React Native Reusables](https://github.com/founded-labs/react-native-reusables) — shadcn/ui patterns adapted for React Native.\n\n## Documentation\n\n- [Installation & Quick Start](docs/installation.md)\n- [AetherProvider](docs/provider.md)\n- [Components](docs/components.md)\n- [Hooks](docs/hooks.md)\n- [Utilities](docs/utilities.md)\n- [Color Tokens](docs/colors.md)\n\n## AI Tools\n\nThis library ships with built-in AI agent support:\n\n- **[Claude Code Skills](https://skills.sh)** — `aether-ui` (component API reference) and `aether-setup` (installation guide). Install via [skills.sh](https://skills.sh) or add `skills/` to your project.\n- **[Context7](https://context7.com)** — AI agents can query up-to-date docs and usage patterns via `context7.json`. Use `use context7` in your prompt to activate.\n\n## Example App\n\nA complete working integration lives in `example/`. It demonstrates provider setup, Storybook integration, and all component variants.\n\n```bash\npnpm example:start # Start Expo dev server\npnpm example:ios # Run on iOS simulator\n```\n\n## Requirements\n\n| Dependency | Version |\n| ------------------------ | ----------- |\n| React | >= 18 |\n| React Native | >= 0.72 |\n| NativeWind | >= 4 |\n| react-native-reanimated | >= 3 |\n| @callstack/liquid-glass | >= 0.7 |\n| expo-linear-gradient | >= 14 |\n| expo-haptics | >= 14 |\n| Tailwind CSS | ^3.3.5 |\n| @expo-google-fonts/inter | >= 0.4.2 |\n| Expo | recommended |\n\n## License\n\nMIT\n","readmeFilename":"README.md"}