-> **v0.1.0** — Shared UI component library for all Operator Uplift applications.
+
-47 components, 13 hooks, Storybook documentation, and a full design token system — published as a single npm package.
+
Captured from a local Storybook build on 30 October 2026.
+
+**`@operatoruplift/ui` is the React component library written in April 2026 for Operator Uplift's AI agent apps.** It packs 49 components, from buttons and tables to agent cards, tool call rows and a memory panel, plus 17 hooks and one set of dark, orange design tokens, into a single package with a Tailwind preset and a Storybook. It was meant to be shared by the website, the developer console and the desktop shell, but it was never published to npm and none of them imported it. Operator Uplift pivoted to commitment infrastructure on 22 May 2026, so this repo is a record of that earlier platform. It still builds, type-checks, tests and renders.
+
+The repo started in December 2025 as an Electron desktop assistant (`aven-assistant`, renamed Uplift Assistant in January 2026), begun by Dhruv Aggarwal. The library replaced it in [pull request 1](https://github.com/operatoruplift/UI/pull/1) on 1 April 2026, and the old app's source is still in `src/`.
+
+
+
+## How it works
+
+
+
+
+
+
+
+
+
Tokens live in CSS variables Colors and radii are --ou-* variables in src/styles/globals.css. The compiled styles.css, the Tailwind preset and the exported designTokens object carry the same values, so an app can retheme by overriding variables.
+
Ready for server rendering 40 of the 49 components start with the "use client" directive for the Next.js App Router. A packed build renders through react-dom/server and imports from both ESM and CommonJS.
+
No keys, no network The library reads no environment variables and makes no network requests. The memory hooks store through an adapter you pass in, and a localStorage adapter ships with them.
The component library, version 0.1.0. On 30 October 2026 it installed, type-checked, passed 119 of 119 Vitest tests, built its package and built a Storybook of 168 stories. It was never published to npm, and the apps it was written for never imported it. The current product is Operator Uplift: one small daily action, proved with a photo, and an AI Game Master decides whether the day counts.
The Uplift Assistant Electron app in src/ (December 2025 to January 2026): Supabase sign-in, chat, voice chat, an agent store and a workspace for installed agents. Its dependencies and build scripts left package.json in April 2026, so it no longer builds from this repo.
+
+
+
+## Where it fit
+
+Operator Uplift was first pitched as AI for your inbox and calendar, built across several repos. This one held the shared interface.
+
+
+
+
Repo
+
Role in the AI-assistant platform
+
+
+
UI (this repo)
+
Shared React components and design tokens. Before April 2026, the Uplift Assistant desktop app.
Prerequisites Node 22 and npm. Checked with Node 22.22.0 and npm 10.9.4 on 30 October 2026.
+
Read first CONTRIBUTING.md: how to add a component with its story and test, and the token, border and radius conventions.
+
What the checks prove 119 Vitest tests in 26 files render components in happy-dom and check variants and states; 12 of the files also simulate clicks or typing. tsc covers the library. Nothing here runs a real Next.js or Tauri app.
+
+
+
+### 1. Browse the components
-## Installation
+```bash
+npm ci
+npm run storybook # Storybook at http://localhost:6006 (npm run dev does the same)
+```
+
+### 2. Check and build
```bash
-npm install @operatoruplift/ui
+npm run lint # tsc over the library
+npm test # 119 Vitest tests in 26 files
+npm run build # dist/: ESM and CJS bundles, type declarations and styles.css
+npm run build-storybook # a static Storybook in storybook-static/
```
-## Setup
+### 3. Use it in an app
+
+The package is not on npm, so build it and install the tarball:
+
+```bash
+npm run build && npm pack # writes operatoruplift-ui-0.1.0.tgz
+cd ../your-app
+npm install path/to/UI/operatoruplift-ui-0.1.0.tgz
+```
-### 1. Import the stylesheet
+Import the stylesheet once, at the root of your app:
```tsx
import "@operatoruplift/ui/styles.css";
```
-### 2. Extend your Tailwind config
+Add the preset to a Tailwind CSS 3 config, so your own classes use the same tokens:
```ts
// tailwind.config.ts
+import type { Config } from "tailwindcss";
import { upliftPreset } from "@operatoruplift/ui/tailwind-preset";
export default {
presets: [upliftPreset],
- content: [
- "./src/**/*.{ts,tsx}",
- "./node_modules/@operatoruplift/ui/dist/**/*.js",
- ],
-};
+ content: ["./src/**/*.{ts,tsx}", "./node_modules/@operatoruplift/ui/dist/**/*.js"],
+} satisfies Config;
```
-## Usage
+Then compose:
```tsx
import { Button, Badge, Card, CardContent } from "@operatoruplift/ui";
-function App() {
+export function App() {
return (
@@ -60,123 +194,40 @@ function App() {
}
```
-## Components
+
+The memory system
+
-### Primitives
-
-| Component | Description |
-|-----------|-------------|
-| `Button` | Primary, outline, ghost, danger variants with loading & icon support |
-| `Badge` | Status labels: default, primary, success, warning, danger |
-| `Card` | Container: default, glass, glass-dark variants with header/content/footer |
-| `Input` | Text, password (show/hide), search with icon & error state |
-| `Textarea` | Auto-resizing textarea with label and error state |
-| `Toggle` | Animated on/off switch |
-| `Select` | Dropdown with search and multi-select |
-| `Tooltip` | Hover tooltips with arrow positioning |
-| `Toast` | Auto-dismiss notifications: success, error, warning, info |
-| `Alert` | Inline alert banners: info, success, warning, error with dismiss |
-| `Avatar` | User/agent avatars with image, fallback initials, and status dot |
-| `AvatarGroup` | Stacked avatar group with overflow count |
-| `Dropdown` | Generic dropdown menu with items, dividers, danger items |
-| `Tabs` | Tabbed navigation: default, pills, underline variants |
-| `Breadcrumb` | Navigation breadcrumbs with custom separator |
-| `Kbd` / `Shortcut` | Keyboard shortcut display |
-| `Divider` | Horizontal/vertical dividers with optional label |
-| `LoadingSpinner` | Spinner with label, optional fullscreen overlay |
-| `CopyButton` | Copy-to-clipboard button with confirmation |
-
-### Layout
-
-| Component | Description |
-|-----------|-------------|
-| `Sidebar` | Collapsible nav with sections and icons |
-| `Header` | Logo, nav links, user menu |
-| `PageWrapper` | Standard page layout with max-width |
-| `Modal` | Centered overlay with backdrop blur, close on Escape |
-| `CommandPalette` | Cmd+K command palette with search, groups, keyboard navigation |
-
-### Data Display
-
-| Component | Description |
-|-----------|-------------|
-| `Table` | Sortable columns, pagination, row selection |
-| `StatCard` | Value + label + change indicator |
-| `ProgressBar` | Determinate and indeterminate |
-| `Skeleton` | Loading placeholders (text, circular, rectangular) |
-| `EmptyState` | Icon + message + action button |
-| `CodeBlock` | Code display with filename, line numbers, copy button |
-| `StatusDot` | Animated status indicator (online, offline, running, error, etc.) |
-| `TokenCounter` | Token usage display with breakdown and progress bar |
-| `CostDisplay` | Cost/spend display with change indicator |
-| `StreamingText` | Animated text streaming with cursor |
-
-### Agent-Specific
-
-| Component | Description |
-|-----------|-------------|
-| `AgentCard` | Avatar, name, status dot, model badge, install button |
-| `RiskBadge` | A/B/C/D/F grade with color coding |
-| `SessionIndicator` | Active session count with animated dot |
-| `PermissionChip` | Icon + label for permission types |
-| `ModelSelector` | Provider-aware model dropdown |
-| `ChatBubble` | User/assistant message bubbles with copy button |
-| `ToolCallCard` | Expandable tool call display with status and I/O |
-| `ConversationThread` | Mixed message + tool call conversation thread |
-| `MemoryCard` | Expandable memory entry with on-demand content fetch |
-| `MemoryPanel` | Full memory management panel with search, filter, CRUD |
-
-### Effects
-
-| Component | Description |
-|-----------|-------------|
-| `SpotlightCard` | Mouse-following gradient highlight |
-| `GlowButton` | Animated glow on hover |
-| `FadeIn` | Intersection observer fade-in animation |
-| `DotGlobe` | Animated rotating dot grid globe |
-
-### Providers
-
-| Component | Description |
-|-----------|-------------|
-| `ThemeProvider` | Dark/light/system theme with persistence |
-| `ToastProvider` | Toast notification context |
-
-## Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useLocalStorage` | Persistent state synced across tabs |
-| `useMediaQuery` | Responsive breakpoint detection |
-| `useIsMobile` / `useIsTablet` / `useIsDesktop` | Convenience breakpoint hooks |
-| `useDebounce` / `useDebouncedCallback` | Debounced values and callbacks |
-| `useClipboard` | Copy to clipboard with auto-reset |
-| `useKeyboard` / `useHotkey` | Keyboard shortcut handling |
-| `useOnClickOutside` | Click outside detection |
-| `useStreamingText` | Animated text streaming for AI responses |
-| `useCostTracker` | Token/cost tracking for AI sessions |
-| `useMemory` | 3-layer memory system (index/topic/search) |
-| `useMemoryConsolidation` | Memory dedup, pruning, and merging |
-| `useTheme` | Theme accessor from ThemeProvider |
-| `useToast` | Toast notification accessor from ToastProvider |
-
-## Memory System
-
-The library includes a structured memory system for agentic applications:
+`useMemory` keeps agent memories in three layers: an index that is always loaded (pointers only, capped at 200 entries), topic files fetched on demand, and a search across topics. It writes the topic first and the index second, so the index never points at a missing topic. `useMemoryConsolidation` merges, prunes and removes duplicates.
```tsx
-import { useMemory, createLocalStorageAdapter } from "@operatoruplift/ui";
+import { MemoryPanel, createLocalStorageAdapter, useMemory } from "@operatoruplift/ui";
const adapter = createLocalStorageAdapter("my-app");
-const { entries, addMemory, searchMemories } = useMemory({ adapter });
+
+export function Memories() {
+ const { index, save, search, remove, count, atCapacity } = useMemory({ adapter });
+
+ async function remember() {
+ await save({ name: "Prefers short replies", description: "Keep answers brief", type: "feedback", content: "Skip recaps." });
+ const results = await search("replies"); // each result has the entry, a 0 to 1 score and a snippet
+ console.log(results.map((r) => r.entry.name));
+ }
+
+ return ;
+}
```
-**3-layer architecture**: Index (always loaded, pointers only) -> Topics (on-demand) -> Search (grep-style)
+Memory types are `user`, `feedback`, `project` and `reference`. Any storage works if it implements `MemoryStorageAdapter`.
+
+
-## Design Tokens
+
+Design tokens
+
-| Token | Value | CSS Variable |
-|-------|-------|-------------|
+| Token | Value | CSS variable |
+|---|---|---|
| Primary (Operator Orange) | `#E77630` | `--ou-primary` |
| Secondary (Amber) | `#F59E0B` | `--ou-secondary` |
| Background (Void) | `#050508` | `--ou-background` |
@@ -185,47 +236,156 @@ const { entries, addMemory, searchMemories } = useMemory({ adapter });
| Muted text | `#9ca3af` | `--ou-muted-foreground` |
| Border | `rgba(255,255,255,0.05)` | `--ou-border` |
| Destructive | `#ef4444` | `--ou-destructive` |
+| Radius | `0.25rem`, `0.375rem`, `0.5rem`, `0.75rem` | `--ou-radius-sm`, `-md`, `-lg`, `-xl` |
-Access tokens programmatically:
+Read them in code with `designTokens`, which also carries success `#22c55e`, warning `#f59e0b` and info `#3b82f6`:
```ts
import { designTokens } from "@operatoruplift/ui";
console.log(designTokens.primary); // "#E77630"
```
-## Storybook
+Known limit: the token colors are plain `var()` values, so Tailwind cannot apply opacity modifiers to them. Classes such as `bg-primary/20` (26 uses in the components) generate no CSS.
-```bash
-npm run dev
-# or
-npm run storybook
-```
+
-Open http://localhost:6006 to browse all components with interactive controls.
+
+Hooks
+
-## Development
+| Hook | Use |
+|---|---|
+| `useLocalStorage` | State persisted to `localStorage` and synced across tabs |
+| `useMediaQuery`, `useIsMobile`, `useIsTablet`, `useIsDesktop` | Responsive breakpoints |
+| `useDebounce`, `useDebouncedCallback` | Debounced values and callbacks |
+| `useClipboard` | Copy to the clipboard with an auto-reset flag |
+| `useKeyboard`, `useHotkey` | Keyboard shortcuts |
+| `useOnClickOutside` | Clicks outside an element |
+| `useStreamingText` | Text revealed as it streams, for AI responses |
+| `useCostTracker` | Token and cost tracking for AI sessions |
+| `useMemory`, `useMemoryConsolidation` | The memory system above |
+| `useTheme`, `useToast` | Accessors for `ThemeProvider` and `ToastProvider` |
-```bash
-npm install # Install dependencies
-npm run dev # Start Storybook
-npm run build # Build library
-npm run test # Run tests
-npm run lint # Type check
-```
+
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on adding new components.
+
+Repository layout
+
-## Compatibility
+| Path | Contents |
+|---|---|
+| `src/components/*.tsx` | The 49 library components, each with a `.stories.tsx`; 26 also have a `.test.tsx` |
+| `src/hooks/` | The 17 hooks, with the memory system in `src/hooks/memory/` |
+| `src/index.ts` | The barrel export: every component, hook, type and the tokens |
+| `src/tailwind-preset.ts`, `tailwind.config.ts` | The tokens as a Tailwind preset, and the config the library's CSS is built with |
+| `src/styles/globals.css` | The `--ou-*` variables and base styles compiled into `dist/styles.css` |
+| `.storybook/` | Storybook config, with the dark "void" background |
+| `src/App.tsx`, `src/main.ts`, `src/preload.ts`, `src/renderer.*`, `src/views/`, `src/services/`, `src/store/`, `src/components/ui/`, `src/components/auth/`, `src/config/`, `src/models/`, `src/types/`, `src/lib/supabase.ts`, `src/lib/timeout.ts`, `src/styles/input.css`, `tailwind.config.js`, `index.html`, `assets/`, `.env.example` | The old Uplift Assistant Electron app. Not built, exported or type-checked. |
-- React 18+ and React 19+
-- Next.js (SSR) and Tauri (CSR)
-- Keyboard accessible interactive components
-- Full TypeScript support with exported types
+
-## Security
+
-This library contains no API keys, secrets, or proprietary logic. All design tokens, components, and hooks are safe to publish publicly. The `src/` directory has been scanned to confirm zero references to `ANTHROPIC`, `SUPABASE`, `SECRET`, `KEY`, or `TOKEN` strings in library code.
-
-## License
+## Components
-MIT - Copyright (c) 2026 Operator Uplift. See [LICENSE](./LICENSE).
+49 components in six Storybook groups, every one exported from `src/index.ts` with its props type.
+
+
+Primitives (19)
+
+
+| Component | What it does |
+|---|---|
+| `Button` | Primary, outline, ghost and danger variants, three sizes, loading state and icons |
+| `Badge` | Status labels: default, primary, success, warning and danger |
+| `Card` | Default, glass and glass-dark containers with header, title, content and footer parts |
+| `Input` | Text, password with show and hide, and search, with icon and error states |
+| `Textarea` | Label, error state and auto-resize |
+| `Toggle` | An animated on and off switch |
+| `Select` | A dropdown with search and multi-select |
+| `Tooltip` | Hover tooltips on any side, with an arrow |
+| `Toast` | Auto-dismissing success, error, warning and info notices, through `ToastProvider` |
+| `Alert` | Inline info, success, warning and error banners that can be dismissed |
+| `Avatar` | Image, initials fallback and status dot |
+| `AvatarGroup` | Stacked avatars with an overflow count |
+| `Dropdown` | A menu with items, dividers and danger items |
+| `Tabs` | Default, pills and underline variants |
+| `Breadcrumb` | Breadcrumbs with a custom separator |
+| `Kbd`, `Shortcut` | Keyboard keys and shortcuts |
+| `Divider` | Horizontal or vertical, with an optional label |
+| `LoadingSpinner` | A spinner with a label and an optional fullscreen overlay |
+| `CopyButton` | Copy to the clipboard with a confirmation |
+
+
+
+
+Layout (5)
+
+
+| Component | What it does |
+|---|---|
+| `Sidebar` | Collapsible navigation with sections and icons |
+| `Header` | Logo, navigation links and a slot for a user menu |
+| `PageWrapper` | A page layout with a maximum width |
+| `Modal` | A centered overlay with a blurred backdrop that closes on Escape |
+| `CommandPalette` | Grouped commands, filtering and arrow-key navigation; your app decides when it opens |
+
+
+
+
+Data display (7)
+
+
+| Component | What it does |
+|---|---|
+| `Table` | Sortable columns, pagination and row selection |
+| `StatCard` | A value, a label and a change indicator |
+| `ProgressBar` | Determinate and indeterminate progress |
+| `Skeleton` | Text, circular and rectangular placeholders |
+| `EmptyState` | An icon, a message and an action |
+| `CodeBlock` | Code with a filename, line numbers and a copy button |
+| `StatusDot` | An animated dot for online, offline, idle, busy, away, running and error |
+
+
+
+
+Agent (12)
+
+
+| Component | What it does |
+|---|---|
+| `AgentCard` | Avatar, name, status dot, model badge and install button |
+| `ChatBubble` | User and assistant messages with a copy button |
+| `ConversationThread` | Messages and tool calls in one thread |
+| `ToolCallCard` | An expandable tool call with status, timing, input and output |
+| `MemoryCard` | An expandable memory entry that fetches its content on demand |
+| `MemoryPanel` | Search, type filters and create, edit and delete callbacks for memories |
+| `ModelSelector` | A model dropdown with a badge for each provider |
+| `TokenCounter` | Token usage with a breakdown and a limit bar |
+| `CostDisplay` | Spend with a change indicator |
+| `SessionIndicator` | An active session count with an animated dot |
+| `PermissionChip` | An icon and label for a granted or denied permission |
+| `RiskBadge` | An A to F grade with color coding |
+
+
+
+
+Effects (5) and providers (1)
+
+
+| Component | What it does |
+|---|---|
+| `SpotlightCard` | A gradient highlight that follows the mouse |
+| `GlowButton` | A button with an animated glow on hover |
+| `FadeIn` | Fades content in when it scrolls into view (IntersectionObserver) |
+| `DotGlobe` | A rotating globe of dots drawn on a canvas |
+| `StreamingText` | Text that streams in with a cursor |
+| `ThemeProvider` | Dark, light or system theme, remembered in `localStorage` |
+
+
+
+
+
+
MIT licensed, copyright 2026 Operator Uplift (see LICENSE); dependencies keep their own licenses.