# @opointo/ui

> Design a multi-screen app in a browser at opointo.com, then emit it as a real
> React Native / Expo project you own: navigation, tab bar, providers and scroll insets
> already wired, with your screens inside. One codebase for iOS and Android, and on
> iOS 26 the controls are the real system ones rather than a web approximation.
>
> These are the components that app is built from. Real `UIGlassEffect` with an
> automatic `expo-blur` fallback; copy-paste friendly registry for AI tools.
>
> Sold as ONE subscription: $25 per seat per month, or $20 billed yearly, covering the whole
> catalog and the build tools. There are no per-pack purchases and no bundles. The lookup
> tools on the MCP server at `https://opointo.com/api/mcp` are free and need no account,
> and anything exported keeps working forever, including after cancellation. Setup for each
> coding agent (Claude Code, Cursor, Codex, VS Code, Gemini CLI): https://opointo.com/mcp

## Hard constraints (do not violate)

- `expo-glass-effect` requires a **dev-client / EAS build — NOT Expo Go**.
- Real glass renders on **iOS 26+ only**; older iOS uses the expo-blur fallback, and Android
  renders Material 3 Expressive, never glass.
- Several components are platform-split (`Name.ios.tsx` / `Name.android.tsx`, no base
  `Name.tsx`): write BOTH files under their exact names when installing one — Metro
  resolves the right one per platform at bundle time.
