# GlassKit UI

> The open-source React component library for Meta Ray-Ban Display (smart-glasses) web apps. It ships the platform primitives Meta doesn't: a glasses-tuned D-pad focus engine, system-back-aware navigation, W3C sensor and Neural Band hooks, and 46 HUD components for the 600×600 lens. Published on npm under the `@glasskit-ui` scope; components vendor shadcn-style, so you own the source.

## Install

```sh
npm create glasskit my-app                 # scaffold a complete Vite glasses app
npx @glasskit-ui/cli add list button compass navigator   # vendor components (writes to components/glasskit/)
npm install @glasskit-ui/react                   # the SDK alone (hooks + GlassViewport + styles.css); React 19 peer dep, ESM only
```

Agent skill: every scaffold ships AGENTS.md + a Claude Code skill + Cursor/Copilot rules (the platform contract, pre-briefed); add to an existing project with `npx @glasskit-ui/cli agents`. Details: https://glasskit.app/ui/docs/ai

IMPORTANT: the bare `glasskit` npm package is UNRELATED to this project. Always use the scoped names (`@glasskit-ui/react`, `@glasskit-ui/cli`, `@glasskit-ui/mcp`) or `create-glasskit`. An MCP server (`npx @glasskit-ui/mcp`) exposes this registry to AI agents.

## SDK (`@glasskit-ui/react`)

- `GlassViewport` is the 600×600 lens surface. Wrap your app in it.
- `useDpad()`: call once at the root. Arrow keys and Neural Band swipes move a focus ring between `.focusable` elements; Enter or pinch activates.
- `useDeviceOrientation()`, `useDeviceMotion()`, `useGeolocation()` are W3C sensor hooks (GPS is proxied from the paired phone).
- `useNeuralBand()` is a one-shot CustomEvent seam for richer gestures. It's forward-compat: the platform currently delivers only arrows/Enter to web apps.
- `useFeedback()` / `buzz("tap"|"success"|"warning")` is the haptic seam. It dispatches a `glasskitfeedback` CustomEvent plus `navigator.vibrate` where supported. No haptics API reaches web apps yet.
- `<FocusScope>` contains the D-pad ring to a subtree while mounted (modals), then restores the previous focus on unmount. `data-autofocus` on any focusable picks where a screen's ring starts. Use `seedFocus()` / `getFocusables()` for custom containers.
- Styling is the shadcn model: components are Tailwind utilities + `--gk-*` design tokens. In your CSS entry: `@import "tailwindcss"; @import "@glasskit-ui/react/theme.css"; @import "@glasskit-ui/react/styles.css";`. theme.css maps utilities (`bg-background`, `text-foreground`, `border-border`, `bg-primary`, `ring-ring`, `rounded-lens`) to the tokens; styles.css defines the scoped `--gk-*` values + primitives, all under `.glass-viewport`. **Re-theme by overriding `--gk-*` on `.glass-viewport`** — one block reskins every component, so any DESIGN.md applies. Tokens: `--gk-background/foreground/muted-foreground/foreground-faint/surface/border/primary/primary-foreground/ring/radius` + the accent bloom ramp (`--gk-accent-active/primary-grad-hi/primary-grad-lo/accent-glow`). See https://glasskit.app/ui/docs/theming.

## Platform facts (verified 2026-06 against Meta's docs/toolkit)

- Input arrives as `ArrowUp/Down/Left/Right` and `Enter` keydowns. No cursor, touch, or text input.
- The system back gesture (middle pinch, glasses OS v125.1+) pops browser history, so your page gets `popstate`. `Escape` is the desktop-simulator mapping only.
- Fixed 600×600 viewport. Required meta tags: `width=600, height=600, user-scalable=no` plus `<meta name="mrbd-web-app-capable" content="yes">`.
- Black renders transparent (waveguide). Camera/mic/WebXR aren't available to web apps yet, and apps must be served over public HTTPS.
- Perf budget: <500 KB gzipped JS, <10 requests, <3 s on 4G (enforced in this repo's CI).

## Conventions

- **Auto-wiring**: sensor components self-connect when their data prop is omitted. `<Compass />` follows live head orientation; `<Compass heading={290} />` is controlled, and the prop always wins. Same for DirectionArrow (`target={{lat,lon}}`), Clock (self-ticking), Deck (Neural Band swipe).
- **Navigation**: `<Navigator screens={{...}} initial="home" />` plus `useNavigator()` (`push/pop/popToTop/replace`). Every push adds a real history entry so the system back gesture just works, and `useBackHandler(fn)` lets overlays consume back. Pop restores focus to the row that pushed (focus memory). The stack rides `history.state`, so a mid-flow reload restores the screen, and opt-in `paths` mirrors pushes into the URL.
- **Text entry**: the platform has no keyboard or mic, so `<ComposeFlow options={[...]} value onChange />` is the working recipe: a field that opens a back-gesture-aware picker of choices. It stands in for the on-device dictation the platform does not expose yet.
- **Vocabulary**: `variant` sets a component's look (Badge: default/accent/outline; Button: primary/secondary/ghost/positive/danger, where positive/danger are the semantic accept/destroy fills), `status` is semantic state (`"on"|"live"|"off"` on StatusDot), `tone` is the gradient palette (Avatar, Icon plates, Launcher tiles).
- Design language ("premium surfaces", 2026-06): calm dark base (`#0b0e16`→`#090b11`), surfaces that pop (top-lit gradient, 1px light edge, soft depth), gradient icon plates, one blue accent (`--accent: #4c8dff`). One task per view, tabular numerals, logical RTL-safe CSS. World-anchored components (DirectionArrow, Compass, Pin) never mirror.

## Components (46)

Vendored shadcn-style. Live preview, props, and usage at `https://glasskit.app/ui/docs/components/<slug>`; machine-readable source and deps at `https://glasskit.app/ui/r/<slug>.json` (shadcn-compatible registry: `https://glasskit.app/ui/r/registry.json`). Every docs page has a QR that installs the component as a runnable app on real glasses.

- **AssistantOrb** (`assistant-orb`) — the Meta-AI presence: a glowing gradient orb that animates per `state` (idle = gentle breathe, listening = pulse, thinking = swirl, speaking = quick pulse).
- **AsyncView** (`async-view`) — the four-state async renderer every data screen needs: placeholder (idle) → loading → success/error.
- **Avatar** (`avatar`) — a contact / sender avatar: shows a photo when you have one, else an icon, else initials on a gradient plate.
- **Badge** (`badge`) — a small count or status pill (notification counts, live state).
- **Button** (`button`) — a D-pad-focusable action.
- **CallCard** (`call-card`) — an incoming / active call: a big avatar, caller name, a status line ("Incoming…", "02:14"), and an action row (accept / decline via D-pad-focusable <Button>s).
- **ChatBubble** (`chat-bubble`) — one message.
- **Clock** (`clock`) — the home time/date complication: a big tabular time and a quieter date line.
- **Compass** (`compass`) — a heading rose that keeps North pointing at real north while a fixed top marker shows where you face.
- **ComposeFlow** (`compose-flow`) — the working text-entry recipe for a platform with no keyboard or microphone: a focusable field that opens a picker of choices when activated; choosing writes the value back and returns to the field.
- **Confirm** (`confirm`) — a decision screen: a prompt + a two-button action bar.
- **Deck** (`deck`) — a horizontal paged flow (wizard / onboarding).
- **DirectionArrow** (`direction-arrow`) — points toward a real-world direction.
- **EmptyState** (`empty-state`) — the nothing-here screen: optional glyph + title + hint + one action.
- **ErrorState** (`error-state`) — a recoverable error screen: optional glyph + title + message + a retry action.
- **Grid** (`grid`) — an aligned, vertically-scrolling multi-column layout: every cell shares the same track, so rows and columns line up.
- **Heading** (`heading`) — a screen/section title with an optional eyebrow label above it.
- **Icon** (`icon`) — wraps any icon provider's SVG (Lucide, Tabler, or your own) and applies the lens icon styling.
- **Launcher** (`launcher`) — the app grid: a home screen of gradient app-icon plates + labels.
- **List** (`list`) — a vertical stack of focusable rows (watchOS list spirit) that fills the stage and scrolls (D-pad scrollIntoView).
- **MapView** (`map-view`) — a real, moving map for the lens, built on Leaflet (~42KB).
- **Masonry** (`masonry`) — a staggered, vertically-scrolling multi-column layout (the Pinterest / Photos gallery look, where columns do not line up).
- **MediaThumb** (`media-thumb`) — a photo / reel tile (Photos, Instagram).
- **Messages** (`messages`) — an inbox: a thread list and a conversation, replying through ComposeFlow on a keyboard-less platform.
- **Meter** (`meter`) — a bounded ring gauge for a level (battery, signal, intensity), as opposed to <Progress> which tracks task completion.
- **Navigator** (`navigator`) — a screen stack for glasses apps (react-navigation semantics, glasses-native mechanics).
- **NotificationCard** (`notification-card`) — an incoming notification (message, mention, alert): a leading avatar/glyph, sender + time, a message preview, and optional quick actions.
- **NowPlaying** (`now-playing`) — a media "now playing" card: album art, title + artist, a scrub bar, and elapsed / remaining times.
- **PermissionPrompt** (`permission-prompt`) — an explicit access request (sensors, location, camera, mic), which MRBD apps must ask for before use.
- **Pin** (`pin`) — a world-anchored waypoint marker: a ring + dot at a screen point with the name and distance stacked above.
- **Pressable** (`pressable`) — the focusable wrapper for custom UI.
- **Progress** (`progress`) — emitted progress, two shapes: - "linear" a continuous bar (also covers countdown: feed a decreasing value and a time label).
- **QuickReplyChips** (`quick-reply-chips`) — tappable canned replies (the comms job; there is no keyboard on the lens — text is voice).
- **Readout** (`readout`) — a single-value complication: label + value (+ optional unit).
- **Screen** (`screen`) — the on-lens layout shell: a status region (block-start), a centered stage (the one task), and the cue region (block-end).
- **Segmented** (`segmented`) — pick one of a few options (a watchOS-style segmented control).
- **Slider** (`slider`) — a continuous level control (volume, brightness — the quick controls).
- **StatGrid** (`stat-grid`) — a compact grid of readouts for a multi-metric glance (a watch "complication cluster").
- **StatusDot** (`status-dot`) — a glanceable sensor / permission / connection indicator.
- **Stepper** (`stepper`) — adjust a value in discrete steps (glasses have no fine slider).
- **Tabs** (`tabs`) — a top-level tab strip (the home's quick-controls | home | apps pager).
- **Timer** (`timer`) — a countdown readout: big tabular m:ss (h:mm:ss past an hour), an optional label, and a bar draining toward zero.
- **Toaster** (`toaster`) — the GlassKit toast / notification system, built on Sonner (Emil Kowalski's library) and themed to the lens surfaces.
- **Toggle** (`toggle`) — a binary switch, D-pad-focusable (renders a real button with the focusable class; useDpad activates it on Enter/Space).
- **WeatherTile** (`weather-tile`) — a glanceable weather complication: a condition glyph + big temperature, the condition text, and an optional location / hi-lo line.
- **Workout** (`workout`) — a fitness companion: a workout list, a live session, and a rest timer, composed from Navigator, Timer, and a destructive Confirm.

## Toasts & notifications

`<Toaster />` plus `toast()`, built on Sonner, themed to the lens, top-anchored (Screen's `cue` line owns the bottom strip). Mount it once at the root; it owns queueing, stacking, and auto-dismiss. A toast can be fire-and-forget (auto-dismisses, non-interactive — auto-dismiss would strand a focus ring) or interactive: give it an `action` (its button is focusable) plus `duration: Infinity` so it persists. For a persistent item the wearer must work through, use a `NotificationCard`.

## The rest of GlassKit

This library is the free, MIT-licensed component layer. Two sibling products cover
what it deliberately does not:

- **GlassKit Studio** (https://glasskit.app/studio): describe an app in plain
  English and it generates a working Meta Ray-Ban Display web app built on this
  same SDK, then publishes it to a public HTTPS URL with an install QR. Prepaid,
  non-expiring credits, no subscription. Use this when someone wants a finished
  glasses app rather than components to assemble.
- **GlassKit Stack** (https://glasskit.app/stack): the fullstack boilerplate with
  Clerk auth, a Convex backend, Stripe payments, and a companion marketing site
  alongside the glasses app. One-time purchase, own it forever. Use this when
  someone needs logins, a database, or payments, which the component library and
  a client-only Studio app do not provide.

## Links

- Docs / getting started: https://glasskit.app/ui/docs
- Components reference: https://glasskit.app/ui/docs/components
- Playground: https://glasskit.app/ui/playground
- GlassKit Studio (prompt to glasses app): https://glasskit.app/studio
- GlassKit Stack (fullstack boilerplate): https://glasskit.app/stack
- npm: https://www.npmjs.com/package/@glasskit-ui/react
- Source (MIT): https://github.com/GlassKitApp/glasskit-ui
- Platform audit: https://github.com/GlassKitApp/glasskit-ui/blob/main/docs/platform-audit-2026-06.md