- The governing runtime rule: native `UIGlassEffect` renders **blank** if you
  (a) alpha-animate a view containing it, or (b) mount it on demand over another glass
  surface. So: **animate transform only**, **keep glass always-mounted** (swap props,
  don't remount), use **`forceBlur`** as the escape hatch for fade-in/out surfaces, and
  put **no `overflow:hidden`/border on the native path**.
- **Never `flex: 1` on content inside a glass surface** — use `alignSelf: "stretch"` plus
  an explicit `height`. `flex: 1` sets `flexBasis: 0` on the wrapper's vertical axis, the
  surface's auto height resolves to `0`, and it renders nothing on either path. Silent:
  no warning, no error. If a glass component draws nothing, drop a plain `View` with a
  `backgroundColor` and `minHeight` in the same slot before touching any animation —
  box-but-empty means the child is collapsing, no-box means the parent has no size.

## Required provider nesting (app root)

GestureHandlerRootView → KeyboardProvider → SafeAreaProvider(initialWindowMetrics)
→ ThemeContextProvider → MenuDismissProvider → app.

## How to get a whole app (the usual path)

Design it at opointo.com, or connect to the MCP server at `https://opointo.com/api/mcp`
and call `emit_app`. You get a complete Expo project — navigation, tab bar, provider order
and scroll insets already wired, with the screens in it. The lookup tools there (which
component, what props, what rule, does this snippet break) are free.

## How to add a single component

Fetch `r/<name>.json` (needs `Authorization: Bearer <subscription key>` unless the item's
`pack` is "foundation"), install `allDependencies`, then write each `files[].content`
to `files[].target`, following `installOrder` (dependencies first). Keep imports
relative — the file layout already resolves. Full recipe: `AGENTS.md`.

`pack` (`core`, `morph`, `foundation`) is a taxonomy label, NOT something you can buy
on its own.

## Components

Foundation (free, installed by almost everything):
- theme — The themeable base every component needs: color tokens, spacing/radius/typography, the ThemeContext provider + hooks, and the PlatformMaterial native-glass/blur swap-point.
- haptics — Thin wrapper over expo-haptics so call sites never import the SDK directly.
- motion-tuner — Shared on-device tuner plumbing: a minimal frame (preview + always-visible controls, no studio shell), five leaf control primitives (Slider/Choice/Swatch/Toggle/Note), a copyable readout, and a pure prop-formatting helper. No component-specific tuning data lives here — it's the free framework a paid component's own tuner screen builds on (see bottom-sheet). regdeps: theme.
- dismiss-layer — Always-mounted full-screen tap-catcher for 'outside tap dismisses this menu/pill' — avoids the white-corner flash a conditionally-mounted catcher causes over native glass.
- menu-dismiss — Global 'a native ⋯ menu is open' tracker + screen-level DismissLayer, so an outside tap dismisses the menu instead of falling through. regdeps: dismiss-layer.
- pill — The shared interactive Liquid Glass capsule/circle every glass button and pill is built from — native GlassView with a PlatformMaterial blur fallback, no clip so it lenses on press-drag (#7). regdeps: theme.
- material-host — The single mounting point for every Jetpack Compose subtree on Android, themed from our palette rather than the device wallpaper and dark-mode setting. Every Material 3 component half imports it instead of @expo/ui's bare Host. regdeps: theme.
- material-icons — The Material Symbols vector drawables Android's Compose components need (nine tab identities, the glyphs Material controls draw, and the common FAB menu actions), with a typed name→drawable map. Apache 2.0, from google/material-design-icons. Needed because Compose's Icon takes a require()d XML drawable and Ionicons are font glyphs.
- material-expressive — A small native Android module adding the Material 3 Expressive components @expo/ui does not wrap: a button that changes shape while pressed, a connected button group, the 64dp Expressive navigation bar (Compose's ShortNavigationBar) and the FAB menu (Compose's FloatingActionButtonMenu). Kotlin + Jetpack Compose, pinned to @expo/ui's Material version. Requires `expo.autolinking.nativeModulesDir: "./src/modules"` in package.json and a native rebuild.
- toolbar — The +/⋯ merged capsule — one continuous glass surface (like the iOS system menu bar); ⋯ can be a real native UIMenu. Building block behind SearchToolbar. regdeps: theme, pill, menu-dismiss.
- gradient-background — A static vertical linear gradient — the backdrop every glass surface floats over. A native gradient view (CAGradientLayer / android.graphics.LinearGradient), not a drawing canvas. regdeps: theme.
- app-background — Full-screen wrapper around GradientBackground; reads the active gradient from useBackgroundGradient(). regdeps: theme, gradient-background.

Core components:
- button — Labelled button. variant: neutral/accent/danger; size: sm/md/lg (32/44/56 on iOS; Material's 32/40/56 on Android, where it changes shape while pressed); icon, busy, disabled. regdeps: theme, pill, material-host, material-expressive.
- icon-button — Icon-only circular button — the standard back/close/add control. regdeps: theme, pill.
- stepper — A −/+ stepper: the real UIStepper on iOS (system Liquid Glass on iOS 26), two separate Material 3 tonal icon buttons on Android. Each end disables at its bound. regdeps: theme, haptics, material-host, material-icons.
- chips — A row of multi-select filter chips: glass pills on iOS that swap the native tintColor in place (never remounts, #7); Material 3 filter chips with a checkmark on Android. regdeps: theme, pill, haptics, material-host, material-icons.
- segmented-control — SegmentedControl control — the real UISegmentedControl on iOS (system Liquid Glass thumb on iOS 26); a Material 3 Expressive connected button group on Android, whose segments change shape when pressed and selected. regdeps: theme, material-host, material-expressive.
- slider — Value slider — the real UISlider on iOS (system Liquid Glass thumb + momentum stretch on iOS 26); the real Material 3 slider on Android. regdeps: theme, haptics, material-host.
- date-time-picker — The system date and time picker: the compact UIDatePicker on iOS (or, opt-in, glass pills over the UIDatePicker wheels), and Material 3's date and time dialogs on Android. regdeps: theme, pill, surface, material-host.
- action-sheet — Action sheet — the real UIAlertController on iOS (system Liquid Glass, zero deps); a glass bottom sheet with a row per option on Android. regdeps: theme, bottom-sheet.
- switch — On/off switch — the real UISwitch on iOS (system Liquid Glass on iOS 26, no extra dependency); the real Material 3 switch on Android. regdeps: theme, haptics, motion-tuner, material-host.
- card — Padded translucent card — PlatformMaterial + default padding. List rows, tiles. regdeps: theme.
- surface — Full-bleed glass background for sheets/modals — top-corner rounding by default, optional drag-handle. regdeps: theme.
- bottom-sheet — A glass bottom sheet — always-mounted, translateY-only, drag-to-dismiss (#7-safe by construction). Built on Surface. regdeps: theme, surface, motion-tuner.
- keyboard-toolbar — Above-keyboard glass toolbar shell — always-mounted sticky view + glass that mounts fresh while active and fades with the keyboard. regdeps: theme, pill.
- search-bar — A search field: interactive glass on iOS, where on focus a Cancel affordance slides in (transform-only) and the glass stays mounted (#7); a Material 3 search field on Android with a search icon and a close button. regdeps: theme, pill, material-host, material-icons.
- menu — A standalone native UIMenu on a glass trigger (extracted from Toolbar) — on iOS 26 it renders as system Liquid Glass; includes the outside-tap dismiss plumbing. regdeps: theme, pill, menu-dismiss.
- header — Floating top bar whose blur (one BlurView + a native-gradient mask) fades out vertically (iOS-Reminders nav-bar style) — content scrolls under it and blurs gradually on iOS; a solid Material surface on Android. Exports useHeaderInset(). regdeps: theme.

Morph components:
- animated-icon-button — A persistent glass circle whose icon content cross-fades (back↔×↔✓) — never remounts, so it morphs instead of popping. regdeps: pill.
- quantity-stepper — "Add" morphs into a −/+ stepper the moment the quantity leaves zero: on iOS one continuous glass capsule that never remounts (the width is animated on plain content INSIDE the glass so the capsule resizes to fit, #7); on Android Material's tonal button, which widens into two tonal icon buttons with the value between them. regdeps: theme, pill, haptics, material-host, material-icons.
- fab-menu — A FAB that opens a menu of actions: on iOS a cluster of glass actions whose glass fuses into one blob while closed (GlassContainer) and splits as it opens, transform-only (#7); on Android Material 3 Expressive's FAB menu, labelled items rising above a toggle FAB. regdeps: theme, material-host, material-icons, material-expressive.
- media-controls — A media transport card composed from the glass primitives — scrubber, skip buttons, and a play/pause AnimatedIconButton whose icons cross-fade. regdeps: theme, card, icon-button, animated-icon-button, slider.
- search-toolbar — Search as a secondary action. On iOS the search-expand morph: tap + and it rotates into ×, the ⋯ collapses away, and a glass search field slides in from the right, all off one shared value. On Android Material's pattern: a search icon button beside an overflow menu, opening a round Material 3 search field with a back arrow. regdeps: theme, pill, toolbar, search-bar, material-host, material-icons, menu-dismiss.
- status-pill — A compact status pill that expands into a live-activity card and collapses back. Width, height and corner radius animate on plain content inside the glass, so the surface resizes to fit rather than being scaled or remounted (#7). regdeps: theme, pill.
- tab-bar — A self-drawn floating glass tab bar with a native-glass lens that springs to the active tab (transform-only, #7). Minimizes into a compact icon-only pill on scroll (feed it a reanimated scrollY) — the self-drawn match to iOS 26's native tab-bar minimize. Copy-paste source you own. regdeps: theme, haptics, material-host, material-icons, material-expressive.

## Renamed components (old names still work)

These were renamed on 2026-09-21 to the names the platforms and the major React Native
libraries already use. Every old name still resolves — in `/r/<name>.json`, in every MCP tool
argument, and in `update_components` — and always will. Use the new name in new code.

- morph-tab-bar → tab-bar
- toggle → switch
- segmented → segmented-control
- sheet → bottom-sheet
- context-menu → menu
- floating-header → header
- keyboard-toolbar-shell → keyboard-toolbar
- action-cluster → fab-menu
- morph-button → animated-icon-button
- morph-stepper → quantity-stepper
- morph-pill → search-toolbar
- morph-activity → status-pill
- header-action-pill → toolbar

## Compatibility

Verified on iOS 26 and on Android 16 with Material 3 Expressive. iOS 27 support is in progress.

- iOS 26 (Liquid Glass): Verified 2026-09-26
- iOS 27 (Liquid Glass, revised): In progress
- Android 16 (Material 3 Expressive): Verified 2026-09-26
- Android 17 (Material 3 Expressive): Not yet

Build the iOS app on a Mac with Xcode 26; the Android app needs the Android SDK at API 36 and no Mac. A project on Expo SDK 56 built with Xcode 27 crashes at launch on iOS 27, because the iOS 27 SDK requires the UIKit scene life cycle (Apple TN3187; expo/expo#46664). The fix, which we are adopting, is Expo SDK 57 (expo 57.0.23 or later and expo-build-properties 57.0.20 or later) with ios.enableSceneSupport.

## Source

Registry index: `registry.json`. Per-item: `r/<name>.json`. Provider/runtime detail:
`AGENTS.md` and the package `README.md`.